types.Table.rawdelete

Method on every table

table.rawdelete(key): any

Removes the slot at key, without calling a _delslot metamethod.

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

key any the key to remove

Return value

The value that was stored at key, or null if the key was not present.

Errors

Throws Cannot modify immutable object when the table was frozen with freeze().

Notes

Write it as t.$rawdelete(key). A table's own slots and its methods share one namespace, so a table that happens to have a slot called rawdelete hides the method behind it, and t.rawdelete("a") then fails with attempt to call 'string'. The $ prefix reaches the built-in type method directly and never sees the slot. Plain t.rawdelete(key) works whenever no such slot exists, but on data whose keys you do not control, $ always works.

Takes exactly one argument; t.$rawdelete() and t.$rawdelete("a", "b") both throw a wrong-number-of-parameters error.

A missing key is not an error here, unlike rawget: deleting a key that is already absent is a silent no-op that returns null.

The delete t.k operator is forbidden by default (it needs the #allow-delete-operator pragma); the compiler's own error for it points at this method: "Usage of 'delete' operator is forbidden. Use 'o.$rawdelete(\"key\")' instead".

Example

examples/types/table/rawdelete.nut

let squad = {name = "alpha", strength = 4}
println("squad.$rawdelete(\"name\") =", squad.$rawdelete("name"))  // returns the removed value
println("squad.len() =", squad.len())

// an absent key is a quiet no-op, not an error
println("squad.$rawdelete(\"missing\") == null:", squad.$rawdelete("missing") == null)

// $ matters: a slot of the same name would otherwise shadow the method
let shadowed = {rawdelete = "just a field"}
println("shadowed.rawdelete =", shadowed.rawdelete)
println("type(shadowed.$rawdelete) =", type(shadowed.$rawdelete))

let frozen = freeze({name = "bravo"})
try {
  frozen.$rawdelete("name")
} catch (e) {
  println("frozen.$rawdelete(\"name\") throws:", e)
}

Output:

squad.$rawdelete("name") = alpha
squad.len() = 1
squad.$rawdelete("missing") == null: true
shadowed.rawdelete = just a field
type(shadowed.$rawdelete) = function
frozen.$rawdelete("name") throws: Cannot modify immutable object