Module `tablex`

A module that contains many helpful table extensions.

Functions

copy (t, copy_meta)	Performs a shallow-copy of the given table, optionally copying the input table's metatable.
deepcopy (t)	Performs a deep copy of the given table, recursively copying all keys and values.
sort (t, func)	Sorts a table, and then returns the new table.
isempty (t)	Returns whether or not the given table is empty (i.e.
size (t)	Get the size of the table (the number of keys with non-nil values in the table).
keys (t)	Returns a list of the keys in a table.
values (t)	Returns a list of the values in a table.
clear (t)	Clears the input table.
update (t, u)	Copy one table into another, in-place.
range (start, fin, step)	Generate a table of all numbers in a range.
transpose (t)	Transpose the table, swapping keys and values.
compare (t, t2, cmp)	Compare two tables using a given comparison function.
comparei (t, t2, cmp)	Compare two list-like tables using a given comparison function.
compare_unordered (t, t2, cmp)	Compare two list-like tables using a given comparison function, without caring about element order.
find (t, val, start)	Returns the index of the first value in a list-like table.
rfind (t, val, start)	Returns the index of the last value in a list-like table.
map (t, func, ...)	Apply a function to all values of a table, returning a table of the results.
mapi (t, func, ...)	Apply a function to all values in a list-like table, returning a list-like table of the results.
transform (t, func, ...)	Apply a function to all values of a table, modifying the table in-place.
mapn (func, ...)	Apply a function to any number of list-like tables, returning a list-like table containing the results.
reduce (t, func, initial)	Apply a function that takes two arguments to all elements in a list-like table, from left to right.
zip (t, t2)	Return a list-like table of list-like tables, such that each sub-table contains the i-th element from the two input values.
zipn (t, ...)	Return a list-like table of list-like tables, such that each sub-table contains the i-th element from the each of the input values.
sub (t, start, fin)	Extract a range of values from a list-like table.
delete_if (t, func)	This function deletes every key-value pair from the given table for which the provided function returns true.
reject (t, func)	This function performs the same operation as delete_if, except it does not modify the original table and instead returns a copy.
keep_if (t, func)	This function deletes every key-value pair from the given table for which the provided function returns a non-true value.
select (t, func)	This function performs the same operation as keep_if, except that it returns a new table and does not modify the original.
any (t, func)	This function passes each key/value pair in the given table to func, and will return true if the block ever returns a truthy value.
all (t, func)	This function passes each key/value pair in the given table to func, and will return true if the block returns a truthy value for all key/value pairs.
detect (t, func)	This function wll pass every key/value pair in the table to the given function, and will return the first pair for which the function returns a non-falsy value.
drop_while (t, func)	Removes elements from the given list-like table up to, but not including, the first element for which func(k, v) returns a falsy value.
group_by (t, func)	Groups the given table by the return value of the given function.
max (t, func)	This function will find the largest value in a table, comparing using the given function.
partition (t, func)	This function will pass each key/value pair in a table to a given function, and then return two tables: one which contains the key/value pairs for which the function returned true, and a table of the ones that returned false.
partitioni (t, func)	This function will pass each index/value pair in a list-like table to a given function, and then return two tables: one which contains the values for which the function returned true, and a table of the ones that returned false.
flatten (t, level)	Given a list-like table, will return a new list-like table that is flattened by the given level.
shuffle (t)	This function will randomly shuffle the given list-like table in-place, and then return the table.
patch (mod)	Adds all the functions in this module to the specified table.

Tables

table_methods

This table stores all functions that take a table as their first argument.

Functions

copy (t, copy_meta)

Performs a shallow-copy of the given table, optionally copying the input table's metatable.

Parameters:

t The table to copy
copy_meta Whether or not to copy the input table's metatable. Defaults to false.

Returns:

A copy of t.

deepcopy (t)

Performs a deep copy of the given table, recursively copying all keys and values. Will also update the new table's metatable to the original tables'.

Parameters:

t The table to copy

Returns:

A deep copy of t.

sort (t, func)

Sorts a table, and then returns the new table. Useful for chaining. Note that this operation will sort the original table - i.e. it does not return a copy of the table.

Parameters:

t The table to sort
func A comparator function

Returns:

A sorted version of t

isempty (t)

Returns whether or not the given table is empty (i.e. whether there are any keys in the table with non-nil values).

Parameters:

t The table to check

Returns:

A boolean value indicating whether the table is empty

size (t)

Get the size of the table (the number of keys with non-nil values in the table). Note that this is also alised as length() and count().

Parameters:

t The table to check

Returns:

An integer that represents the size of the table

keys (t)

Returns a list of the keys in a table.

Parameters:

t The table

Returns:

The input table, cleared

values (t)

Returns a list of the values in a table.

Parameters:

t The table

Returns:

A list-like table representing the values found in t

clear (t)

Clears the input table.

Parameters:

t The table to clear

Returns:

The original table passed in, which is now empty

update (t, u)

Copy one table into another, in-place.

Parameters:

t The table to copy into
u The table to copy from

Returns:

The original table t

range (start, fin, step)

Generate a table of all numbers in a range.

Parameters:

start The start index
fin The number to end at
step The step size, which can be negative (default: 1)

Returns:

A list-like table of numbers

transpose (t)

Transpose the table, swapping keys and values.

Parameters:

t The table to transpose

Returns:

A copy of the table, with the keys and values transposes

compare (t, t2, cmp)

Compare two tables using a given comparison function.

Parameters:

t The table to compare
t2 The table to compare against
cmp The comparison function. Should return a truthy value of two table values are equal.

Returns:

A boolean indicating whether the two tables are equal.

comparei (t, t2, cmp)

Compare two list-like tables using a given comparison function.

Parameters:

t The list-like table to compare
t2 The list-like table to compare against
cmp The comparison function. Should return a truthy value of two table values are equal.

Returns:

A boolean indicating whether the two tables are equal.

compare_unordered (t, t2, cmp)

Compare two list-like tables using a given comparison function, without caring about element order.

Parameters:

t The list-like table to compare
t2 The list-like table to compare against
cmp The comparison function. Should return a truthy value of two table values are equal.

Returns:

A boolean indicating whether the two tables are equal.

find (t, val, start)

Returns the index of the first value in a list-like table.

Parameters:

t The list-like table to search
val The value to search for
start The starting index to search at. Negative indexes are taken from the end of the list (defaults to 1).

Returns:

An integer index if found, or nil otherwise

rfind (t, val, start)

Returns the index of the last value in a list-like table.

Parameters:

t The list-like table to search
val The value to search for
start The starting index to search at. Negative indexes are taken from the end of the list (defaults to 1).

Returns:

An integer index if found, or nil otherwise

map (t, func, ...)

Apply a function to all values of a table, returning a table of the results. This function will copy the metatable of the input table to the output.

Parameters:

t The table
func A function that takes 1 or more arguments
... Any additional arguments to pass to the function

Returns:

A table containing the results of applying func(t[value], ...) for all values in t.

mapi (t, func, ...)

Apply a function to all values in a list-like table, returning a list-like table of the results.

Parameters:

t The list-like table
func A function that takes 1 or more arguments
... Any additional arguments to pass to the function

Returns:

A list-like table containing the results of applying func(t[value], ...) for all values in t.

transform (t, func, ...)

Apply a function to all values of a table, modifying the table in-place. This is the same as the map() function, except it operates in-place.

Parameters:

t The table
func A function that takes 1 or more arguments
... Any additional arguments to pass to the function

Returns:

The original table, t

Parameters:

func A function that takes a number of arguments equal to the number of tables that were passed in.
... Any number of tables passed.

Returns:

A table containing the results of applying func(t1[i], t2[i], ...) for all i.

reduce (t, func, initial)

Apply a function that takes two arguments to all elements in a list-like table, from left to right. This reduces the sequence to a single value. If the 'initial' parameter is given, then it will also act as the default value if the sequence is empty. Otherwise, if the sequence is empty and no initial value is given, this function will return nil. Note: this function is aliased as "foldl".

Parameters:

t The table
func A function that takes two arguments and returns a single value
initial (optional) The initial value to use. If present, this is placed "before" the other elements in the sequence

Returns:

The result of the reduce operation.

zip (t, t2)

Return a list-like table of list-like tables, such that each sub-table contains the i-th element from the two input values. For example, zip({1,2,3}, {4,5,6}) == {{1,4}, {2,5}, {3,6}}

Parameters:

t The first table
t2 The second table

Returns:

The zipped table, as above.

zipn (t, ...)

Return a list-like table of list-like tables, such that each sub-table contains the i-th element from the each of the input values. For example, zip({1,2,3}, {4,5,6}) == {{1,4}, {2,5}, {3,6}}. Note that this function is less efficient on two values than zip().

Parameters:

t The first table
... Any number of additional tables to zip.

Returns:

The zipped table, as above.

sub (t, start, fin)

Extract a range of values from a list-like table.

Parameters:

t A list-like table
start If given, the start index. Defaults to 1, negative indexes are from the end of the table.
fin If given, the end index. Defaults to #t, negative indexes are from the end of the table.

Returns:

A list-like table with the contents of the specified slice.

delete_if (t, func)

This function deletes every key-value pair from the given table for which the provided function returns true.

Parameters:

t The table to delete from
func A function that is passed the key and value, and should return true if the pair is to be deleted, or false otherwise

Returns:

The original table

reject (t, func)

This function performs the same operation as delete_if, except it does not modify the original table and instead returns a copy.

Parameters:

t The table to delete from
func A function that is passed the key and value, and should return true if the pair is to be deleted, or false otherwise

Returns:

A new table that contains all values for which func(k, v) did not return true.

Parameters:

t The table to process
func A function that is passed the key and value, and should return true if the pair is to be kept, or false otherwise

Returns:

The original table

select (t, func)

This function performs the same operation as keep_if, except that it returns a new table and does not modify the original.

Parameters:

t The table to process
func A function that is passed the key and value, and should return true if the pair is to be kept, or false otherwise

Returns:

A new table that contains all values for which func(k, v) returned true

Parameters:

t The table to test
func A function that receives all key/value pairs

Returns:

A boolean value which represents whether the given function ever returned a truthy value.

all (t, func)

This function passes each key/value pair in the given table to func, and will return true if the block returns a truthy value for all key/value pairs. If func is not given, then the implementation will default to function(k, v) return v end - i.e. will test the truthiness of the values.

Parameters:

t The table to test
func A function that receives all key/value pairs

Returns:

A boolean value which represents whether the given function returns a truthy value for all k/v pairs.

detect (t, func)

This function wll pass every key/value pair in the table to the given function, and will return the first pair for which the function returns a non-falsy value.

Parameters:

t The table to search
func A function that will receive key/value pairs

Returns:

The first k, v for which func(k, v) returns a non-falsy value, or nil if no non-falsy value was returned

drop_while (t, func)

Removes elements from the given list-like table up to, but not including, the first element for which func(k, v) returns a falsy value.

Parameters:

t The table to process
func A function that receives key/value pairs, and returns a single value

Returns:

A new list-like table with all elements including and after the first element for which func(k, v) returns a falsy value

group_by (t, func)

Groups the given table by the return value of the given function. The returned table will have keys that are the results of func(i, v), and values as a list-like table with the corresponding values.

Parameters:

t The table to group
func A function that takes an index/value pair and should return a single value.

Returns:

A table, with keys that are the results of func(i, v), and values that are list-like tables containing all values.

max (t, func)

This function will find the largest value in a table, comparing using the given function. If not given, a function that performs "v1 < v2" will be used instead.

Parameters:

t The table to search
func The comparison function, receives (key1, val1, key2, val2), and should return a boolean

Returns:

max_key, max_val, which are the maximum values found in the input table, or nil, nil if the table is empty

partition (t, func)

This function will pass each key/value pair in a table to a given function, and then return two tables: one which contains the key/value pairs for which the function returned true, and a table of the ones that returned false.

Parameters:

t The table to partition
func The partitioning function - called with func(k, v), and should return a boolean

Returns:

Two tables, which contain the {key, value} pairs for which the function returned true and false

partitioni (t, func)

This function will pass each index/value pair in a list-like table to a given function, and then return two tables: one which contains the values for which the function returned true, and a table of the ones that returned false.

Parameters:

t The table to partition
func The partitioning function - called with func(i, v), and should return a boolean

Returns:

Two tables, which contain the values for which the function returned true and false

flatten (t, level)

Given a list-like table, will return a new list-like table that is flattened by the given level. That is to say, for every value that is a list-like table, extract it's elements into the new list, to the recursive depth specified.

Parameters:

t The list-like table to flatten
level The level to flatten to. Use math.huge to represent "flatten everything"

Returns:

A new list-like table that has been flattened.

shuffle (t)

This function will randomly shuffle the given list-like table in-place, and then return the table.

Parameters:

t The list-like table to shuffle

Returns:

The input table, shuffled

patch (mod)

Adds all the functions in this module to the specified table. Note that we default to the 'table' table, and we exclude this function itself.

Parameters:

mod If given, the module to patch these functions into. Defaults to the table module.

Tables

table_methods

This table stores all functions that take a table as their first argument. This is particularly useful if you want to set a metatable on a table so that you can call functions like: tbl:copy(), as opposed to table.copy(tbl)

Fields:

copy
deepcopy
sort
isempty
size
keys
values
clear
update
transpose
compare
comparei
compare_unordered
find
rfind
map
mapi
transform
reduce
zip
normalize_slice
sub
delete_if
reject
keep_if
select
any
all
detect
drop_while
group_by
max
partition
partitioni
flatten
shuffle

ldoc

Contents

Modules

Module tablex

Functions

Tables

Functions

Parameters:

Returns:

Parameters:

Returns:

Parameters:

Returns:

Parameters:

Returns:

Parameters:

Returns:

Parameters:

Returns:

Parameters:

Returns:

Parameters:

Returns:

Parameters:

Returns:

Parameters:

Returns:

Parameters:

Returns:

Parameters:

Returns:

Parameters:

Returns:

Parameters:

Returns:

Parameters:

Returns:

Parameters:

Returns:

Parameters:

Returns:

Parameters:

Returns:

Parameters:

Returns:

see also:

Parameters:

Returns:

Parameters:

Returns:

Parameters:

Returns:

Parameters:

Returns:

Parameters:

Returns:

Parameters:

Returns:

Parameters:

Returns:

see also:

Parameters:

Returns:

Parameters:

Returns:

see also:

Parameters:

Returns:

Parameters:

Returns:

Parameters:

Returns:

Parameters:

Returns:

Parameters:

Returns:

Parameters:

Returns:

Parameters:

Returns:

Module `tablex`