types.Table.findvalue

Method on every table

pure table.findvalue(callback: function, [default], ...): any

Returns 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
`default`	any	value to return when nothing matches optional
`...`	any	repeats

Return value

The first matching value, or default if given and nothing matches, otherwise null.

Errors

Throws Too many arguments for findvalue() when a third argument follows callback and default - findvalue accepts at most those two. Whatever callback throws also propagates out.

Notes

Takes 1 required argument (callback) plus 1 truly optional one (default)

despite the VM-reported signature ending in ..., a third argument is a hard error, not a variadic tail; the check happens before callback even runs. This is the opposite trap from reduce: there the VM's ... hides a real optional parameter that never appears in the signature; here it shows a ... that is not open-ended.

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

Example

examples/types/table/findvalue.nut

let t = {a=1, b=2, c=3}
println("t.findvalue(v == 2) =", t.findvalue(function(v) { return v == 2 }))
println("t.findvalue(v > 100) == null:", t.findvalue(function(v) { return v > 100 }) == null)
println("t.findvalue(v > 100, \"none\") =", t.findvalue(function(v) { return v > 100 }, "none"))  // default value

try {
  t.findvalue(function(v) { return false }, "none", "extra")
} catch (e) {
  println("findvalue with extra arg throws:", e)   // a real error, not a variadic tail
}

Output:

t.findvalue(v == 2) = 2
t.findvalue(v > 100) == null: true
t.findvalue(v > 100, "none") = none
findvalue with extra arg throws: Too many arguments for findvalue()