tbl

Utility functions for working with Lua tables.

Quick Reference

Basics:

Function	Description
clear(t)	Remove all entries from the table.
count(t)	Return the number of keys in the table.

Copying:

Function	Description
copy(t)	Create a shallow copy of the table.
deepcopy(v)	Create a deep copy of a value.

Query:

Function	Description
filter(t, pred)	Filter entries by a value predicate.
find(t, v)	Find the first key whose value equals the given value.
find_if(t, pred)	Find first value and key matching predicate.
get(t, ...)	Safely get nested value by keys.

Transforms:

Function	Description
invert(t)	Invert keys/values into new table.
isempty(t)	Return true if table has no entries.
keys(t)	Return a list of all keys in the table.
map(t, fn)	Return a new table by mapping each value (keys preserved).
pairmap(t, fn)	Return a new table by mapping each key-value pair.
update(t1, t2)	Merge entries from t2 into t1 and return t1.
values(t)	Return a list of all values in the table.

Functions

Basics

clear(t)

Remove all entries from the table.

local t = { a = 1, b = 2 }
clear(t)
-- result: {}

count(t)

Return the number of keys in the table.

local n = count({ a = 1, b = 2 })
-- result: 2

Copying

copy(t)

Create a shallow copy of the table.

local t = copy({ a = 1, b = 2 })
-- result: { a = 1, b = 2 }

deepcopy(v)

Create a deep copy of a value. If v is a table, all nested tables are copied recursively; other types are returned as-is.

local n = deepcopy(42)
-- result: 42

local t = deepcopy({ a = { b = 1 } })
-- result: { a = { b = 1 } }

Query

filter(t, pred)

Filter entries by a value predicate.

local even = filter({ a = 1, b = 2, c = 3 }, function(v)
 return v % 2 == 0
end)
-- result: { b = 2 }

find(t, v)

Find the first key whose value equals the given value.

local key = find({ a = 1, b = 2, c = 2 }, 2)
-- result: "b" or "c"

find_if(t, pred)

Find first value and key matching predicate.

local v, k = find_if({ a = 1, b = 2 }, function(v, k)
 return k == "b" and v == 2
end)
-- result: 2, "b"

get(t, ...)

Safely get nested value by keys. If no keys are provided, returns the input table.

local t = { a = { b = { c = 1 } } }
local v = get(t, "a", "b", "c")
-- result: 1

local v2 = get(t)
-- result: { a = { b = { c = 1 } } }

Transforms

invert(t)

Invert keys/values into new table.

local t = invert({ a = 1, b = 2 })
-- result: { [1] = "a", [2] = "b" }

isempty(t)

Return true if table has no entries.

local empty = isempty({})
-- result: true

keys(t)

Return a list of all keys in the table.

local keys = keys({ a = 1, b = 2 })
-- result: { "a", "b" }

map(t, fn)

Return a new table by mapping each value (keys preserved).

local t = map({ a = 1, b = 2 }, function(v)
 return v * 10
end)
-- result: { a = 10, b = 20 }

pairmap(t, fn)

Return a new table by mapping each key-value pair. The resulting table keeps the same keys, with values transformed by fn.

local t = pairmap({ a = 1, b = 2 }, function(k, v)
 return k .. v
end)
-- result: { a = "a1", b = "b2" }

update(t1, t2)

Merge entries from t2 into t1 and return t1.

local t1 = { a = 1, b = 2 }
update(t1, { b = 3, c = 4 })
-- result: t1 is { a = 1, b = 3, c = 4 }

values(t)

Return a list of all values in the table.

local vals = values({ a = 1, b = 2 })
-- result: { 1, 2 }