list


elems: An iterator over the elements of a list
  l: list to iterate over
returns
  f: iterator function
    l: list
    n: index
  returns
    v: value (l[n - 1])
  l: the list, as above
  @param 0


relems: An iterator over the elements of a list, in reverse
  l: list to iterate over
returns
  f: iterator function
    l: list
    n: index
  returns
    v: value (l[n - 1))
  l: the list, as above
  n: #l + 1


map: Map a function over a list
  f: function
  l: list
returns
  m: result list {f (l[1]), ..., f (l[#l])}


mapWith: Map a function over a list of lists
  f: function
  ls: list of lists
returns
  m: result list {f (unpack (ls[1]))), ...,
    f (unpack (ls[#ls]))}


filter: Filter a list according to a predicate
  p: predicate
    a: argument
  returns
    f: flag
  l: list of lists
returns
  m: result list containing elements e of l for which p (e)
    is true


slice: Slice a list
  l: list
  [from], @param [to]: start and end of slice
    from defaults to 1 and to to #l;
    negative values count from the end
returns
  m: {l[from], ..., l[to]}


tail: Return a list with its first element removed
  l: list
returns
  m: {l[2], ..., l[#l]}


foldl: Fold a binary function through a list left
associatively
  f: function
  e: element to place in left-most position
  l: list
returns
  r: result


foldr: Fold a binary function through a list right
associatively
  f: function
  e: element to place in right-most position
  l: list
returns
  r: result


cons: Prepend an item to a list
  x: item
  l: list
returns
  r: {x, unpack (l)}


append: Append an item to a list
  x: item
  l: list
returns
  r: {l[1], ..., l[#l], x}


concat: Concatenate lists
  l1, l2, ... ln: lists
returns
  r: result {l1[1], ..., l1[#l1], ...,
                    ln[1], ..., ln[#ln]}


rep: Repeat a list
  n: number of times to repeat
  l: list
returns
  r: n copies of l appended together


reverse: Reverse a list
  l: list
returns
  m: list {l[#l], ..., l[1]}


transpose: Transpose a list of lists
  ls: {{l11, ..., l1c}, ..., {lr1, ..., lrc}}
returns
  ms: {{l11, ..., lr1}, ..., {l1c, ..., lrc}}
This function is equivalent to zip and unzip in more strongly typed
languages


zipWith: Zip lists together with a function
  f: function
  ls: list of lists
returns
  m: {f (ls[1][1], ..., ls[#ls][1]), ...,
             f (ls[1][N], ..., ls[#ls][N])
    where N = max {map (table.getn, ls)}


project: Project a list of fields from a list of tables
  f: field to project
  l: list of tables
returns
  m: list of f fields


enpair: Turn a table into a list of pairs
FIXME: Find a better name
  t: table {i1=v1, ..., in=vn}
returns
  ls: list {{i1, v1}, ..., {in, vn}}


depair: Turn a list of pairs into a table
FIXME: Find a better name
  ls: list {{i1, v1}, ..., {in, vn}}
returns
  t: table {i1=v1, ..., in=vn}


flatten: Flatten a list
  l: list to flatten
returns
  m: flattened list


shape: 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.
  s: {d1, ..., dn}
  l: list to reshape
returns
  m: reshaped list
Algorithm: turn shape into all +ve 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.


indexKey: Make an index of a list of tables on a given
field
  f: field
  l: list of tables {t1, ..., tn}
returns
  m: index {t1[f]=1, ..., tn[f]=n}


indexValue: Copy a list of tables, indexed on a given
field
  f: field whose value should be used as index
  l: list of tables {i1=t1, ..., in=tn}
returns
  m: index {t1[f]=t1, ..., tn[f]=tn}


Metamethods for lists



new: List constructor
Needed in order to use metamethods
  t: list (as a table)
returns
  l: list (with list metamethods)


Function forms of operators