0
* Enum - enumeration over abstract collection of elements.
0
* Copyright (C) 2003 Nicolas Cannasse
0
+ * 2008 David Teller (contributor)
0
* This library is free software; you can redistribute it and/or
0
* modify it under the terms of the GNU Lesser General Public
0
* License along with this library; if not, write to the Free Software
0
* Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
0
(** Enumeration over abstract collection of elements.
0
Enumerations are entirely functional and most of the operations do not
0
@@ -106,6 +106,17 @@ val force : 'a t -> unit
0
of enumerated elements is constructed and [e] will now enumerate over
0
that data structure. *)
0
+val drop : int -> 'a t -> unit
0
+(** [drop n e] removes the first [n] element from the enumeration, if any. *)
0
+val take_while : ('a -> bool) -> 'a t -> 'a t
0
+ (** [take_while f e] produces a new enumeration in which only remain
0
+ the first few elements [x] of [e] such that [f x] *)
0
+val drop_while : ('a -> bool) -> 'a t -> 'a t
0
+ (** [drop_while p e] produces a new enumeration in which only
0
+ all the first elements such that [f e] have been junked.*)
0
(** {6 Lazy constructors}
0
These functions are lazy which means that they will create a new modified
0
@@ -154,6 +165,10 @@ exception No_more_elements
0
other function specified in the interface.
0
+exception Infinite_enum
0
+(** As a convenience for debugging, this exception {i may} be raised by
0
+ the [count] function of [make] when attempting to count an infinite enum.*)
0
val empty : unit -> 'a t
0
(** The empty enumeration : contains no element *)
0
@@ -163,7 +178,8 @@ val make : next:(unit -> 'a) -> count:(unit -> int) -> clone:(unit -> 'a t) -> '
0
enumeration or raise [No_more_elements] if the underlying data structure
0
does not have any more elements to enumerate.}
0
{li the [count] function {i shall} return the actual number of remaining
0
- elements in the enumeration.}
0
+ elements in the enumeration or {i may} raise [Infinite_enum] if it is known
0
+ that the enumeration is infinite.}
0
{li the [clone] function {i shall} create a clone of the enumeration
0
such as operations on the original enumeration will not affect the
0
@@ -176,14 +192,55 @@ val from : (unit -> 'a) -> 'a t
0
(** [from next] creates an enumeration from the [next] function.
0
[next] {i shall} return the next element of the enumeration or raise
0
[No_more_elements] when no more elements can be enumerated. Since the
0
- enumeration definition is incomplete, a call to [clone] or [count] will
0
- result in a call to [force] that will enumerate all elements in order to
0
+ enumeration definition is incomplete, a call to [count] will result in
0
+ a call to [force] that will enumerate all elements in order to
0
return a correct value. *)
0
+val from_while : (unit -> 'a option) -> 'a t
0
+(** [from_while next] creates an enumeration from the [next] function.
0
+ [next] {i shall} return [Some x] where [x] is the next element of the
0
+ enumeration or [None] when no more elements can be enumerated. Since the
0
+ enumeration definition is incomplete, a call to [clone] or [count] will
0
+ result in a call to [force] that will enumerate all elements in order to
0
+ return a correct value. *)
0
+val from_loop: 'b -> ('b -> ('a * 'b)) -> 'a t
0
+ (**[from_loop data next] creates a (possibly infinite) enumeration from
0
+ the successive results of applying [next] to [data], then to the
0
+ result, etc. The list ends whenever the function raises
0
+ {!LazyList.No_more_elements}*)
0
+val seq : 'a -> ('a -> 'a) -> ('a -> bool) -> 'a t
0
+ (** [seq init step cond] creates a sequence of data, which starts
0
+ from [init], extends by [step], until the condition [cond]
0
+ fails. E.g. [seq 1 ((+) 1) ((>) 100)] returns [1, 2, ... 99]. If [cond
0
+ init] is false, the result is empty. *)
0
+val seq_hide: 'b -> ('b -> ('a * 'b) option) -> 'a t
0
+ (**More powerful version of [seq], with the ability of hiding data.
0
+ [seq_hide data next] creates a (possibly infinite) enumeration from
0
+ the successive results of applying [next] to [data], then to the
0
+ result, etc. The list ends whenever the function returns [None]*)
0
val init : int -> (int -> 'a) -> 'a t
0
(** [init n f] creates a new enumeration over elements
0
[f 0, f 1, ..., f (n-1)] *)
0
+val singleton : 'a -> 'a t
0
+(** Create an enumeration consisting in exactly one element.*)
0
+val repeat : ?times:int -> 'a -> 'a t
0
+ (** [repeat ~times:n x] creates a enum sequence filled with [n] times of
0
+ [x]. It return infinite enum when [~times] is absent. It returns empty
0
+ enum when [times <= 0] *)
0
+val cycle : ?times:int -> 'a t -> 'a t
0
+ (** [cycle] is similar to [repeat], except that the content to fill is a
0
+ subenum rather than a single element. Note that [times] represents the
0
+ times of repeating not the length of enum. *)
0
val count : 'a t -> int
0
@@ -199,3 +256,72 @@ val fast_count : 'a t -> bool
0
function that will give an hint about [count] implementation. Basically, if
0
the enumeration has been created with [make] or [init] or if [force] has
0
been called on it, then [fast_count] will return true. *)
0
+val range : ?until:int -> int -> int t
0
+(** [range p until:q] creates an enumeration of integers [[p, p+1, ..., q]].
0
+ If [until] is omitted, the enumeration is not bounded. Behaviour is
0
+ not-specified once [max_int] has been reached.*)
0
+val ( -- ) : int -> int -> int t
0
+(** As [range], without the label.
0
+ [5 -- 10] is the enumeration 5,6,7,8,9,10.
0
+ [10 -- 5] is the empty enumeration*)
0
+val ( --- ) : int -> int -> int t
0
+(** As [--], but accepts enumerations in reverse order.
0
+ [5 --- 10] is the enumeration 5,6,7,8,9,10.
0
+ [10 --- 5] is the enumeration 10,9,8,7,6,5.*)
0
+val ( ~~ ) : char -> char -> char t
0
+(** As ( -- ), but for characters.*)
0
+val switchn: int -> ('a -> int) -> 'a t -> 'a t array
0
+ (** [switchn] is the array version of [switch]. [switch n f fl] split [fl] to an array of [n] enums, [f] is
0
+ applied to each element of [fl] to decide the id of its destination
0
+val switch : ('a -> bool) -> 'a t -> 'a t * 'a t
0
+ (** [switch test enum] split [enum] into two enums, where the first enum have
0
+ all the elements satisfying [test], the second enum is opposite. The
0
+ order of elements in the source enum is preserved. *)
0
+module ExceptionLess : sig
0
+ val find : ('a -> bool) -> 'a t -> 'a option
0
+ (** [find f e] returns [Some x] where [x] is the first element [x] of [e]
0
+ such that [f x] returns [true], consuming the enumeration up to and
0
+ including the found element, or [None] if no such element exists
0
+ in the enumeration, consuming the whole enumeration in the search.
0
+ Since [find] consumes a prefix of the enumeration, it can be used several
0
+ times on the same enumeration to find the next element. *)
0
+(** {6 For system use only, not for the casual user}
0
+ For compatibility with [Stream]
0
+val iapp : 'a t -> 'a t -> 'a t
0
+val icons : 'a -> 'a t -> 'a t
0
+val lapp : (unit -> 'a t) -> 'a t -> 'a t
0
+val lcons : (unit -> 'a) -> 'a t -> 'a t
0
+val lsing : (unit -> 'a) -> 'a t
0
+val slazy : (unit -> 'a t) -> 'a t
) is private.
