Module `pl.tablex`

Extended operations on Lua tables.

Dependencies: pl.utils

Functions

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

Functions

update (t1, t2)

copy a table into another, in-place.

Parameters:

t1: destination table
t2: source table

Returns:

first table

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

Returns:

the size

copy (t)

make a shallow copy of a table

Parameters:

t: source table

Returns:

new table

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

Returns:

new table

deepcompare (t1, t2, ignore_mt, eps)

compare two values. if they are tables, then compare their keys and fields recursively.

Parameters:

t1: A value
t2: A value
ignore_mt: if true, ignore __eq metamethod (default false)
eps: if defined, then used for any number comparisons

Returns:

true or false

compare (t1, t2, cmp)

compare two arrays using a predicate.

Parameters:

t1: an array
t2: an array
cmp: A comparison function

compare_no_order (t1, t2, cmp)

compare two list-like tables using an optional predicate, without regard for element order.

Parameters:

t1: a list-like table
t2: a list-like table
cmp: A comparison function (may be nil)

find (t, val, idx)

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)

Usage:

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

Returns:

index of value or nil if not found

rfind (t, val, idx)

return the index of a value in a list, searching from the end. 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)

Usage:

rfind({10,10,10},10) == 3

Returns:

index of value or nil if not found

find_if (t, cmp, arg)

return the index (or key) of a value in a table using a comparison function.

Parameters:

t: A table
cmp: A comparison function
arg: an optional second argument to the function

Returns:

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

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 keys)

Usage:

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

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

Returns:

a list-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
...: optional arguments

Usage:

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

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)
...: optional arguments

Usage:

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

Returns:

a list-like table

map_named_method (name, t, ...)

apply a named method to values from a table.

Parameters:

name: the method name
t: a list-like table
...: any extra arguments to the method

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
...: extra arguments

range (start, finish, step)

generate a table of all numbers in a range

Parameters:

start: number
finish: number
step: optional increment (default 1 for increasing, -1 for decreasing)

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
...: extra arguments

Usage:

map2('+',{1,2,3,m=4},{10,20,30,m=40}) is {11,22,23,m=44}

Returns:

a table

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
...: extra arguments

Usage:

imap2('+',{1,2,3,m=4},{10,20,30,m=40}) is {11,22,23}

reduce (fun, t)

‘reduce’ a list using a binary function.

Parameters:

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

Usage:

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

Returns:

the result of the 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. Note that the Lua 5.0 function table.foreach passed the key first.

Parameters:

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

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
...: optional arguments

mapn (fun, ..., 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
...: n tables
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}

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
...: optional arguments

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}}

keys (t)

return all the keys of a table in arbitrary order.

Parameters:

t: A table

values (t)

return all the values of the table in arbitrary order

Parameters:

t: A 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

Returns:

a map-like 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

Returns:

a set (a map-like table)

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:

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

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

Parameters:

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

Returns:

a map-like table or set

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 ==)

Returns:

a map-like table

Parameters:

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

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.

Usage:

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

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

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: number of elements to copy from source (default source size)

move (dest, src, idest, isrc, nsrc)

copy an array into another one.

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: number of elements to copy from source (default source size)

sub (t, first, last)

Extract a range from a table, like ‘string.sub’. If first or last are negative then they are relative to the end of the list eg. sub(t,-2) gives last 2 entries in a list, and sub(t,-4,-2) gives from -4th to -2nd

Parameters:

t: a list-like table
first: An index
last: An index

Returns:

a new List

set (t, val, i1, i2)

set an array range to a value. If it’s a function we use the result of applying it to the indices.

Parameters:

t: a list-like table
val: a value
i1: start range (default 1)
i2: end range (default table 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!)

Returns:

the table

clear (t, istart)

clear out the contents of a table.

Parameters:

t: a table
istart: optional start position

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:
...:

removevalues (t, i1, i2)

remove a range of values from a table.

Parameters:

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

Returns:

the table

search (t, value, exclude)

find a value in a table by recursive search.

Parameters:

t: the table
value: the value
exclude: any tables to avoid searching

Usage:

search(_G,math.sin,{package.path}) == 'math.sin'

Returns:

a fieldspec, e.g. ‘a.b’ or ‘math.sin’

Penlight

Contents

Modules

Topics

Examples

Module pl.tablex

Functions

Functions

Parameters:

Returns:

Parameters:

Returns:

Parameters:

Returns:

Parameters:

Returns:

Parameters:

Returns:

Parameters:

Parameters:

Parameters:

Usage:

Returns:

Parameters:

Usage:

Returns:

Parameters:

Returns:

Parameters:

Usage:

Returns:

Parameters:

Usage:

Parameters:

Usage:

Returns:

Parameters:

Parameters:

Parameters:

Parameters:

Usage:

Returns:

Parameters:

Usage:

Parameters:

Usage:

Returns:

Parameters:

Parameters:

Parameters:

Usage:

Parameters:

Usage:

Parameters:

Parameters:

Parameters:

Returns:

Parameters:

Returns:

Parameters:

Usage:

see also:

Parameters:

Returns:

Parameters:

Returns:

see also:

Parameters:

Usage:

Parameters:

Parameters:

Parameters:

Returns:

Parameters:

Parameters:

Returns:

Parameters:

Parameters:

Parameters:

Returns:

Module `pl.tablex`