module BatEnum:sig..end
Enumerations are a representation of finite or infinite sequences of elements. In Batteries Included, enumerations are used pervasively, both as a uniform manner of reading and manipulating the contents of a data structure, or as a simple manner of reading or writing sequences of characters, numbers, strings, etc. from/to files, network connections or other inputs/outputs.
Enumerations are typically computed as needed, which allows the
definition and manipulation of huge (possibly infinite) sequences.
Manipulating an enumeration is a uniform and often comfortable way
of extracting subsequences (function BatEnum.filter or operator // et
al), converting sequences into other sequences (function BatEnum.map or
operators /@ and @/ et al), gathering information (function
BatEnum.scanl et al) or performing loops (functions BatEnum.iter and
BatEnum.map).
For instance, function BatRandom.enum_int creates an
infinite enumeration of random numbers. Combined with //
and BatEnum.map, we may turn this into an infinite enumeration of
squares of random even numbers:
map (fun x -> x * x) ( (Random.enum_int 100) // even )
Similarly, to obtain an enumeration of 50 random integers,
we may use BatEnum.take, as follows:
take 50 (Random.enum_int 100)
As most data structures in Batteries can be enumerated and built from enumerations, these operations may be used also on lists, arrays, hashtables, etc. When designing a new data structure, it is usuallly a good idea to allow enumeration and construction from an enumeration.
Note Enumerations are not thread-safe. You should not attempt
to access one enumeration from different threads.
Author(s): Nicolas Cannasse, David Rajchenbach-Teller
type 'a t
module type Enumerable =sig..end
enum.
include BatEnum.Enumerable
include BatInterfaces.Mappable
These functions consume the enumeration until
it ends or an exception is raised by the first
argument function.
val iter : ('a -> unit) -> 'a t -> unititer f e calls the function f with each elements of e in turn.val iter2 : ('a -> 'b -> unit) -> 'a t -> 'b t -> unititer2 f e1 e2 calls the function f with the next elements of e1 and
e2 repeatedly until one of the two enumerations ends.val exists : ('a -> bool) -> 'a t -> boolexists f e returns true if there is some x in e such
that f xval for_all : ('a -> bool) -> 'a t -> boolfor_all f e returns true if for every x in e, f x is trueval fold : ('b -> 'a -> 'b) -> 'b -> 'a t -> 'b
If e is empty, fold f v e returns v. Otherwise, fold v e
returns f (... (f (f v a0) a1) ...) aN where a0,a1..aN are the
elements of e. This function may be used, for instance, to
compute the sum of all elements of an enumeration e as follows:
fold ( + ) 0 e. Eager.
val reduce : ('a -> 'a -> 'a) -> 'a t -> 'afold, which uses the first element
of the enumeration as a default value.
reduce f e throws Not_found if e is empty, returns its only
element if e is a singleton, otherwise f (... (f (f a0 a1)
a2)...) aN where a0,a1..aN are the elements of e.
val sum : int t -> intsum returns the sum of the given int enum. If the argument is
empty, returns 0. Eagerval fsum : float t -> floatval kahan_sum : float t -> floatkahan_sum l returns a numerically-accurate sum of the floats of
l. See BatArray.fsum for more details.val fold2 : ('a -> 'b -> 'c -> 'c) -> 'c -> 'a t -> 'b t -> 'cfold2 is similar to fold but will fold over two enumerations at the
same time until one of the two enumerations ends.val scanl : ('b -> 'a -> 'b) -> 'b -> 'a t -> 'b tfold producing an enumeration of its intermediate values.
If e contains x0, x1, ..., scanl f init e is the enumeration
containing init, f init x0, f (f init x0) x1... Lazy.val scan : ('a -> 'a -> 'a) -> 'a t -> 'a tscan is similar to scanl but without the init value: if e
contains x0, x1, x2 ..., scan f e is the enumeration containing
x0, f x0 x1, f (f x0 x1) x2...
For instance, scan ( * ) (1 -- 10) will produce an enumeration
containing the successive values of the factorial function.
val iteri : (int -> 'a -> unit) -> 'a t -> unit
val iter2i : (int -> 'a -> 'b -> unit) -> 'a t -> 'b t -> unit
val foldi : (int -> 'a -> 'b -> 'b) -> 'b -> 'a t -> 'b
val fold2i : (int -> 'a -> 'b -> 'c -> 'c) -> 'c -> 'a t -> 'b t -> 'cval find : ('a -> bool) -> 'a t -> 'afind f e returns the first element x of e such that f x returns
true, consuming the enumeration up to and including the
found element.Not_found if no such element exists
in the enumeration, consuming the whole enumeration in the search.
Since find (eagerly) consumes a prefix of the enumeration, it
can be used several times on the same enumeration to find the
next element.
val find_map : ('a -> 'b option) -> 'a t -> 'bfind_map f e finds the first element x of e such that f x returns
Some r, then returns r. It consumes the enumeration up to and including
the found element.Not_found if no such element exists in the
enumeration, consuming the whole enumeration in the search.
Since find_map (eagerly) consumes a prefix of the enumeration, it can be
used several times on the same enumeration to find the next element.
val is_empty : 'a t -> boolis_empty e returns true if e does not contains any element.
Forces at most one element.val peek : 'a t -> 'a optionpeek e returns None if e is empty or Some x where x is
the next element of e. The element is not removed from the
enumeration.val get : 'a t -> 'a optionget e returns None if e is empty or Some x where x is
the next element of e, in which case the element is removed
from the enumeration.val get_exn : 'a t -> 'aget_exn e returns the first element of e.No_more_elements if e is empty.val push : 'a t -> 'a -> unitpush e x will add x at the beginning of e.val junk : 'a t -> unitjunk e removes the first element from the enumeration, if any.val clone : 'a t -> 'a tclone e creates a new enumeration that is copy of e. If e
is consumed by later operations, the clone will not get affected.val force : 'a t -> unitforce e forces the application of all lazy functions and the
enumeration of all elements, exhausting the enumeration.
An efficient intermediate data structure
of enumerated elements is constructed and e will now enumerate over
that data structure.
val take : int -> 'a t -> 'a ttake n e returns the prefix of e of length n, or e
itself if n is greater than the length of eval drop : int -> 'a t -> unitdrop n e removes the first n element from the enumeration, if any.val skip : int -> 'a t -> 'a tskip n e removes the first n element from the enumeration, if any,
then returns e.
This function has the same behavior as drop but is often easier to
compose with, e.g., skip 5 %> take 3 is a new function which skips
5 elements and then returns the next 3 elements.
val take_while : ('a -> bool) -> 'a t -> 'a ttake_while f e produces a new enumeration in which only remain
the first few elements x of e such that f xval drop_while : ('a -> bool) -> 'a t -> 'a tdrop_while p e produces a new enumeration in which only
all the first elements such that f e have been junked.val span : ('a -> bool) -> 'a t -> 'a t * 'a tspan test e produces two enumerations (hd, tl), such that
hd is the same as take_while test e and tl is the same
as drop_while test e.val break : ('a -> bool) -> 'a t -> 'a t * 'a tbreak test e is equivalent to span (fun x -> not (test x)) eval group : ('a -> 'b) -> 'a t -> 'a t tgroup test e divides e into an enumeration of enumerations,
where each sub-enumeration is the longest continuous enumeration
of elements whose test results are the same.
Enum.group (x -> x mod 2) [1;2;4;1] = [[1];[2;4];[1]]
Enum.group (fun x -> x mod 3) [1;2;4;1] = [[1];[2];[4;1]]
Enum.group (fun s -> s.[0]) ["cat"; "canary"; "dog"; "dodo"; "ant"; "cow"] = [["cat"; "canary"];["dog";"dodo"];["ant"];["cow"]]
Warning: The result of this operation cannot be directly cloned
safely; instead, reify to a non-lazy structure and read from that
structure multiple times.
val group_by : ('a -> 'a -> bool) -> 'a t -> 'a t tgroup_by eq e divides e into an enumeration of enumerations,
where each sub-enumeration is the longest continuous enumeration
of elements that are equal, as judged by eq.
Warning: The result of this operation cannot be directly cloned
safely; instead, reify to a non-lazy structure and read from that
structure multiple times.
val clump : int -> ('a -> unit) -> (unit -> 'b) -> 'a t -> 'b tclump size add get e runs add on size (or less at the end)
elements of e and then runs get to produce value for the
result enumeration. Useful to convert a char enum into string
enum.val cartesian_product : 'a t -> 'b t -> ('a * 'b) tcartesian_product e1 e2 computes the cartesian product of e1 and e2.
Pairs are enumerated in a non-specified order, but in fair enough an order
so that it works on infinite enums (i.e. even then, any pair is eventually
returned)These functions are lazy which means that they will create a new modified enumeration without actually enumerating any element until they are asked to do so by the programmer (using one of the functions above).
When the resulting enumerations of these functions are consumed, the
underlying enumerations they were created from are also consumed.
val map : ('a -> 'b) -> 'a t -> 'b tmap f e returns an enumeration over (f a0, f a1, ...) where
a0,a1... are the elements of e. Lazy.val mapi : (int -> 'a -> 'b) -> 'a t -> 'b tmapi is similar to map except that f is passed one extra argument
which is the index of the element in the enumeration, starting from 0 :
mapi f e returns an enumeration over (f 0 a0, f 1 a1, ...) where
a0,a1... are the elements of e.val filter : ('a -> bool) -> 'a t -> 'a tfilter f e returns an enumeration over all elements x of e such
as f x returns true. Lazy.
Note filter is lazy in that it returns a lazy enumeration, but
each element in the result is eagerly searched in the input
enumeration. Therefore, the access to a given element in the result
will diverge if it is preceded, in the input enumeration, by
infinitely many false elements (elements on which the predicate
p returns false).
Other functions that may drop an unbound number of elements
(filter_map, take_while, etc.) have the same behavior.
val filter_map : ('a -> 'b option) -> 'a t -> 'b tfilter_map f e returns an enumeration over all elements x such as
f y returns Some x , where y is an element of e.
filter_map works on infinite enumerations; see filter.
val append : 'a t -> 'a t -> 'a tappend e1 e2 returns an enumeration that will enumerate over all
elements of e1 followed by all elements of e2. Lazy.
Note The behavior of appending e to itself or to something
derived from e is not specified. In particular, cloning append e e
may destroy any sharing between the first and the second argument.
val prefix_action : (unit -> unit) -> 'a t -> 'a tprefix_action f e will behave as e but guarantees that f ()
will be invoked exactly once before the current first element of e
is read.
If prefix_action f e is cloned, f is invoked only once, during
the cloning. If prefix_action f e is counted, f is invoked
only once, during the counting.
May be used for signalling that reading starts or for performing
delayed evaluations.
val suffix_action : (unit -> unit) -> 'a t -> 'a tsuffix_action f e will behave as e but guarantees that f ()
will be invoked after the contents of e are exhausted.
If suffix_action f e is cloned, f is invoked only once, when
the original enumeration is exhausted. If suffix_action f e
is counted, f is only invoked if the act of counting
requires a call to force.
May be used for signalling that reading stopped or for performing
delayed evaluations.
val concat : 'a t t -> 'a tconcat e returns an enumeration over all elements of all enumerations
of e.val flatten : 'a t t -> 'a tBatEnum.concatval concat_map : ('a -> 'b t) -> 'a t -> 'b tBatEnum.Monad.bind, with flipped arguments.
concat_map f e is the same as concat (map f e).
In this section the word shall denotes a semantic
requirement. The correct operation of the functions in this
interface are conditional on the client meeting these
requirements.
exception No_more_elements
next function of make
or from when no more elements can be enumerated, it shall not
be raised by any function which is an argument to any
other function specified in the interface.exception Infinite_enum
count function of make when attempting to count an infinite enum.val empty : unit -> 'a tval make : next:(unit -> 'a) ->
count:(unit -> int) -> clone:(unit -> 'a t) -> 'a t
next function shall return the next element of the
enumeration or raise No_more_elements if the underlying data structure
does not have any more elements to enumerate.count function shall return the actual number of remaining
elements in the enumeration or may raise Infinite_enum if it is known
that the enumeration is infinite.clone function shall create a clone of the enumeration
such as operations on the original enumeration will not affect the
clone.
For some samples on how to correctly use make, you can have a look
at implementation of BatList.enum.
val from : (unit -> 'a) -> 'a tfrom next creates an enumeration from the next function.
next shall return the next element of the enumeration or raise
No_more_elements when no more elements can be enumerated. Since the
enumeration definition is incomplete, a call to count will result in
a call to force that will enumerate all elements in order to
return a correct value.val from_while : (unit -> 'a option) -> 'a tfrom_while next creates an enumeration from the next function.
next shall return Some x where x is the next element of the
enumeration or None when no more elements can be enumerated. Since the
enumeration definition is incomplete, a call to clone or count will
result in a call to force that will enumerate all elements in order to
return a correct value.val from_loop : 'b -> ('b -> 'a * 'b) -> 'a tfrom_loop data next creates a (possibly infinite) enumeration from
the successive results of applying next to data, then to the
result, etc. The list ends whenever the function raises
BatEnum.No_more_elements.val seq : 'a -> ('a -> 'a) -> ('a -> bool) -> 'a tseq init step cond creates a sequence of data, which starts
from init, extends by step, until the condition cond
fails. E.g. seq 1 ((+) 1) ((>) 100) returns 1, 2, ... 99. If cond
init is false, the result is empty.val unfold : 'b -> ('b -> ('a * 'b) option) -> 'a tfrom_loop, except uses option type to signal the end of the enumeration.
unfold data next creates a (possibly infinite) enumeration from
the successive results of applying next to data, then to the
result, etc. The enumeration ends whenever the function returns None
Example: Enum.unfold n (fun x -> if x = 1 then None else Some
(x, if x land 1 = 1 then 3 * x + 1 else x / 2)) returns the
hailstone sequence starting at n.
val init : int -> (int -> 'a) -> 'a tinit n f creates a new enumeration over elements
f 0, f 1, ..., f (n-1)val singleton : 'a -> 'a tval repeat : ?times:int -> 'a -> 'a trepeat ~times:n x creates a enum sequence filled with n times of
x. It return infinite enum when ~times is absent. It returns empty
enum when times <= 0val cycle : ?times:int -> 'a t -> 'a tcycle is similar to repeat, except that the content to fill is a
subenum rather than a single element. Note that times represents the
times of repeating not the length of enum. When ~times is absent the
result is an infinite enum.val delay : (unit -> 'a t) -> 'a tdelay (fun () -> e) produces an enumeration which behaves as e.
The enumeration itself will only be computed when consumed.
A typical use of this function is to explore lazily non-trivial data structures, as follows:
type 'a tree = Leaf
| Node of 'a * 'a tree * 'a tree
let enum_tree =
let rec aux = function
| Leaf -> BatEnum.empty ()
| Node (n, l, r) -> BatEnum.append (BatEnum.singleton n)
(BatEnum.append (delay (fun () -> aux l))
(delay (fun () -> aux r)))
val to_object : 'a t -> (< clone : 'b; count : int; next : 'a > as 'b)to_object e returns a representation of e as an object.val of_object : (< clone : 'b; count : int; next : 'a > as 'b) -> 'a tof_object e returns a representation of an object as an enumerationval enum : 'a t -> 'a tval of_enum : 'a t -> 'a tval count : 'a t -> intcount e returns the number of remaining elements in e without
consuming the enumeration.
Depending of the underlying data structure that is implementing the
enumeration functions, the count operation can be costly, and even sometimes
can cause a call to force.
val fast_count : 'a t -> boolcount you can call the fast_count
function that will give an hint about count implementation. Basically, if
the enumeration has been created with make or init or if force has
been called on it, then fast_count will return true.val hard_count : 'a t -> inthard_count returns the number of remaining in elements in e,
consuming the whole enumeration somewhere along the way. This
function is always at least as fast as the fastest of either
count or a fold on the elements of t.
This function is useful when you have opened an enumeration for
the sole purpose of counting its elements (e.g. the number of
lines in a file).
val range : ?until:int -> int -> int trange p until:q creates an enumeration of integers [p, p+1, ..., q].
If until is omitted, the enumeration is not bounded. Behaviour is
not-specified once max_int has been reached.val dup : 'a t -> 'a t * 'a tdup stream returns a pair of streams which are identical to stream. Note
that stream is a destructive data structure, the point of dup is to
return two streams can be used independently.val combine : 'a t * 'b t -> ('a * 'b) tcombine transform a pair of stream into a stream of pairs of corresponding
elements. If one stream is short, excess elements of the longer stream are
ignored.val uncombine : ('a * 'b) t -> 'a t * 'b tuncombine is the opposite of combineval merge : ('a -> 'a -> bool) -> 'a t -> 'a t -> 'a tmerge test a b merge the elements from a and b into a single
enumeration. At each step, test is applied to the first element xa of
a and the first element xb of b to determine which should get first
into resulting enumeration. If test xa xb returns true, xa (the
first element of a) is used, otherwise xb is used. If a or b runs
out of elements, the process will append all elements of the other
enumeration to the result.
For example, if a and b are enumerations of integers sorted
in increasing order, then merge (<) a b will also be sorted.
val interleave : 'a t array -> 'a tinterleave enums creates a new enumeration from an array of enumerations.
The new enumeration first yields the first elements of the enumerations in
the supplied order, then second elements, etc. Thus, a sequence
[| [x11 ; x12 ; ...] ; [x21 ; x22, ...] , ... [xN1 ; xN2 ; ...] |] becomes
[ x11 ; x12 ; ... ; xN1 ; x21 ; x22 ; ... ; xN2 ; x31 ; ... ].val uniq : 'a t -> 'a tuniq e returns a duplicate of e with repeated values
omitted (similar to unix's uniq command).
It uses structural equality to compare consecutive elements.val uniqq : 'a t -> 'a tuniqq e behaves as uniq e except it uses physical equality
to compare consecutive elements.val uniq_by : ('a -> 'a -> bool) -> 'a t -> 'a tuniqq cmp e behaves as uniq e except it allows to specify a
comparison function.val switch : ('a -> bool) -> 'a t -> 'a t * 'a tswitch test enum splits enum into two enums, where the first enum have
all the elements satisfying test, the second enum is opposite. The
order of elements in the source enum is preserved.val partition : ('a -> bool) -> 'a t -> 'a t * 'a tswitchval arg_min : ('a -> 'b) -> 'a t -> 'a
val arg_max : ('a -> 'b) -> 'a t -> 'aarg_min f xs returns the x in xs for which f x is minimum.
Similarly for arg_max, except it returns the maximum. If
multiple values reach the maximum, one of them is
returned. (currently the first, but this is not guaranteed)
Example: -5 -- 5 |> arg_min (fun x -> x * x + 6 * x - 5) = -3
Example: List.enum ["cat"; "canary"; "dog"; "dodo"; "ant"; "cow"] |> arg_max String.length = "canary"
Raises Invalid_argument if the input enum is empty
val while_do : ('a -> bool) ->
('a t -> 'a t) -> 'a t -> 'a twhile_do cont f e is a loop on e using f as body and cont as
condition for continuing.
If e contains elements x0, x1, x2..., then if cont x0 is false,
x0 is returned as such and treatment stops. On the other hand, if cont x0
is true, f x0 is returned and the loop proceeds with x1...
Note that f is used as halting condition after the
corresponding element has been added to the result stream.
This module groups together all infix operators so that
you can open it without opening the whole batEnum module.
module Infix:sig..end
val (--) : int -> int -> int t
val (--^) : int -> int -> int t
val (--.) : float * float -> float -> float t
val (---) : int -> int -> int t
val (--~) : char -> char -> char t
val (//) : 'a t -> ('a -> bool) -> 'a t
val (/@) : 'a t -> ('a -> 'b) -> 'b t
val (@/) : ('a -> 'b) -> 'a t -> 'b t
val (//@) : 'a t -> ('a -> 'b option) -> 'b t
val (@//) : ('a -> 'b option) -> 'a t -> 'b tmodule WithMonad:
module Monad:sig..end
val print : ?first:string ->
?last:string ->
?sep:string ->
('a BatInnerIO.output -> 'b -> unit) ->
'a BatInnerIO.output -> 'b t -> unitval print_at_most : ?first:string ->
?last:string ->
?sep:string ->
limit:int ->
('a BatInnerIO.output -> 'b -> unit) ->
'a BatInnerIO.output -> 'b t -> unitprint_at_most pp limit out enum consumes enum to print its elements
into out (using pp to print individual elements).
At most limit arguments are printed, if more elements are
available an ellipsis "..." is added.Invalid_argument if the limit is <= 0.val compare : ('a -> 'a -> int) -> 'a t -> 'a t -> intcompare cmp a b compares enumerations a and b
by lexicographical order using comparison cmp.compare cmp a' b', where a' and b' are
respectively equal to a and b without their first
element, if both a and b are non-empty and cmp x y = 0,
where x is the first element of a and y is the first
element of bval ord : ('a -> 'a -> BatOrd.order) -> 'a t -> 'a t -> BatOrd.order
val equal : ('a -> 'a -> bool) -> 'a t -> 'a t -> boolequal eq a b returns true when a and b contain
the same sequence of elements.BatEnum with functions
behaving slightly differently but having the same name. This is by design:
the functions meant to override the corresponding functions of BatEnum.module Exceptionless:sig..end
BatEnum without exceptions.
module Labels:sig..end
BatEnum with labels.