Module pl.tablex
Extended operations on Lua tables.
See ???
Dependencies: `pl.utils`, `pl.types`
| size (t) |
total number of elements in this table. |
| index_by (tbl) |
return a list of all values in a table indexed by another list. |
| transform (fun, t, ...) |
apply a function to all values of a table, in-place. |
| range (start, finish[, step=1]) |
generate a table of all numbers in a range. |
| reduce (fun) |
'reduce' a list using a binary function. |
| index_map (t) |
create an index map from a list-like table. |
| makeset (t) |
create a set from a list-like table. |
| union (t1, t2) |
the union of two map-like tables. |
| intersection (t1, t2) |
the intersection of two map-like tables. |
| count_map (cmp) |
A table where the key/values are the values and value counts of the table. |
| set (val[, i1=1[, i2=#t]]) |
set an array range to a value. |
| new (n, val) |
create a new array of specified size with initial value. |
| clear (istart) |
clear out the contents of a table. |
| removevalues (i1, i2) |
remove a range of values from a table. |
| readonly (t) |
modifies a table to be read only. |
| map (fun, t, ...) |
apply a function to all values of a table. |
| imap (fun, ...) |
apply a function to all values of a list. |
| map_named_method (name, ...) |
apply a named method to values from a table. |
| map2 (fun, t1, t2, ...) |
apply a function to values from two tables. |
| imap2 (fun, ...) |
apply a function to values from two arrays. |
| 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. |
| filter (pred, arg) |
filter an array's values using a predicate function |
| keys (t) |
return all the keys of a table in arbitrary order. |
| values (t) |
return all the values of the table in arbitrary order |
| sub (first, last) |
Extract a range from a table, like 'string.sub'. |
-
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:
Returns:
the size
-
index_by (tbl)
-
return a list of all values in a table indexed by another list.
Parameters:
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}
-
transform (fun, t, ...)
-
apply a function to all values of a table, in-place.
Any extra arguments are passed to the function.
Parameters:
- fun
func
A function that takes at least one argument
- t
tab
a table
- ...
extra arguments passed to `fun`
See also:
-
range (start, finish[, step=1])
-
generate a table of all numbers in a range.
This is consistent with a numerical for loop.
Parameters:
- start
int
number
- finish
int
number
- step
int
make this negative for start < finish
(default 1)
-
reduce (fun)
-
'reduce' a list using a binary function.
Parameters:
- fun
func
a function of two arguments
Returns:
the result of the function
Usage:
reduce('+',{1,2,3,4}) == 10
-
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:
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:
Returns:
a set (a map-like table)
-
union (t1, t2)
-
the union of two map-like tables.
If there are duplicate keys, the second table wins.
Parameters:
- t1
tab
a table
- t2
tab
a table
Returns:
tab
See also:
-
intersection (t1, t2)
-
the intersection of two map-like tables.
Parameters:
- t1
tab
a table
- t2
tab
a table
Returns:
tab
See also:
-
count_map (cmp)
-
A table where the key/values are the values and value counts of the table.
Parameters:
- cmp
func
a function that defines equality (otherwise uses ==)
Returns:
a map-like table
See also:
-
set (val[, i1=1[, i2=#t]])
-
set an array range to a value. If it's a function we use the result
of applying it to the indices.
Parameters:
- val
a value
- i1
int
start range
(default 1)
- i2
int
end range
(default #t)
-
new (n, val)
-
create a new array of specified size with initial value.
Parameters:
- n
int
size
- val
initial value (can be `nil`, but don't expect `#` to work!)
Returns:
the table
-
clear (istart)
-
clear out the contents of a table.
Parameters:
- istart
optional start position
-
removevalues (i1, i2)
-
remove a range of values from a table.
End of range may be negative.
Parameters:
- i1
int
start index
- i2
int
end index
Returns:
the table
-
readonly (t)
-
modifies a table to be read only.
This only offers weak protection. Tables can still be modified with
`table.insert` and `rawset`.
*NOTE*: for Lua 5.1 length, pairs and ipairs will not work, since the
equivalent metamethods are only available in Lua 5.2 and newer.
Parameters:
Returns:
the table read only (a proxy).
-
update (t1, t2)
-
copy a table into another, in-place.
Parameters:
- t1
tab
destination table
- t2
tab
source (actually any iterable object)
Returns:
first table
-
copy (t)
-
make a shallow copy of a table
Parameters:
Returns:
new table
-
deepcopy (t)
-
make a deep copy of a table, recursively copying all the keys and fields.
This supports cycles in tables; cycles will be reproduced in the copy.
This will also set the copied table's metatable to that of the original.
Parameters:
Returns:
new table
-
icopy ([idest=1[, isrc=1[, nsrc=#src]]])
-
copy an array into another one, clearing `dest` after `idest+nsrc`, if necessary.
Parameters:
- idest
int
where to start copying values into destination
(default 1)
- isrc
int
where to start copying values from source
(default 1)
- nsrc
int
number of elements to copy from source
(default #src)
-
move ([idest=1[, isrc=1[, nsrc=#src]]])
-
copy an array into another one.
Parameters:
- idest
int
where to start copying values into destination
(default 1)
- isrc
int
where to start copying values from source
(default 1)
- nsrc
int
number of elements to copy from source
(default #src)
-
insertvalues ([position])
-
insert values into a table.
similar to `table.insert` but inserts values from given table `values`,
not the object itself, into table `t` at position `pos`.
Parameters:
- position
int
(default is at end)
(optional)
-
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
bool
if true, ignore __eq metamethod (default false)
(optional)
- eps
number
if defined, then used for any number comparisons
(optional)
Returns:
true or false
-
compare (cmp)
-
compare two arrays using a predicate.
Parameters:
- cmp
func
A comparison function; `bool = cmp(t1_value, t2_value)`
Returns:
true or false
Usage:
assert(tablex.compare({ 1, 2, 3 }, { 1, 2, 3 }, "=="))
assert(tablex.compare(
{1,2,3, hello = "world"}, {1,2,3}, function(v1, v2) return v1 == v2 end)
-
compare_no_order (cmp)
-
compare two list-like tables using an optional predicate, without regard for element order.
Parameters:
- cmp
A comparison function (may be nil)
-
find (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:
- val
A value
- idx
int
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) == 2find({'a','b','a','c'},'a',2) == 3
-
rfind (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:
- val
A value
- idx
index to start; -1 means last element,etc (default `#t`)
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.
*NOTE*: the 2nd return value of this function, the value returned
by the comparison function, has a limitation that it cannot be `false`.
Because if it is, then it indicates the comparison failed, and the
function will continue the search. See examples.
Parameters:
- t
tab
A table
- cmp
func
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 (cannot be `false`!)
Usage:
local lst = { "Rudolph", true, false, 15 }
local idx, cmp_result = tablex.rfind(lst, "==", "Rudolph")
assert(idx == 1)
assert(cmp_result == true)
local idx, cmp_result = tablex.rfind(lst, "==", false)
assert(idx == 3)
assert(cmp_result == true)
local cmp = function(v1, v2) return v1 == v2 and v2 end
local idx, cmp_result = tablex.rfind(lst, cmp, "Rudolph")
assert(idx == 1)
assert(cmp_result == "Rudolph")
local idx, cmp_result = tablex.rfind(lst, cmp, false)
assert(idx == nil) assert(cmp_result == nil)
-
search (t, value)
-
find a value in a table by recursive search.
Parameters:
- t
tab
the table
- value
the value
Returns:
a fieldspec, e.g. 'a.b' or 'math.sin'
Usage:
search(_G,math.sin,{package.path}) == 'math.sin'
-
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
func
A function that takes at least one argument
- t
tab
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, ...)
-
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
func
A function that takes at least one argument
- ...
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, ...)
-
apply a named method to values from a table.
Parameters:
- name
string
the method name
- ...
any extra arguments to the method
Returns:
a `List` with the results of the method (1st result only)
Usage:
local Car = {}
Car.__index = Car
function Car.new(car)
return setmetatable(car or {}, Car)
end
Car.speed = 0
function Car:faster(increase)
self.speed = self.speed + increase
return self.speed
end
local ferrari = Car.new{ name = "Ferrari" }
local lamborghini = Car.new{ name = "Lamborghini", speed = 50 }
local cars = { ferrari, lamborghini }
assert(ferrari.speed == 0)
assert(lamborghini.speed == 50)
tablex.map_named_method("faster", cars, 10)
assert(ferrari.speed == 10)
assert(lamborghini.speed == 60)
-
map2 (fun, t1, t2, ...)
-
apply a function to values from two tables.
Parameters:
- fun
func
a function of at least two arguments
- t1
tab
a table
- t2
tab
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, ...)
-
apply a function to values from two arrays.
The result will be the length of the shortest array.
Parameters:
- fun
func
a function of at least two arguments
- ...
extra arguments
Usage:
imap2('+',{1,2,3,m=4},{10,20,30,m=40}) is {11,22,23}
-
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
- ...
tab
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 the key already exists, we convert the value for that
key into a table and append into it. If only value is not nil, then it is appended to the result.
Parameters:
- fun
func
A function which will be passed each key and value as arguments, plus any extra arguments to pairmap.
- t
tab
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}}
-
filter (pred, arg)
-
filter an array's values using a predicate function
Parameters:
- pred
func
a boolean function
- arg
optional argument to be passed as second argument of the predicate
-
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
tab
a table
- fun
func
a function on the elements; `function(value, key, ...)`
- ...
extra arguments passed to `fun`
See also:
-
foreachi (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:
- fun
func
a function with at least one argument
- ...
optional arguments
-
sort (t, f)
-
return an iterator to a table sorted by its keys
Parameters:
- t
tab
the table
- f
func
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
tab
the table
- f
func
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
-
keys (t)
-
return all the keys of a table in arbitrary order.
Parameters:
- t
tab
A list-like table where the values are the keys of the input table
-
values (t)
-
return all the values of the table in arbitrary order
Parameters:
- t
tab
A list-like table where the values are the values of the input table
-
sub (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:
- first
int
An index
- last
int
An index
Returns:
a new List
-
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
tab
a table
- t2
tab
a table
- dup
bool
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
tab
a map-like table or set
- s2
tab
a map-like table or set
- symm
bool
symmetric difference (default false)
Returns:
a map-like table or set
-
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}}