list: Module Index

# Module `list`

Tables as lists.

## Functions

append (l, x) | Append an item to a list.
compare (l, m) | Compare two lists element by element left-to-right
concat (...) | Concatenate lists.
cons (l, x) | Prepend an item to a list.
depair (ls) | Turn a list of pairs into a table.
elems (l) | An iterator over the elements of a list.
enpair (t) | Turn a table into a list of pairs.
filter (p, l) | Filter a list according to a predicate.
flatten (l) | Flatten a list.
foldl (f, e, l) | Fold a binary function through a list left associatively.
foldr (f, e, l) | Fold a binary function through a list right associatively.
indexKey (f, l) | Make an index of a list of tables on a given field
indexValue (f, l) | Copy a list of tables, indexed on a given field
map (f, l) | Map a function over a list.
mapWith (f, l, ls) | Map a function over a list of lists.
new (l, t) | List constructor.
project (f, l) | Project a list of fields from a list of tables.
relems (l) | An iterator over the elements of a list, in reverse.
rep (l, n) | Repeat a list.
reverse (l) | Reverse a list.
shape (s, l) | Shape a list according to a list of dimensions.
slice (l, from, to) | Return a slice of a list.
tail (l) | Return a list with its first element removed.
transpose (ls) | Transpose a list of lists.
zipWith (f, ls) | Zip lists together with a function.

## Functions

append (l, x)
  Append an item to a list.

  ### Parameters

  - l: list
  - x: item

  ### Return value:

  `{l[1], ..., l[#l], x}`
compare (l, m)
  Compare two lists element by element left-to-right

  ### Parameters

  - l: first list
  - m: second list

  ### Return value:

  -1 if `l` is less than `m`, 0 if they are the same, and 1 if `l` is greater than `m`
concat (...)
  Concatenate lists.

  ### Parameters

  - ...: lists

  ### Return value:

  `{l1[1], ..., l1[#l1], ..., ln[1], ..., ln[#ln]}`
cons (l, x)
  Prepend an item to a list.

  ### Parameters

  - l: list
  - x: item

  ### Return value:

  `{x, unpack (l)}`
depair (ls)
  Turn a list of pairs into a table.
  FIXME: Find a better name.

  ### Parameters

  - ls: list `{{i1, v1}, ..., {in, vn}}`

  ### Return value:

  table `{i1=v1, ..., in=vn}`
elems (l)
  An iterator over the elements of a list.

  ### Parameters

  - l: list to iterate over

  ### Return values:

  1. iterator function which returns successive elements of the list
  2. the list `l` as above
  3. `true`
enpair (t)
  Turn a table into a list of pairs.
  FIXME: Find a better name.

  ### Parameters

  - t: table `{i1=v1, ..., in=vn}`

  ### Return value:

  list `{{i1, v1}, ..., {in, vn}}`
filter (p, l)
  Filter a list according to a predicate.

  ### Parameters

  - p: predicate (function of one argument returning a boolean)
  - l: list of lists

  ### Return value:

  result list containing elements `e` of `l` for which `p (e)` is true
flatten (l)
  Flatten a list.

  ### Parameters

  - l: list to flatten

  ### Return value:

  flattened list
foldl (f, e, l)
  Fold a binary function through a list left associatively.

  ### Parameters

  - f: function
  - e: element to place in left-most position
  - l: list

  ### Return value:

  result
foldr (f, e, l)
  Fold a binary function through a list right associatively.

  ### Parameters

  - f: function
  - e: element to place in right-most position
  - l: list

  ### Return value:

  result
indexKey (f, l)
  Make an index of a list of tables on a given field

  ### Parameters

  - f: field
  - l: list of tables `{t1, ..., tn}`

  ### Return value:

  index `{t1[f]=1, ..., tn[f]=n}`
indexValue (f, l)
  Copy a list of tables, indexed on a given field

  ### Parameters

  - f: field whose value should be used as index
  - l: list of tables `{i1=t1, ..., in=tn}`

  ### Return value:

  index `{t1[f]=t1, ..., tn[f]=tn}`
map (f, l)
  Map a function over a list.

  ### Parameters

  - f: function
  - l: list

  ### Return value:

  result list `{f (l[1]), ..., f (l[#l])}`
mapWith (f, l, ls)
  Map a function over a list of lists.

  ### Parameters

  - f: function
  - l:
  - ls: list of lists

  ### Return value:

  result list `{f (unpack (ls[1]))), ..., f (unpack (ls[#ls]))}`
new (l, t)
  List constructor. Needed in order to use metamethods.

  ### Parameters

  - l:
  - t: list (as a table)

  ### Return value:

  list (with list metamethods)
project (f, l)
  Project a list of fields from a list of tables.

  ### Parameters

  - f: field to project
  - l: list of tables

  ### Return value:

  list of `f` fields
relems (l)
  An iterator over the elements of a list, in reverse.

  ### Parameters

  - l: list to iterate over

  ### Return values:

  1. iterator function which returns precessive elements of the list
  2. the list `l` as above
  3. `true`
rep (l, n)
  Repeat a list.

  ### Parameters

  - l: list
  - n: number of times to repeat

  ### Return value:

  `n` copies of `l` appended together
reverse (l)
  Reverse a list.

  ### Parameters

  - l: list

  ### Return value:

  list `{l[#l], ..., l[1]}`
shape (s, l)
  Shape a list according to a list of dimensions. Dimensions are given outermost first and items from the original list are distributed breadth first; there may be one 0 indicating an indefinite number. Hence, `{0}` is a flat list, `{1}` is a singleton, `{2, 0}` is a list of two lists, and `{0, 2}` is a list of pairs.
  Algorithm: turn shape into all positive numbers, calculating the zero if necessary and making sure there is at most one; recursively walk the shape, adding empty tables until the bottom level is reached at which point add table items instead, using a counter to walk the flattened original list.

  ### Parameters

  - s: `{d1, ..., dn}`
  - l: list to reshape

  ### Return value:

  reshaped list FIXME: Use ileaves instead of flatten (needs a while instead of a for in fill function)
slice (l, from, to)
  Return a slice of a list. (Negative list indices count from the end of the list.)

  ### Parameters

  - l: list
  - from: start of slice (default: 1)
  - to: end of slice (default: `#l`)

  ### Return value:

  `{l[from], ..., l[to]}`
tail (l)
  Return a list with its first element removed.

  ### Parameters

  - l: list

  ### Return value:

  `{l[2], ..., l[#l]}`
transpose (ls)
  Transpose a list of lists. This function in Lua is equivalent to zip and unzip in more strongly typed languages.

  ### Parameters

  - ls: `{{l1,1, ..., l1,c}, ..., {lr,1, ..., lr,c}}`

  ### Return value:

  `{{l1,1, ..., lr,1}, ..., {l1,c, ..., lr,c}}`
zipWith (f, ls)
  Zip lists together with a function.

  ### Parameters

  - f: function
  - ls: list of lists

  ### Return value:

  `{f (ls[1][1], ..., ls[#ls][1]), ..., f (ls[1][N], ..., ls[#ls][N])` where `N = max {map (function (l) return #l end, ls)}`