Module pl.tablex

Extended operations on Lua tables

Functions

clear (t, istart) 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 list-like tables using an optional predicate, without regard for element order.
copy (t) 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) return the index of a value in a list.
find_if (t, cmp, arg) return the index (or key) of a value in a table 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.
map_named_method (name, t, ...) apply a named method to values from a table.
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.
range (start, finish, step) generate a table of all numbers in a range
reduce (fun, t) 'reduce' a list using a binary function.
removevalues (t, i1, i2) remove a range of values from a table.
rfind (t, val, idx) return the index of a value in a list, searching from the end.
search (t, value, exclude) find a value in a table by recursive search.
set (t, val, i1, i2) set an array range to a value.
size (t) total number of elements in this table.
sub (t, first, last) Extract a range from a table, like 'string.sub'.
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, istart)
clear out the contents of a table.

Parameters:

  • t: a table
  • istart:
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 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)
copy (t)
make a shallow copy of a table

Parameters:

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

See also:

deepcompare (t1, t2, ignore_mt)
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)

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

Return value:

    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

Return values:

  1. index of value, or nil if not found
  2. 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. 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
  • ...:
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(function(v) return v*v end, {10,20,30,fred=2}) is {100,400,900}

Return value:

    a list-like 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}
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}

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

Usage:

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

Return value:

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

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

See also:

move (dest, src, idest, isrc, nsrc, n)
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:
  • 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}}
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)
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

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

Return value:

    index of value or nil if not found
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'

Return value:

    a fieldspec, e.g. 'a.b' or 'math.sin'
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)
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
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

Return value:

    a new List
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
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}}

Valid XHTML 1.0!