types.Array.resize

Method on every array

array.resize(size: number, ...): any

Grows or shrinks the array to size elements.

The binding carries no declaration string, so the VM cannot report parameter names. The names above are from this page; the types and attributes still come from the VM. The VM also cannot tell an optional parameter from a variadic tail here, so read the brackets and any trailing ... from the prose below, not from the signature.

Parameters

`size`	number	the new element count
`...`	any	repeats

Return value

This array.

Errors

Throws resizing to negative length when size is negative.

Notes

This binding's type mask covers only size, so the VM's signature shows only that one parameter with a trailing ...; resize also takes a second, optional fill value for the slots a growing resize adds (null when left out), the same fill value the array constructor takes, with the same aliasing caveat: it is stored as is, not cloned per slot. That fill value is invisible to the VM's introspection, since the mask never mentions it. A third real argument beyond that is silently ignored.

Shrinking to a quarter or less of the array's reserved capacity releases the unused storage, the same as clear does at size 0.

Example

examples/types/array/resize.nut

let a = [1, 2, 3];
a.resize(5, 9);        // grows: new elements get the fill value
println("a =", ", ".join(a.map(@(v) v.tostring())));

a.resize(2);             // shrinks: default_value left out, extra elements are just dropped
println("a.len() =", a.len());

try { a.resize(-1) } catch (e) { println("a.resize(-1) throws:", e); }

Output:

a = 1, 2, 3, 9, 9
a.len() = 2
a.resize(-1) throws: resizing to negative length