Module `pl.tablex`

Extended operations on Lua tables

Functions

clear (t)	clear out the contents of a table.
compare (t1, t2, cmp)	compare two list-like tables using a predicate.
compare_no_order (t1, t2, cmp)	compare two tables using a predicate, without regard for element order.
copy (t, t2)	make a shallow copy of a table
count_map (t, cmp)	A table where the key/values are the values and value counts of the table.
deepcompare (t1, t2, ignore_mt)	compare two values.
deepcopy (t)	make a deep copy of a table, recursively copying all the keys and fields.
difference (s1, s2, symm)	a new table which is the difference of two tables.
filter (t, pred, arg, optional)	filter a table's values using a predicate function
find (t, val, idx, backwards)	return the index of a value in a list.
find_if (t, cmp, arg)	return the index of a value in a list using a comparison function.
foreach (t, fun, ...)	apply a function to all elements of a table.
foreachi (t, fun, ...)	apply a function to all elements of a list-like table in order.
icopy (dest, src, idest, isrc, nsrc, n)	copy an array into another one, resizing the destination if necessary.
imap (fun, t, ...)	apply a function to all values of a list.
imap2 (fun, t1, t2, ...)	apply a function to values from two arrays.
index_by (tbl, idx)	return a list of all values in a table indexed by another list.
index_map (t)	create an index map from a list-like table.
insertvalues (t, ...)	insert values into a table.
keys (t)	return all the keys of a table in arbitrary order.
makeset (t)	create a set from a list-like table.
map (fun, t, ...)	apply a function to all values of a table.
map2 (fun, t1, t2, ...)	apply a function to values from two tables.
mapn (fun, ...)	Apply a function to a number of tables.
merge (t1, t2, dup)	combine two tables, either as union or intersection.
move (dest, src, idest, isrc, nsrc, n)	copy an array into another one.
new (n, val)	create a new array of specified size with initial value.
pairmap (fun, t, ...)	call the function with the key and value pairs from a table.
reduce (fun, t)	'reduce' a table using a binary function.
removevalues (t, i1, i2)	remove a range of values from a table.
set (t, val, i1, i2)	set an array range to a value.
size (t)	total number of elements in this table.
transform (fun, t, ...)	apply a function to all values of a table, in-place.
update (t1, t2)	copy a table into another, in-place.
values (t)	return all the values of the table in arbitrary order
zip (...)	return a table where each element is a table of the ith values of an arbitrary number of tables.

Functions

clear (t)

clear out the contents of a table.

Parameters:

t: a table

compare (t1, t2, cmp)

compare two list-like tables using a predicate.

Parameters:

t1: a table
t2: a table
cmp: A comparison function

compare_no_order (t1, t2, cmp)

compare two tables using a predicate, without regard for element order.

Parameters:

t1: a table
t2: a table
cmp: A comparison function

copy (t, t2)

make a shallow copy of a table

Parameters:

t: source table
t2: source table

Return value:

new table

count_map (t, cmp)

A table where the key/values are the values and value counts of the table.

Parameters:

t: a list-like table
cmp: a function that defines equality (otherwise uses ==)

Return value:

a map-like table

Parameters:

t1: A value
t2: A value
ignore_mt: if true, ignore __eq metamethod (default false)

Return value:

true or false

deepcopy (t)

make a deep copy of a table, recursively copying all the keys and fields. This will also set the copied table's metatable to that of the original.

Parameters:

t: A table

Return value:

new table

difference (s1, s2, symm)

a new table which is the difference of two tables. With sets (where the values are all true) this is set difference and symmetric difference depending on the third parameter.

Parameters:

s1: a map-like table or set
s2: a map-like table or set
symm: symmetric difference (default false)

Return value:

a map-like table or set

filter (t, pred, arg, optional)

filter a table's values using a predicate function

Parameters:

t: a list-like table
pred: a boolean function
arg:
optional: argument to be passed as second argument of the predicate

find (t, val, idx, backwards)

return the index of a value in a list.
Like string.find, there is an optional index to start searching, which can be negative.

Parameters:

t: A list-like table (i.e. with numerical indices)
val: A value
idx: index to start; -1 means last element,etc (default 1)
backwards: search back from the end

Usage:

```
find({10,20,30},20) == 2
```
```
find({'a','b','a','c'},'a',2) == 3
```
```
find({10,10,10},10,nil,true) == 3
```

Return value:

index of value or nil if not found

find_if (t, cmp, arg)

return the index of a value in a list using a comparison function.

Parameters:

t: A list-like table (i.e. with numerical indices)
cmp: A comparison function
arg: an optional second argument to the function

Return values:

index of value, or nil if not found
value returned by comparison function

foreach (t, fun, ...)

apply a function to all elements of a table. The arguments to the function will be the value, the key and finally any extra arguments passed to this function

Parameters:

t: a table
fun: a function with at least one argument
...:

foreachi (t, fun, ...)

apply a function to all elements of a list-like table in order. The arguments to the function will be the value, the index and finally any extra arguments passed to this function

Parameters:

t: a table
fun: a function with at least one argument
...:

icopy (dest, src, idest, isrc, nsrc, n)

copy an array into another one, resizing the destination if necessary.

Parameters:

dest: a list-like table
src: a list-like table
idest: where to start copying values from source (default 1)
isrc: where to start copying values into destination (default 1)
nsrc:
n: number of elements to copy from source (default source size)

imap (fun, t, ...)

apply a function to all values of a list. This returns a table of the results. Any extra arguments are passed to the function.

Parameters:

fun: A function that takes at least one argument
t: a table (applies to array part)
...:

Usage:

imap({10,20,30,fred=2},function(v) return v*v end) is {100,400,900}

imap2 (fun, t1, t2, ...)

apply a function to values from two arrays.

Parameters:

fun: a function of at least two arguments
t1: a list-like table
t2: a list-like table
...:

index_by (tbl, idx)

return a list of all values in a table indexed by another list.

Parameters:

tbl: a table
idx: an index table (a list of kyes)

Usage:

index_by({10,20,30,40},{2,4}) == {20,40}

index_by({one=1,two=2,three=3},{'one','three'}) == {1,3}

Return value:

a list-like table

index_map (t)

create an index map from a list-like table. The original values become keys, and the associated values are the indices into the original list.

Parameters:

t: a list-like table

Return value:

a map-like table

insertvalues (t, ...)

insert values into a table.
insertvalues(t, [pos,] values)
similar to table.insert but inserts values from given table "values", not the object itself, into table "t" at position "pos".

Parameters:

t:
...:

keys (t)

return all the keys of a table in arbitrary order.

Parameters:

t: A table

makeset (t)

create a set from a list-like table. A set is a table where the original values become keys, and the associated values are all true.

Parameters:

t: a list-like table

Return value:

a set (a map-like table)

map (fun, t, ...)

apply a function to all values of a table. This returns a table of the results. Any extra arguments are passed to the function.

Parameters:

fun: A function that takes at least one argument
t: A table
...:

Usage:

map(function(v) return v*v end, {10,20,30,fred=2}) is {100,400,900,fred=4}

map2 (fun, t1, t2, ...)

apply a function to values from two tables.

Parameters:

fun: a function of at least two arguments
t1: a table
t2: a table
...:

mapn (fun, ...)

Apply a function to a number of tables. A more general version of map The result is a table containing the result of applying that function to the ith value of each table. Length of output list is the minimum length of all the lists

Parameters:

fun: A function that takes as many arguments as there are tables
...:

Usage:

mapn(function(x,y,z) return x+y+z end, {1,2,3},{10,20,30},{100,200,300}) is {111,222,333}

mapn(math.max, {1,20,300},{10,2,3},{100,200,100}) is	{100,200,300}

merge (t1, t2, dup)

combine two tables, either as union or intersection. Corresponds to set operations for sets () but more general. Not particularly useful for list-like tables.

Parameters:

t1: a table
t2: a table
dup: true for a union, false for an intersection.

Usage:

tablex.merge({alice=23,fred=34},{bob=25,fred=34}) is {fred=34}

tablex.merge({alice=23,fred=34},{bob=25,fred=34},true) is {bob=25,fred=34,alice=23}

Parameters:

dest: a list-like table
src: a list-like table
idest: where to start copying values from source (default 1)
isrc: where to start copying values into destination (default 1)
nsrc:
n: number of elements to copy from source (default source size)

new (n, val)

create a new array of specified size with initial value.

Parameters:

n: size
val: initial value (can be nil, but don't expect # to work!)

Return value:

the table

pairmap (fun, t, ...)

call the function with the key and value pairs from a table. The function can return a value and a key (note the order!). If both are not nil, then this pair is inserted into the result. If only value is not nil, then it is appended to the result.

Parameters:

fun: A function which will be passed each key and value as arguments, plus any extra arguments to pairmap.
t: A table
...:

Usage:

pairmap({fred=10,bonzo=20},function(k,v) return v end) is {10,20}

pairmap({one=1,two=2},function(k,v) return {k,v},k end) is {one={'one',1},two={'two',2}}

reduce (fun, t)

'reduce' a table using a binary function.

Parameters:

fun: a function of two arguments
t: a list-like table

Usage:

reduce('+',{1,2,3,4}) == 10

Return value:

the result of the function

removevalues (t, i1, i2)

remove a range of values from a table.

Parameters:

t: a list-like table
i1: start index
i2: end index

Return value:

the table

set (t, val, i1, i2)

set an array range to a value.

Parameters:

t: a list-like table
val: a value
i1: start range (default 1)
i2: end range (default table size)

size (t)

total number of elements in this table.
Note that this is distinct from #t, which is the number of values in the array part; this value will always be greater or equal. The difference gives the size of the hash part, for practical purposes.

Parameters:

t: a table

Return value:

the size

transform (fun, t, ...)

apply a function to all values of a table, in-place. Any extra arguments are passed to the function.

Parameters:

fun: A function that takes at least one argument
t: a table
...:

update (t1, t2)

copy a table into another, in-place.

Parameters:

t1: destination table
t2: source table

Return value:

first table

values (t)

return all the values of the table in arbitrary order

Parameters:

t: A table

zip (...)

return a table where each element is a table of the ith values of an arbitrary number of tables. It is equivalent to a matrix transpose.

Parameters:

...:

Usage:

zip({10,20,30},{100,200,300}) is {{10,100},{20,200},{30,300}}

LuaDoc

Modules

Module pl.tablex

Functions

Functions

Parameters:

Parameters:

Parameters:

Parameters:

Return value:

Parameters:

Return value:

See also:

Parameters:

Return value:

Parameters:

Return value:

Parameters:

Return value:

Parameters:

Parameters:

Usage:

Return value:

Parameters:

Return values:

Parameters:

Parameters:

Parameters:

Parameters:

Usage:

Parameters:

Parameters:

Usage:

Return value:

Parameters:

Return value:

Parameters:

Parameters:

Parameters:

Return value:

Parameters:

Usage:

Parameters:

Parameters:

Usage:

Parameters:

Usage:

See also:

Parameters:

Parameters:

Return value:

Parameters:

Usage:

Parameters:

Usage:

Return value:

Parameters:

Return value:

Parameters:

Parameters:

Return value:

Parameters:

Parameters:

Return value:

Parameters:

Parameters:

Usage:

Module `pl.tablex`