types.Array.apply

Method on every array

array.apply(callback: function): any

Replaces every element with the result of callback on it.

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

callback function callback(value, [index], [array]), called for each element, in order

Return value

This array.

Errors

Whatever callback throws, on the first element where it throws.

Notes

callback gets exactly as many of the arguments listed above as it declares parameters for, and never more; a native callback that does not fix its own parameter count is called with all three.

apply transforms in place: an element is overwritten as soon as callback returns for it. If callback throws partway through, the elements already processed keep their new values and the rest keep their old ones; the array is left half-transformed, not rolled back.

Unlike map, apply does not give throw null any special meaning: a thrown null aborts the loop like any other thrown value.

Example

examples/types/array/apply.nut

let a = [1, 2, 3]
let same = a.apply(function(v) { return v * v })

println("same == a:", same == a)           // apply returns this array, not a copy
println("a (squared) =", ", ".join(a.map(@(v) v.tostring())))

// a throw aborts the loop, and the elements already written stay written
let b = [1, 2, 3, 4]
try { b.apply(function(v) { if (v == 3) throw "stop"; return v * 10 }) }
catch (e) { println("apply() throws:", e) }
println("b (after throw) =", ", ".join(b.map(@(v) v.tostring())))

Output:

same == a: true
a (squared) = 1, 4, 9
apply() throws: stop
b (after throw) = 10, 20, 3, 4