types.Array.insert

Method on every array

array.insert(index: number, value): any

Inserts value before the element currently at index, shifting the rest up by one.

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

`index`	number	where to insert
`value`	any	the value to insert

Return value

This array.

Errors

Throws index out of range unless 0 <= index <= len(). Note the upper bound is inclusive: index == len() inserts at the end, same as append.

Notes

index is not adjusted for negative values the way slice and swap adjust theirs; a negative index is always out of range here.

Example

examples/types/array/insert.nut

let a = [1, 2, 3];
a.insert(1, 99);
println("a =", ", ".join(a.map(@(v) v.tostring())));

a.insert(a.len(), 100);   // inserting at len() behaves like append
println("a.top() =", a.top());

try { a.insert(-1, 0) } catch (e) { println("a.insert(-1, 0) throws:", e); }    // negative index is not wrapped
try { a.insert(999, 0) } catch (e) { println("a.insert(999, 0) throws:", e); }

Output:

a = 1, 99, 2, 3
a.top() = 100
a.insert(-1, 0) throws: index out of range
a.insert(999, 0) throws: index out of range