Module ExtList.List

module List: sig .. end


New functions

val init : int -> (int -> 'a) -> 'a list
Similar to Array.init, init n f returns the list containing the results of (f 0),(f 1).... (f (n-1)). Raise Invalid_arg "ExtList.init" if n < 0.
val make : int -> 'a -> 'a list
Similar to String.make, make n x returns a list containing n elements x.
val first : 'a list -> 'a
Returns the first element of the list, or raise Empty_list if the list is empty (similar to hd).
val last : 'a list -> 'a
Returns the last element of the list, or raise Empty_list if the list is empty. This function takes linear time.
val iteri : (int -> 'a -> unit) -> 'a list -> unit
iteri f l will call (f 0 a0);(f 1 a1) ... (f n an) where a0..an are the elements of the list l.
val mapi : (int -> 'a -> 'b) -> 'a list -> 'b list
mapi f l will build the list containing (f 0 a0);(f 1 a1) ... (f n an) where a0..an are the elements of the list l.
val rfind : ('a -> bool) -> 'a list -> 'a
rfind p l returns the last element x of l such as p x returns true or raises Not_found if such element as not been found.
val find_exc : ('a -> bool) -> exn -> 'a list -> 'a
find_exc p e l returns the first element of l such as p x returns true or raises e if such element as not been found.
val findi : (int -> 'a -> bool) -> 'a list -> int * 'a
findi p e l returns the first element ai of l along with its index i such that p i ai is true, or raises Not_found if no such element has been found.
val unique : ?cmp:('a -> 'a -> bool) -> 'a list -> 'a list
unique cmp l returns the list l without any duplicate element. Default comparator ( = ) is used if no comparison function specified.
val filter_map : ('a -> 'b option) -> 'a list -> 'b list
filter_map f l call (f a0) (f a1).... (f an) where a0..an are the elements of l. It returns the list of elements bi such as f ai = Some bi (when f returns None, the corresponding element of l is discarded).
val find_map : ('a -> 'b option) -> 'a list -> 'b
find_map pred list finds the first element of list for which pred element returns Some r. It returns r immediately once found or raises Not_found if no element matches the predicate. See also ExtList.List.filter_map.
val split_nth : int -> 'a list -> 'a list * 'a list
split_nth n l returns two lists l1 and l2, l1 containing the first n elements of l and l2 the others. Raise Invalid_index if n is outside of l size bounds.
val remove : 'a list -> 'a -> 'a list
remove l x returns the list l without the first element x found or returns l if no element is equal to x. Elements are compared using ( = ).
val remove_if : ('a -> bool) -> 'a list -> 'a list
remove_if cmp l is similar to remove, but with cmp used instead of ( = ).
val remove_all : 'a list -> 'a -> 'a list
remove_all l x is similar to remove but removes all elements that are equal to x and not only the first one.
val take : int -> 'a list -> 'a list
take n l returns up to the n first elements from list l, if available.
val drop : int -> 'a list -> 'a list
drop n l returns l without the first n elements, or the empty list if l have less than n elements.
val takewhile : ('a -> bool) -> 'a list -> 'a list
takewhile f xs returns the first elements of list xs which satisfy the predicate f.
val dropwhile : ('a -> bool) -> 'a list -> 'a list
dropwhile f xs returns the list xs with the first elements satisfying the predicate f dropped.

Enum functions


Enumerations are important in ExtLib, they are a good way to work with abstract enumeration of elements, regardless if they are located in a list, an array, or a file.
val enum : 'a list -> 'a Enum.t
Returns an enumeration of the elements of a list.
val of_enum : 'a Enum.t -> 'a list
Build a list from an enumeration.

Modified functions


Some minor modifications have been made to the specification of some functions, especially concerning exceptions raised.
val hd : 'a list -> 'a
Returns the first element of the list or raise Empty_list if the list is empty.
val tl : 'a list -> 'a list
Returns the list without its first elements or raise Empty_list if the list is empty.
val nth : 'a list -> int -> 'a
nth l n returns the n-th element of the list l or raise Invalid_index is the index is outside of l bounds.
val sort : ?cmp:('a -> 'a -> int) -> 'a list -> 'a list
Sort the list using optional comparator (by default compare).

The following functions have been improved so all of them are tail-recursive. They have also been modified so they no longer raise Invalid_arg but Different_list_size when used on two lists having a different number of elements.
val map2 : ('a -> 'b -> 'c) -> 'a list -> 'b list -> 'c list
val iter2 : ('a -> 'b -> unit) -> 'a list -> 'b list -> unit
val fold_left2 : ('a -> 'b -> 'c -> 'a) -> 'a -> 'b list -> 'c list -> 'a
val fold_right2 : ('a -> 'b -> 'c -> 'c) -> 'a list -> 'b list -> 'c -> 'c
val for_all2 : ('a -> 'b -> bool) -> 'a list -> 'b list -> bool
val exists2 : ('a -> 'b -> bool) -> 'a list -> 'b list -> bool
val combine : 'a list -> 'b list -> ('a * 'b) list

Improved functions


The following functions have the same behavior as the List module ones but are tail-recursive. That means they will not cause a Stack_overflow when used on very long list.

The implementation might be a little more slow in bytecode, but compiling in native code will not affect performances.

val map : ('a -> 'b) -> 'a list -> 'b list
val append : 'a list -> 'a list -> 'a list
val flatten : 'a list list -> 'a list
val concat : 'a list list -> 'a list
val fold_right : ('a -> 'b -> 'b) -> 'a list -> 'b -> 'b
val remove_assoc : 'a -> ('a * 'b) list -> ('a * 'b) list
val remove_assq : 'a -> ('a * 'b) list -> ('a * 'b) list
val split : ('a * 'b) list -> 'a list * 'b list

The following functions were already tail-recursive in the List module but were using List.rev calls. The new implementations have better performances.
val filter : ('a -> bool) -> 'a list -> 'a list
val find_all : ('a -> bool) -> 'a list -> 'a list
val partition : ('a -> bool) -> 'a list -> 'a list * 'a list

Older functions


These functions are already part of the Ocaml standard library and have not been modified. Please refer to the Ocaml Manual for documentation.
val length : 'a list -> int
val rev_append : 'a list -> 'a list -> 'a list
val rev : 'a list -> 'a list
val rev_map : ('a -> 'b) -> 'a list -> 'b list
val iter : ('a -> unit) -> 'a list -> unit
val fold_left : ('b -> 'a -> 'b) -> 'b -> 'a list -> 'b
val for_all : ('a -> bool) -> 'a list -> bool
val exists : ('a -> bool) -> 'a list -> bool
val find : ('a -> bool) -> 'a list -> 'a
val mem : 'a -> 'a list -> bool
val memq : 'a -> 'a list -> bool
val assoc : 'a -> ('a * 'b) list -> 'b
val assq : 'a -> ('a * 'b) list -> 'b
val mem_assoc : 'a -> ('a * 'b) list -> bool
val mem_assq : 'a -> ('a * 'b) list -> bool
val stable_sort : ('a -> 'a -> int) -> 'a list -> 'a list
val fast_sort : ('a -> 'a -> int) -> 'a list -> 'a list
val merge : ('a -> 'a -> int) -> 'a list -> 'a list -> 'a list

Exceptions

exception Empty_list
Empty_list is raised when an operation applied on an empty list is invalid : hd for example.
exception Invalid_index of int
Invalid_index is raised when an indexed access on a list is out of list bounds.
exception Different_list_size of string
Different_list_size is raised when applying functions such as iter2 on two lists having different size.