Module:ListUtil/doc

Lua metamodule containing higher-order functions for lists.


 * : A valid Lua sequence; that is, a Lua table that contains values from only  to   for some positive integer N.
 * Examples:,  ,
 * : Function which accepts a value from a table as its first argument and the value's corresponding key as its second argument.
 * Examples: ,
 * : Predicate which accepts a value from a table as its first argument and the value's corresponding key as its second argument. Only truthiness of the return value is considered.
 * Examples: ,
 * : Function which accepts two table values.
 * Examples: ,

Most functions in this module that accept lists will invoke Lua's built-in  operator to obtain their lengths. This is problematic for list-like objects which have an  metamethod, such as , as the   metamethod does not work for Lua tables in Scribunto's current Lua version (5.1). Functions that work without invoking  are explicitly noted.

Generation

 * range (i, j, k)
 * Returns a list whose entries are the values produced by the Lua for-loop .   defaults to 1 if   and -1 otherwise if not given.


 * generate (n, f)
 * Returns.


 * array (x, ...)
 * Returns a multi-dimensional array with ranks  and all elements.

Counting

 * any (t, pr)
 * Returns true if  is true for any element of.


 * all (t, pr)
 * Returns true if  is true for all elements of.


 * none (t, pr)
 * Returns true if  is true for none of the elements of.


 * count (t, x)
 * Returns the number of elements of  that compare equal to.


 * count_if (t, pr)
 * Returns the number of elements of  that satisfy.

Searching

 * find (t, x, b = 1)
 * Returns the key-value pair of the list's first element that compares equal to, or   if none can be found, starting from the  -th element (negative indices count from the end of the table).


 * find_if (t, pr, b = 1)
 * Returns the key-value pair of the list's first element that satisfies, or   if none can be found, starting from the  -th element (negative indices count from the end of the table).


 * rfind (t, x, e = -1)
 * Returns the key-value pair of the list's last element that compares equal to, or   if none can be found, starting from the  -th element (negative indices count from the end of the table).   may be any list-like object as long as   is positive.


 * rfind_if (t, pr, e = -1)
 * Returns the key-value pair of the list's last element that satisfies, or   if none can be found, starting from the  -th element (negative indices count from the end of the table).   may be any list-like object as long as   is positive.


 * min (t, op)
 * Returns the key-value pair of the list's smallest element.  should return true if   compares less than  ; if not given, it defaults to Lua's less-than operator.


 * max (t, op)
 * Returns the key-value pair of the list's largest element.  should return true if   compares less than  ; if not given, it defaults to Lua's less-than operator.


 * minmax (t, op)
 * Returns the list's smallest and largest values. Keys of the values are not returned.  should return true if   compares less than  ; if not given, it defaults to Lua's less-than operator.

Comparison

 * equal (t1, t2)
 * Returns true if the two lists have equal sizes and their elements compare equal to each other.


 * compare (t1, t2)
 * Returns the lexicographic order between the two lists: -1 if, 1 if  , 0 if the two lists compare equal. Element-wise comparison is done using Lua's less-than operator.


 * equality_mixin 
 * Returns a metatable where the  metamethod wraps equal, such that lists using this metatable can be compared with each other for equality.


 * ordering_mixin 
 * Returns a metatable where the  metamethod wraps equal, and the   and   metamethods wrap compare, such that lists using this metatable can be ordered against each other using all of Lua's relational operators.

Selection

 * sub (t, i, j)
 * Returns a sublist.  and   may be negative values and are adjusted in the same way as  . If any out-of-bound index is accessed,   is inserted into the sublist and the returned table may not be a valid Lua sequence.   may be any list-like object as long as both   and   are positive.


 * select (t, pr)
 * Returns a new list containing only the elements of  that satisfy.


 * keep_if (t, pr)
 * Removes elements of  that do not satisfy  . The remaining elements form a valid Lua sequence, and relative order between these elements is preserved. Returns.


 * delete_if (t, pr)
 * Removes elements of  that satisfy , and returns these removed elements. The removed elements and the remaining elements in   each form a valid Lua sequence, and the relative orders between the elements within each table are preserved.


 * uniq (t, f)
 * Returns a copy of  with all duplicate elements other than their first occurrences removed. If   is given, uniqueness between elements is determined by the results of calling   on each element.


 * compact (t)
 * Given an arbitrary Lua table, returns a new list containing only values corresponding to numeric keys of  , sorted by key in ascending order.

Transformation

 * reverse (t)
 * Returns a new list with the elements of  in reversed order.


 * reverse_self (t)
 * Reverses the order of the elements of . Returns.


 * map (t, f)
 * Returns a new list with the results of calling  on each element of.


 * map_self (t, f)
 * Replaces every element of  with the result of calling   on it. Returns.


 * zip (t1, t2, op)
 * Returns a new list with the results of calling  on each element of   and the corresponding element of   with the same key.


 * sort_by (t, f)
 * Returns a copy of  sorted by the results of calling   on each element of the table.   is evaluated exactly once for each element. The original table is unmodified.


 * concat (t1, t2)
 * Returns a new list with all elements from  followed by all elements from.


 * concat_self (t1, t2)
 * Appends all elements of  to the end of   in the same order. Returns.


 * to_set (t)
 * Returns a new table where the elements of  become the keys of the table with all corresponding values.


 * transpose (t)
 * Given a list-of-lists, returns a new table   with row indices and column indices swapped such that   for all elements in lists of  . The elements of   may not be valid Lua sequences if   is a jagged 2D array.

Other

 * reduce (t, op)
 * Returns the left fold of the first element of the table over the other elements, i.e..


 * reduce (t, op, z)
 * Returns the left fold of  over the elements of the table, i.e..


 * sum (t) 
 * Returns the sum of the elements of the table, using Lua's built-in addition operator. Equivalent to.


 * group_by (t, f)
 * Returns a new table in which the keys are the results of calling  on the elements of the table, and the values are lists of elements whose results compare equal to the corresponding keys.