The Standard ML Basis Library

The List structure

Synopsis

signatureLISTstructureList :> LIST

The List structure provides a collection of utility functions for manipulating polymorphic lists, traditionally an important datatype in functional programming.

Following the concrete syntax provided by the list :: operator, the head of a list appears leftmost. Thus, a traversal of a list from left to right starts with the head, then recurses on the tail. In addition, as a sequence type, a list has an indexing of its elements, with the head having index 0, the second element having index 1, etc.

returns NONE if the list is empty, and SOME(hd l,tl l) otherwise. This function is particularly useful for creating value readers from lists of characters. For example, Int.scan StringCvt.DEC getItem has the type

(int,char list) StringCvt.reader

and can be used to scan decimal integers from lists of characters.

nth (l, i)

returns the i(th) element of the list l, counting from 0. It raises Subscript if i < 0 or i >= lengthl. We have nth(l,0) = hd l, ignoring exceptions.

take (l, i)

returns the first i elements of the list l. It raises Subscript if i < 0 or i > lengthl. We have take(l, lengthl) = l.

drop (l, i)

returns what is left after dropping the first i elements of the list l. It raises Subscript if i < 0 or i > lengthl. It holds that take(l, i) @drop(l, i) = l when 0 <= i <= lengthl. We also have drop(l, lengthl) = [].

rev l

returns a list consisting of l's elements in reverse order.

concat l

returns the list that is the concatenation of all the lists in l in order.

concat[l1,l2,...ln] = l1 @ l2 @ ... @ ln

revAppend (l1, l2)

returns (rev l1) @ l2.

app fl

applies f to the elements of l, from left to right.

map fl

applies f to each element of l from left to right, returning the list of results.

mapPartial fl

applies f to each element of l from left to right, returning a list of results, with SOME stripped, where f was defined. f is not defined for an element of l if f applied to the element returns NONE. The above expression is equivalent to:

((map valOf) o (filter isSome) o (map f)) l

find fl

applies f to each element x of the list l, from left to right, until fx evaluates to true. It returns SOME(x) if such an x exists; otherwise it returns NONE.

filter fl

applies f to each element x of l, from left to right, and returns the list of those x for which fx evaluated to true, in the same order as they occurred in the argument list.

partition fl

applies f to each element x of l, from left to right, and returns a pair (pos, neg) where pos is the list of those x for which fx evaluated to true, and neg is the list of those for which fx evaluated to false. The elements of pos and neg retain the same relative order they possessed in l.

foldl finit [x1, x2, ..., xn]

returns

f(xn,...,f(x2, f(x1, init))...)

or init if the list is empty.

foldr finit [x1, x2, ..., xn]

returns

f(x1, f(x2, ..., f(xn, init)...))

or init if the list is empty.

exists fl

applies f to each element x of the list l, from left to right, until fx evaluates to true; it returns true if such an x exists and false otherwise.

all fl

applies f to each element x of the list l, from left to right, until fx evaluates to false; it returns false if such an x exists and true otherwise. It is equivalent to not(exists (not o f) l)).

tabulate (n, f)

returns a list of length n equal to [f(0), f(1), ..., f(n-1)], created from left to right. It raises Size if n < 0.

collate f (l1, l2)

performs lexicographic comparison of the two lists using the given ordering f on the list elements.

See Also

Discussion

The list type is considered primitive and is defined in the top-level environment. It is rebound here for consistency.

Rationale:

Lists are usually supported with a large collection of library functions. Here, we provide a somewhat smaller collection of operations that reflect common usage. We feel the collection is moderately complete, in that most programs will not need to define additional list operations. We have tried to adopt names that reflect a consensus from various existing libraries and texts. We have avoided functions relying on equality types.

Different SML implementations may still desire to provide list utility library modules, though if the design of List is right, they should be small.

Permission is granted for internet users to make one paper copy for their
own personal use. Further hardcopy reproduction is strictly prohibited.
Permission to distribute the HTML document electronically on any medium
other than the internet must be requested from the copyright holders by
contacting the editors.
Printed versions of the SML Basis Manual are available from Cambridge
University Press.
To order, please visit
www.cup.org (North America) or
www.cup.cam.ac.uk (outside North America).