simon/iter
1
0
Fork 0
mirror of https://github.com/c-cube/iter.git synced 2025-12-06 11:15:32 -05:00
Code Issues Projects Releases Packages Wiki Activity Actions

Iterification.

Browse source
This commit is contained in:
Drup 2019-03-08 17:25:47 +01:00 • committed by Simon Cruanes
parent 0b67b4641b
commit fd8ae7559e
13 changed files with 226 additions and 226 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

4
.ocamlinit
View file

@ -1,7 +1,7 @@
#directory "_build/src";; #directory "_build/src";;
#load "sequence.cma";; #load "iter.cma";;
open Sequence.Infix;; open Iter.Infix;;
#directory "_build/src/bigarray/";; #directory "_build/src/bigarray/";;
#load "bigarray.cma";; #load "bigarray.cma";;

2
Makefile
View file

@ -26,7 +26,7 @@ build-benchs:
examples: examples:
dune build examples/test_sexpr.exe dune build examples/test_sexpr.exe
VERSION=$(shell awk '/^version:/ {print $$2}' sequence.opam) VERSION=$(shell awk '/^version:/ {print $$2}' iter.opam)
update_next_tag: update_next_tag:
@echo "update version to $(VERSION)..." @echo "update version to $(VERSION)..."

6
README.md
View file

@ -11,7 +11,7 @@ way of iterating on a finite number of values, only allocating (most of the time
one intermediate closure to do so. For instance, iterating on keys, or values, one intermediate closure to do so. For instance, iterating on keys, or values,
of a `Hashtbl.t`, without creating a list. of a `Hashtbl.t`, without creating a list.
[![build status](https://travis-ci.org/c-cube/sequence.svg?branch=master)](https://travis-ci.org/c-cube/sequence) [![build status](https://travis-ci.org/c-cube/iter.svg?branch=master)](https://travis-ci.org/c-cube/iter)
## Documentation ## Documentation
@ -21,7 +21,7 @@ To get an overview of iter (originally "sequence"), its origins and why it was c
you can start with [the slides of a talk](http://simon.cedeela.fr/assets/talks/sequence.pdf) you can start with [the slides of a talk](http://simon.cedeela.fr/assets/talks/sequence.pdf)
I (@c-cube) made at some OCaml meeting. I (@c-cube) made at some OCaml meeting.
See [the online API](https://c-cube.github.io/sequence/) See [the online API](https://c-cube.github.io/iter/)
for more details on the set of available functions. for more details on the set of available functions.
## Build ## Build
@ -213,7 +213,7 @@ Be careful that this is quite obscure.
- `Iter` is an *internal* iterator. When one wishes to iterate over - `Iter` is an *internal* iterator. When one wishes to iterate over
an `'a Iter.t`, one has to give a callback `f : 'a -> unit` an `'a Iter.t`, one has to give a callback `f : 'a -> unit`
that is called in succession over every element of the sequence. that is called in succession over every element of the iterator.
Control is not handed back to the caller before the whole iteration is over. Control is not handed back to the caller before the whole iteration is over.
This makes `zip` impossible to implement. However, the type `'a Iter.t` This makes `zip` impossible to implement. However, the type `'a Iter.t`
is general enough that it can be extracted from any classic `iter` function, is general enough that it can be extracted from any classic `iter` function,

22
examples/sexpr.ml
View file

@ -27,7 +27,7 @@ type t =
(** Token that compose a Sexpr once serialized *) (** Token that compose a Sexpr once serialized *)
type token = [`Open | `Close | `Atom of string] type token = [`Open | `Close | `Atom of string]
(** {2 Traverse a sequence of tokens} *) (** {2 Traverse an iterator of tokens} *)
(** Iterate on the S-expression, calling the callback with tokens *) (** Iterate on the S-expression, calling the callback with tokens *)
let rec iter f s = match s with let rec iter f s = match s with
@ -37,11 +37,11 @@ and iter_list f l = match l with
| [] -> () | [] -> ()
| x::l' -> iter f x; iter_list f l' | x::l' -> iter f x; iter_list f l'
(** Traverse. This yields a sequence of tokens *) (** Traverse. This yields an iterator of tokens *)
let traverse s = Iter.from_iter (fun k -> iter k s) let traverse s = Iter.from_iter (fun k -> iter k s)
(** Returns the same sequence of tokens, but during iteration, if (** Returns the same iterator of tokens, but during iteration, if
the structure of the Sexpr corresponding to the sequence the structure of the Sexpr corresponding to the iterator
is wrong (bad parenthesing), Invalid_argument is raised is wrong (bad parenthesing), Invalid_argument is raised
and iteration is stoped *) and iteration is stoped *)
let validate seq = let validate seq =
@ -57,7 +57,7 @@ let validate seq =
(** {2 Text <-> tokens} *) (** {2 Text <-> tokens} *)
(** Lex: create a sequence of tokens from the given in_channel. *) (** Lex: create an iterator of tokens from the given in_channel. *)
let lex input = let lex input =
let seq_fun k = let seq_fun k =
let in_word = ref false in let in_word = ref false in
@ -83,7 +83,7 @@ let lex input =
in in
Iter.from_iter seq_fun Iter.from_iter seq_fun
(** Build a Sexpr from a sequence of tokens *) (** Build a Sexpr from an iterator of tokens *)
let of_seq seq = let of_seq seq =
(* called on every token *) (* called on every token *)
let rec k stack token = match token with let rec k stack token = match token with
@ -96,7 +96,7 @@ let of_seq seq =
| `Expr a::stack' -> collapse (a :: acc) stack' | `Expr a::stack' -> collapse (a :: acc) stack'
| _ -> assert false | _ -> assert false
in in
(* iterate on the sequence, given an empty initial stack *) (* iterate, given an empty initial stack *)
let stack = Iter.fold k [] seq in let stack = Iter.fold k [] seq in
(* stack should contain exactly one expression *) (* stack should contain exactly one expression *)
match stack with match stack with
@ -112,7 +112,7 @@ let pp_token formatter token = match token with
| `Close -> Format.fprintf formatter ")@]" | `Close -> Format.fprintf formatter ")@]"
| `Atom s -> Format.pp_print_string formatter s | `Atom s -> Format.pp_print_string formatter s
(** Print a sequence of Sexpr tokens on the given formatter *) (** Print an iterator of Sexpr tokens on the given formatter *)
let pp_tokens formatter tokens = let pp_tokens formatter tokens =
let first = ref true in let first = ref true in
let last = ref false in let last = ref false in
@ -149,7 +149,7 @@ let output_str name str k =
(** {2 Parsing} *) (** {2 Parsing} *)
(** Monadic combinators for parsing data from a sequence of tokens, (** Monadic combinators for parsing data from an iterator of tokens,
without converting to concrete S-expressions. without converting to concrete S-expressions.
The [one] parser can raise ParseFailure if it fails to parse The [one] parser can raise ParseFailure if it fails to parse
@ -247,7 +247,7 @@ type 'a state =
| Bottom : 'a state | Bottom : 'a state
| Push : ('b parser * ('b -> 'a state)) -> 'a state | Push : ('b parser * ('b -> 'a state)) -> 'a state
(** Actually parse the sequence of tokens, with a callback to be called (** Actually parse the iterator of tokens, with a callback to be called
on every parsed value. The callback decides whether to push another on every parsed value. The callback decides whether to push another
state or whether to continue. *) state or whether to continue. *)
let parse_k p tokens k = let parse_k p tokens k =
@ -295,7 +295,7 @@ let parse p tokens =
| None -> raise (ParseFailure "incomplete input") | None -> raise (ParseFailure "incomplete input")
| Some x -> x | Some x -> x
(** Parse a sequence of values *) (** Parse an iterator of values *)
let parse_seq p tokens = let parse_seq p tokens =
let seq_fun k = let seq_fun k =
parse_k p tokens (fun x -> k x; `Continue) parse_k p tokens (fun x -> k x; `Continue)

22
examples/sexpr.mli
View file

@ -28,27 +28,27 @@ type t =
type token = [`Open | `Close | `Atom of string] type token = [`Open | `Close | `Atom of string]
(** Token that compose a Sexpr once serialized *) (** Token that compose a Sexpr once serialized *)
(** {2 Traverse a sequence of tokens} *) (** {2 Traverse an iterator of tokens} *)
val iter : (token -> unit) -> t -> unit val iter : (token -> unit) -> t -> unit
(** Iterate on the S-expression, calling the callback with tokens *) (** Iterate on the S-expression, calling the callback with tokens *)
val traverse : t -> token Iter.t val traverse : t -> token Iter.t
(** Traverse. This yields a sequence of tokens *) (** Traverse. This yields an iterator of tokens *)
val validate : token Iter.t -> token Iter.t val validate : token Iter.t -> token Iter.t
(** Returns the same sequence of tokens, but during iteration, if (** Returns the same iterator of tokens, but during iteration, if
the structure of the Sexpr corresponding to the sequence the structure of the Sexpr corresponding to the iterator
is wrong (bad parenthesing), Invalid_argument is raised is wrong (bad parenthesing), Invalid_argument is raised
and iteration is stoped *) and iteration is stoped *)
(** {2 Text <-> tokens} *) (** {2 Text <-> tokens} *)
val lex : char Iter.t -> token Iter.t val lex : char Iter.t -> token Iter.t
(** Lex: create a sequence of tokens from the given sequence of chars. *) (** Lex: create an iterator of tokens from the given iterator of chars. *)
val of_seq : token Iter.t -> t val of_seq : token Iter.t -> t
(** Build a Sexpr from a sequence of tokens, or raise Failure *) (** Build a Sexpr from an iterator of tokens, or raise Failure *)
(** {2 Printing} *) (** {2 Printing} *)
@ -56,7 +56,7 @@ val pp_token : Format.formatter -> token -> unit
(** Print a token on the given formatter *) (** Print a token on the given formatter *)
val pp_tokens : Format.formatter -> token Iter.t -> unit val pp_tokens : Format.formatter -> token Iter.t -> unit
(** Print a sequence of Sexpr tokens on the given formatter *) (** Print an iterator of Sexpr tokens on the given formatter *)
val pp_sexpr : ?indent:bool -> Format.formatter -> t -> unit val pp_sexpr : ?indent:bool -> Format.formatter -> t -> unit
(** Pretty-print the S-expr. If [indent] is true, the S-expression (** Pretty-print the S-expr. If [indent] is true, the S-expression
@ -65,14 +65,14 @@ val pp_sexpr : ?indent:bool -> Format.formatter -> t -> unit
(** {2 Serializing} *) (** {2 Serializing} *)
val output_seq : string -> token Iter.t -> (token -> unit) -> unit val output_seq : string -> token Iter.t -> (token -> unit) -> unit
(** print a pair "(name @,sequence)" *) (** print a pair "(name @,iterator)" *)
val output_str : string -> string -> (token -> unit) -> unit val output_str : string -> string -> (token -> unit) -> unit
(** print a pair "(name str)" *) (** print a pair "(name str)" *)
(** {2 Parsing} *) (** {2 Parsing} *)
(** Monadic combinators for parsing data from a sequence of tokens, (** Monadic combinators for parsing data from an iterator of tokens,
without converting to concrete S-expressions. *) without converting to concrete S-expressions. *)
type 'a parser type 'a parser
@ -125,8 +125,8 @@ val many : 'a parser -> 'a list parser
val many1 : 'a parser -> 'a list parser val many1 : 'a parser -> 'a list parser
val parse : 'a parser -> token Iter.t -> 'a val parse : 'a parser -> token Iter.t -> 'a
(** Parses exactly one value from the sequence of tokens. Raises (** Parses exactly one value from the iterator of tokens. Raises
ParseFailure if anything goes wrong. *) ParseFailure if anything goes wrong. *)
val parse_seq : 'a parser -> token Iter.t -> 'a Iter.t val parse_seq : 'a parser -> token Iter.t -> 'a Iter.t
(** Parses a sequence of values *) (** Parses an iterator of values *)

4
examples/test_sexpr.ml
View file

@ -1,5 +1,5 @@
(** {2 Test sequences} *) (** {2 Test iterators} *)
(** print a list of items using the printing function *) (** print a list of items using the printing function *)
let pp_list ?(sep=", ") pp_item formatter l = let pp_list ?(sep=", ") pp_item formatter l =
@ -94,7 +94,7 @@ let _ =
(Iter.of_array (Iter.of_array
(Iter.to_array (Iter.append (Iter.to_array (Iter.append
(Iter.take 5 (Iter.of_list l3)) (Iter.of_list l4)))); (Iter.take 5 (Iter.of_list l3)) (Iter.of_list l4))));
(* sequence, persistent, etc *) (* iterator, persistent, etc *)
let seq = Iter.int_range ~start:0 ~stop:100000 in let seq = Iter.int_range ~start:0 ~stop:100000 in
let seq' = Iter.persistent seq in let seq' = Iter.persistent seq in
let stream = Iter.to_stream seq' in let stream = Iter.to_stream seq' in

8
iter.opam
View file

@ -19,11 +19,11 @@ depends: [
"mdx" {with-test} "mdx" {with-test}
"odoc" {with-doc} "odoc" {with-doc}
] ]
tags: [ "sequence" "iterator" "iter" "fold" ] tags: [ "iter" "iterator" "iter" "fold" ]
homepage: "https://github.com/c-cube/iter/" homepage: "https://github.com/c-cube/iter/"
depopts: [ depopts: [
"base-bigarray" "base-bigarray"
] ]
doc: "https://c-cube.github.io/sequence/" doc: "https://c-cube.github.io/iter/"
bug-reports: "https://github.com/c-cube/sequence/issues" bug-reports: "https://github.com/c-cube/iter/issues"
dev-repo: "git+https://github.com/c-cube/sequence.git" dev-repo: "git+https://github.com/c-cube/iter.git"

192
src/Iter.mli
View file

@ -11,15 +11,15 @@
function is provided, storing elements of a transient iterator function is provided, storing elements of a transient iterator
in memory; the iterator can then be used several times (See further). in memory; the iterator can then be used several times (See further).
Note that some combinators also return sequences (e.g. {!group}). The Note that some combinators also return iterators (e.g. {!group}). The
transformation is computed on the fly every time one iterates over transformation is computed on the fly every time one iterates over
the resulting sequence. If a transformation performs heavy computation, the resulting iterator. If a transformation performs heavy computation,
{!persistent} can also be used as intermediate storage. {!persistent} can also be used as intermediate storage.
Most functions are {b lazy}, i.e. they do not actually use their arguments Most functions are {b lazy}, i.e. they do not actually use their arguments
until their result is iterated on. For instance, if one calls {!map} until their result is iterated on. For instance, if one calls {!map}
on an iterator, one gets a new sequence, but nothing else happens until on an iterator, one gets a new iterator, but nothing else happens until
this new sequence is used (by folding or iterating on it). this new iterator is used (by folding or iterating on it).
If an iterator is built from an iteration function that is {b repeatable} If an iterator is built from an iteration function that is {b repeatable}
(i.e. calling it several times always iterates on the same set of (i.e. calling it several times always iterates on the same set of
@ -55,19 +55,19 @@ val from_labelled_iter : (f:('a -> unit) -> unit) -> 'a t
val from_fun : (unit -> 'a option) -> 'a t val from_fun : (unit -> 'a option) -> 'a t
(** Call the function repeatedly until it returns None. This (** Call the function repeatedly until it returns None. This
sequence is transient, use {!persistent} if needed! *) iterator is transient, use {!persistent} if needed! *)
val empty : 'a t val empty : 'a t
(** Empty sequence. It contains no element. *) (** Empty iterator. It contains no element. *)
val singleton : 'a -> 'a t val singleton : 'a -> 'a t
(** Singleton sequence, with exactly one element. *) (** Singleton iterator, with exactly one element. *)
val doubleton : 'a -> 'a -> 'a t val doubleton : 'a -> 'a -> 'a t
(** Iterator with exactly two elements *) (** Iterator with exactly two elements *)
val init : (int -> 'a) -> 'a t val init : (int -> 'a) -> 'a t
(** [init f] is the infinite sequence [f 0; f 1; f 2; …]. (** [init f] is the infinite iterator [f 0; f 1; f 2; …].
@since 0.9 *) @since 0.9 *)
val cons : 'a -> 'a t -> 'a t val cons : 'a -> 'a t -> 'a t
@ -84,37 +84,37 @@ val pure : 'a -> 'a t
(** Synonym to {!singleton} *) (** Synonym to {!singleton} *)
val repeat : 'a -> 'a t val repeat : 'a -> 'a t
(** Infinite sequence of the same element. You may want to look (** Infinite iterator of the same element. You may want to look
at {!take} and the likes if you iterate on it. *) at {!take} and the likes if you iterate on it. *)
val iterate : ('a -> 'a) -> 'a -> 'a t val iterate : ('a -> 'a) -> 'a -> 'a t
(** [iterate f x] is the infinite sequence [x, f(x), f(f(x)), ...] *) (** [iterate f x] is the infinite iterator [x, f(x), f(f(x)), ...] *)
val forever : (unit -> 'b) -> 'b t val forever : (unit -> 'b) -> 'b t
(** Iterator that calls the given function to produce elements. (** Iterator that calls the given function to produce elements.
The sequence may be transient (depending on the function), and definitely The iterator may be transient (depending on the function), and definitely
is infinite. You may want to use {!take} and {!persistent}. *) is infinite. You may want to use {!take} and {!persistent}. *)
val cycle : 'a t -> 'a t val cycle : 'a t -> 'a t
(** Cycle forever through the given sequence. Assume the given sequence can (** Cycle forever through the given iterator. Assume the given iterator can
be traversed any amount of times (not transient). This yields an be traversed any amount of times (not transient). This yields an
infinite sequence, you should use something like {!take} not to loop infinite iterator, you should use something like {!take} not to loop
forever. *) forever. *)
(** {2 Consume an iterator} *) (** {2 Consume an iterator} *)
val iter : ('a -> unit) -> 'a t -> unit val iter : ('a -> unit) -> 'a t -> unit
(** Consume the sequence, passing all its arguments to the function. (** Consume the iterator, passing all its arguments to the function.
Basically [iter f seq] is just [seq f]. *) Basically [iter f seq] is just [seq f]. *)
val iteri : (int -> 'a -> unit) -> 'a t -> unit val iteri : (int -> 'a -> unit) -> 'a t -> unit
(** Iterate on elements and their index in the sequence *) (** Iterate on elements and their index in the iterator *)
val fold : ('a -> 'b -> 'a) -> 'a -> 'b t -> 'a val fold : ('a -> 'b -> 'a) -> 'a -> 'b t -> 'a
(** Fold over elements of the sequence, consuming it *) (** Fold over elements of the iterator, consuming it *)
val foldi : ('a -> int -> 'b -> 'a) -> 'a -> 'b t -> 'a val foldi : ('a -> int -> 'b -> 'a) -> 'a -> 'b t -> 'a
(** Fold over elements of the sequence and their index, consuming it *) (** Fold over elements of the iterator and their index, consuming it *)
val fold_map : ('acc -> 'a -> 'acc * 'b) -> 'acc -> 'a t -> 'b t val fold_map : ('acc -> 'a -> 'acc * 'b) -> 'acc -> 'a t -> 'b t
(** [fold_map f acc l] is like {!map}, but it carries some state as in (** [fold_map f acc l] is like {!map}, but it carries some state as in
@ -128,14 +128,14 @@ val fold_filter_map : ('acc -> 'a -> 'acc * 'b option) -> 'acc -> 'a t -> 'b t
@since 0.9 *) @since 0.9 *)
val map : ('a -> 'b) -> 'a t -> 'b t val map : ('a -> 'b) -> 'a t -> 'b t
(** Map objects of the sequence into other elements, lazily *) (** Map objects of the iterator into other elements, lazily *)
val mapi : (int -> 'a -> 'b) -> 'a t -> 'b t val mapi : (int -> 'a -> 'b) -> 'a t -> 'b t
(** Map objects, along with their index in the sequence *) (** Map objects, along with their index in the iterator *)
val map_by_2 : ('a -> 'a -> 'a) -> 'a t -> 'a t val map_by_2 : ('a -> 'a -> 'a) -> 'a t -> 'a t
(** Map objects two by two. lazily. (** Map objects two by two. lazily.
The last element is kept in the sequence if the count is odd. The last element is kept in the iterator if the count is odd.
@since 0.7 *) @since 0.7 *)
val for_all : ('a -> bool) -> 'a t -> bool val for_all : ('a -> bool) -> 'a t -> bool
@ -145,7 +145,7 @@ val exists : ('a -> bool) -> 'a t -> bool
(** Exists there some element satisfying the predicate? *) (** Exists there some element satisfying the predicate? *)
val mem : ?eq:('a -> 'a -> bool) -> 'a -> 'a t -> bool val mem : ?eq:('a -> 'a -> bool) -> 'a -> 'a t -> bool
(** Is the value a member of the sequence? (** Is the value a member of the iterator?
@param eq the equality predicate to use (default [(=)]) @param eq the equality predicate to use (default [(=)])
@since 0.5 *) @since 0.5 *)
@ -176,34 +176,34 @@ val find_pred_exn : ('a -> bool) -> 'a t -> 'a
@since 0.9 *) @since 0.9 *)
val length : 'a t -> int val length : 'a t -> int
(** How long is the sequence? Forces the sequence. *) (** How long is the iterator? Forces the iterator. *)
val is_empty : 'a t -> bool val is_empty : 'a t -> bool
(** Is the sequence empty? Forces the sequence. *) (** Is the iterator empty? Forces the iterator. *)
(** {2 Transform an iterator} *) (** {2 Transform an iterator} *)
val filter : ('a -> bool) -> 'a t -> 'a t val filter : ('a -> bool) -> 'a t -> 'a t
(** Filter on elements of the sequence *) (** Filter on elements of the iterator *)
val append : 'a t -> 'a t -> 'a t val append : 'a t -> 'a t -> 'a t
(** Append two sequences. Iterating on the result is like iterating (** Append two iterators. Iterating on the result is like iterating
on the first, then on the second. *) on the first, then on the second. *)
val append_l : 'a t list -> 'a t val append_l : 'a t list -> 'a t
(** Append sequences. Iterating on the result is like iterating (** Append iterators. Iterating on the result is like iterating
on the each sequence of the list in order. on the each iterator of the list in order.
@since 0.11 *) @since 0.11 *)
val concat : 'a t t -> 'a t val concat : 'a t t -> 'a t
(** Concatenate an iterator of sequences into one sequence. *) (** Concatenate an iterator of iterators into one iterator. *)
val flatten : 'a t t -> 'a t val flatten : 'a t t -> 'a t
(** Alias for {!concat} *) (** Alias for {!concat} *)
val flat_map : ('a -> 'b t) -> 'a t -> 'b t val flat_map : ('a -> 'b t) -> 'a t -> 'b t
(** Monadic bind. Intuitively, it applies the function to every (** Monadic bind. Intuitively, it applies the function to every
element of the initial sequence, and calls {!concat}. element of the initial iterator, and calls {!concat}.
Formerly [flatMap] Formerly [flatMap]
@since 0.5 *) @since 0.5 *)
@ -212,8 +212,8 @@ val flat_map_l : ('a -> 'b list) -> 'a t -> 'b t
@since 0.9 *) @since 0.9 *)
val seq_list : 'a t list -> 'a list t val seq_list : 'a t list -> 'a list t
(** [seq_list l] returns all the ways to pick one element in each sub-sequence (** [seq_list l] returns all the ways to pick one element in each sub-iterator
in [l]. Assumes the sub-sequences can be iterated on several times. in [l]. Assumes the sub-iterators can be iterated on several times.
@since 0.11 *) @since 0.11 *)
val seq_list_map : ('a -> 'b t) -> 'a list -> 'b list t val seq_list_map : ('a -> 'b t) -> 'a list -> 'b list t
@ -235,7 +235,7 @@ val filter_count : ('a -> bool) -> 'a t -> int
@since 1.0 *) @since 1.0 *)
val intersperse : 'a -> 'a t -> 'a t val intersperse : 'a -> 'a t -> 'a t
(** Insert the single element between every element of the sequence *) (** Insert the single element between every element of the iterator *)
val keep_some : 'a option t -> 'a t val keep_some : 'a option t -> 'a t
(** [filter_some l] retains only elements of the form [Some x]. (** [filter_some l] retains only elements of the form [Some x].
@ -253,14 +253,14 @@ val keep_error : (_, 'e) Result.result t -> 'e t
(** {2 Caching} *) (** {2 Caching} *)
val persistent : 'a t -> 'a t val persistent : 'a t -> 'a t
(** Iterate on the sequence, storing elements in an efficient internal structure.. (** Iterate on the iterator, storing elements in an efficient internal structure..
The resulting sequence can be iterated on as many times as needed. The resulting iterator can be iterated on as many times as needed.
{b Note}: calling persistent on an already persistent sequence {b Note}: calling persistent on an already persistent iterator
will still make a new copy of the sequence! *) will still make a new copy of the iterator! *)
val persistent_lazy : 'a t -> 'a t val persistent_lazy : 'a t -> 'a t
(** Lazy version of {!persistent}. When calling [persistent_lazy s], (** Lazy version of {!persistent}. When calling [persistent_lazy s],
a new sequence [s'] is immediately returned (without actually consuming a new iterator [s'] is immediately returned (without actually consuming
[s]) in constant time; the first time [s'] is iterated on, [s]) in constant time; the first time [s'] is iterated on,
it also consumes [s] and caches its content into a inner data it also consumes [s] and caches its content into a inner data
structure that will back [s'] for future iterations. structure that will back [s'] for future iterations.
@ -272,15 +272,15 @@ val persistent_lazy : 'a t -> 'a t
(** {2 Misc} *) (** {2 Misc} *)
val sort : ?cmp:('a -> 'a -> int) -> 'a t -> 'a t 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 iterator. Eager, O(n) ram and O(n ln(n)) time.
It iterates on elements of the argument sequence immediately, It iterates on elements of the argument iterator immediately,
before it sorts them. *) before it sorts them. *)
val sort_uniq : ?cmp:('a -> 'a -> int) -> 'a t -> 'a t val sort_uniq : ?cmp:('a -> 'a -> int) -> 'a t -> 'a t
(** Sort the sequence and remove duplicates. Eager, same as [sort] *) (** Sort the iterator and remove duplicates. Eager, same as [sort] *)
val sorted : ?cmp:('a -> 'a -> int) -> 'a t -> bool val sorted : ?cmp:('a -> 'a -> int) -> 'a t -> bool
(** Checks whether the sequence is sorted. Eager, same as {!sort}. (** Checks whether the iterator is sorted. Eager, same as {!sort}.
@since 0.9 *) @since 0.9 *)
val group_succ_by : ?eq:('a -> 'a -> bool) -> 'a t -> 'a list t val group_succ_by : ?eq:('a -> 'a -> bool) -> 'a t -> 'a list t
@ -291,7 +291,7 @@ val group_succ_by : ?eq:('a -> 'a -> bool) -> 'a t -> 'a list t
val group_by : ?hash:('a -> int) -> ?eq:('a -> 'a -> bool) -> val group_by : ?hash:('a -> int) -> ?eq:('a -> 'a -> bool) ->
'a t -> 'a list t 'a t -> 'a list t
(** Group equal elements, disregarding their order of appearance. (** Group equal elements, disregarding their order of appearance.
The result sequence is traversable as many times as required. The result iterator is traversable as many times as required.
precondition: for any [x] and [y], if [eq x y] then [hash x=hash y] must hold. precondition: for any [x] and [y], if [eq x y] then [hash x=hash y] must hold.
@since 0.6 *) @since 0.6 *)
@ -307,19 +307,19 @@ val uniq : ?eq:('a -> 'a -> bool) -> 'a t -> 'a t
like [fun seq -> map List.hd (group seq)]. *) like [fun seq -> map List.hd (group seq)]. *)
val product : 'a t -> 'b t -> ('a * 'b) t val product : 'a t -> 'b t -> ('a * 'b) t
(** Cartesian product of the sequences. When calling [product a b], (** Cartesian product of iterators. When calling [product a b],
the caller {b MUST} ensure that [b] can be traversed as many times the caller {b MUST} ensure that [b] can be traversed as many times
as required (several times), possibly by calling {!persistent} on it as required (several times), possibly by calling {!persistent} on it
beforehand. *) beforehand. *)
val diagonal_l : 'a list -> ('a * 'a) t val diagonal_l : 'a list -> ('a * 'a) t
(** All pairs of distinct positions of the list. [diagonal l] will (** All pairs of distinct positions of the list. [diagonal l] will
return the sequence of all [List.nth i l, List.nth j l] if [i < j]. return the iterator of all [List.nth i l, List.nth j l] if [i < j].
@since 0.9 *) @since 0.9 *)
val diagonal : 'a t -> ('a * 'a) t val diagonal : 'a t -> ('a * 'a) t
(** All pairs of distinct positions of the sequence. (** All pairs of distinct positions of the iterator.
Iterates only once on the sequence, which must be finite. Iterates only once on the iterator, which must be finite.
@since 0.9 *) @since 0.9 *)
val join : join_row:('a -> 'b -> 'c option) -> 'a t -> 'b t -> 'c t val join : join_row:('a -> 'b -> 'c option) -> 'a t -> 'b t -> 'c t
@ -335,7 +335,7 @@ val join_by : ?eq:'key equal -> ?hash:'key hash ->
'b t -> 'b t ->
'c t 'c t
(** [join key1 key2 ~merge] is a binary operation (** [join key1 key2 ~merge] is a binary operation
that takes two sequences [a] and [b], projects their that takes two iterators [a] and [b], projects their
elements resp. with [key1] and [key2], and combine elements resp. with [key1] and [key2], and combine
values [(x,y)] from [(a,b)] with the same [key] values [(x,y)] from [(a,b)] with the same [key]
using [merge]. If [merge] returns [None], the combination using [merge]. If [merge] returns [None], the combination
@ -350,7 +350,7 @@ val join_all_by : ?eq:'key equal -> ?hash:'key hash ->
'b t -> 'b t ->
'c t 'c t
(** [join_all_by key1 key2 ~merge] is a binary operation (** [join_all_by key1 key2 ~merge] is a binary operation
that takes two sequences [a] and [b], projects their that takes two iterators [a] and [b], projects their
elements resp. with [key1] and [key2], and, for each key [k] elements resp. with [key1] and [key2], and, for each key [k]
occurring in at least one of them: occurring in at least one of them:
- compute the list [l1] of elements of [a] that map to [k] - compute the list [l1] of elements of [a] that map to [k]
@ -366,9 +366,9 @@ val group_join_by : ?eq:'a equal -> ?hash:'a hash ->
'b t -> 'b t ->
('a * 'b list) t ('a * 'b list) t
(** [group_join_by key2] associates to every element [x] of (** [group_join_by key2] associates to every element [x] of
the first sequence, all the elements [y] of the second the first iterator, all the elements [y] of the second
sequence such that [eq x (key y)]. Elements of the first iterator such that [eq x (key y)]. Elements of the first
sequences without corresponding values in the second one iterators without corresponding values in the second one
are mapped to [[]] are mapped to [[]]
precondition: for any [x] and [y], if [eq x y] then [hash x=hash y] must hold. precondition: for any [x] and [y], if [eq x y] then [hash x=hash y] must hold.
@since 0.10 *) @since 0.10 *)
@ -429,22 +429,22 @@ val scan : ('b -> 'a -> 'b) -> 'b -> 'a t -> 'b t
(** Iterator of intermediate results *) (** Iterator of intermediate results *)
val max : ?lt:('a -> 'a -> bool) -> 'a t -> 'a option val max : ?lt:('a -> 'a -> bool) -> 'a t -> 'a option
(** Max element of the sequence, using the given comparison function. (** Max element of the iterator, using the given comparison function.
@return None if the sequence is empty, Some [m] where [m] is the maximal @return None if the iterator is empty, Some [m] where [m] is the maximal
element otherwise *) element otherwise *)
val max_exn : ?lt:('a -> 'a -> bool) -> 'a t -> 'a val max_exn : ?lt:('a -> 'a -> bool) -> 'a t -> 'a
(** Unsafe version of {!max} (** Unsafe version of {!max}
@raise Not_found if the sequence is empty @raise Not_found if the iterator is empty
@since 0.10 *) @since 0.10 *)
val min : ?lt:('a -> 'a -> bool) -> 'a t -> 'a option val min : ?lt:('a -> 'a -> bool) -> 'a t -> 'a option
(** Min element of the sequence, using the given comparison function. (** Min element of the iterator, using the given comparison function.
see {!max} for more details. *) see {!max} for more details. *)
val min_exn : ?lt:('a -> 'a -> bool) -> 'a t -> 'a val min_exn : ?lt:('a -> 'a -> bool) -> 'a t -> 'a
(** Unsafe version of {!min} (** Unsafe version of {!min}
@raise Not_found if the sequence is empty @raise Not_found if the iterator is empty
@since 0.10 *) @since 0.10 *)
val sum : int t -> int val sum : int t -> int
@ -461,36 +461,36 @@ val head : 'a t -> 'a option
val head_exn : 'a t -> 'a val head_exn : 'a t -> 'a
(** First element, if any, fails (** First element, if any, fails
@raise Invalid_argument if the sequence is empty @raise Invalid_argument if the iterator is empty
@since 0.5.1 *) @since 0.5.1 *)
val take : int -> 'a t -> 'a t val take : int -> 'a t -> 'a t
(** Take at most [n] elements from the sequence. Works on infinite (** Take at most [n] elements from the iterator. Works on infinite
sequences. *) iterators. *)
val take_while : ('a -> bool) -> 'a t -> 'a t val take_while : ('a -> bool) -> 'a t -> 'a t
(** Take elements while they satisfy the predicate, then stops iterating. (** Take elements while they satisfy the predicate, then stops iterating.
Will work on an infinite sequence [s] if the predicate is false for at Will work on an infinite iterator [s] if the predicate is false for at
least one element of [s]. *) least one element of [s]. *)
val fold_while : ('a -> 'b -> 'a * [`Stop | `Continue]) -> 'a -> 'b t -> 'a val fold_while : ('a -> 'b -> 'a * [`Stop | `Continue]) -> 'a -> 'b t -> 'a
(** Folds over elements of the sequence, stopping early if the accumulator (** Folds over elements of the iterator, stopping early if the accumulator
returns [('a, `Stop)] returns [('a, `Stop)]
@since 0.5.5 *) @since 0.5.5 *)
val drop : int -> 'a t -> 'a t val drop : int -> 'a t -> 'a t
(** Drop the [n] first elements of the sequence. Lazy. *) (** Drop the [n] first elements of the iterator. Lazy. *)
val drop_while : ('a -> bool) -> 'a t -> 'a t val drop_while : ('a -> bool) -> 'a t -> 'a t
(** Predicate version of {!drop} *) (** Predicate version of {!drop} *)
val rev : 'a t -> 'a t val rev : 'a t -> 'a t
(** Reverse the sequence. O(n) memory and time, needs the (** Reverse the iterator. O(n) memory and time, needs the
sequence to be finite. The result is persistent and does iterator to be finite. The result is persistent and does
not depend on the input being repeatable. *) not depend on the input being repeatable. *)
val zip_i : 'a t -> (int * 'a) t val zip_i : 'a t -> (int * 'a) t
(** Zip elements of the sequence with their index in the sequence. (** Zip elements of the iterator with their index in the iterator.
Changed type @since 1.0 to just give an iterator of pairs *) Changed type @since 1.0 to just give an iterator of pairs *)
val fold2 : ('c -> 'a -> 'b -> 'c) -> 'c -> ('a * 'b) t -> 'c val fold2 : ('c -> 'a -> 'b -> 'c) -> 'c -> ('a * 'b) t -> 'c
@ -505,12 +505,12 @@ val map2_2 : ('a -> 'b -> 'c) -> ('a -> 'b -> 'd) -> ('a * 'b) t -> ('c * 'd) t
(** {2 Basic data structures converters} *) (** {2 Basic data structures converters} *)
val to_list : 'a t -> 'a list val to_list : 'a t -> 'a list
(** Convert the sequence into a list. Preserves order of elements. (** Convert the iterator into a list. Preserves order of elements.
This function is tail-recursive, but consumes 2*n memory. This function is tail-recursive, but consumes 2*n memory.
If order doesn't matter to you, consider {!to_rev_list}. *) If order doesn't matter to you, consider {!to_rev_list}. *)
val to_rev_list : 'a t -> 'a list val to_rev_list : 'a t -> 'a list
(** Get the list of the reversed sequence (more efficient than {!to_list}) *) (** Get the list of the reversed iterator (more efficient than {!to_list}) *)
val of_list : 'a list -> 'a t val of_list : 'a list -> 'a t
@ -520,7 +520,7 @@ val on_list : ('a t -> 'b t) -> 'a list -> 'b list
*) *)
val pair_with_idx : 'a t -> (int * 'a) t val pair_with_idx : 'a t -> (int * 'a) t
(** Similar to {!zip_i} but returns a normal sequence of tuples (** Similar to {!zip_i} but returns a normal iterator of tuples
@since 0.11 *) @since 0.11 *)
val to_opt : 'a t -> 'a option val to_opt : 'a t -> 'a option
@ -551,23 +551,23 @@ val to_stream : 'a t -> 'a Stream.t
(** Convert to a stream. linear in memory and time (a copy is made in memory) *) (** Convert to a stream. linear in memory and time (a copy is made in memory) *)
val to_stack : 'a Stack.t -> 'a t -> unit val to_stack : 'a Stack.t -> 'a t -> unit
(** Push elements of the sequence on the stack *) (** Push elements of the iterator on the stack *)
val of_stack : 'a Stack.t -> 'a t val of_stack : 'a Stack.t -> 'a t
(** Iterator of elements of the stack (same order as [Stack.iter]) *) (** Iterator of elements of the stack (same order as [Stack.iter]) *)
val to_queue : 'a Queue.t -> 'a t -> unit val to_queue : 'a Queue.t -> 'a t -> unit
(** Push elements of the sequence into the queue *) (** Push elements of the iterator into the queue *)
val of_queue : 'a Queue.t -> 'a t val of_queue : 'a Queue.t -> 'a t
(** Iterator of elements contained in the queue, FIFO order *) (** Iterator of elements contained in the queue, FIFO order *)
val hashtbl_add : ('a, 'b) Hashtbl.t -> ('a * 'b) t -> unit val hashtbl_add : ('a, 'b) Hashtbl.t -> ('a * 'b) t -> unit
(** Add elements of the sequence to the hashtable, with (** Add elements of the iterator to the hashtable, with
Hashtbl.add *) Hashtbl.add *)
val hashtbl_replace : ('a, 'b) Hashtbl.t -> ('a * 'b) t -> unit val hashtbl_replace : ('a, 'b) Hashtbl.t -> ('a * 'b) t -> unit
(** Add elements of the sequence to the hashtable, with (** Add elements of the iterator to the hashtable, with
Hashtbl.replace (erases conflicting bindings) *) Hashtbl.replace (erases conflicting bindings) *)
val to_hashtbl : ('a * 'b) t -> ('a, 'b) Hashtbl.t val to_hashtbl : ('a * 'b) t -> ('a, 'b) Hashtbl.t
@ -593,12 +593,12 @@ exception OneShotSequence
val of_in_channel : in_channel -> char t val of_in_channel : in_channel -> char t
(** Iterates on characters of the input (can block when one (** Iterates on characters of the input (can block when one
iterates over the sequence). If you need to iterate iterates over the iterator). If you need to iterate
several times on this sequence, use {!persistent}. several times on this iterator, use {!persistent}.
@raise OneShotSequence when used more than once. *) @raise OneShotIterator when used more than once. *)
val to_buffer : char t -> Buffer.t -> unit val to_buffer : char t -> Buffer.t -> unit
(** Copy content of the sequence into the buffer *) (** Copy content of the iterator into the buffer *)
val int_range : start:int -> stop:int -> int t val int_range : start:int -> stop:int -> int t
(** Iterator on integers in [start...stop] by steps 1. Also see (** Iterator on integers in [start...stop] by steps 1. Also see
@ -611,7 +611,7 @@ val int_range_dec : start:int -> stop:int -> int t
val int_range_by : step:int -> int -> int -> int t val int_range_by : step:int -> int -> int -> int t
(** [int_range_by ~step i j] is the range starting at [i], including [j], (** [int_range_by ~step i j] is the range starting at [i], including [j],
where the difference between successive elements is [step]. where the difference between successive elements is [step].
use a negative [step] for a decreasing sequence. use a negative [step] for a decreasing iterator.
@raise Invalid_argument if [step=0] *) @raise Invalid_argument if [step=0] *)
val bools : bool t val bools : bool t
@ -622,7 +622,7 @@ val of_set : (module Set.S with type elt = 'a and type t = 'b) -> 'b -> 'a t
(** Convert the given set to an iterator. The set module must be provided. *) (** Convert the given set to an iterator. The set module must be provided. *)
val to_set : (module Set.S with type elt = 'a and type t = 'b) -> 'a t -> 'b val to_set : (module Set.S with type elt = 'a and type t = 'b) -> 'a t -> 'b
(** Convert the sequence to a set, given the proper set module *) (** Convert the iterator to a set, given the proper set module *)
type 'a gen = unit -> 'a option type 'a gen = unit -> 'a option
type 'a klist = unit -> [`Nil | `Cons of 'a * 'a klist] type 'a klist = unit -> [`Nil | `Cons of 'a * 'a klist]
@ -631,15 +631,15 @@ val of_gen : 'a gen -> 'a t
(** Traverse eagerly the generator and build an iterator from it *) (** Traverse eagerly the generator and build an iterator from it *)
val to_gen : 'a t -> 'a gen val to_gen : 'a t -> 'a gen
(** Make the sequence persistent (O(n)) and then iterate on it. Eager. *) (** Make the iterator persistent (O(n)) and then iterate on it. Eager. *)
val of_klist : 'a klist -> 'a t val of_klist : 'a klist -> 'a t
(** Iterate on the lazy list *) (** Iterate on the lazy list *)
val to_klist : 'a t -> 'a klist val to_klist : 'a t -> 'a klist
(** Make the sequence persistent and then iterate on it. Eager. *) (** Make the iterator persistent and then iterate on it. Eager. *)
(** {2 Functorial conversions between sets and sequences} *) (** {2 Functorial conversions between sets and iterators} *)
module Set : sig module Set : sig
module type S = sig module type S = sig
@ -663,7 +663,7 @@ module Set : sig
module Make(X : Set.OrderedType) : S with type elt = X.t module Make(X : Set.OrderedType) : S with type elt = X.t
end end
(** {2 Conversion between maps and sequences.} *) (** {2 Conversion between maps and iterators.} *)
module Map : sig module Map : sig
module type S = sig module type S = sig
@ -682,21 +682,21 @@ module Map : sig
(** @deprecated use {!of_iter} instead *) (** @deprecated use {!of_iter} instead *)
end end
(** Adapt a pre-existing Map module to make it sequence-aware *) (** Adapt a pre-existing Map module to make it iterator-aware *)
module Adapt(M : Map.S) : S with type key = M.key and type 'a t = 'a M.t module Adapt(M : Map.S) : S with type key = M.key and type 'a t = 'a M.t
(** Create an enriched Map module, with sequence-aware functions *) (** Create an enriched Map module, with iterator-aware functions *)
module Make(V : Map.OrderedType) : S with type key = V.t module Make(V : Map.OrderedType) : S with type key = V.t
end end
(** {2 Infinite sequences of random values} *) (** {2 Infinite iterators of random values} *)
val random_int : int -> int t val random_int : int -> int t
(** Infinite sequence of random integers between 0 and (** Infinite iterator of random integers between 0 and
the given higher bound (see Random.int) *) the given higher bound (see Random.int) *)
val random_bool : bool t val random_bool : bool t
(** Infinite sequence of random bool values *) (** Infinite iterator of random bool values *)
val random_float : float -> float t val random_float : float -> float t
@ -704,7 +704,7 @@ val random_array : 'a array -> 'a t
(** Iterator of choices of an element in the array *) (** Iterator of choices of an element in the array *)
val random_list : 'a list -> 'a t val random_list : 'a list -> 'a t
(** Infinite sequence of random elements of the list. Basically the (** Infinite iterator of random elements of the list. Basically the
same as {!random_array}. *) same as {!random_array}. *)
val shuffle : 'a t -> 'a t val shuffle : 'a t -> 'a t
@ -716,7 +716,7 @@ val shuffle_buffer : int -> 'a t -> 'a t
(** [shuffle_buffer n seq] returns an iterator of element of [seq] in random (** [shuffle_buffer n seq] returns an iterator of element of [seq] in random
order. The shuffling is *not* uniform. Uses O(n) memory. order. The shuffling is *not* uniform. Uses O(n) memory.
The first [n] elements of the sequence are consumed immediately. The The first [n] elements of the iterator are consumed immediately. The
rest is consumed lazily. rest is consumed lazily.
@since 0.7 *) @since 0.7 *)
@ -724,7 +724,7 @@ val shuffle_buffer : int -> 'a t -> 'a t
val sample : int -> 'a t -> 'a array val sample : int -> 'a t -> 'a array
(** [sample n seq] returns k samples of [seq], with uniform probability. (** [sample n seq] returns k samples of [seq], with uniform probability.
It will consume the sequence and use O(n) memory. It will consume the iterator and use O(n) memory.
It returns an array of size [min (length seq) n]. It returns an array of size [min (length seq) n].
@since 0.7 *) @since 0.7 *)
@ -754,13 +754,13 @@ module Infix : sig
@since 0.5 *) @since 0.5 *)
val (<+>) : 'a t -> 'a t -> 'a t val (<+>) : 'a t -> 'a t -> 'a t
(** Concatenation of sequences (** Concatenation of iterators
@since 0.5 *) @since 0.5 *)
end end
include module type of Infix include module type of Infix
(** {2 Pretty printing of sequences} *) (** {2 Pretty printing of iterators} *)
val pp_seq : ?sep:string -> (Format.formatter -> 'a -> unit) -> val pp_seq : ?sep:string -> (Format.formatter -> 'a -> unit) ->
Format.formatter -> 'a t -> unit Format.formatter -> 'a t -> unit
@ -776,8 +776,8 @@ val to_string : ?sep:string -> ('a -> string) -> 'a t -> string
(** {2 Basic IO} (** {2 Basic IO}
Very basic interface to manipulate files as sequence of chunks/lines. The Very basic interface to manipulate files as iterator of chunks/lines. The
sequences take care of opening and closing files properly; every time iterators take care of opening and closing files properly; every time
one iterates over an iterator, the file is opened/closed again. one iterates over an iterator, the file is opened/closed again.
Example: copy a file ["a"] into file ["b"], removing blank lines: Example: copy a file ["a"] into file ["b"], removing blank lines:
@ -807,7 +807,7 @@ module IO : sig
same exception as would opening the file and read from it, except same exception as would opening the file and read from it, except
from [End_of_file] (which is caught). The file is {b always} properly from [End_of_file] (which is caught). The file is {b always} properly
closed. closed.
Every time the sequence is iterated on, the file is opened again, so Every time the iterator is iterated on, the file is opened again, so
different iterations might return different results different iterations might return different results
@param mode default [0o644] @param mode default [0o644]
@param flags default: [[Open_rdonly]] *) @param flags default: [[Open_rdonly]] *)
@ -816,7 +816,7 @@ module IO : sig
string -> string t string -> string t
(** Read chunks of the given [size] from the file. The last chunk might be (** Read chunks of the given [size] from the file. The last chunk might be
smaller. Behaves like {!lines_of} regarding errors and options. smaller. Behaves like {!lines_of} regarding errors and options.
Every time the sequence is iterated on, the file is opened again, so Every time the iterator is iterated on, the file is opened again, so
different iterations might return different results *) different iterations might return different results *)
val write_to : ?mode:int -> ?flags:open_flag list -> val write_to : ?mode:int -> ?flags:open_flag list ->

184
src/IterLabels.mli
View file

@ -1,5 +1,5 @@
(* This file is free software, part of sequence. See file "license" for more details. *) (* This file is free software, part of iterator. See file "license" for more details. *)
(** {1 Simple and Efficient Iterators} (** {1 Simple and Efficient Iterators}
@ -31,19 +31,19 @@ val from_labelled_iter : (f:('a -> unit) -> unit) -> 'a t
val from_fun : (unit -> 'a option) -> 'a t val from_fun : (unit -> 'a option) -> 'a t
(** Call the function repeatedly until it returns None. This (** Call the function repeatedly until it returns None. This
sequence is transient, use {!persistent} if needed! *) iterator is transient, use {!persistent} if needed! *)
val empty : 'a t val empty : 'a t
(** Empty sequence. It contains no element. *) (** Empty iterator. It contains no element. *)
val singleton : 'a -> 'a t val singleton : 'a -> 'a t
(** Singleton sequence, with exactly one element. *) (** Singleton iterator, with exactly one element. *)
val doubleton : 'a -> 'a -> 'a t val doubleton : 'a -> 'a -> 'a t
(** Iterator with exactly two elements *) (** Iterator with exactly two elements *)
val init : f:(int -> 'a) -> 'a t val init : f:(int -> 'a) -> 'a t
(** [init f] is the infinite sequence [f 0; f 1; f 2; …]. (** [init f] is the infinite iterator [f 0; f 1; f 2; …].
@since 0.9 *) @since 0.9 *)
val cons : 'a -> 'a t -> 'a t val cons : 'a -> 'a t -> 'a t
@ -60,37 +60,37 @@ val pure : 'a -> 'a t
(** Synonym to {!singleton} *) (** Synonym to {!singleton} *)
val repeat : 'a -> 'a t val repeat : 'a -> 'a t
(** Infinite sequence of the same element. You may want to look (** Infinite iterator of the same element. You may want to look
at {!take} and the likes if you iterate on it. *) at {!take} and the likes if you iterate on it. *)
val iterate : ('a -> 'a) -> 'a -> 'a t val iterate : ('a -> 'a) -> 'a -> 'a t
(** [iterate f x] is the infinite sequence [x, f(x), f(f(x)), ...] *) (** [iterate f x] is the infinite iterator [x, f(x), f(f(x)), ...] *)
val forever : (unit -> 'b) -> 'b t val forever : (unit -> 'b) -> 'b t
(** Iterator that calls the given function to produce elements. (** Iterator that calls the given function to produce elements.
The sequence may be transient (depending on the function), and definitely The iterator may be transient (depending on the function), and definitely
is infinite. You may want to use {!take} and {!persistent}. *) is infinite. You may want to use {!take} and {!persistent}. *)
val cycle : 'a t -> 'a t val cycle : 'a t -> 'a t
(** Cycle forever through the given sequence. Assume the given sequence can (** Cycle forever through the given iterator. Assume the given iterator can
be traversed any amount of times (not transient). This yields an be traversed any amount of times (not transient). This yields an
infinite sequence, you should use something like {!take} not to loop infinite iterator, you should use something like {!take} not to loop
forever. *) forever. *)
(** {2 Consume an iterator} *) (** {2 Consume an iterator} *)
val iter : f:('a -> unit) -> 'a t -> unit val iter : f:('a -> unit) -> 'a t -> unit
(** Consume the sequence, passing all its arguments to the function. (** Consume the iterator, passing all its arguments to the function.
Basically [iter f seq] is just [seq f]. *) Basically [iter f seq] is just [seq f]. *)
val iteri : f:(int -> 'a -> unit) -> 'a t -> unit val iteri : f:(int -> 'a -> unit) -> 'a t -> unit
(** Iterate on elements and their index in the sequence *) (** Iterate on elements and their index in the iterator *)
val fold : f:('a -> 'b -> 'a) -> init:'a -> 'b t -> 'a val fold : f:('a -> 'b -> 'a) -> init:'a -> 'b t -> 'a
(** Fold over elements of the sequence, consuming it *) (** Fold over elements of the iterator, consuming it *)
val foldi : f:('a -> int -> 'b -> 'a) -> init:'a -> 'b t -> 'a val foldi : f:('a -> int -> 'b -> 'a) -> init:'a -> 'b t -> 'a
(** Fold over elements of the sequence and their index, consuming it *) (** Fold over elements of the iterator and their index, consuming it *)
val fold_map : f:('acc -> 'a -> 'acc * 'b) -> init:'acc -> 'a t -> 'b t val fold_map : f:('acc -> 'a -> 'acc * 'b) -> init:'acc -> 'a t -> 'b t
(** [fold_map f acc l] is like {!map}, but it carries some state as in (** [fold_map f acc l] is like {!map}, but it carries some state as in
@ -104,14 +104,14 @@ val fold_filter_map : f:('acc -> 'a -> 'acc * 'b option) -> init:'acc -> 'a t ->
@since 0.9 *) @since 0.9 *)
val map : f:('a -> 'b) -> 'a t -> 'b t val map : f:('a -> 'b) -> 'a t -> 'b t
(** Map objects of the sequence into other elements, lazily *) (** Map objects of the iterator into other elements, lazily *)
val mapi : f:(int -> 'a -> 'b) -> 'a t -> 'b t val mapi : f:(int -> 'a -> 'b) -> 'a t -> 'b t
(** Map objects, along with their index in the sequence *) (** Map objects, along with their index in the iterator *)
val map_by_2 : f:('a -> 'a -> 'a) -> 'a t -> 'a t val map_by_2 : f:('a -> 'a -> 'a) -> 'a t -> 'a t
(** Map objects two by two. lazily. (** Map objects two by two. lazily.
The last element is kept in the sequence if the count is odd. The last element is kept in the iterator if the count is odd.
@since 0.7 *) @since 0.7 *)
val for_all : f:('a -> bool) -> 'a t -> bool val for_all : f:('a -> bool) -> 'a t -> bool
@ -121,7 +121,7 @@ val exists : f:('a -> bool) -> 'a t -> bool
(** Exists there some element satisfying the predicate? *) (** Exists there some element satisfying the predicate? *)
val mem : ?eq:('a -> 'a -> bool) -> x:'a -> 'a t -> bool val mem : ?eq:('a -> 'a -> bool) -> x:'a -> 'a t -> bool
(** Is the value a member of the sequence? (** Is the value a member of the iterator?
@param eq the equality predicate to use (default [(=)]) @param eq the equality predicate to use (default [(=)])
@since 0.5 *) @since 0.5 *)
@ -152,27 +152,27 @@ val find_pred_exn : f:('a -> bool) -> 'a t -> 'a
@since 0.9 *) @since 0.9 *)
val length : 'a t -> int val length : 'a t -> int
(** How long is the sequence? Forces the sequence. *) (** How long is the iterator? Forces the iterator. *)
val is_empty : 'a t -> bool val is_empty : 'a t -> bool
(** Is the sequence empty? Forces the sequence. *) (** Is the iterator empty? Forces the iterator. *)
(** {2 Transform an iterator} *) (** {2 Transform an iterator} *)
val filter : f:('a -> bool) -> 'a t -> 'a t val filter : f:('a -> bool) -> 'a t -> 'a t
(** Filter on elements of the sequence *) (** Filter on elements of the iterator *)
val append : 'a t -> 'a t -> 'a t val append : 'a t -> 'a t -> 'a t
(** Append two sequences. Iterating on the result is like iterating (** Append two iterators. Iterating on the result is like iterating
on the first, then on the second. *) on the first, then on the second. *)
val append_l : 'a t list -> 'a t val append_l : 'a t list -> 'a t
(** Append sequences. Iterating on the result is like iterating (** Append iterators. Iterating on the result is like iterating
on the each sequence of the list in order. on the each iterator of the list in order.
@since 0.11 *) @since 0.11 *)
val concat : 'a t t -> 'a t val concat : 'a t t -> 'a t
(** Concatenate an iterator of sequences into one sequence. *) (** Concatenate an iterator of iterators into one iterator. *)
val flatten : 'a t t -> 'a t val flatten : 'a t t -> 'a t
(** Alias for {!concat} *) (** Alias for {!concat} *)
@ -185,8 +185,8 @@ val flat_map_l : f:('a -> 'b list) -> 'a t -> 'b t
@since 0.9 *) @since 0.9 *)
val seq_list : 'a t list -> 'a list t val seq_list : 'a t list -> 'a list t
(** [seq_list l] returns all the ways to pick one element in each sub-sequence (** [seq_list l] returns all the ways to pick one element in each sub-iterator
in [l]. Assumes the sub-sequences can be iterated on several times. in [l]. Assumes the sub-iterators can be iterated on several times.
@since 0.11 *) @since 0.11 *)
val seq_list_map : f:('a -> 'b t) -> 'a list -> 'b list t val seq_list_map : f:('a -> 'b t) -> 'a list -> 'b list t
@ -207,7 +207,7 @@ val filter_count : f:('a -> bool) -> 'a t -> int
@since 1.0 *) @since 1.0 *)
val intersperse : x:'a -> 'a t -> 'a t val intersperse : x:'a -> 'a t -> 'a t
(** Insert the single element between every element of the sequence *) (** Insert the single element between every element of the iterator *)
val keep_some : 'a option t -> 'a t val keep_some : 'a option t -> 'a t
(** [filter_some l] retains only elements of the form [Some x]. (** [filter_some l] retains only elements of the form [Some x].
@ -225,14 +225,14 @@ val keep_error : (_, 'e) Result.result t -> 'e t
(** {2 Caching} *) (** {2 Caching} *)
val persistent : 'a t -> 'a t val persistent : 'a t -> 'a t
(** Iterate on the sequence, storing elements in an efficient internal structure.. (** Iterate on the iterator, storing elements in an efficient internal structure..
The resulting sequence can be iterated on as many times as needed. The resulting iterator can be iterated on as many times as needed.
{b Note}: calling persistent on an already persistent sequence {b Note}: calling persistent on an already persistent iterator
will still make a new copy of the sequence! *) will still make a new copy of the iterator! *)
val persistent_lazy : 'a t -> 'a t val persistent_lazy : 'a t -> 'a t
(** Lazy version of {!persistent}. When calling [persistent_lazy s], (** Lazy version of {!persistent}. When calling [persistent_lazy s],
a new sequence [s'] is immediately returned (without actually consuming a new iterator [s'] is immediately returned (without actually consuming
[s]) in constant time; the first time [s'] is iterated on, [s]) in constant time; the first time [s'] is iterated on,
it also consumes [s] and caches its content into a inner data it also consumes [s] and caches its content into a inner data
structure that will back [s'] for future iterations. structure that will back [s'] for future iterations.
@ -244,15 +244,15 @@ val persistent_lazy : 'a t -> 'a t
(** {2 Misc} *) (** {2 Misc} *)
val sort : ?cmp:('a -> 'a -> int) -> 'a t -> 'a t 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 iterator. Eager, O(n) ram and O(n ln(n)) time.
It iterates on elements of the argument sequence immediately, It iterates on elements of the argument iterator immediately,
before it sorts them. *) before it sorts them. *)
val sort_uniq : ?cmp:('a -> 'a -> int) -> 'a t -> 'a t val sort_uniq : ?cmp:('a -> 'a -> int) -> 'a t -> 'a t
(** Sort the sequence and remove duplicates. Eager, same as [sort] *) (** Sort the iterator and remove duplicates. Eager, same as [sort] *)
val sorted : ?cmp:('a -> 'a -> int) -> 'a t -> bool val sorted : ?cmp:('a -> 'a -> int) -> 'a t -> bool
(** Checks whether the sequence is sorted. Eager, same as {!sort}. (** Checks whether the iterator is sorted. Eager, same as {!sort}.
@since 0.9 *) @since 0.9 *)
val group_succ_by : ?eq:('a -> 'a -> bool) -> 'a t -> 'a list t val group_succ_by : ?eq:('a -> 'a -> bool) -> 'a t -> 'a list t
@ -263,7 +263,7 @@ val group_succ_by : ?eq:('a -> 'a -> bool) -> 'a t -> 'a list t
val group_by : ?hash:('a -> int) -> ?eq:('a -> 'a -> bool) -> val group_by : ?hash:('a -> int) -> ?eq:('a -> 'a -> bool) ->
'a t -> 'a list t 'a t -> 'a list t
(** Group equal elements, disregarding their order of appearance. (** Group equal elements, disregarding their order of appearance.
The result sequence is traversable as many times as required. The result iterator is traversable as many times as required.
precondition: for any [x] and [y], if [eq x y] then [hash x=hash y] must hold. precondition: for any [x] and [y], if [eq x y] then [hash x=hash y] must hold.
@since 0.6 *) @since 0.6 *)
@ -278,19 +278,19 @@ val uniq : ?eq:('a -> 'a -> bool) -> 'a t -> 'a t
like [fun seq -> map List.hd (group seq)]. *) like [fun seq -> map List.hd (group seq)]. *)
val product : 'a t -> 'b t -> ('a * 'b) t val product : 'a t -> 'b t -> ('a * 'b) t
(** Cartesian product of the sequences. When calling [product a b], (** Cartesian product of the iterators. When calling [product a b],
the caller {b MUST} ensure that [b] can be traversed as many times the caller {b MUST} ensure that [b] can be traversed as many times
as required (several times), possibly by calling {!persistent} on it as required (several times), possibly by calling {!persistent} on it
beforehand. *) beforehand. *)
val diagonal_l : 'a list -> ('a * 'a) t val diagonal_l : 'a list -> ('a * 'a) t
(** All pairs of distinct positions of the list. [diagonal l] will (** All pairs of distinct positions of the list. [diagonal l] will
return the sequence of all [List.nth i l, List.nth j l] if [i < j]. return the iterator of all [List.nth i l, List.nth j l] if [i < j].
@since 0.9 *) @since 0.9 *)
val diagonal : 'a t -> ('a * 'a) t val diagonal : 'a t -> ('a * 'a) t
(** All pairs of distinct positions of the sequence. (** All pairs of distinct positions of the iterator.
Iterates only once on the sequence, which must be finite. Iterates only once on the iterator, which must be finite.
@since 0.9 *) @since 0.9 *)
val join : join_row:('a -> 'b -> 'c option) -> 'a t -> 'b t -> 'c t val join : join_row:('a -> 'b -> 'c option) -> 'a t -> 'b t -> 'c t
@ -306,7 +306,7 @@ val join_by : ?eq:'key equal -> ?hash:'key hash ->
'b t -> 'b t ->
'c t 'c t
(** [join key1 key2 ~merge] is a binary operation (** [join key1 key2 ~merge] is a binary operation
that takes two sequences [a] and [b], projects their that takes two iterators [a] and [b], projects their
elements resp. with [key1] and [key2], and combine elements resp. with [key1] and [key2], and combine
values [(x,y)] from [(a,b)] with the same [key] values [(x,y)] from [(a,b)] with the same [key]
using [merge]. If [merge] returns [None], the combination using [merge]. If [merge] returns [None], the combination
@ -321,7 +321,7 @@ val join_all_by : ?eq:'key equal -> ?hash:'key hash ->
'b t -> 'b t ->
'c t 'c t
(** [join_all_by key1 key2 ~merge] is a binary operation (** [join_all_by key1 key2 ~merge] is a binary operation
that takes two sequences [a] and [b], projects their that takes two iterators [a] and [b], projects their
elements resp. with [key1] and [key2], and, for each key [k] elements resp. with [key1] and [key2], and, for each key [k]
occurring in at least one of them: occurring in at least one of them:
- compute the list [l1] of elements of [a] that map to [k] - compute the list [l1] of elements of [a] that map to [k]
@ -337,9 +337,9 @@ val group_join_by : ?eq:'a equal -> ?hash:'a hash ->
'b t -> 'b t ->
('a * 'b list) t ('a * 'b list) t
(** [group_join_by key2] associates to every element [x] of (** [group_join_by key2] associates to every element [x] of
the first sequence, all the elements [y] of the second the first iterator, all the elements [y] of the second
sequence such that [eq x (key y)]. Elements of the first iterator such that [eq x (key y)]. Elements of the first
sequences without corresponding values in the second one iterators without corresponding values in the second one
are mapped to [[]] are mapped to [[]]
precondition: for any [x] and [y], if [eq x y] then [hash x=hash y] must hold. precondition: for any [x] and [y], if [eq x y] then [hash x=hash y] must hold.
@since 0.10 *) @since 0.10 *)
@ -400,22 +400,22 @@ val scan : ('b -> 'a -> 'b) -> 'b -> 'a t -> 'b t
(** Iterator of intermediate results *) (** Iterator of intermediate results *)
val max : ?lt:('a -> 'a -> bool) -> 'a t -> 'a option val max : ?lt:('a -> 'a -> bool) -> 'a t -> 'a option
(** Max element of the sequence, using the given comparison function. (** Max element of the iterator, using the given comparison function.
@return None if the sequence is empty, Some [m] where [m] is the maximal @return None if the iterator is empty, Some [m] where [m] is the maximal
element otherwise *) element otherwise *)
val max_exn : ?lt:('a -> 'a -> bool) -> 'a t -> 'a val max_exn : ?lt:('a -> 'a -> bool) -> 'a t -> 'a
(** Unsafe version of {!max} (** Unsafe version of {!max}
@raise Not_found if the sequence is empty @raise Not_found if the iterator is empty
@since 0.10 *) @since 0.10 *)
val min : ?lt:('a -> 'a -> bool) -> 'a t -> 'a option val min : ?lt:('a -> 'a -> bool) -> 'a t -> 'a option
(** Min element of the sequence, using the given comparison function. (** Min element of the iterator, using the given comparison function.
see {!max} for more details. *) see {!max} for more details. *)
val min_exn : ?lt:('a -> 'a -> bool) -> 'a t -> 'a val min_exn : ?lt:('a -> 'a -> bool) -> 'a t -> 'a
(** Unsafe version of {!min} (** Unsafe version of {!min}
@raise Not_found if the sequence is empty @raise Not_found if the iterator is empty
@since 0.10 *) @since 0.10 *)
val sum : int t -> int val sum : int t -> int
@ -432,36 +432,36 @@ val head : 'a t -> 'a option
val head_exn : 'a t -> 'a val head_exn : 'a t -> 'a
(** First element, if any, fails (** First element, if any, fails
@raise Invalid_argument if the sequence is empty @raise Invalid_argument if the iterator is empty
@since 0.5.1 *) @since 0.5.1 *)
val take : int -> 'a t -> 'a t val take : int -> 'a t -> 'a t
(** Take at most [n] elements from the sequence. Works on infinite (** Take at most [n] elements from the iterator. Works on infinite
sequences. *) iterators. *)
val take_while : f:('a -> bool) -> 'a t -> 'a t val take_while : f:('a -> bool) -> 'a t -> 'a t
(** Take elements while they satisfy the predicate, then stops iterating. (** Take elements while they satisfy the predicate, then stops iterating.
Will work on an infinite sequence [s] if the predicate is false for at Will work on an infinite iterator [s] if the predicate is false for at
least one element of [s]. *) least one element of [s]. *)
val fold_while : f:('a -> 'b -> 'a * [`Stop | `Continue]) -> init:'a -> 'b t -> 'a val fold_while : f:('a -> 'b -> 'a * [`Stop | `Continue]) -> init:'a -> 'b t -> 'a
(** Folds over elements of the sequence, stopping early if the accumulator (** Folds over elements of the iterator, stopping early if the accumulator
returns [('a, `Stop)] returns [('a, `Stop)]
@since 0.5.5 *) @since 0.5.5 *)
val drop : int -> 'a t -> 'a t val drop : int -> 'a t -> 'a t
(** Drop the [n] first elements of the sequence. Lazy. *) (** Drop the [n] first elements of the iterator. Lazy. *)
val drop_while : f:('a -> bool) -> 'a t -> 'a t val drop_while : f:('a -> bool) -> 'a t -> 'a t
(** Predicate version of {!drop} *) (** Predicate version of {!drop} *)
val rev : 'a t -> 'a t val rev : 'a t -> 'a t
(** Reverse the sequence. O(n) memory and time, needs the (** Reverse the iterator. O(n) memory and time, needs the
sequence to be finite. The result is persistent and does iterator to be finite. The result is persistent and does
not depend on the input being repeatable. *) not depend on the input being repeatable. *)
val zip_i : 'a t -> (int * 'a) t val zip_i : 'a t -> (int * 'a) t
(** Zip elements of the sequence with their index in the sequence. (** Zip elements of the iterator with their index in the iterator.
Changed type @since 1.0 to just give an iterator of pairs *) Changed type @since 1.0 to just give an iterator of pairs *)
val fold2 : f:('c -> 'a -> 'b -> 'c) -> init:'c -> ('a * 'b) t -> 'c val fold2 : f:('c -> 'a -> 'b -> 'c) -> init:'c -> ('a * 'b) t -> 'c
@ -476,12 +476,12 @@ val map2_2 : f:('a -> 'b -> 'c) -> ('a -> 'b -> 'd) -> ('a * 'b) t -> ('c * 'd)
(** {2 Basic data structures converters} *) (** {2 Basic data structures converters} *)
val to_list : 'a t -> 'a list val to_list : 'a t -> 'a list
(** Convert the sequence into a list. Preserves order of elements. (** Convert the iterator into a list. Preserves order of elements.
This function is tail-recursive, but consumes 2*n memory. This function is tail-recursive, but consumes 2*n memory.
If order doesn't matter to you, consider {!to_rev_list}. *) If order doesn't matter to you, consider {!to_rev_list}. *)
val to_rev_list : 'a t -> 'a list val to_rev_list : 'a t -> 'a list
(** Get the list of the reversed sequence (more efficient than {!to_list}) *) (** Get the list of the reversed iterator (more efficient than {!to_list}) *)
val of_list : 'a list -> 'a t val of_list : 'a list -> 'a t
@ -491,7 +491,7 @@ val on_list : ('a t -> 'b t) -> 'a list -> 'b list
*) *)
val pair_with_idx : 'a t -> (int * 'a) t val pair_with_idx : 'a t -> (int * 'a) t
(** Similar to {!zip_i} but returns a normal sequence of tuples (** Similar to {!zip_i} but returns a normal iterator of tuples
@since 0.11 *) @since 0.11 *)
val to_opt : 'a t -> 'a option val to_opt : 'a t -> 'a option
@ -522,23 +522,23 @@ val to_stream : 'a t -> 'a Stream.t
(** Convert to a stream. linear in memory and time (a copy is made in memory) *) (** Convert to a stream. linear in memory and time (a copy is made in memory) *)
val to_stack : 'a Stack.t -> 'a t -> unit val to_stack : 'a Stack.t -> 'a t -> unit
(** Push elements of the sequence on the stack *) (** Push elements of the iterator on the stack *)
val of_stack : 'a Stack.t -> 'a t val of_stack : 'a Stack.t -> 'a t
(** Iterator of elements of the stack (same order as [Stack.iter]) *) (** Iterator of elements of the stack (same order as [Stack.iter]) *)
val to_queue : 'a Queue.t -> 'a t -> unit val to_queue : 'a Queue.t -> 'a t -> unit
(** Push elements of the sequence into the queue *) (** Push elements of the iterator into the queue *)
val of_queue : 'a Queue.t -> 'a t val of_queue : 'a Queue.t -> 'a t
(** Iterator of elements contained in the queue, FIFO order *) (** Iterator of elements contained in the queue, FIFO order *)
val hashtbl_add : ('a, 'b) Hashtbl.t -> ('a * 'b) t -> unit val hashtbl_add : ('a, 'b) Hashtbl.t -> ('a * 'b) t -> unit
(** Add elements of the sequence to the hashtable, with (** Add elements of the iterator to the hashtable, with
Hashtbl.add *) Hashtbl.add *)
val hashtbl_replace : ('a, 'b) Hashtbl.t -> ('a * 'b) t -> unit val hashtbl_replace : ('a, 'b) Hashtbl.t -> ('a * 'b) t -> unit
(** Add elements of the sequence to the hashtable, with (** Add elements of the iterator to the hashtable, with
Hashtbl.replace (erases conflicting bindings) *) Hashtbl.replace (erases conflicting bindings) *)
val to_hashtbl : ('a * 'b) t -> ('a, 'b) Hashtbl.t val to_hashtbl : ('a * 'b) t -> ('a, 'b) Hashtbl.t
@ -564,12 +564,12 @@ exception OneShotSequence
val of_in_channel : in_channel -> char t val of_in_channel : in_channel -> char t
(** Iterates on characters of the input (can block when one (** Iterates on characters of the input (can block when one
iterates over the sequence). If you need to iterate iterates over the iterator). If you need to iterate
several times on this sequence, use {!persistent}. several times on this iterator, use {!persistent}.
@raise OneShotSequence when used more than once. *) @raise OneShotIterator when used more than once. *)
val to_buffer : char t -> Buffer.t -> unit val to_buffer : char t -> Buffer.t -> unit
(** Copy content of the sequence into the buffer *) (** Copy content of the iterator into the buffer *)
val int_range : start:int -> stop:int -> int t val int_range : start:int -> stop:int -> int t
(** Iterator on integers in [start...stop] by steps 1. Also see (** Iterator on integers in [start...stop] by steps 1. Also see
@ -582,7 +582,7 @@ val int_range_dec : start:int -> stop:int -> int t
val int_range_by : step:int -> start:int -> stop:int -> int t val int_range_by : step:int -> start:int -> stop:int -> int t
(** [int_range_by ~step ~start:i ~stop:j] is the range starting at [i], including [j], (** [int_range_by ~step ~start:i ~stop:j] is the range starting at [i], including [j],
where the difference between successive elements is [step]. where the difference between successive elements is [step].
use a negative [step] for a decreasing sequence. use a negative [step] for a decreasing iterator.
@since 0.9 @since 0.9
@raise Invalid_argument if [step=0] *) @raise Invalid_argument if [step=0] *)
@ -594,7 +594,7 @@ val of_set : (module Set.S with type elt = 'a and type t = 'b) -> 'b -> 'a t
(** Convert the given set to an iterator. The set module must be provided. *) (** Convert the given set to an iterator. The set module must be provided. *)
val to_set : (module Set.S with type elt = 'a and type t = 'b) -> 'a t -> 'b val to_set : (module Set.S with type elt = 'a and type t = 'b) -> 'a t -> 'b
(** Convert the sequence to a set, given the proper set module *) (** Convert the iterator to a set, given the proper set module *)
type 'a gen = unit -> 'a option type 'a gen = unit -> 'a option
type 'a klist = unit -> [`Nil | `Cons of 'a * 'a klist] type 'a klist = unit -> [`Nil | `Cons of 'a * 'a klist]
@ -603,15 +603,15 @@ val of_gen : 'a gen -> 'a t
(** Traverse eagerly the generator and build an iterator from it *) (** Traverse eagerly the generator and build an iterator from it *)
val to_gen : 'a t -> 'a gen val to_gen : 'a t -> 'a gen
(** Make the sequence persistent (O(n)) and then iterate on it. Eager. *) (** Make the iterator persistent (O(n)) and then iterate on it. Eager. *)
val of_klist : 'a klist -> 'a t val of_klist : 'a klist -> 'a t
(** Iterate on the lazy list *) (** Iterate on the lazy list *)
val to_klist : 'a t -> 'a klist val to_klist : 'a t -> 'a klist
(** Make the sequence persistent and then iterate on it. Eager. *) (** Make the iterator persistent and then iterate on it. Eager. *)
(** {2 Functorial conversions between sets and sequences} *) (** {2 Functorial conversions between sets and iterators} *)
module Set : sig module Set : sig
module type S = sig module type S = sig
@ -635,7 +635,7 @@ module Set : sig
module Make(X : Set.OrderedType) : S with type elt = X.t module Make(X : Set.OrderedType) : S with type elt = X.t
end end
(** {2 Conversion between maps and sequences.} *) (** {2 Conversion between maps and iterators.} *)
module Map : sig module Map : sig
module type S = sig module type S = sig
@ -654,21 +654,21 @@ module Map : sig
(** @deprecated use {!of_iter} instead *) (** @deprecated use {!of_iter} instead *)
end end
(** Adapt a pre-existing Map module to make it sequence-aware *) (** Adapt a pre-existing Map module to make it iterator-aware *)
module Adapt(M : Map.S) : S with type key = M.key and type 'a t = 'a M.t module Adapt(M : Map.S) : S with type key = M.key and type 'a t = 'a M.t
(** Create an enriched Map module, with sequence-aware functions *) (** Create an enriched Map module, with iterator-aware functions *)
module Make(V : Map.OrderedType) : S with type key = V.t module Make(V : Map.OrderedType) : S with type key = V.t
end end
(** {2 Infinite sequences of random values} *) (** {2 Infinite iterators of random values} *)
val random_int : int -> int t val random_int : int -> int t
(** Infinite sequence of random integers between 0 and (** Infinite iterator of random integers between 0 and
the given higher bound (see Random.int) *) the given higher bound (see Random.int) *)
val random_bool : bool t val random_bool : bool t
(** Infinite sequence of random bool values *) (** Infinite iterator of random bool values *)
val random_float : float -> float t val random_float : float -> float t
@ -676,7 +676,7 @@ val random_array : 'a array -> 'a t
(** Iterator of choices of an element in the array *) (** Iterator of choices of an element in the array *)
val random_list : 'a list -> 'a t val random_list : 'a list -> 'a t
(** Infinite sequence of random elements of the list. Basically the (** Infinite iterator of random elements of the list. Basically the
same as {!random_array}. *) same as {!random_array}. *)
val shuffle : 'a t -> 'a t val shuffle : 'a t -> 'a t
@ -688,7 +688,7 @@ val shuffle_buffer : n:int -> 'a t -> 'a t
(** [shuffle_buffer n seq] returns an iterator of element of [seq] in random (** [shuffle_buffer n seq] returns an iterator of element of [seq] in random
order. The shuffling is not uniform. Uses O(n) memory. order. The shuffling is not uniform. Uses O(n) memory.
The first [n] elements of the sequence are consumed immediately. The The first [n] elements of the iterator are consumed immediately. The
rest is consumed lazily. rest is consumed lazily.
@since 0.7 *) @since 0.7 *)
@ -696,7 +696,7 @@ val shuffle_buffer : n:int -> 'a t -> 'a t
val sample : n:int -> 'a t -> 'a array val sample : n:int -> 'a t -> 'a array
(** [sample n seq] returns k samples of [seq], with uniform probability. (** [sample n seq] returns k samples of [seq], with uniform probability.
It will consume the sequence and use O(n) memory. It will consume the iterator and use O(n) memory.
It returns an array of size [min (length seq) n]. It returns an array of size [min (length seq) n].
@since 0.7 *) @since 0.7 *)
@ -726,13 +726,13 @@ module Infix : sig
@since 0.5 *) @since 0.5 *)
val (<+>) : 'a t -> 'a t -> 'a t val (<+>) : 'a t -> 'a t -> 'a t
(** Concatenation of sequences (** Concatenation of iterators
@since 0.5 *) @since 0.5 *)
end end
include module type of Infix include module type of Infix
(** {2 Pretty printing of sequences} *) (** {2 Pretty printing of iterators} *)
val pp_seq : ?sep:string -> (Format.formatter -> 'a -> unit) -> val pp_seq : ?sep:string -> (Format.formatter -> 'a -> unit) ->
Format.formatter -> 'a t -> unit Format.formatter -> 'a t -> unit
@ -748,8 +748,8 @@ val to_string : ?sep:string -> ('a -> string) -> 'a t -> string
(** {2 Basic IO} (** {2 Basic IO}
Very basic interface to manipulate files as sequence of chunks/lines. The Very basic interface to manipulate files as iterator of chunks/lines. The
sequences take care of opening and closing files properly; every time iterators take care of opening and closing files properly; every time
one iterates over an iterator, the file is opened/closed again. one iterates over an iterator, the file is opened/closed again.
Example: copy a file ["a"] into file ["b"], removing blank lines: Example: copy a file ["a"] into file ["b"], removing blank lines:
@ -779,7 +779,7 @@ module IO : sig
same exception as would opening the file and read from it, except same exception as would opening the file and read from it, except
from [End_of_file] (which is caught). The file is {b always} properly from [End_of_file] (which is caught). The file is {b always} properly
closed. closed.
Every time the sequence is iterated on, the file is opened again, so Every time the iterator is iterated on, the file is opened again, so
different iterations might return different results different iterations might return different results
@param mode default [0o644] @param mode default [0o644]
@param flags default: [[Open_rdonly]] *) @param flags default: [[Open_rdonly]] *)
@ -788,7 +788,7 @@ module IO : sig
string -> string t string -> string t
(** Read chunks of the given [size] from the file. The last chunk might be (** Read chunks of the given [size] from the file. The last chunk might be
smaller. Behaves like {!lines_of} regarding errors and options. smaller. Behaves like {!lines_of} regarding errors and options.
Every time the sequence is iterated on, the file is opened again, so Every time the iterator is iterated on, the file is opened again, so
different iterations might return different results *) different iterations might return different results *)
val write_to : ?mode:int -> ?flags:open_flag list -> val write_to : ?mode:int -> ?flags:open_flag list ->

2
src/bench/bench_persistent.ml
View file

@ -77,7 +77,7 @@ module MList = struct
(** Build a MList of elements of the Seq. The optional argument indicates (** Build a MList of elements of the Seq. The optional argument indicates
the size of the blocks *) the size of the blocks *)
let of_seq ?(size=8) seq = let of_seq ?(size=8) seq =
(* read sequence into a MList.t *) (* read iterator into a MList.t *)
let start = make size in let start = make size in
let l = ref start in let l = ref start in
seq (fun x -> l := push x !l); seq (fun x -> l := push x !l);

2
src/bench/bench_persistent_read.ml
View file

@ -77,7 +77,7 @@ module MList = struct
(** Build a MList of elements of the Seq. The optional argument indicates (** Build a MList of elements of the Seq. The optional argument indicates
the size of the blocks *) the size of the blocks *)
let of_seq ?(size=8) seq = let of_seq ?(size=8) seq =
(* read sequence into a MList.t *) (* read iterator into a MList.t *)
let start = make size in let start = make size in
let l = ref start in let l = ref start in
seq (fun x -> l := push x !l); seq (fun x -> l := push x !l);

2
src/bigarray/IterBigarray.ml
View file

@ -1,5 +1,5 @@
(* This file is free software, part of sequence. See file "license" for more details. *) (* This file is free software, part of iter. See file "license" for more details. *)
(** {1 Interface and Helpers for bigarrays} *) (** {1 Interface and Helpers for bigarrays} *)

2
src/bigarray/IterBigarray.mli
View file

@ -1,5 +1,5 @@
(* This file is free software, part of sequence. See file "license" for more details. *) (* This file is free software, part of iter. See file "license" for more details. *)
(** {1 Interface and Helpers for bigarrays} (** {1 Interface and Helpers for bigarrays}