types.Table.replace_with

Method on every table

table.replace_with(other: table): any

Replaces the table's entire contents with a copy of other's slots, in place.

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

other table table to copy from

Return value

The table itself, now holding a copy of other's slots.

Errors

Throws Cannot modify immutable object when the table was frozen with freeze(). Throws parameter 1 of 'replace_with' has an invalid type 'array' ; expected: 'table' (with the actual type in place of array) when other is not a table.

Notes

Takes exactly one argument, and it must be a table - unlike __update, which also accepts a class or instance. Existing references to the table being replaced see the new contents too, since this mutates the same object rather than building a new one; other itself is left untouched.

Every old slot is gone before any slot of other is copied in, so a slot that other does not have cannot survive the call.

Replacing a table with itself is a no-op and keeps every slot.

Example

examples/types/table/replace_with.nut

let dst = {a=1, b=2}
let src = {c=3}

println("dst.replace_with(src) == dst:", dst.replace_with(src) == dst)   // the same table, mutated in place
println("dst.len() =", dst.len())                      // only src's slot remains
println("\"a\" in dst:", "a" in dst)
println("src.len() =", src.len())                      // src itself is untouched

// replacing a table with itself keeps every slot
let t = {a=1, b=2}
t.replace_with(t)
println("t.len() =", t.len())

Output:

dst.replace_with(src) == dst: true
dst.len() = 1
"a" in dst: false
src.len() = 1
t.len() = 2