documentation

sequence.mli

@@ -71,23 +71,28 @@ val from_fun : (unit -> 'a option) -> 'a t
       sequence is transient, use {!persistent} if needed! *)
 
 val empty : 'a t
-  (** Empty sequence *)
+  (** Empty sequence. It contains no element. *)
 
 val singleton : 'a -> 'a t
-  (** Singleton sequence *)
+  (** Singleton sequence, with exactly one element. *)
 
 val repeat : 'a -> 'a t
-  (** Infinite sequence of the same element *)
+  (** Infinite sequence of the same element. You may want to look
+      at {!take} if you iterate on it. *)
 
 val iterate : ('a -> 'a) -> 'a -> 'a t
   (** [iterate f x] is the infinite sequence (x, f(x), f(f(x)), ...) *)
 
 val forever : (unit -> 'b) -> 'b t
-  (** Sequence that calls the given function to produce elements *)
+  (** Sequence that calls the given function to produce elements.
+      The sequence may be transient (depending on the function), and definitely
+      is infinite. You may want to use {!take} and {!persistent}. *)
 
 val cycle : 'a t -> 'a t
-  (** Cycle forever through the given sequence. Assume the
+  (** Cycle forever through the given sequence. Assume the given sequence can
-      given sequence can be traversed any amount of times (not transient). *)
+      be traversed any amount of times (not transient).  This yields an
+      infinite sequence, you should use something like {!take} not to loop
+      forever. *)
 
 (** {2 Consume a sequence} *)
 
@@ -116,10 +121,10 @@ val exists : ('a -> bool) -> 'a t -> bool
   (** Exists there some element satisfying the predicate? *)
 
 val length : 'a t -> int
-  (** How long is the sequence? *)
+  (** How long is the sequence? Forces the sequence. *)
 
 val is_empty : 'a t -> bool
-  (** Is the sequence empty? *)
+  (** Is the sequence empty? Forces the sequence. *)
 
 (** {2 Transform a sequence} *)
 
@@ -127,23 +132,24 @@ val filter : ('a -> bool) -> 'a t -> 'a t
   (** Filter on elements of the sequence *)
 
 val append : 'a t -> 'a t -> 'a t
-  (** Append two sequences *)
+  (** Append two sequences. Iterating on the result is like iterating
+      on the first, then on the second. *)
 
 val concat : 'a t t -> 'a t
-  (** Concatenate a sequence of sequences into one sequence *)
+  (** Concatenate a sequence of sequences into one sequence. *)
 
 val flatten : 'a t t -> 'a t
   (** Alias for {!concat} *)
 
 val flatMap : ('a -> 'b t) -> 'a t -> 'b t
-  (** Monadic bind. It applies the function to every element of the
+  (** Monadic bind. Intuitively, it applies the function to every element of the
-      initial sequence, and calls [concat]. *)
+      initial sequence, and calls {!concat}. *)
 
 val fmap : ('a -> 'b option) -> 'a t -> 'b t
   (** Specialized version of {!flatMap} for options.  *)
 
 val intersperse : 'a -> 'a t -> 'a t
-  (** Insert the second element between every element of the sequence *)
+  (** Insert the single element between every element of the sequence *)
 
 val persistent : 'a t -> 'a t
   (** Iterate on the sequence, storing elements in a data structure.
@@ -152,7 +158,9 @@ val persistent : 'a t -> 'a t
       will still make a new copy of the sequence! *)
 
 val sort : ?cmp:('a -> 'a -> int) -> 'a t -> 'a t
-  (** Sort the sequence. Eager, O(n) ram and O(n ln(n)) time. *)
+  (** Sort the sequence. Eager, O(n) ram and O(n ln(n)) time.
+      It iterates on elements of the argument sequence immediately,
+      before it sorts them. *)
 
 val sort_uniq : ?cmp:('a -> 'a -> int) -> 'a t -> 'a t
   (** Sort the sequence and remove duplicates. Eager, same as [sort] *)
@@ -191,13 +199,16 @@ val min : ?lt:('a -> 'a -> bool) -> 'a t -> 'a -> 'a
   (** Min element of the sequence, using the given comparison function *)
 
 val take : int -> 'a t -> 'a t
-  (** Take at most [n] elements from the sequence *)
+  (** Take at most [n] elements from the sequence. Works on infinite
+      sequences. *)
 
 val drop : int -> 'a t -> 'a t
-  (** Drop the [n] first elements of the sequence *)
+  (** Drop the [n] first elements of the sequence. Lazy. *)
 
 val rev : 'a t -> 'a t
-  (** Reverse the sequence. O(n) memory and time. *)
+  (** Reverse the sequence. O(n) memory and time, needs the
+      sequence to be finite. The result is persistent and does
+      not depend on the input being repeatable. *)
 
 (** {2 Binary sequences} *)
 
@@ -290,7 +301,11 @@ val hashtbl_values : ('a, 'b) Hashtbl.t -> 'b t
 
 val of_str : string -> char t
 val to_str :  char t -> string
+
 val of_in_channel : in_channel -> char t
+  (** Iterates on characters of the input (can block when one
+      iterates over the sequence). If you need to iterate
+      several times on this sequence, use {!persistent}. *)
 
 val to_buffer : char t -> Buffer.t -> unit
   (** Copy content of the sequence into the buffer *)
@@ -341,8 +356,11 @@ end
 (** {2 Infinite sequences of random values} *)
 
 val random_int : int -> int t
+  (** Infinite sequence of random integers between 0 and
+      the given higher bound (see Random.int) *)
 
 val random_bool : bool t
+  (** Infinite sequence of random bool values *)
 
 val random_float : float -> float t
 
@@ -350,6 +368,8 @@ val random_array : 'a array -> 'a t
   (** Sequence of choices of an element in the array *)
 
 val random_list : 'a list -> 'a t
+  (** Infinite sequence of random elements of the list. Basically the
+      same as {!random_array}. *)
 
 (** {2 Type-classes} *)