A polymorphic data structure parametrized by 'a to represent lists of elements of 'a while supporting constant time append operations.
One example of use is to manipulate a decorated text represented as a sequence of words. Eventually we are interested in producing the concatenation of all the word in some form, but we do not want to pay the allocation costs of buildings intermediate string concatenations.
This module is a generalization of the Rope module. Essentially: type Rope.t = string Appendable_list.t
The following operations all run in constant time: empty, of_list, singleton, append, concat, add_front, add_back
to_sequence builds a sequence where access to the next element has an amortized constant time.
All traversal operations such as iter and fold are tail recursive.
The monad exported by the module is semantically the same as the one in List. That is: bind t f applies f to each element of t and append the resulting list respecting the order in which the elements appear in t.
t >>= f returns a computation that sequences the computations represented by two monad elements. The resulting computation first does t to yield a value v, and then runs the computation returned by f v.
ignore_m t is map t ~f:(fun _ -> ()). ignore_m used to be called ignore, but we decided that was a bad name, because it shadowed the widely used Caml.ignore. Some monads still do let ignore = ignore_m for historical reasons.
fold_result t ~init ~f is a short-circuiting version of fold that runs in the Result monad. If f returns an Error _, that value is returned without any additional invocations of f.
fold_until t ~init ~f ~finish is a short-circuiting version of fold. If f returns Stop _ the computation ceases and results in that value. If f returns Continue _, the fold will proceed. If f never returns Stop _, the final result is computed by finish.
Example:
type maybe_negative =
| Found_negative of int
| All_nonnegative of { sum : int }
(** [first_neg_or_sum list] returns the first negative number in [list], if any,
otherwise returns the sum of the list. *)
let first_neg_or_sum =
List.fold_until ~init:0
~f:(fun sum x ->
if x < 0
then Stop (Found_negative x)
else Continue (sum + x))
~finish:(fun sum -> All_nonnegative { sum })
;;
let x = first_neg_or_sum [1; 2; 3; 4; 5]
val x : maybe_negative = All_nonnegative {sum = 15}
let y = first_neg_or_sum [1; 2; -3; 4; 5]
val y : maybe_negative = Found_negative -3
Returns a minimum (resp maximum) element from the collection using the provided compare function, or None if the collection is empty. In case of a tie, the first element encountered while traversing the collection is returned. The implementation uses fold so it has the same complexity as fold.