types.Table.findindex

Method on every table

pure table.findindex(callback: function): any

Returns the key of the first value for which callback returns a truthy result.

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, [key], [table]), tested against every value

Return value

The key of the first match, or nothing (null) if no value matches.

Errors

Whatever callback throws propagates out of findindex.

Notes

Takes exactly one argument - callback - despite the VM-reported signature showing no brackets or ...; there is no optional second argument here (see findvalue, which does have one and is easy to confuse this with).

callback gets exactly as many of the arguments listed above as it declares parameters for, and never more - the same rule as each.

Iteration order is otherwise unspecified, so callback should not rely on seeing keys in any particular order, only that every slot is offered once until a match is found.

Example

examples/types/table/findindex.nut

let t = {a=1, b=2, c=3}
// exactly one slot matches, so the result does not depend on visit order
println("t.findindex(v == 2) =", t.findindex(function(v) { return v == 2 }))
println("t.findindex(k == \"a\") =", t.findindex(function(v, k) { return k == "a" }))
println("t.findindex(v > 100) == null:", t.findindex(function(v) { return v > 100 }) == null)

// three parameters: (value, key, table itself)
println("t.findindex(tbl==t && v==3) =", t.findindex(function(v, k, tbl) { return tbl == t && v == 3 }))

Output:

t.findindex(v == 2) = b
t.findindex(k == "a") = a
t.findindex(v > 100) == null: true
t.findindex(tbl==t && v==3) = c