Arrays and strings
An array holds values of one type and can grow; a string is immutable bytes, usually UTF-8 text. Both have a short, fixed list of methods — far fewer than in JavaScript — and both are bounds-checked. The normative rules are in the reference's Array literals, Element access, Arrays and strings as receivers and Template literals sections.
Arrays
T[] (or Array<T>) is an array of T. A literal's elements must all have
one type, and an empty literal [] needs a type to take from its context:
export const main = (): i32 => {
const primes = [2, 3, 5, 7]; // i32[]
const names: string[] = []; // [] needs the annotation
names.push("ada");
names.push("grace");
primes.push(11);
const last = primes.pop(); // 11
primes[0] = 1;
console.log(`${primes.length} ${last} ${primes[0]}`); // 4 11 1
console.log(`${primes.indexOf(5)} ${primes.indexOf(4)}`); // 2 -1
console.log(names.join(", ")); // ada, grace
return 0;
};
Those — length (read-only), push, pop, indexOf and join (on a
string[] only) — with set and fill on arrays of numbers, sort,
map, filter, forEach, some, every, findIndex and slice (below),
are every array method there is. There is no find or reduce, and no
spread. Write the loop, or a function that takes
a function argument.
const fixes the binding, not the contents: primes.push(11) and
primes[0] = 1 above are fine on a const, and primes = [] would not be.
Declare a parameter readonly T[] to promise the function writes nothing
into it.
Sorting
xs.sort(cmp) sorts the array in place and answers it. The comparator says
how two elements compare: a negative number puts a first, a positive one
puts b first, and zero keeps them in the order they had — the sort is
stable, so the result is exactly the one Node gives.
class Score {
name: string;
points: i32;
constructor(name: string, points: i32) {
this.name = name;
this.points = points;
}
}
const byPoints = (a: Score, b: Score): number => b.points - a.points;
export const main = (): i32 => {
const xs: i32[] = [5, -2, 9, 0];
xs.sort((a, b) => a - b);
console.log(`${xs[0]} ${xs[3]}`); // -2 9
const board: Score[] = [new Score("ada", 3), new Score("bo", 7), new Score("cy", 3)];
board.sort(byPoints);
const names: string[] = [];
for (const s of board) {
names.push(s.name);
}
console.log(names.join(" ")); // bo ada cy
return 0;
};
Three things are refused where JavaScript would do something surprising or Nish cannot follow:
-
xs.sort()with no comparator. JavaScript compares the elements as strings, so[10, 9].sort()is[10, 9]; Nish asks you to writexs.sort((a, b) => a - b). - Sorting a
readonly T[], orprocess.argv. -
A comparator that reads a
letof the function it is written in. It may read that function'sconstlocals and parameters, as any arrow argument may (Functions):xs.sort((a, b) => rank[a] - rank[b])with aconst rank. Bind aletto aconstbefore the call.
(a, b) => a - b is checked i32 arithmetic: on elements more than
2^31 - 1 apart, such as [2147483647, -1], it panics with
attempt to subtract with overflow. When the values may span the whole range,
compare instead: (a, b) => (a > b ? 1 : a < b ? -1 : 0). An array holding
NaN, or a comparator that is not a consistent order, sorts to some
permutation of its elements, which, as in JavaScript, need not be Node's.
Each comparator compiles to its own copy of the sort, with the comparator
called directly in the inner loop. A sort uses one temporary copy of the
array, given back before sort returns, so sorting in a loop does not grow
memory.
map, filter and slice
map, filter, forEach, some, every and findIndex take a callback,
which gets the element, or the element and its index, as in TypeScript.
slice copies a range into a new array.
export const main = (): i32 => {
const xs: i32[] = [3, 8, 1, 6];
const doubled = xs.map((x) => x * 2);
const big = xs.filter((x) => x > 2);
const labels = xs.map((x, i) => `${i}:${x}`);
const middle = xs.slice(1, 3);
console.log(`${doubled[1]} ${big.length} ${middle[0]}`); // 16 3 8
console.log(labels.join(" ")); // 0:3 1:8 2:1 3:6
console.log(`${xs.some((x) => x > 7)} ${xs.every((x) => x > 0)}`); // true true
console.log(`${xs.findIndex((x) => x === 1)}`); // 2
return 0;
};
The callback follows the comparator's rule above: a top-level function, or an
arrow that reads only const locals and parameters. Each callback compiles to
its own loop that calls it directly. Three things differ from JavaScript:
-
There is no
find. TypeScript says it answersT | undefined, and Nish has noundefined. UsefindIndexand index the array:const i = xs.findIndex(f); if (i >= 0) { ... xs[i] ... }. - A callback takes at most two parameters. JavaScript passes the array as a third; read the array you called the method on instead.
-
slicestops the program on a bad range, as stringslicedoes:xs.slice(start, end)needs0 <= start <= end <= xs.length. A negative index does not count from the end, and an end past the length is not clamped.xs.slice()copies the whole array, andxs.slice(start)copies fromstartto the end.
Walking an array
for (const x of xs) visits each element in order; use an index loop when
you need the position:
const sum = (xs: f64[]): f64 => {
let total: f64 = 0.0;
for (const x of xs) {
total = total + x;
}
return total;
};
const largestAt = (xs: i32[]): i32 => {
let best = 0;
for (let i = 1; i < xs.length; i++) {
if (xs[i] > xs[best]) {
best = i;
}
}
return best;
};
export const main = (): i32 => {
console.log(`${sum([1.5, 2.5, 4.0])}`); // 8
console.log(`${largestAt([3, 9, 4])}`); // 1
return 0;
};
xs.forEach(f) walks the array as that for...of loop does, with f written
in as its body, except that it stops at the length the array had when the call
began, as Node does, so an element f pushes is not visited. It answers
nothing (void), and f follows the callback rule above, so it may call,
print and push onto an array it can see, but not assign a local of the
function around it. To add up, write the for...of loop of sum above: a
forEach callback that assigns a total is refused (NL2586), and the message
says to use for...of.
export const main = (): i32 => {
const xs: i32[] = [3, 8, 1];
const seen: i32[] = [];
xs.forEach((x, i) => console.log(`${i}:${x}`)); // 0:3 1:8 2:1
xs.forEach((x) => {
seen.push(x * 10);
});
console.log(`${seen[2]}`); // 10
return 0;
};
Bounds
Every xs[i] is checked: an index outside 0 … xs.length - 1 — a negative
one included — stops the program with index out of range on stderr and
exit status 1, where JavaScript would answer undefined. pop() on an
empty array stops the program the same way. The compiler removes the check
wherever it can prove the index is in range, as in the i < xs.length loop
above.
export const main = (): i32 => {
const xs = [10, 20, 30];
const i = 3;
console.log(`${xs[i]}`); // stops: index out of range: 3 >= 3
return 0;
};
An array of arrays is written i32[][]. An array of an interface type
that no class implements stores the records themselves back to back, which
is why holding one of its elements across a push onto the same array is
refused. An array of class instances, of an interface some class implements,
or of a T | null holds a pointer to each element instead
(Arrays of records are contiguous).
Lookup tables
A top-level const declared readonly u8[] (or u16, u32, i32, i64
or f64) and given an array literal of constants is a constant table. Its
elements are worked out when the program compiles and kept as read-only
data in the binary: nothing runs to build it, and nothing can write it
(Constant tables).
const LIMIT: i32 = 100;
const SCALE: readonly i32[] = [1, 10, LIMIT, LIMIT * 10];
export const main = (): i32 => {
let total: i32 = 0;
for (let i = 0; i < SCALE.length; i++) {
total += SCALE[i];
}
console.log(`${SCALE.length} ${total}`); // 4 1111
return 0;
};
-
Each element is a constant: a number, another module constant, or
arithmetic over them, and it must fit the element type;
256in areadonly u8[]is refused. A table has at least one element. -
It is spelled
readonly. Reading it — indexing,length,slice,indexOf,map, afor...of— works as on any array; writing an element,push,sort, or handing it where a writableu8[]is expected is refused:
const XS: i32[] = [1, 2, 3];
export const main = (): i32 => {
return XS[0];
};
-
A
u8index into a 256-entryreadonly u8[]needs no bounds check: au8cannot be out of range, soTABLE[c]is one load. That is the shape of a byte classifier — one table entry per possible byte — which answers in one read where a chain ofifs compares the byte several times.
Module storage
A top-level const holding a new array of a constant length is module
storage: a fixed block of memory, zero-filled when the program starts, that
keeps its values from one call to the next. It is the one piece of state a
module keeps, and no code runs to set it up.
(Module storage).
const SCORES = new Int32Array(4);
const sum = (xs: Int32Array): i32 => {
let total: i32 = 0;
for (let i = 0; i < xs.length; i++) {
total += xs[i];
}
return total;
};
export const main = (): i32 => {
SCORES[0] = 30;
SCORES[3] = 4;
console.log(`${sum(SCORES)} ${SCORES[1]}`); // 34 0
return 0;
};
-
Its length is known when the program compiles: a number, or a
constthe compiler can work out, from 1 to 16,777,216, and the storage holds at most 256 MiB.new Array<T>(n)andnew Int32Array(n),Float32Array,Float64ArrayandBigInt64Arrayall make one. - Its elements are numbers, booleans, enums, handles, or records of those. A string, an array, a nullable element or a class is refused, and so is an enum with no member equal to zero, since every element starts at zero.
-
It never grows and never moves. No method may be called on it (
push,popandsortincluded), nor may itslengthbe assigned; keep a count beside it for the slots in use:
const xs = new Int32Array(4);
export const main = (): i32 => {
xs.push(1);
return 0;
};
-
It is a place, not a value. You index it and read its
length; you do not store, return or alias the array itself. The one way to hand it to another function is a parameter spelled with a typed-array name, such asxs: Int32Arrayabove, which has nopusheither. An element of a storage of records is a place too:bodies[i].x = 1writes a field andbodies[i] = bodies[j]copies a whole element, but bindingbodies[i]to a name or passing it to a function is refused; pass the index instead.
In a wasm module built for a page, module storage is the memory the page reads and writes directly (In a browser).
Strings
A string is immutable bytes, usually UTF-8 text, and Nish does not check that
they are valid UTF-8. + joins two strings, === compares them by
content, and these are its methods, all of them:
| Member | Answers |
|---|---|
s.length |
the length in bytes |
s.charCodeAt(i) |
the byte at i, bounds-checked |
s.substring(start, end?) |
the bytes from start up to end, clamped into range as in JavaScript |
s.slice(start, end?) |
the same, but an out-of-range or reversed pair stops the program instead of being clamped |
s.indexOf(sub, from?) |
the first byte offset of sub at or after from (default 0), or -1 |
s.startsWith(sub), s.endsWith(sub) |
a boolean |
String.fromCharCode(c) |
the one-byte string of c |
String.fromBytes(bytes, start, end) |
the bytes of a u8[] from start up to end as one string; an out-of-range or reversed pair stops the program, as slice's does |
toUpperCase, split, trim, replace and the rest do not exist;
build them from these, or look in the
standard library.
Lengths and offsets count bytes, not characters. An ASCII character is
one byte, but é is two and most emoji are four:
const word = "café";
console.log(`${word.length}`); // 5
console.log(word.substring(0, 3)); // caf
console.log(`${word.charCodeAt(0)}`); // 99
console.log(`${word.indexOf("fé")}`); // 2
console.log(`${word.startsWith("ca")}`); // true
Since every offset is a byte offset, substring can cut a multi-byte
character in half; that is the cost of indexing a string in constant time.
Bytes become text the other way with String.fromBytes: the range of a
u8[], from start up to end, as one string in one allocation. It is the
way to turn what a file or a socket handed you into a string, where a
String.fromCharCode per byte joined together allocates once per byte:
const bytes: u8[] = [99, 97, 102, 195, 169];
console.log(String.fromBytes(bytes, 0, 5)); // café
console.log(String.fromBytes(bytes, 0, 3)); // caf
The bytes are copied as they are, so é's two bytes are é again. Under
Node each byte is one character instead, as with String.fromCharCode, so the
two answers agree only where the bytes are ASCII.
Template literals
A template literal is how a number becomes text: each ${…} hole may be a
string, a number of any type or a boolean. "n = " + n is
refused (no implicit conversion), and so are String(n) and
n.toString():
export const main = (): i32 => {
const name = "nish";
const version = 0;
const ok = true;
console.log(`${name} ${version}.${version + 18} ${ok}`); // nish 0.18 true
return 0;
};
const n = 3;
console.log("n = " + n);
console.log takes exactly one argument, so join what you want to print
into one template.

