package batteries

Empty_list is raised when an operation applied on an empty list is invalid. For instance, hd nil will raise Empty_list.

Invalid_index is raised when an indexed access on a list is out of list bounds.

Different_list_size is raised when applying functions such as iter2 on two lists having different size.

See from and from_loop for more information on this exception.

The type of a lazy list.

The empty list.

Build a list from a head and a tail.

As cons: x^:^l is the lazy list with head x and tail l

peek l returns the first element of l, if it exists.

get l returns the head and tail of l, if l is not empty.

from next creates a (possibly infinite) lazy list from the successive results of next.

• raises LazyList.No_more_elements

  to denote the end of the list.

from next creates a (possibly infinite) lazy list from the successive results of next. The list ends whenever next returns None.

seq data next cond creates a lazy list from the successive results of applying next to data, then to the result, etc. The list continues until the condition cond fails. For example, seq 1 ((+) 1) ((>) 100) returns [^1, 2, ... 99^]. If cond init is false, the result is empty. To create an infinite lazy list, pass (fun _ -> true) as cond.

unfold data next creates a (possibly infinite) lazy list from the successive results of applying next to data, then to the result, etc. The list ends whenever next returns None. The function next should return a pair option whose first element will be the current value of the sequence; the second element will be passed (lazily) to next in order to compute the following element. One example of a use of unfold is to make each element of the resulting sequence to depend on the previous two elements, as in this Fibonacci sequence definition:

let data = (1, 1)
let next (x, y) = Some (x, (y, x + y))
let fib = unfold data next

The first element x of the pair within Some will be the current value of the sequence; the next value of the sequence, and the one after that, are recorded as y and x + y respectively.

from_loop data next creates a (possibly infinite) lazy list from the successive results of applying next to data, then to the result, etc. The list ends whenever the function raises LazyList.No_more_elements. (For further information see unfold; ignore references to option and Some.)

Similar to Array.init, init n f returns the lazy list containing the results of (f 0),(f 1).... (f (n-1)).

• raises Invalid_argument

  "LazyList.init" if n < 0.

Similar to String.make, make n x returns a list containing n elements x.

Compute lazily a range of integers a .. b as a lazy list.

The range is empty if b <= a.

Eager iteration

iter f [^ a0; a1; ...; an ^] applies function f in turn to a0; a1; ...; an. It is equivalent to begin f a0; f a1; ...; f an; () end. In particular, it causes all the elements of the list to be evaluated.

Eager iteration, with indices

iteri f [^ a0; a1; ...; an ^] applies function f in turn to a0; a1;...; an, along with the corresponding 0,1..n index. It is equivalent to begin f 0 a0; f 1 a1; ...; f n an; () end. In particular, it causes all the elements of the list to be evaluated.

Lazy map

map f [^ a0; a1; ... ^] builds the list [^ f a0; f a1; ... ^] with the results returned by f. Not tail-recursive. Evaluations of f take place only when the contents of the list are forced.

Lazy map, with indices

mapi f [^ a0; a1; ... ^] builds the list [^ f 0 a0; f 1 a1; ... ^] with the results returned by f. Not tail-recursive. Evaluations of f take place only when the contents of the list are forced.

Eager fold_left

LazyList.fold_left f a [^ b0; b1; ...; bn ^] is f (... (f (f a b0) b1) ...) bn. This causes evaluation of all the elements of the list.

Eager fold_right

fold_right f b [^ a0; a1; ...; an ^] is f a0 (f a1 (... (f an b) ...)). This causes evaluation of all the elements of the list. Not tail-recursive.

Note that the argument order of this function is the same as fold_left above, but inconsistent with other fold_right functions in Batteries. We hope to fix this inconsistency in the next compatibility-breaking release, so you should rather use the more consistent eager_fold_right.

• since 2.2.0

Eager fold_right

As fold_right above, but with the usual argument order for a fold_right.

Just as fold_left on a structure 'a t turns an element-level function of type ('b -> 'a -> 'b), with the accumulator argument 'b on the left, into a structure-level function 'b -> 'a t -> 'b, fold_right turns a function ('a -> 'b -> 'b) (accumulator on the right) into a 'a t -> 'b -> 'b.

Lazy fold_right lazy_fold_right f (Cons (a0, Cons (a1, Cons (a2, nil)))) b is lazy (f a0 (lazy (f a1 (lazy (f a2 b))))).

Forcing the result of lazy_fold_right forces the first element of the list; the rest is forced only if/when the function f forces its accumulator argument.

• since 2.1

mem x l determines if x is part of l. Evaluates all the elements of l which appear before x.

As mem, but with physical equality

find p l returns the first element of l such as p x returns true.

• raises Not_found

  if such an element has not been found.

rfind p l returns the last element x of l such as p x returns true.

• raises Not_found

  if such element as not been found.

find_exn p e l returns the first element of l such as p x returns true or raises e if such an element has not been found.

rfind_exn p e l returns the last element of l such as p x returns true or raises e if such an element has not been found.

findi p e l returns the first element ai of l along with its index i such that p i ai is true.

• raises Not_found

  if no such element has been found.

rfindi p e l returns the last element ai of l along with its index i such that p i ai is true.

• raises Not_found

  if no such element has been found.

index_of e l returns the index of the first occurrence of e in l, or None if there is no occurrence of e in l

index_ofq e l behaves as index_of e l except it uses physical equality

index_of e l returns the index of the last occurrence of e in l, or None if there is no occurrence of e in l

rindex_ofq e l behaves as rindex_of e l except it uses physical equality

Compute and return the first node from the list as a Cons. This differs from hd, which returns the first element (the first component of the first node).

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

Causes the evaluation of all the elements of the list.

Returns true if the list is empty, false otherwise.

would_at_fail l n returns true if l contains strictly less than n elements, false otherwise

Return the first element of the given list.

• raises Empty_list

  if the list is empty.

  Note: this function does not comply with the usual exceptionless error-management recommendations, as doing so would essentially render it useless.

Return the given list without its first element.

• raises Empty_list

  if the list is empty.

  Note: this function does not comply with the usual exceptionless error-management recommendations, as doing so would essentially render it useless.

As hd

Returns the last element of the list.

• raises Empty_list

  if the list is empty. This function takes linear time and causes the evaluation of all elements of the list

at l n returns the element at index n (starting from 0) in the list l.

• raises Invalid_index

  is the index is outside of l bounds.

Obsolete. As at

assoc a l returns the value associated with key a in the list of pairs l. That is, assoc a [^ ...; (a,b); ...^] = b if (a,b) is the leftmost binding of a in list l.

• raises Not_found

  if there is no value associated with a in the list l.

As assoc but with physical equality

As assoc but simply returns true if a binding exists, false otherwise.

As mem_assoc but with physical equality.

Eager list reversal.

Evaluate a list and append another list after this one.

Cost is linear in the length of the first list, not tail-recursive.

Eager reverse-and-append

Cost is linear in the length of the first list, tail-recursive.

Lazy append

Cost is constant. All evaluation is delayed until the contents of the list are actually read. Reading itself is delayed by a constant.

As lazy append

Lazy concatenation of a lazy list of lazy lists

Lazy concatenation of a list of lazy lists

split_at n l returns two lists l1 and l2, l1 containing the first n elements of l and l2 the others.

• raises Invalid_index

  if n is outside of l size bounds.

Obsolete. As split_at.

unique cmp l returns the list l without any duplicate element. Default comparator ( = ) is used if no comparison function specified.

as unique except only uses an equality function. Use for short lists when comparing is expensive compared to equality testing

• since 1.3.0

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

remove_if cmp l is similar to remove, but with cmp used instead of ( = ).

remove_all l x is similar to remove but removes all elements that are equal to x and not only the first one.

remove_all_such f l is similar to remove but removes all elements that satisfy the predicate f and not only the first one.

take n l returns up to the n first elements from list l, if available.

drop n l returns l without the first n elements, or the empty list if l have less than n elements.

take_while f xs returns the first elements of list xs which satisfy the predicate f.

drop_while f xs returns the list xs with the first elements satisfying the predicate f dropped.

combinations l yields a list of all combinations of elements of l. Each combination selects a "subset" of the elements of l (duplicates are considered as distinct elements).

permutations l yields a lazy list of all permutations of the list l. Every permutation has the same elements as l, but in a different order. There are factorial (length l) permutations.

Eager conversion to string.

Lazy conversion to stream.

Eager conversion to array.

Lazy conversion to enumeration

Lazy conversion from lists

Albeit slower than eager conversion, this is the default mechanism for converting from regular lists to lazy lists. This for two reasons : * if you're using lazy lists, total speed probably isn't as much an issue as start-up speed * this will let you convert regular infinite lists to lazy lists.

Lazy conversion from stream.

Lazy conversion from enum.

Eager conversion from lists.

This function is much faster than of_list but will freeze on cyclic lists.

Eager conversion from array

Lazy filtering.

filter p l returns all the elements of the list l that satisfy the predicate p. The order of the elements in the input list is preserved.

Eager existential.

exists p [^ a0; a1; ... ^] checks if at least one element of the list satisfies the predicate p. That is, it returns (p a0) || (p a1) || ... .

Eager universal.

for_all p [^ a0; a1; ... ^] checks if all elements of the list satisfy the predicate p. That is, it returns (p a0) && (p a1) && ... .

Lazily eliminate some elements and transform others.

filter_map f [^ a0; a1; ... ^] applies lazily f to each a0, a1... If f ai evaluates to None, the element is not included in the result. Otherwise, if f ai evaluates to Some x, element x is included in the result.

This is equivalent to match f a0 with | Some x0 -> x0 ^:^ (match f a1 with | Some x1 -> x1 ^:^ ... | None -> [^ ^]) | None -> [^ ^] .

An infinite list of nothing

Sort the list using optional comparator (by default compare).

map2 f [^ a0; a1; ...^] [^ b0; b1; ... ^] is [^ f a0 b0; f a1 b1; ... ^].

• raises Different_list_size

  if the two lists have different lengths. Not tail-recursive, lazy. In particular, the exception is raised only after the shortest list has been entirely consumed.

iter2 f [^ a0; ...; an ^] [^ b0; ...; bn ^] calls in turn f a0 b0; ...; f an bn. Tail-recursive, eager.

• raises Different_list_size

  if the two lists have different lengths.

fold_left2 f a [^ b0; b1; ...; bn ^] [^ c0; c1; ...; cn ^] is f (... (f (f a b0 c0) b1 c1) ...) bn cn. Eager.

• raises Different_list_size

  if the two lists have different lengths.

fold_right2 f [^ a0; a1; ...; an ^] [^ b0; b1; ...; bn ^] c is f a0 b0 (f a1 b1 (... (f an bn c) ...)). Eager.

• raises Different_list_size

  if the two lists have different lengths. Tail-recursive.

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

• raises Different_list_size

  if the two lists have different lengths.

equal eq s1 s2 compares elements of s1 and s2 pairwise using eq and returns true if all elements pass the test and the lists have the same length; otherwise it returns false. Examples:

equal (=) (range 0 4) (range 0 4) (* true *)

(* Make lazy lists of lazy lists: *)
let s1 = init 5 (range 0)
let s2 = init 5 (range 0)
equal (equal (=)) s1 s2 (* true *)

(Calling = directly on a pair of lazy lists may succeed but is not guaranteed to behave consistently.)

Note that on lists of equal length, equal and for_all2 can perform the same function; their intended uses differ, however, as signaled by behavior on lists of different lengths.

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

• raises Different_list_size

  if the two lists have different lengths.

Transform a pair of lists into a list of pairs: combine [^ a0; a1; ... ^] [^ b0; b1; ... ^] is [^ (a0, b0); (a1, b1); ... ^].

• raises Different_list_size

  if the two lists have different lengths. Tail-recursive, lazy.

Divide a list of pairs into a pair of lists.

Exceptionless counterparts for error-raising operations

Operations on LazyList with labels.