Module pl.tablex
Extended operations on Lua tables.
See the Guide
Dependencies: pl.utils , pl.types
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, clearing dest after idest+nsrc, 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. |
sort (t, f) | return an iterator to a table sorted by its keys |
sortv (t, f) | return an iterator to a table sorted by its values |
readonly (t) | modifies a table to be read only. |
Functions
- update (t1, t2)
-
copy a table into another, in-place.
Parameters:
- t1 destination table
- t2 source (any iterable object)
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. Works for any object with a __pairs metamethod.Parameters:
- t a table
Returns:
-
the size
- copy (t)
-
make a shallow copy of a table
Parameters:
- t an iterable source
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)
Returns:
-
index of value or nil if not found
Usage:
find({10,20,30},20) == 2
find({'a','b','a','c'},'a',2) == 3
- 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)
Returns:
-
index of value or nil if not found
Usage:
rfind({10,10,10},10) == 3
- 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)
Returns:
-
a list-like table
Usage:
index_by({10,20,30,40},{2,4}) == {20,40}
index_by({one=1,two=2,three=3},{'one','three'}) == {1,3}
- 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
Returns:
-
a list-like table
Usage:
imap(function(v) return v*v end, {10,20,30,fred=2}) is {100,400,900}
- 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
Returns:
-
a table
Usage:
map2('+',{1,2,3,m=4},{10,20,30,m=40}) is {11,22,23,m=44}
- imap2 (fun, t1, t2, ...)
-
apply a function to values from two arrays.
The result will be the length of the shortest array.
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
Returns:
-
the result of the function
Usage:
reduce('+',{1,2,3,4}) == 10
- 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(function(k,v) return v end,{fred=10,bonzo=20}) is {10,20} _or_ {20,10}
pairmap(function(k,v) return {k,v},k end,{one=1,two=2}) 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.
See also:
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}
- 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)
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
See also:
- filter (t, pred, arg)
-
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
- 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}}
- icopy (dest, src, idest, isrc, nsrc)
-
copy an array into another one, clearing dest after idest+nsrc, if necessary.
Parameters:
- dest a list-like table
- src a list-like table
- idest where to start copying values into destination (default 1)
- isrc where to start copying values from source (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 into destination (default 1)
- isrc where to start copying values from source (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
Returns:
-
a fieldspec, e.g. 'a.b' or 'math.sin'
Usage:
search(_G,math.sin,{package.path}) == 'math.sin'
- sort (t, f)
-
return an iterator to a table sorted by its keys
Parameters:
- t the table
- f an optional comparison function (f(x,y) is true if x < y)
Returns:
-
an iterator to traverse elements sorted by the keys
Usage:
for k,v in tablex.sort(t) do print(k,v) end
- sortv (t, f)
-
return an iterator to a table sorted by its values
Parameters:
- t the table
- f an optional comparison function (f(x,y) is true if x < y)
Returns:
-
an iterator to traverse elements sorted by the values
Usage:
for k,v in tablex.sortv(t) do print(k,v) end
- readonly (t)
-
modifies a table to be read only.
This only offers weak protection. Tables can still be modified with
table.insert and rawset.
Parameters:
- t the table
Returns:
-
the table read only.