## list.api
#
# List(X) type and core operations on lists.
#
# See also:
#
# src/lib/std/src/paired-lists.api# Compiled by:
# src/lib/std/src/standard-core.sublib# Available (unqualified) at top level:
# type list
# my NIL, . , head, tail, null, length, @, apply, map, fold_right, fold_left, reverse
#
# Consequently the following are not visible at top level:
# my last, nth, take, drop, cat, revAppend, map', find, filter,
# partition, exists, all, tabulate
# exception EMPTY
#
# The following infix declarations will hold at top level:
# infixr 60 . @
### "We were not out to win over the Lisp programmers;
### we were after the C++ programmers. We managed to
### drag a lot of them about halfway to Lisp."
###
### -- Guy Steele, author of Java
### (and Scheme and CommonLisp) spec
api List {
#
List(X) = NIL
| ! (X, List(X))
;
exception EMPTY;
null: List(X) -> Bool; # Returns TRUE iff list is empty.
head: List(X) -> X; # Returns first element in list. Raises EMPTY if list is not long enough.
tail: List(X) -> List(X); # Returns all but first element in list. Raises EMPTY if list is not long enough.
last: List(X) -> X; # Returns last element in list. Raises EMPTY if list is not long enough.
get_item: List(X) -> Null_Or( (X, List(X)));
nth: (List(X), Int) -> X; # Returns n-th element from list. Raises SUBSCRIPT if list is not long enough.
take_n: (List(X), Int) -> List(X); # Returns first N elements from list. Raises SUBSCRIPT if list is not long enough.
drop_n: (List(X), Int) -> List(X); # Drops first N elements from list, return remainder. Raises SUBSCRIPT if list is not long enough.
split_n: (List(X), Int) -> (List(X), List(X)); # split ((1..4), 2) == ([1, 2], [3, 4]).
length: List(X) -> Int;
reverse: List(X) -> List(X);
@ : (List(X), List(X)) -> List(X); # Return concatenation of two lists.
cat: List( List(X) ) -> List(X); # Return concatenation of N lists.
reverse_and_prepend: (List(X), List(X)) -> List(X);
apply: (X -> Void) -> List(X) -> Void; # Apply given fn to each element of list.
map: (X -> Y) -> List(X) -> List(Y); # Apply given fn to each element of list and return resulting values.
apply': List(X) -> (X -> Void) -> Void; # apply' x f = apply f x.
map': List(X) -> (X -> Y) -> List(Y); # map' x f = map f x.
map_partial_fn: (X -> Null_Or(Y)) -> List(X) -> List(Y); # Map given fn across list and drop NULLs.
find: (X -> Bool) -> List(X) -> Null_Or(X); # Return first predicate-accepted element in the list, else NULL.
remove_first: (X -> Bool) -> List(X) -> List(X); # Returns all elements except first satisfying predicate.
filter: (X -> Bool) -> List(X) -> List(X); # Return list of all elements accepted by predicate.
remove: (X -> Bool) -> List(X) -> List(X); # Return list of all elements NOT accepted by predicate.
partition: (X -> Bool) -> List(X) -> (List(X), List(X)); # Return list of elements satisfying predicate plus list of remaining elements.
split_at_first: (X -> Bool) -> List(X) -> (List(X), List(X)); # Return longest prefix list of elements not satisfying predicate, followed by remaining list elements.
prefix_to_first: (X -> Bool) -> List(X) -> List(X); # All elements up to first satisfying predicate.
suffix_from_first: (X -> Bool) -> List(X) -> List(X); # All elements after first satisfying predicate.
fold_right: ((X, Y) -> Y) -> Y -> List(X) -> Y;
fold_left: ((X, Y) -> Y) -> Y -> List(X) -> Y;
exists: (X -> Bool) -> List(X) -> Bool;
all: (X -> Bool) -> List(X) -> Bool;
tabulate: ((Int, (Int -> X))) -> List(X); # Raises SIZE
collate: ((X, X) -> Order) -> (List(X), List(X)) -> Order;
in: (_X, List _X) -> Bool; # Return TRUE iff given element is in given list.
drop: (_X, List _X) -> List _X; # Return given list with all copies of given element removed.
}; # Api List
## COPYRIGHT (c) 1995 AT&T Bell Laboratories.
## Subsequent changes by Jeff Prothero Copyright (c) 2010-2012,
## released under Gnu Public Licence version 3.