- Deletes the first occurrence of a value from a sequence in a table.
- tbl
-
- The table.
- v
-
- The value to match and remove.
The del() function searches a sequence in a table for an element that equals the given value then removes it. All subsequent values in the sequence shift down by one slot to keep the sequence contiguous.
Specifically, del() starts with the element at index 1, then increments the index while comparing elements to the given value. When it finds the first element that is equal to the value, it reassigns the indexes of the subsequent values until it reaches an unassigned index (nil).
From PICO-8 0.1.12, the del() function returns the object being removed (on prior versions, nil is returned). This can be ignored, tested it to see if the removal was successful, or used as needed.
Examples
t = {1, 3, 5, 3, 7, 5}
del(t, 3) -- t = {1, 5, 3, 7, 5}
del(t, 7) -- t = {1, 5, 3, 5}
del(t, 5) -- t = {1, 3, 5}
del(t, 9) -- not found, no changes to t
The following example demonstrates how equality is used to match elements. A value is only equal to a table if the value is the same table in memory. (Two tables are not equal even if they contain the same elements.)
x = {'foo'}
t = {}
add(t, {'bar'})
add(t, {'foo'})
add(t, {'baz'})
add(t, x)
add(t, {'bat'})
for v in all(t) do print(v[0]) end -- bar foo baz foo bat
del(t, x)
for v in all(t) do print(v[0]) end -- bar foo baz bat