Module Prelude.Gen

Trivial generators ("lazy" sequences / streams). NOT thread-safe.

An 'a t generator is just a thunk that, called repeatedly, returns (Some 'a) for each element of the sequence it represents until the sequence is exhausted, when it returns None.

Example:

Terminology:

Types

type 'a t = unit -> 'a option

The type of generators.

val empty : unit -> 'a option

empty is the empty generator; immediately returns None.

Functions to Create Generators

val catch : ?this:exn -> ('b -> 'a) -> 'b -> 'a t

(catch f x) creates a generator from a function f that, after repeated application to x, eventually raises an exception.

Example: (catch input_line chan) is a generator of the lines on chan.

Any exception will indicate the end of the sequence; if you want more precision, specify the exception with ~this -- in this case, any other exception will be re-raised: e.g. (catch ~this:End_of_file input_line chan)

val optional : ('a -> 'b option) -> 'a -> 'b t

(optional f x) creates a generator from a function f that, after repeated application to x, eventually returns None.

val cons : 'a -> 'a t -> 'a t

(cons x g) is the the generator g with x at its head.

(cons 3 empty |> cons 2 |> cons 1 |> to_list) = [1;2;3]
val singleton : 'a -> 'a t

(singleton x) is the generator producing x and only x.

val append : 'a t -> 'a t -> 'a t

(append g1 g2) is the generator that produces all the items in g1 followed by those in g2.

val of_list : 'a list -> 'a t

(to_list list) is the generator that produces all the elements of list.

(of_list [1;2;3] |> to_list) = [1;2;3]
val chars_of_string : string -> unit -> char option

(chars_of_string str) is the generator that produces all the characters of str.

val lines : Stdlib.in_channel -> string t

(lines chan) is the generator that produces all the lines on the input channel chan.

(random ~size elt ()) is a generator of (size ()) (default: > 100) random elements; each element is the result of a call to (elt ()).

val random : size:(unit -> int) -> (unit -> 'a) -> unit -> 'a t

(random ~size elt ()) is a generator of (size ()) (default: > 100) random elements; each element is the result of a call to (elt ()).

Exhaustive Functions to Consume Generators

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

(fold f acc g) folds f across all the values of the generator g; exhaustive.

val len : 'a t -> int

(len g) is the length of the generator g; exhaustive.

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

(iter f g) iterates f across all the values of the generator g; exhaustive.

val to_list : 'a t -> 'a list

(to_list g) returns the list of all the values of the generator g; exhaustive.

val to_string : char t -> string

(to_string g) returns the string of all the characters of the generator g; exhaustive.

Functions to Transform Generators

val map : ('a -> 'b) -> 'a t -> unit -> 'b option

(map f g) maps f across all the value of the generator g; lazy.

val mapi : (int -> 'a -> 'b) -> 'a t -> unit -> 'b option

(mapi f g) maps (fun x -> f i x) across all the values of the generator g, where i is the 0-based index of each value; lazy.

val take : int -> 'a t -> 'a t

(take n g) is the generator consisting of the first n elements of g; lazy.

val drop : int -> 'a t -> 'a t

(drop n g) is the generator consisting of all the elements of g, excluding the first n; lazy.

val splitwhile : ('a -> bool) -> 'a t -> 'a t * 'a t

(splitwhile p g) is (a,b) where a is the generator that produces the longest prefix of g of elements that satisfy p and b is the generator that produces the remaining suffix.

Exhaustive in the prefix, lazy in the suffix.

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

(takewhile p g) is the generator that produces (only) the leading elements of g for which p is true.

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

(dropwhile p g) is the generator that produces (only) the suffix of g after discarding the leading elements for which p is true.