# 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, memo) | '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 (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 passed to `fun`

  ### See also:

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

  ### Parameters:

  - fun func a function of two arguments
  - t array a list-like table
  - memo array optional initial memo value. Defaults to first value in 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)
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:

  tablex.merge
intersection (t1, t2)
  the intersection of two map-like tables.

  ### Parameters:

  - t1 tab a table
  - t2 tab a table

  ### Returns:

  tab

  ### See also:

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

  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:

  - t tab the table

  ### Returns:

  the table read only (a proxy).

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

  - 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; `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"},  -- fields are not compared!
         {1,2,3}, function(v1, v2) return v1 == v2 end)

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

  1. index of value, or nil if not found
  2. value returned by comparison function (cannot be `false`!)

  ### Usage:

      -- using an operator
      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)       -- looking up 'false' works!

      -- using a function returning the value looked up
      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")  -- the value is returned

      -- NOTE: this fails, since 'false' cannot be returned!
      local idx, cmp_result = tablex.rfind(lst, cmp, false)
      assert(idx == nil)               -- looking up 'false' failed!
      assert(cmp_result == nil)

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

  ### 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, 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 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 (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 on the elements; `function(value, key, ...)`
  - ... extra arguments passed to `fun`

  ### See also:

  tablex.transform
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 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 (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.6