ocaml-base-compiler
Legend:
Library
Module
Module type
Parameter
Class
Class type

List operations.

Some functions are flagged as not tail-recursive. A tail-recursive function uses constant stack space, while a non-tail-recursive function uses stack space proportional to the length of its list argument, which can be a problem with very long lists. When the function takes several list arguments, an approximate formula giving stack usage (in some unspecified constant unit) is shown in parentheses.

The above considerations can usually be ignored if your lists are not longer than about 10000 elements.

`type 'a t = 'a list = `
1. `| []`
2. `| :: of 'a * 'a list`

An alias for the type of lists.

`val length : 'a list -> int`

Return the length (number of elements) of the given list.

`val compare_lengths : 'a list -> 'b list -> int`

Compare the lengths of two lists. `compare_lengths l1 l2` is equivalent to `compare (length l1) (length l2)`, except that the computation stops after itering on the shortest list.

• since 4.05.0
`val compare_length_with : 'a list -> int -> int`

Compare the length of a list to an integer. `compare_length_with l n` is equivalent to `compare (length l) n`, except that the computation stops after at most `n` iterations on the list.

• since 4.05.0
`val cons : 'a -> 'a list -> 'a list`

`cons x xs` is `x :: xs`

• since 4.03.0
`val hd : 'a list -> 'a`

Return the first element of the given list.

• raises Failure

if the list is empty.

`val tl : 'a list -> 'a list`

Return the given list without its first element.

• raises Failure

if the list is empty.

`val nth : 'a list -> int -> 'a`

Return the `n`-th element of the given list. The first element (head of the list) is at position 0.

• raises Failure

if the list is too short.

• raises Invalid_argument

if `n` is negative.

`val nth_opt : 'a list -> int -> 'a option`

Return the `n`-th element of the given list. The first element (head of the list) is at position 0. Return `None` if the list is too short.

• raises Invalid_argument

if `n` is negative.

• since 4.05
`val rev : 'a list -> 'a list`

List reversal.

`val init : int -> (int -> 'a) -> 'a list`

`List.init len f` is `[f 0; f 1; ...; f (len-1)]`, evaluated left to right.

• raises Invalid_argument

if len < 0.

• since 4.06.0
`val append : 'a list -> 'a list -> 'a list`

Concatenate two lists. Same as the infix operator `@`. Not tail-recursive (length of the first argument).

`val rev_append : 'a list -> 'a list -> 'a list`

`List.rev_append l1 l2` reverses `l1` and concatenates it to `l2`. This is equivalent to `List.rev`` l1 @ l2`, but `rev_append` is tail-recursive and more efficient.

`val concat : 'a list list -> 'a list`

Concatenate a list of lists. The elements of the argument are all concatenated together (in the same order) to give the result. Not tail-recursive (length of the argument + length of the longest sub-list).

`val flatten : 'a list list -> 'a list`

An alias for `concat`.

## Iterators

`val iter : ('a -> unit) -> 'a list -> unit`

`List.iter f [a1; ...; an]` applies function `f` in turn to `a1; ...; an`. It is equivalent to `begin f a1; f a2; ...; f an; () end`.

`val iteri : (int -> 'a -> unit) -> 'a list -> unit`

Same as `List.iter`, but the function is applied to the index of the element as first argument (counting from 0), and the element itself as second argument.

• since 4.00.0
`val map : ('a -> 'b) -> 'a list -> 'b list`

`List.map f [a1; ...; an]` applies function `f` to `a1, ..., an`, and builds the list `[f a1; ...; f an]` with the results returned by `f`. Not tail-recursive.

`val mapi : (int -> 'a -> 'b) -> 'a list -> 'b list`

Same as `List.map`, but the function is applied to the index of the element as first argument (counting from 0), and the element itself as second argument. Not tail-recursive.

• since 4.00.0
`val rev_map : ('a -> 'b) -> 'a list -> 'b list`

`List.rev_map f l` gives the same result as `List.rev`` (``List.map`` f l)`, but is tail-recursive and more efficient.

`val filter_map : ('a -> 'b option) -> 'a list -> 'b list`

`filter_map f l` applies `f` to every element of `l`, filters out the `None` elements and returns the list of the arguments of the `Some` elements.

• since 4.08.0
`val concat_map : ('a -> 'b list) -> 'a list -> 'b list`

`List.concat_map f l` gives the same result as `List.concat`` (``List.map`` f l)`. Tail-recursive.

• since 4.10.0
`val fold_left_map : ('a -> 'b -> 'a * 'c) -> 'a -> 'b list -> 'a * 'c list`

`fold_left_map` is a combination of `fold_left` and `map` that threads an accumulator through calls to `f`

• since 4.11.0
`val fold_left : ('a -> 'b -> 'a) -> 'a -> 'b list -> 'a`

`List.fold_left f a [b1; ...; bn]` is `f (... (f (f a b1) b2) ...) bn`.

`val fold_right : ('a -> 'b -> 'b) -> 'a list -> 'b -> 'b`

`List.fold_right f [a1; ...; an] b` is `f a1 (f a2 (... (f an b) ...))`. Not tail-recursive.

## Iterators on two lists

`val iter2 : ('a -> 'b -> unit) -> 'a list -> 'b list -> unit`

`List.iter2 f [a1; ...; an] [b1; ...; bn]` calls in turn `f a1 b1; ...; f an bn`.

• raises Invalid_argument

if the two lists are determined to have different lengths.

`val map2 : ('a -> 'b -> 'c) -> 'a list -> 'b list -> 'c list`

`List.map2 f [a1; ...; an] [b1; ...; bn]` is `[f a1 b1; ...; f an bn]`.

• raises Invalid_argument

if the two lists are determined to have different lengths. Not tail-recursive.

`val rev_map2 : ('a -> 'b -> 'c) -> 'a list -> `