lua_table

Contents

• Local Functions

Modules

• lua_table

Module lua_table

Set of helpful table manipulation functions

Info:

• Copyright: IMAIA, 2019
• License: MIT
• Author: Italo Maia

Local Functions

append (t1, t2)	inserts all values of t2 in t1 keys of t2 are not preserved; t2 are inserted in order only if t2 is an array.
copy (t)	creates a deep copy of t; ignores metatable keys are copied as they are; if value is a table, copy is recursively called for it; make sure table is not a cyclic tree before using copy.
distinct (t)	creates a new array without repeated values
keys (t)	creates a new array with all keys of t
same (t1, t2)	compares the values of t1 and t2 for each key of both returns false if any of the values differ and works with nested tables
flat (t, level)	flattens up array items of t into single values level controls how many levels of the array should be flattened
foreach (t, fn)	calls fn for each (key, value) of t
proxy (t, newindex, base)	creates a table with protected values use it to easely customize table value set and unset
immutable (t)	creates a immutable table
join (t1, t2)	copies all (key, value) of t1 and t2 into a new table and returns it if t1 and t2 have key collision, t2 value will have precedence
merge (t1, t2)	copies all (key, value) of t2 into t1 and returns t1
set ([t={}])	creates a new array without repeated values that ignores repeated values
patch (t1, t2[, rename[, only[, exclude]]])	copies all (key, value) of t2 into t1; throws an error on key collision useful if you want to prevent collision
slice (t, _i, _e)	gets you an slice of the array negative indexes are not supported
sorted (t, fn)	creates a sorted copy of t
union (t1, t2)	creates a new array with all values of t1 and t2 keys are not preserved; order of the values is not guaranteed.
values (t)	creates a new array with all values of t

Local Functions

append (t1, t2)

inserts all values of t2 in t1 keys of t2 are not preserved; t2 are inserted in order only if t2 is an array.

Parameters:

• t1 array
• t2 array

Returns:

t1

See also:

union

Usage:

a, b = {1}, {2}; append(a, b) -- {1, 2}

copy (t)

creates a deep copy of t; ignores metatable keys are copied as they are; if value is a table, copy is recursively called for it; make sure table is not a cyclic tree before using copy.

Parameters:

• t table non cyclic table

Returns:

new table with all attributes of `t`

distinct (t)

creates a new array without repeated values

Parameters:

• t array

Returns:

new array without duplicate values

Usage:

distinct({1, 1, 2, 3})  -- {1, 2, 3}

keys (t)

creates a new array with all keys of t

Parameters:

• t table

Returns:

new table

See also:

values

Usage:

• values({3,4,5})  -- {1, 2, 3}

• values({a=1, b=2, c=3})  -- {'a', 'b', 'c'}

same (t1, t2)

compares the values of t1 and t2 for each key of both returns false if any of the values differ and works with nested tables

Parameters:

• t1 table
• t2 table

Returns:

whether all key/values are the same

See also:

• distinct
• append
• keys

Usage:

• same({1, 2}, {1, 2})  -- true

• same({1, 2}, {2, 1})  -- false

• same({a=1, b=2}, {b=2, a=1})  -- true

flat (t, level)

flattens up array items of t into single values level controls how many levels of the array should be flattened

Parameters:

• t array
• level int

Returns:

new flattened array

Usage:

• flat({1, {2}})  -- {1, 2}

• flat({1, {2, {3}}})  -- {1, 2, {3}}

• flat({1, {2, {3}}}, 2)  -- {1, 2, 3}

foreach (t, fn)

calls fn for each (key, value) of t

Parameters:

• t table
• fn function (k, v) as params

Usage:

foreach({3,4,5}, function (k, v) print(k) end)

proxy (t, newindex, base)

creates a table with protected values use it to easely customize table value set and unset

Parameters:

• t table
• newindex function (t, k, v) as params
• base table ; use it for custom functions

Returns:

proxied table

immutable (t)

creates a immutable table

Parameters:

• t table

Returns:

new immutable table

Usage:

• immutable({a=1, b=2, c=3})  -- constants map

• immutable({1, 2, 3})  -- tuple

join (t1, t2)

copies all (key, value) of t1 and t2 into a new table and returns it if t1 and t2 have key collision, t2 value will have precedence

Parameters:

• t1 table
• t2 table

Returns:

new table with the values of t1 and t2

See also:

merge

Usage:

• join({a=1, c=3}, {a=2, b=2}) -- {a=2, b=2, c=3}

• join({a=1}, {b=2}) -- {a=1, b=2}

• join({a=1}, {2}) -- {a=1, [1]=2}

merge (t1, t2)

copies all (key, value) of t2 into t1 and returns t1

Parameters:

• t1 table
• t2 table

Returns:

updated t1

See also:

join

Usage:

• merge({a=1, c=3}, {a=2, b=2}) -- {a=2, b=2, c=3}

• merge({a=1}, {b=2}) -- {a=1, b=2}

• merge({a=1}, {2}) -- {a=1, [1]=2}

set ([t={}])

creates a new array without repeated values that ignores repeated values

Parameters:

• t array (default {})

Returns:

new set table

Usage:

set({1, 1, 2, 2, 3})  -- {1, 2, 3}

patch (t1, t2[, rename[, only[, exclude]]])

copies all (key, value) of t2 into t1; throws an error on key collision useful if you want to prevent collision

Parameters:

• t1 table
• t2 table
• rename table - copy values of t2 to t1 to a different index; {copy_t2_key=as_t1_key} (optional)
• only array - only copy this subset of t2 values to t1 (optional)
• exclude array - do not copy this subset of t2 values to t1 (optional)

See also:

• merge
• join

Usage:

• local a, b = {a=1}, {a=2}; patch(a, b)  -- error

• local a, b = {a=1}, {b=2, c=3}; patch(a, b)  -- {a=1, b=2, c=3}

• local a, b = {a=1}, {b=2}; patch(a, b, {b='c'})  -- {a=1, c=2}

• local a, b = {a=1}, {b=2, c=3}; patch(a, b, nil, {'c'})  -- {a=1, c=3}

• local a, b = {a=1}, {b=2, c=3}; patch(a, b, nil, nil, {'c'})  -- {a=1, b=2}

slice (t, _i, _e)

gets you an slice of the array negative indexes are not supported

Parameters:

• t array
• _i int initial position of the slice
• _e int final position of the slice

Returns:

table with only the elements of the slice

sorted (t, fn)

creates a sorted copy of t

Parameters:

• t table
• fn function (a, b) as params; same as fn in table.sort(t, fn)

Returns:

new sorted table

Usage:

sorted({4, 3})  -- {3, 4}

union (t1, t2)

creates a new array with all values of t1 and t2 keys are not preserved; order of the values is not guaranteed.

Parameters:

• t1 table
• t2 table

Returns:

new table

See also:

append

Usage:

union({3, 4}, {1, 2})  -- {3, 4, 1, 2}

values (t)

creates a new array with all values of t

Parameters:

• t table

Returns:

new table

See also:

keys

Usage:

• values({3,4,5})  -- {3, 4, 5}

• values({a=1, b=2, c=3})  -- {1, 2, 3}