Module pl.tablex

useful operations on Lua tables

Functions

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.
deepcompare (t1, t2) compare two values.
deepcopy (t) make a deep copy of a table, recursively copying all the keys and fields.
filter (t, pred) filter a table's values using a predicate function
find (t, val) 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.
imap (fun, t, ...) apply a function to all values of a list.
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.
keys (t) return all the keys of a table in arbitrary order.
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.
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.
set (t) create a set from a list-like table.
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

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
deepcompare (t1, t2)
compare two values. if they are tables, then compare their keys and fields recursively.

Parameters:

  • t1: A value
  • t2: A value
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
filter (t, pred)
filter a table's values using a predicate function

Parameters:

  • t: a list-like table
  • pred: a boolean function
find (t, val)
return the index of a value in a list.

Parameters:

  • t: A list-like table (i.e. with numerical indices)
  • val: A value

Usage:

    index({10,20,30},20) is 2

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:

  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

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
  • ...:
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 list-like table
  • ...:

Usage:

    imap({10,20,30,fred=2},function(v) return v*v end) is {100,400,900}
index_by (tbl, idx)
return a list of all values in a table indexed by another list.

Parameters:

  • tbl: a list-like table
  • idx: an index table (a list of indices)

Usage:

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

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
keys (t)
return all the keys of a table in arbitrary order.

Parameters:

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

See also:

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
set (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
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!