# Module `pl.tablex`

Extended operations on Lua tables.

See the Guide

Dependencies: `pl.utils`, `pl.types`

## Functions

size (t) | total number of elements in this table.
index_by (tbl, idx) | 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, t) | '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.
count_map (t, cmp) | A table where the key/values are the values and value counts of the table.
set (t, 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 (t, istart) | clear out the contents of a table.
removevalues (t, i1, i2) | remove a range of values from a table.
readonly (t) | modifies a table to be read only.

## Copying

update (t1, t2) | copy a table into another, in-place.
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.
icopy (dest, src[, idest=1[, isrc=1[, nsrc=#src]]]) | copy an array into another one, clearing `dest` after `idest+nsrc`, if necessary.
move (dest, src[, idest=1[, isrc=1[, nsrc=#src]]]) | copy an array into another one.
insertvalues (t[, position], values) | insert values into a table.

## Comparing

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.

## Finding

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.
search (t, value[, exclude]) | find a value in a table by recursive search.

## MappingAndFiltering

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.
map2 (fun, t1, t2, ...) | apply a function to values from two tables.
imap2 (fun, t1, t2, ...) | 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 (t, pred, arg) | filter an array's values using a predicate function

## Iterating

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.
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

## Extraction

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 (t, first, last) | Extract a range from a table, like 'string.sub'.

## Merging

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.
zip (...) | return a table where each element is a table of the ith values of an arbitrary number of tables.

## Functions

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 tab a table

  ### Returns:

  the size
index_by (tbl, idx)
  return a list of all values in a table indexed by another list.

  ### Parameters:

  - tbl tab a table
  - idx array 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}

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
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, t)
  'reduce' a list using a binary function.

  ### Parameters:

  - fun func a function of two arguments
  - t array a list-like table

  ### 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:

  - t array 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 array a list-like table

  ### Returns:

  a set (a map-like table)
count_map (t, cmp)
  A table where the key/values are the values and value counts of the table.

  ### Parameters:

  - t array a list-like table
  - cmp func a function that defines equality (otherwise uses ==)

  ### Returns:

  a map-like table

  ### See also:

  seq.count_map
set (t, 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:

  - t array a list-like table
  - 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 (t, istart)
  clear out the contents of a table.

  ### Parameters:

  - t array a list
  - istart optional start position
removevalues (t, i1, i2)
  remove a range of values from a table. End of range may be negative.

  ### Parameters:

  - t array a list-like table
  - 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`.

  ### Parameters:

  - t tab the table

  ### Returns:

  the table read only.

## Copying

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:

  - t tab 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 tab A table

  ### Returns:

  new table
icopy (dest, src[, idest=1[, isrc=1[, nsrc=#src]]])
  copy an array into another one, clearing `dest` after `idest+nsrc`, if necessary.

  ### Parameters:

  - dest array a list-like table
  - src array a list-like table
  - 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 (dest, src[, idest=1[, isrc=1[, nsrc=#src]]])
  copy an array into another one.

  ### Parameters:

  - dest array a list-like table
  - src array a list-like table
  - 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 (t[, position], values)
  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:

  - t array the list
  - position int (default is at end) (optional)
  - values array

## Comparing

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 (t1, t2, cmp)
  compare two arrays using a predicate.

  ### Parameters:

  - t1 array an array
  - t2 array an array
  - cmp func 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 array a list-like table
  - t2 array a list-like table
  - cmp A comparison function (may be nil)

## Finding

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 array A list-like table
  - 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) == 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 array A list-like table
  - 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 tab A table
  - cmp func A comparison function
  - arg an optional second argument to the function

  ### Returns:

  1. index of value, or nil if not found
  2. value returned by comparison function
search (t, value[, exclude])
  find a value in a table by recursive search.

  ### Parameters:

  - t tab the table
  - value the value
  - exclude array any tables to avoid searching (optional)

  ### Returns:

  a fieldspec, e.g. 'a.b' or 'math.sin'

  ### Usage:

      search(_G,math.sin,{package.path}) == 'math.sin'

## MappingAndFiltering

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, 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 func A function that takes at least one argument
  - t array 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 string the method name
  - t array a list-like table
  - ... any extra arguments to the method
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, t1, t2, ...)
  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
  - t1 array a list-like table
  - t2 array a list-like table
  - ... 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 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 (t, pred, arg)
  filter an array's values using a predicate function

  ### Parameters:

  - t array a list-like table
  - pred func a boolean function
  - arg optional argument to be passed as second argument of the predicate

## Iterating

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 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 array a table
  - 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

## Extraction

keys (t)
  return all the keys of a table in arbitrary order.

  ### Parameters:

  - t tab A table
values (t)
  return all the values of the table in arbitrary order

  ### Parameters:

  - t tab A table
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 array a list-like table
  - first int An index
  - last int An index

  ### Returns:

  a new List

## Merging

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:

  tablex.index_map

  ### 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:

  - ... array arrays to be zipped

  ### Usage:

      zip({10,20,30},{100,200,300}) is {{10,100},{20,200},{30,300}}

generated by LDoc 1.4.3 Last updated Tue, 18 Aug 2015 11:21:53 +0200