Up
# module Enum

: sig
###### Final functions

###### Useful functions

###### Lazy constructors

###### Constructors

###### Counting

Enumeration over abstract collection of elements.

Enumerations are entirely functional and most of the operations do not actually require the allocation of data structures. Using enumerations to manipulate data is therefore efficient and simple. All data structures in ExtLib such as lists, arrays, etc. have support to convert from and to enumerations.

#

type 'a t

These functions consume the enumeration until it ends or an exception is raised by the first argument function.

#

val iter : ('a -> unit) -> 'a t -> unit

`iter f e`

calls the function `f`

with each elements of `e`

in turn.

#

val fold : ('a -> 'b -> 'b) -> 'b -> 'a t -> 'b

`fold f v e`

returns `v`

if `e`

is empty,
otherwise `f aN (... (f a2 (f a1 v)) ...)`

where a1..N are
the elements of `e`

.

Indexed functions : these functions are similar to previous ones except that they call the function with one additional argument which is an index starting at 0 and incremented after each call to the function.

#

val find : ('a -> bool) -> 'a t -> 'a

`find 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, or, raises `Not_found`

if no such element exists
in the enumeration, consuming the whole enumeration in the search.

Since `find`

consumes a prefix of the enumeration, it can be used several
times on the same enumeration to find the next element.

#

val peek : 'a t -> 'a option

`peek 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 option

`get 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 next : 'a t -> 'a

`next e`

returns the next element of `e`

(and removes it from enumeration).

Raises

`No_more_elements`

if enumeration is empty
#

val force : 'a t -> unit

`force 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.

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.

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

This exception *shall* be raised by the `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.

#

val make : next:(unit -> 'a) -> count:(unit -> int) -> clone:(unit -> 'a t) -> 'a t

This function creates a fully defined enumeration.

- the
`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. - the
`count`

function*shall*return the actual number of remaining elements in the enumeration. - the
`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 `ExtList.enum`

.

#

val from : (unit -> 'a) -> 'a t

`from 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 `clone`

or `count`

will
result in a call to `force`

that will enumerate all elements in order to
return a correct value.

#

val init : int -> (int -> 'a) -> 'a t

`init n f`

creates a new enumeration over elements
`f 0, f 1, ..., f (n-1)`

end