package containers

Fast internal iterator.

• since 2.8

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

Return the first element of the given list.

• raises Failure

  if the list is empty.

Return the given list without its first element.

• raises Failure

  if the list is empty.

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.

List reversal.

rev_append l1 l2 reverses l1 and concatenates it with l2. This is equivalent to (rev l1) @ l2.

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).

iter ~f [a1; ...; an] applies function f in turn to [a1; ...; an]. It is equivalent to f a1; f a2; ...; f an.

rev_map ~f l gives the same result as rev (map f l), but is more efficient.

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

• since 4.10

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

• since 4.11

fold_left ~f ~init [b1; ...; bn] is f (... (f (f init b1) b2) ...) bn.

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.

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.

rev_map2 ~f l1 l2 gives the same result as rev (map2 f l1 l2), but is more efficient.

fold_left2 ~f ~init [a1; ...; an] [b1; ...; bn] is f (... (f (f init a1 b1) a2 b2) ...) an bn.

• raises Invalid_argument

  if the two lists are determined to have different lengths.

fold_right2 ~f [a1; ...; an] [b1; ...; bn] ~init is f a1 b1 (f a2 b2 (... (f an bn init) ...)).

• raises Invalid_argument

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

for_all ~f [a1; ...; an] checks if all elements of the list satisfy the predicate f. That is, it returns (f a1) && (f a2) && ... && (f an) for a non-empty list and true if the list is empty.

exists ~f [a1; ...; an] checks if at least one element of the list satisfies the predicate f. That is, it returns (f a1) || (f a2) || ... || (f an) for a non-empty list and false if the list is empty.

Same as for_all, but for a two-argument predicate.

• raises Invalid_argument

  if the two lists are determined to have different lengths.

Same as exists, but for a two-argument predicate.

• raises Invalid_argument

  if the two lists are determined to have different lengths.

Same as mem, but uses physical equality instead of structural equality to compare list elements.

find ~f l returns the first element of the list l that satisfies the predicate f.

• raises Not_found

  if there is no value that satisfies f in the list l.

find_index ~f xs returns Some i, where i is the index of the first element of the list xs that satisfies f x, if there is such an element.

It returns None if there is no such element.

• since 5.1

find_all is another name for filter.

Same as filter, but the predicate is applied to the index of the element as first argument (counting from 0), and the element itself as second argument.

• since 4.11

partition ~f l returns a pair of lists (l1, l2), where l1 is the list of all the elements of l that satisfy the predicate f, and l2 is the list of all the elements of l that do not satisfy f. The order of the elements in the input list is preserved.

Same as assoc, but uses physical equality instead of structural equality to compare keys.

Same as mem_assoc, but uses physical equality instead of structural equality to compare keys.

Same as remove_assoc, but uses physical equality instead of structural equality to compare keys. Not tail-recursive.

Sort a list in increasing order according to a comparison function. The comparison function must return 0 if its arguments compare as equal, a positive integer if the first is greater, and a negative integer if the first is smaller (see Array.sort for a complete specification). For example, Stdlib.compare is a suitable comparison function. The resulting list is sorted in increasing order. sort is guaranteed to run in constant heap space (in addition to the size of the result list) and logarithmic stack space.

The current implementation uses Merge Sort. It runs in constant heap space and logarithmic stack space.

Same as sort, but the sorting algorithm is guaranteed to be stable (i.e. elements that compare equal are kept in their original order).

The current implementation uses Merge Sort. It runs in constant heap space and logarithmic stack space.

Same as sort or stable_sort, whichever is faster on typical input.

Merge two lists: Assuming that l1 and l2 are sorted according to the comparison function cmp, merge ~cmp l1 l2 will return a sorted list containing all the elements of l1 and l2. If several elements compare equal, the elements of l1 will be before the elements of l2. Not tail-recursive (sum of the lengths of the arguments).

empty is [].

is_empty l returns true iff l = [].

• since 0.11

map ~f [a0; a1; …; an] applies function f in turn to [a0; a1; …; an]. Safe version of List.map.

cons x l is x::l.

• since 0.12

append l1 l2 returns the list that is the concatenation of l1 and l2. Safe version of List.append.

cons' l x is the same as x :: l. This is convenient for fold functions such as List.fold_left or Array.fold_left.

• since 3.3

cons_maybe (Some x) l is x :: l. cons_maybe None l is l.

• since 0.13

cons_when true x l is x :: l. cons_when false x l is l.

• since 3.13.1

filter ~f l returns all the elements of the list l that satisfy the predicate f. The order of the elements in the input list l is preserved. Safe version of List.filter.

fold_right ~f [a1; …; an] ~init is f a1 (f a2 ( … (f an init) … )). Safe version of List.fold_right.

fold_while ~f ~init l folds until a stop condition via ('a, `Stop) is indicated by the accumulator.

• since 0.8

fold_map ~f ~init l is a fold_left-like function, but it also maps the list to another list.

• since 0.14

fold_map_i ~f ~init l is a foldi-like function, but it also maps the list to another list.

• since 2.8

fold_on_map ~f ~reduce ~init l combines map ~f and fold_left ~reduce ~init in one operation.

• since 2.8

scan_left ~f ~init l returns the list [init; f init x0; f (f init x0) x1; …] where x0, x1, etc. are the elements of l.

• since 1.2, but only

• since 2.2 with labels

reduce f (hd::tl) returns Some (fold_left f hd tl). If l is empty, then None is returned.

• since 3.2

reduce_exn is the unsafe version of reduce.

• raises Invalid_argument

  if the given list is empty.

• since 3.2

fold_map2 ~f ~init l1 l2 is to fold_map what List.map2 is to List.map.

• raises Invalid_argument

  if the lists do not have the same length.

• since 0.16

fold_filter_map ~f ~init l is a fold_left-like function, but also generates a list of output in a way similar to filter_map.

• since 0.17

fold_filter_map_i ~f ~init l is a foldi-like function, but also generates a list of output in a way similar to filter_map.

• since 2.8

fold_flat_map ~f ~init l is a fold_left-like function, but it also maps the list to a list of lists that is then flatten'd.

• since 0.14

fold_flat_map_i ~f ~init l is a fold_left-like function, but it also maps the list to a list of lists that is then flatten'd.

• since 2.8

unfold ~f ~init builds up a list from a seed value. When f produces Some (next_seed, value), value is added to the output list and next_seed is used in the next call to f. However, when f produces None, list production ends. NOTE if f never produces None, then a stack overflow will occur. Therefore, great care must be taken to ensure that f will produce None.

• since 3.13

count ~f l counts how many elements of l satisfy predicate f.

• since 1.5, but only

• since 2.2 with labels

count_true_false ~f l returns a pair (int1,int2) where int1 is the number of elements in l that satisfy the predicate f, and int2 the number of elements that do not satisfy f.

• since 2.4

init len ~f is f 0; f 1; …; f (len-1).

• raises Invalid_argument

  if len < 0.

• since 0.6

combine [a1; …; an] [b1; …; bn] is [(a1,b1); …; (an,bn)]. Transform two lists into a list of pairs. Like List.combine but tail-recursive.

• raises Invalid_argument

  if the lists have distinct lengths.

• since 1.2, but only

• since 2.2 with labels

combine_gen l1 l2 transforms two lists into a gen of pairs. Lazy version of combine. Unlike combine, it does not fail if the lists have different lengths; instead, the output has as many pairs as the smallest input list.

• since 1.2, but only

• since 2.2 with labels

combine_shortest [a1; …; am] [b1; …; bn] is [(a1,b1); …; (am,bm)] if m <= n. Like combine but stops at the shortest list rather than raising.

• since 3.1

split [(a1,b1); …; (an,bn)] is ([a1; …; an], [b1; …; bn]). Transform a list of pairs into a pair of lists. A tail-recursive version of List.split.

• since 1.2, but only

• since 2.2 with labels

compare cmp l1 l2 compares the two lists l1 and l2 using the given comparison function cmp.

compare_lengths l1 l2 compare the lengths of the two lists l1 and l2. Equivalent to compare (length l1) (length l2) but more efficient.

• since 1.5, but only

• since 2.2 with labels

compare_length_with l x compares the length of the list l to an integer x. Equivalent to compare (length l) x but more efficient.

• since 1.5, but only

• since 2.2 with labels

equal p l1 l2 returns true if l1 and l2 are equal.

flat_map ~f l maps and flattens at the same time (safe). Evaluation order is not guaranteed.

flat_map_i ~f l maps with index and flattens at the same time (safe). Evaluation order is not guaranteed.

• since 2.8

flatten [l1]; [l2]; … concatenates a list of lists. Safe version of List.flatten.

product ~f l1 l2 computes the cartesian product of the two lists, with the given combinator f.

fold_product ~f ~init l1 l2 applies the function f with the accumulator init on all the pair of elements of l1 and l2. Fold on the cartesian product.

cartesian_product [[l1];[l2]; …; [ln]] produces the cartesian product of this list of lists, by returning all the ways of picking one element per sublist. NOTE the order of the returned list is unspecified. For example:

# cartesian_product [[1;2];[3];[4;5;6]] |> sort =
[[1;3;4];[1;3;5];[1;3;6];[2;3;4];[2;3;5];[2;3;6]];;
# cartesian_product [[1;2];[];[4;5;6]] = [];;
# cartesian_product [[1;2];[3];[4];[5];[6]] |> sort =
[[1;3;4;5;6];[2;3;4;5;6]];;

invariant: cartesian_product l = map_product id l.

• since 1.2, but only

• since 2.2 with labels

map_product_l ~f l maps each element of l to a list of objects of type 'b using f. We obtain [l1; l2; …; ln] where length l=n and li : 'b list. Then, it returns all the ways of picking exactly one element per li.

• since 1.2, but only

• since 2.2 with labels

diagonal l returns all pairs of distinct positions of the list l, that is the list of List.nth i l, List.nth j l if i < j.

partition_map_either ~f l maps f on l and gather results in lists:

• if f x = Left y, adds y to the first list.
• if f x = Right z, adds z to the second list.

• since 3.3

partition_filter_map ~f l maps f on l and gather results in lists:

• if f x = `Left y, adds y to the first list.
• if f x = `Right z, adds z to the second list.
• if f x = `Drop, ignores x.

• since 0.11

• deprecated

  use partition_filter_map instead

group_by ?hash ?eq l groups equal elements, regardless of their order of appearance. precondition: for any x and y, if eq x y then hash x = hash y must hold.

• since 2.3

join ~join_row a b combines every element of a with every element of b using join_row. If join_row returns None, then the two elements do not combine. Assume that b allows for multiple iterations.

• since 2.3

join_by ?eq ?hash key1 key2 ~merge la lb is a binary operation that takes two sequences a and b, projects their elements resp. with key1 and key2, and combine values (x,y) from (a,b) with the same key using merge. If merge returns None, the combination of values is discarded. precondition: for any x and y, if eq x y then hash x = hash y must hold.

• since 2.3

join_all_by ?eq ?hash key1 key2 ~merge la lb is a binary operation that takes two sequences a and b, projects their elements resp. with key1 and key2, and, for each key k occurring in at least one of them:

• compute the list l1 of elements of a that map to k
• compute the list l2 of elements of b that map to k
• call merge k l1 l2. If merge returns None, the combination of values is discarded, otherwise it returns Some c and c is inserted in the result.

• since 2.3

group_join_by ?eq ?hash key la lb associates to every element x of the first sequence, all the elements y of the second sequence such that eq x (key y). Elements of the first sequences without corresponding values in the second one are mapped to [] precondition: for any x and y, if eq x y then hash x = hash y must hold.

• since 2.3

sublists_of_len ?last ?offset n l returns sub-lists of l that have length n. By default, these sub-lists are non overlapping: sublists_of_len 2 [1;2;3;4;5;6] returns [1;2]; [3;4]; [5;6].

Examples:

• sublists_of_len 2 [1;2;3;4;5;6] = [[1;2]; [3;4]; [5;6]].
• sublists_of_len 2 ~offset:3 [1;2;3;4;5;6] = [1;2];[4;5].
• sublists_of_len 3 ~last:CCOption.return [1;2;3;4] = [1;2;3];[4].
• sublists_of_len 2 [1;2;3;4;5] = [[1;2]; [3;4]].

• parameter offset

  the number of elements skipped between two consecutive sub-lists. By default it is n. If offset < n, the sub-lists will overlap; if offset > n, some elements will not appear at all.

• parameter last

  if provided and the last group of elements g is such that length g < n, last g is called. If last g = Some g', g' is appended; otherwise g is dropped. If last = CCOption.return, it will simply keep the last group. By default, last = fun _ -> None, i.e. the last group is dropped if shorter than n.

• raises Invalid_argument

  if offset <= 0 or n <= 0. See CCList.sublists_of_len for more details.

• since 1.0, but only

• since 1.5 with labels

chunks n l returns consecutives chunks of size at most n from l. Each item of l will occur in exactly one chunk. Only the last chunk might be of length smaller than n. Invariant: (chunks n l |> List.flatten) = l.

• since 3.2

intersperse ~x l inserts the element x between adjacent elements of the list l.

• since 2.1, but only

• since 2.2 with labels

interleave [x1…xn] [y1…ym] is [x1,y1,x2,y2,…] and finishes with the suffix of the longest list.

• since 2.1, but only

• since 2.2 with labels

pure x is return x.

mguard c is pure () if c is true, [] otherwise. This is useful to define a list by comprehension, e.g.:

# let square_even xs =
      let* x = xs in
      let* () = mguard (x mod 2 = 0) in
      return @@ x * x;;
val square_even : int list -> int list = <fun>
# square_even [1;2;4;3;5;2];;
- : int list = [4; 16; 4]

• since 3.1

return x is x.

take n l takes the n first elements of the list l, drop the rest.

drop n l drops the n first elements of the list l, keep the rest.

hd_tl (x :: l) returns x, l.

• raises Failure

  if the list is empty.

• since 0.16

take_drop n l returns l1, l2 such that l1 @ l2 = l and length l1 = min (length l) n.

take_while ~f l returns the longest prefix of l for which f is true.

• since 0.13

drop_while ~f l drops the longest prefix of l for which f is true.

• since 0.13

take_drop_while ~f l = take_while ~f l, drop_while ~f l.

• since 1.2, but only

• since 2.2 with labels

last n l takes the last n elements of l (or less if l doesn't have that many elements).

head_opt l returns Some x (the first element of the list l) or None if the list l is empty.

• since 0.20

tail_opt l returns Some l' (the given list l without its first element) or None if the list l is empty.

• since 2.0

last_opt l returns Some x (the last element of l) or None if the list l is empty.

• since 0.20

find_pred ~f l finds the first element of l that satisfies f, or returns None if no element satisfies f.

• since 0.11

find_opt ~f l is the safe version of find.

• since 1.5, but only

• since 2.2 with labels

find_pred_exn ~f l is the unsafe version of find_pred.

• raises Not_found

  if no such element is found.

• since 0.11

find_map ~f l traverses l, applying f to each element. If for some element x, f x = Some y, then Some y is returned. Otherwise the call returns None.

• since 0.11

find_mapi ~f l is like find_map, but also pass the index to the predicate function.

• since 0.11

find_idx ~f x returns Some (i,x) where x is the i-th element of l, and f x holds. Otherwise returns None.

remove ~eq ~key l removes every instance of key from l. Tail-recursive.

• parameter eq

  equality function.

• since 0.11

filter_map ~f l is the sublist of l containing only elements for which f returns Some e. Map and remove elements at the same time.

keep_some l retains only elements of the form Some x. Like filter_map CCFun.id.

• since 1.3, but only

• since 2.2 with labels

keep_ok l retains only elements of the form Ok x.

• since 1.3, but only

• since 2.2 with labels

all_some l returns Some l' if all elements of l are of the form Some x, or None otherwise.

• since 1.3, but only

• since 2.2 with labels

all_ok l returns Ok l' if all elements of l are of the form Ok x, or Error e otherwise (with the first error met).

• since 1.3, but only

• since 2.2 with labels

sorted_mem ~cmp x l and mem x l give the same result for any sorted list l, but potentially more efficiently.

• since 3.5

sorted_merge ~cmp l1 l2 merges elements from both sorted list using the given comparison function cmp.

sorted_diff ~cmp l1 l2 returns the elements in l1 that are not in l2. Both lists are assumed to be sorted with respect to cmp and duplicate elements in the input lists are treated individually; for example, sorted_diff ~cmp [1;1;1;2;2;3] [1;2;2] would be [1;1;3]. It is the left inverse of sorted_merge; that is, sorted_diff ~cmp (sorted_merge ~cmp l1 l2) l2 is always equal to l1 for sorted lists l1 and l2.

• since 3.5

sort_uniq ~cmp l sorts the list l using the given comparison function cmp and remove duplicate elements.

sorted_merge_uniq ~cmp l1 l2 merges the sorted lists l1 and l2 and removes duplicates.

• since 0.10

sorted_diff_uniq ~cmp l1 l2 collects the elements in l1 that are not in l2 and then remove duplicates. Both lists are assumed to be sorted with respect to cmp and duplicate elements in the input lists are treated individually; for example, sorted_diff_uniq ~cmp [1;1;1;2;2] [1;2;2;2] would be [1]. sorted_diff_uniq ~cmp l1 l2 and uniq_succ ~eq (sorted_diff ~cmp l1 l2) always give the same result for sorted l1 and l2 and compatible cmp and eq.

• since 3.5

is_sorted ~cmp l returns true iff l is sorted (according to given order).

• parameter cmp

  the comparison function.

• since 0.17

sorted_insert ~cmp ?uniq x l inserts x into l such that, if l was sorted, then sorted_insert x l is sorted too.

• parameter uniq

  if true and x is already in sorted position in l, then x is not duplicated. Default false (x will be inserted in any case).

• since 0.17

sorted_remove ~cmp x l removes x from a sorted list l such that the return value is sorted too. By default, it is the left inverse of sorted_insert; that is, sorted_remove ~cmp x (sorted_insert ~cmp x l) is equal to l for any sorted list l.

• parameter all

  if true then all occurrences of x will be removed. Otherwise, only the first x will be removed (if any). Default false (only the first will be removed).

• since 3.5

uniq_succ ~eq l removes duplicate elements that occur one next to the other. Examples: uniq_succ [1;2;1] = [1;2;1]. uniq_succ [1;1;2] = [1;2].

• since 0.10

group_succ ~eq l groups together consecutive elements that are equal according to eq.

• since 0.11

mapi ~f l is like map, but the function f is applied to the index of the element as first argument (counting from 0), and the element itself as second argument.

iteri ~f l is like iter, but the function f is applied to the index of the element as first argument (counting from 0), and the element itself as second argument.

iteri2 ~f l1 l2 applies f to the two lists l1 and l2 simultaneously. The integer passed to f indicates the index of element.

• raises Invalid_argument

  when lists do not have the same length.

• since 2.0, but only

• since 2.2 with labels

foldi ~f ~init l is like fold but it also passes in the index of each element, from 0 to length l - 1 as additional argument to the folded function f. Tail-recursive.

foldi2 ~f ~init l1 l2 folds on the two lists l1 and l2, with index of each element passed to the function f. Computes f(… (f init i_0 l1_0 l2_0) …) i_n l1_n l2_n .

• raises Invalid_argument

  when lists do not have the same length.

• since 2.0, but only

• since 2.2 with labels

get_at_idx i l returns Some i-th element of the given list l or None if the list l is too short. If the index is negative, it will get element starting from the end of the list l.

nth_opt l n returns Some n-th element of l. Safe version of nth.

• raises Invalid_argument

  if the int is negative.

• since 1.5, but only

• since 2.2 with labels

get_at_idx_exn i l gets the i-th element of l, or

• raises Not_found

  if the index is invalid. The first element has index 0. If the index is negative, it will get element starting from the end of the list.

set_at_idx i x l replaces the i-th element with x (removes the old one), or does nothing if index is too high. If the index is negative, it will set element starting from the end of the list.

insert_at_idx i x l inserts x at i-th position, between the two existing elements. If the index is too high, append at the end of the list. If the index is negative, it will insert element starting from the end of the list.

remove_at_idx i l removes element at given index i. Does nothing if the index is too high. If the index is negative, it will remove element starting from the end of the list.

add_nodup ~eq x set adds x to set if it was not already present. Linear time.

• since 0.11

remove_one ~eq x set removes one occurrence of x from set. Linear time.

• since 0.11

mem ?eq x l is true iff x is equal to an element of l. A comparator function eq can be provided. Linear time.

subset ~eq l1 l2 tests if all elements of the list l1 are contained in the list l2 by applying eq.

uniq ~eq l removes duplicates in l w.r.t the equality predicate eq. Complexity is quadratic in the length of the list, but the order of elements is preserved. If you wish for a faster de-duplication but do not care about the order, use sort_uniq.

union ~eq l1 l2 is the union of the lists l1 and l2 w.r.t. the equality predicate eq. Complexity is product of length of inputs.

inter ~eq l1 l2 is the intersection of the lists l1 and l2 w.r.t. the equality predicate eq. Complexity is product of length of inputs.

range_by ~step i j iterates on integers from i to j included, where the difference between successive elements is step. Use a negative step for a decreasing list.

• raises Invalid_argument

  if step=0.

• since 0.18

range i j iterates on integers from i to j included. It works both for decreasing and increasing ranges.

range' i j is like range but the second bound j is excluded. For instance range' 0 5 = [0;1;2;3;4].

replicate n x replicates the given element x n times.

repeat n l concatenates the list l with itself n times.

assoc ~eq k alist returns the value v associated with key k in alist. Like Assoc.get_exn.

• since 2.0

assoc_opt ~eq k alist returns Some v if the given key k is present into alist, or None if not present. Like Assoc.get.

• since 1.5, but only

• since 2.0 with labels

assq_opt k alist returns Some v if the given key k is present into alist. Like Assoc.assoc_opt but use physical equality instead of structural equality to compare keys. Safe version of assq.

• since 1.5, but only

• since 2.0 with labels

mem_assoc ?eq k alist returns true iff k is a key in alist. Like Assoc.mem.

• since 2.0

remove_assoc ~eq k alist returns the alist without the first pair with key k, if any. Like Assoc.remove.

• since 2.0

random_choose l randomly chooses an element in the list l.

• raises Not_found

  if the list is empty.

to_string ?start ?stop ?sep item_to_string l print l to a string using sep as a separator between elements of l.

• since 2.7

to_iter l returns a iter of the elements of the list l.

• since 2.8

to_seq l returns a Seq.t of the elements of the list l. Renamed from to_std_seq since 3.0.

• since 3.0

of_iter iter builds a list from a given iter. In the result, elements appear in the same order as they did in the source iter.

• since 2.8

of_seq_rev seq builds a list from a given Seq.t, in reverse order. Renamed from of_std_seq_rev since 3.0.

• since 3.0

of_seq seq builds a list from a given Seq.t. In the result, elements appear in the same order as they did in the source Seq.t. Renamed from of_std_seq since 3.0.

• since 3.0

to_gen l returns a gen of the elements of the list l.

of_gen gen builds a list from a given gen. In the result, elements appear in the same order as they did in the source gen.

pp ?pp_start ?pp_stop ?pp_sep ppf l prints the contents of a list.