# 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
l: list
x: item
returns
r: {x, unpack (l)}

append: Append an item to a list
l: list
x: item
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
l: list
n: number of times to repeat
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