diff --git a/.ocamlinit b/.ocamlinit index c753a9f..5898ef5 100644 --- a/.ocamlinit +++ b/.ocamlinit @@ -1,7 +1,7 @@ #directory "_build/src";; -#load "sequence.cma";; +#load "iter.cma";; -open Sequence.Infix;; +open Iter.Infix;; #directory "_build/src/bigarray/";; #load "bigarray.cma";; diff --git a/Makefile b/Makefile index af1db78..5fb1ec6 100644 --- a/Makefile +++ b/Makefile @@ -26,7 +26,7 @@ build-benchs: examples: 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: @echo "update version to $(VERSION)..." diff --git a/README.md b/README.md index 90ec053..cda3412 100644 --- a/README.md +++ b/README.md @@ -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, 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 @@ -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) 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. ## Build @@ -213,7 +213,7 @@ Be careful that this is quite obscure. - `Iter` is an *internal* iterator. When one wishes to iterate over 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. 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, diff --git a/examples/sexpr.ml b/examples/sexpr.ml index 8152d3c..46df7ef 100644 --- a/examples/sexpr.ml +++ b/examples/sexpr.ml @@ -27,7 +27,7 @@ type t = (** Token that compose a Sexpr once serialized *) 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 *) 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' -(** 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) -(** Returns the same sequence of tokens, but during iteration, if - the structure of the Sexpr corresponding to the sequence +(** Returns the same iterator of tokens, but during iteration, if + the structure of the Sexpr corresponding to the iterator is wrong (bad parenthesing), Invalid_argument is raised and iteration is stoped *) let validate seq = @@ -57,7 +57,7 @@ let validate seq = (** {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 seq_fun k = let in_word = ref false in @@ -83,7 +83,7 @@ let lex input = in 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 = (* called on every token *) let rec k stack token = match token with @@ -96,7 +96,7 @@ let of_seq seq = | `Expr a::stack' -> collapse (a :: acc) stack' | _ -> assert false in - (* iterate on the sequence, given an empty initial stack *) + (* iterate, given an empty initial stack *) let stack = Iter.fold k [] seq in (* stack should contain exactly one expression *) match stack with @@ -112,7 +112,7 @@ let pp_token formatter token = match token with | `Close -> Format.fprintf formatter ")@]" | `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 first = ref true in let last = ref false in @@ -149,7 +149,7 @@ let output_str name str k = (** {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. The [one] parser can raise ParseFailure if it fails to parse @@ -247,7 +247,7 @@ type 'a state = | Bottom : '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 state or whether to continue. *) let parse_k p tokens k = @@ -295,7 +295,7 @@ let parse p tokens = | None -> raise (ParseFailure "incomplete input") | Some x -> x -(** Parse a sequence of values *) +(** Parse an iterator of values *) let parse_seq p tokens = let seq_fun k = parse_k p tokens (fun x -> k x; `Continue) diff --git a/examples/sexpr.mli b/examples/sexpr.mli index af579b2..38239b8 100644 --- a/examples/sexpr.mli +++ b/examples/sexpr.mli @@ -28,27 +28,27 @@ type t = type token = [`Open | `Close | `Atom of string] (** 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 (** Iterate on the S-expression, calling the callback with tokens *) 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 - (** Returns the same sequence of tokens, but during iteration, if - the structure of the Sexpr corresponding to the sequence + (** Returns the same iterator of tokens, but during iteration, if + the structure of the Sexpr corresponding to the iterator is wrong (bad parenthesing), Invalid_argument is raised and iteration is stoped *) (** {2 Text <-> tokens} *) 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 - (** Build a Sexpr from a sequence of tokens, or raise Failure *) + (** Build a Sexpr from an iterator of tokens, or raise Failure *) (** {2 Printing} *) @@ -56,7 +56,7 @@ val pp_token : Format.formatter -> token -> unit (** Print a token on the given formatter *) 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 (** 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} *) 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 (** print a pair "(name str)" *) (** {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. *) type 'a parser @@ -125,8 +125,8 @@ val many : 'a parser -> 'a list parser val many1 : 'a parser -> 'a list parser 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. *) val parse_seq : 'a parser -> token Iter.t -> 'a Iter.t - (** Parses a sequence of values *) + (** Parses an iterator of values *) diff --git a/examples/test_sexpr.ml b/examples/test_sexpr.ml index edc46d7..0f7fc0c 100644 --- a/examples/test_sexpr.ml +++ b/examples/test_sexpr.ml @@ -1,5 +1,5 @@ -(** {2 Test sequences} *) +(** {2 Test iterators} *) (** print a list of items using the printing function *) let pp_list ?(sep=", ") pp_item formatter l = @@ -94,7 +94,7 @@ let _ = (Iter.of_array (Iter.to_array (Iter.append (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.persistent seq in let stream = Iter.to_stream seq' in diff --git a/iter.opam b/iter.opam index a13886e..42ee4a2 100644 --- a/iter.opam +++ b/iter.opam @@ -19,11 +19,11 @@ depends: [ "mdx" {with-test} "odoc" {with-doc} ] -tags: [ "sequence" "iterator" "iter" "fold" ] +tags: [ "iter" "iterator" "iter" "fold" ] homepage: "https://github.com/c-cube/iter/" depopts: [ "base-bigarray" ] -doc: "https://c-cube.github.io/sequence/" -bug-reports: "https://github.com/c-cube/sequence/issues" -dev-repo: "git+https://github.com/c-cube/sequence.git" +doc: "https://c-cube.github.io/iter/" +bug-reports: "https://github.com/c-cube/iter/issues" +dev-repo: "git+https://github.com/c-cube/iter.git" diff --git a/src/Iter.mli b/src/Iter.mli index 66cdc90..5d1d5f4 100644 --- a/src/Iter.mli +++ b/src/Iter.mli @@ -11,15 +11,15 @@ function is provided, storing elements of a transient iterator 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 - 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. 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} - on an iterator, one gets a new sequence, but nothing else happens until - this new sequence is used (by folding or iterating on it). + on an iterator, one gets a new iterator, but nothing else happens until + this new iterator is used (by folding or iterating on it). 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 @@ -55,19 +55,19 @@ val from_labelled_iter : (f:('a -> unit) -> unit) -> 'a t val from_fun : (unit -> 'a option) -> 'a t (** 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 -(** Empty sequence. It contains no element. *) +(** Empty iterator. It contains no element. *) val singleton : 'a -> 'a t -(** Singleton sequence, with exactly one element. *) +(** Singleton iterator, with exactly one element. *) val doubleton : 'a -> 'a -> 'a t (** Iterator with exactly two elements *) 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 *) val cons : 'a -> 'a t -> 'a t @@ -84,37 +84,37 @@ val pure : 'a -> 'a t (** Synonym to {!singleton} *) 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. *) 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 (** 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}. *) 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 - infinite sequence, you should use something like {!take} not to loop + infinite iterator, you should use something like {!take} not to loop forever. *) (** {2 Consume an iterator} *) 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]. *) 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 -(** 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 -(** 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 (** [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 *) 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 -(** 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 (** 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 *) 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? *) 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 [(=)]) @since 0.5 *) @@ -176,34 +176,34 @@ val find_pred_exn : ('a -> bool) -> 'a t -> 'a @since 0.9 *) 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 -(** Is the sequence empty? Forces the sequence. *) +(** Is the iterator empty? Forces the iterator. *) (** {2 Transform an iterator} *) 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 -(** 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. *) val append_l : 'a t list -> 'a t -(** Append sequences. Iterating on the result is like iterating - on the each sequence of the list in order. +(** Append iterators. Iterating on the result is like iterating + on the each iterator of the list in order. @since 0.11 *) 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 (** Alias for {!concat} *) val flat_map : ('a -> 'b t) -> 'a t -> 'b t (** 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] @since 0.5 *) @@ -212,8 +212,8 @@ val flat_map_l : ('a -> 'b list) -> 'a t -> 'b t @since 0.9 *) val seq_list : 'a t list -> 'a list t -(** [seq_list l] returns all the ways to pick one element in each sub-sequence - in [l]. Assumes the sub-sequences can be iterated on several times. +(** [seq_list l] returns all the ways to pick one element in each sub-iterator + in [l]. Assumes the sub-iterators can be iterated on several times. @since 0.11 *) 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 *) 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 (** [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} *) val persistent : 'a t -> 'a t -(** Iterate on the sequence, storing elements in an efficient internal structure.. - The resulting sequence can be iterated on as many times as needed. - {b Note}: calling persistent on an already persistent sequence - will still make a new copy of the sequence! *) +(** Iterate on the iterator, storing elements in an efficient internal structure.. + The resulting iterator can be iterated on as many times as needed. + {b Note}: calling persistent on an already persistent iterator + will still make a new copy of the iterator! *) val persistent_lazy : 'a t -> 'a t (** 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, it also consumes [s] and caches its content into a inner data structure that will back [s'] for future iterations. @@ -272,15 +272,15 @@ val persistent_lazy : 'a t -> 'a t (** {2 Misc} *) val sort : ?cmp:('a -> 'a -> int) -> 'a t -> 'a t -(** Sort the sequence. Eager, O(n) ram and O(n ln(n)) time. - It iterates on elements of the argument sequence immediately, +(** Sort the iterator. Eager, O(n) ram and O(n ln(n)) time. + It iterates on elements of the argument iterator 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] *) +(** Sort the iterator and remove duplicates. Eager, same as [sort] *) 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 *) 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) -> 'a t -> 'a list t (** 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. @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)]. *) 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 as required (several times), possibly by calling {!persistent} on it beforehand. *) val diagonal_l : 'a list -> ('a * 'a) t (** 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 *) val diagonal : 'a t -> ('a * 'a) t -(** All pairs of distinct positions of the sequence. - Iterates only once on the sequence, which must be finite. +(** All pairs of distinct positions of the iterator. + Iterates only once on the iterator, which must be finite. @since 0.9 *) 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 -> 'c t (** [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 values [(x,y)] from [(a,b)] with the same [key] using [merge]. If [merge] returns [None], the combination @@ -350,7 +350,7 @@ val join_all_by : ?eq:'key equal -> ?hash:'key hash -> 'b t -> 'c t (** [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] occurring in at least one of them: - 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 -> ('a * 'b list) t (** [group_join_by key2] associates to every element [x] of - the first sequence, all the elements [y] of the second - sequence such that [eq x (key y)]. Elements of the first - sequences without corresponding values in the second one + the first iterator, all the elements [y] of the second + iterator such that [eq x (key y)]. Elements of the first + iterators without corresponding values in the second one are mapped to [[]] precondition: for any [x] and [y], if [eq x y] then [hash x=hash y] must hold. @since 0.10 *) @@ -429,22 +429,22 @@ val scan : ('b -> 'a -> 'b) -> 'b -> 'a t -> 'b t (** Iterator of intermediate results *) val max : ?lt:('a -> 'a -> bool) -> 'a t -> 'a option -(** Max element of the sequence, using the given comparison function. - @return None if the sequence is empty, Some [m] where [m] is the maximal +(** Max element of the iterator, using the given comparison function. + @return None if the iterator is empty, Some [m] where [m] is the maximal element otherwise *) val max_exn : ?lt:('a -> 'a -> bool) -> 'a t -> 'a (** Unsafe version of {!max} - @raise Not_found if the sequence is empty + @raise Not_found if the iterator is empty @since 0.10 *) 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. *) val min_exn : ?lt:('a -> 'a -> bool) -> 'a t -> 'a (** Unsafe version of {!min} - @raise Not_found if the sequence is empty + @raise Not_found if the iterator is empty @since 0.10 *) val sum : int t -> int @@ -461,36 +461,36 @@ val head : 'a t -> 'a option val head_exn : 'a t -> 'a (** 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 *) val take : int -> 'a t -> 'a t -(** Take at most [n] elements from the sequence. Works on infinite - sequences. *) +(** Take at most [n] elements from the iterator. Works on infinite + iterators. *) val take_while : ('a -> bool) -> 'a t -> 'a t (** 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]. *) 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)] @since 0.5.5 *) 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 (** Predicate version of {!drop} *) val rev : 'a t -> 'a t -(** Reverse the sequence. O(n) memory and time, needs the - sequence to be finite. The result is persistent and does +(** Reverse the iterator. O(n) memory and time, needs the + iterator to be finite. The result is persistent and does not depend on the input being repeatable. *) 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 *) 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} *) 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. If order doesn't matter to you, consider {!to_rev_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 @@ -520,7 +520,7 @@ val on_list : ('a t -> 'b t) -> 'a list -> 'b list *) 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 *) 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) *) 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 (** Iterator of elements of the stack (same order as [Stack.iter]) *) 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 (** Iterator of elements contained in the queue, FIFO order *) 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 *) 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) *) val to_hashtbl : ('a * 'b) t -> ('a, 'b) Hashtbl.t @@ -593,12 +593,12 @@ exception OneShotSequence 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}. - @raise OneShotSequence when used more than once. *) + iterates over the iterator). If you need to iterate + several times on this iterator, use {!persistent}. + @raise OneShotIterator when used more than once. *) 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 (** 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 (** [int_range_by ~step i j] is the range starting at [i], including [j], 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] *) 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. *) 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 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 *) 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 (** Iterate on the lazy list *) 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 type S = sig @@ -663,7 +663,7 @@ module Set : sig module Make(X : Set.OrderedType) : S with type elt = X.t end -(** {2 Conversion between maps and sequences.} *) +(** {2 Conversion between maps and iterators.} *) module Map : sig module type S = sig @@ -682,21 +682,21 @@ module Map : sig (** @deprecated use {!of_iter} instead *) 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 - (** 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 end -(** {2 Infinite sequences of random values} *) +(** {2 Infinite iterators of random values} *) 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) *) val random_bool : bool t -(** Infinite sequence of random bool values *) +(** Infinite iterator of random bool values *) 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 *) 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}. *) 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 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. @since 0.7 *) @@ -724,7 +724,7 @@ val shuffle_buffer : int -> 'a t -> 'a t val sample : int -> 'a t -> 'a array (** [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]. @since 0.7 *) @@ -754,13 +754,13 @@ module Infix : sig @since 0.5 *) val (<+>) : 'a t -> 'a t -> 'a t - (** Concatenation of sequences + (** Concatenation of iterators @since 0.5 *) end include module type of Infix -(** {2 Pretty printing of sequences} *) +(** {2 Pretty printing of iterators} *) val pp_seq : ?sep:string -> (Format.formatter -> 'a -> unit) -> Format.formatter -> 'a t -> unit @@ -776,8 +776,8 @@ val to_string : ?sep:string -> ('a -> string) -> 'a t -> string (** {2 Basic IO} - Very basic interface to manipulate files as sequence of chunks/lines. The - sequences take care of opening and closing files properly; every time + Very basic interface to manipulate files as iterator of chunks/lines. The + iterators take care of opening and closing files properly; every time one iterates over an iterator, the file is opened/closed again. 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 from [End_of_file] (which is caught). The file is {b always} properly 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 @param mode default [0o644] @param flags default: [[Open_rdonly]] *) @@ -816,7 +816,7 @@ module IO : sig string -> string t (** Read chunks of the given [size] from the file. The last chunk might be 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 *) val write_to : ?mode:int -> ?flags:open_flag list -> diff --git a/src/IterLabels.mli b/src/IterLabels.mli index f0efd15..cde8328 100644 --- a/src/IterLabels.mli +++ b/src/IterLabels.mli @@ -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} @@ -31,19 +31,19 @@ val from_labelled_iter : (f:('a -> unit) -> unit) -> 'a t val from_fun : (unit -> 'a option) -> 'a t (** 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 -(** Empty sequence. It contains no element. *) +(** Empty iterator. It contains no element. *) val singleton : 'a -> 'a t -(** Singleton sequence, with exactly one element. *) +(** Singleton iterator, with exactly one element. *) val doubleton : 'a -> 'a -> 'a t (** Iterator with exactly two elements *) 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 *) val cons : 'a -> 'a t -> 'a t @@ -60,37 +60,37 @@ val pure : 'a -> 'a t (** Synonym to {!singleton} *) 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. *) 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 (** 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}. *) 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 - infinite sequence, you should use something like {!take} not to loop + infinite iterator, you should use something like {!take} not to loop forever. *) (** {2 Consume an iterator} *) 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]. *) 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 -(** 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 -(** 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 (** [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 *) 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 -(** 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 (** 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 *) 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? *) 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 [(=)]) @since 0.5 *) @@ -152,27 +152,27 @@ val find_pred_exn : f:('a -> bool) -> 'a t -> 'a @since 0.9 *) 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 -(** Is the sequence empty? Forces the sequence. *) +(** Is the iterator empty? Forces the iterator. *) (** {2 Transform an iterator} *) 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 -(** 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. *) val append_l : 'a t list -> 'a t -(** Append sequences. Iterating on the result is like iterating - on the each sequence of the list in order. +(** Append iterators. Iterating on the result is like iterating + on the each iterator of the list in order. @since 0.11 *) 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 (** Alias for {!concat} *) @@ -185,8 +185,8 @@ val flat_map_l : f:('a -> 'b list) -> 'a t -> 'b t @since 0.9 *) val seq_list : 'a t list -> 'a list t -(** [seq_list l] returns all the ways to pick one element in each sub-sequence - in [l]. Assumes the sub-sequences can be iterated on several times. +(** [seq_list l] returns all the ways to pick one element in each sub-iterator + in [l]. Assumes the sub-iterators can be iterated on several times. @since 0.11 *) 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 *) 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 (** [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} *) val persistent : 'a t -> 'a t -(** Iterate on the sequence, storing elements in an efficient internal structure.. - The resulting sequence can be iterated on as many times as needed. - {b Note}: calling persistent on an already persistent sequence - will still make a new copy of the sequence! *) +(** Iterate on the iterator, storing elements in an efficient internal structure.. + The resulting iterator can be iterated on as many times as needed. + {b Note}: calling persistent on an already persistent iterator + will still make a new copy of the iterator! *) val persistent_lazy : 'a t -> 'a t (** 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, it also consumes [s] and caches its content into a inner data structure that will back [s'] for future iterations. @@ -244,15 +244,15 @@ val persistent_lazy : 'a t -> 'a t (** {2 Misc} *) val sort : ?cmp:('a -> 'a -> int) -> 'a t -> 'a t -(** Sort the sequence. Eager, O(n) ram and O(n ln(n)) time. - It iterates on elements of the argument sequence immediately, +(** Sort the iterator. Eager, O(n) ram and O(n ln(n)) time. + It iterates on elements of the argument iterator 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] *) +(** Sort the iterator and remove duplicates. Eager, same as [sort] *) 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 *) 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) -> 'a t -> 'a list t (** 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. @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)]. *) 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 as required (several times), possibly by calling {!persistent} on it beforehand. *) val diagonal_l : 'a list -> ('a * 'a) t (** 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 *) val diagonal : 'a t -> ('a * 'a) t -(** All pairs of distinct positions of the sequence. - Iterates only once on the sequence, which must be finite. +(** All pairs of distinct positions of the iterator. + Iterates only once on the iterator, which must be finite. @since 0.9 *) 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 -> 'c t (** [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 values [(x,y)] from [(a,b)] with the same [key] using [merge]. If [merge] returns [None], the combination @@ -321,7 +321,7 @@ val join_all_by : ?eq:'key equal -> ?hash:'key hash -> 'b t -> 'c t (** [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] occurring in at least one of them: - 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 -> ('a * 'b list) t (** [group_join_by key2] associates to every element [x] of - the first sequence, all the elements [y] of the second - sequence such that [eq x (key y)]. Elements of the first - sequences without corresponding values in the second one + the first iterator, all the elements [y] of the second + iterator such that [eq x (key y)]. Elements of the first + iterators without corresponding values in the second one are mapped to [[]] precondition: for any [x] and [y], if [eq x y] then [hash x=hash y] must hold. @since 0.10 *) @@ -400,22 +400,22 @@ val scan : ('b -> 'a -> 'b) -> 'b -> 'a t -> 'b t (** Iterator of intermediate results *) val max : ?lt:('a -> 'a -> bool) -> 'a t -> 'a option -(** Max element of the sequence, using the given comparison function. - @return None if the sequence is empty, Some [m] where [m] is the maximal +(** Max element of the iterator, using the given comparison function. + @return None if the iterator is empty, Some [m] where [m] is the maximal element otherwise *) val max_exn : ?lt:('a -> 'a -> bool) -> 'a t -> 'a (** Unsafe version of {!max} - @raise Not_found if the sequence is empty + @raise Not_found if the iterator is empty @since 0.10 *) 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. *) val min_exn : ?lt:('a -> 'a -> bool) -> 'a t -> 'a (** Unsafe version of {!min} - @raise Not_found if the sequence is empty + @raise Not_found if the iterator is empty @since 0.10 *) val sum : int t -> int @@ -432,36 +432,36 @@ val head : 'a t -> 'a option val head_exn : 'a t -> 'a (** 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 *) val take : int -> 'a t -> 'a t -(** Take at most [n] elements from the sequence. Works on infinite - sequences. *) +(** Take at most [n] elements from the iterator. Works on infinite + iterators. *) val take_while : f:('a -> bool) -> 'a t -> 'a t (** 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]. *) 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)] @since 0.5.5 *) 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 (** Predicate version of {!drop} *) val rev : 'a t -> 'a t -(** Reverse the sequence. O(n) memory and time, needs the - sequence to be finite. The result is persistent and does +(** Reverse the iterator. O(n) memory and time, needs the + iterator to be finite. The result is persistent and does not depend on the input being repeatable. *) 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 *) 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} *) 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. If order doesn't matter to you, consider {!to_rev_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 @@ -491,7 +491,7 @@ val on_list : ('a t -> 'b t) -> 'a list -> 'b list *) 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 *) 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) *) 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 (** Iterator of elements of the stack (same order as [Stack.iter]) *) 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 (** Iterator of elements contained in the queue, FIFO order *) 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 *) 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) *) val to_hashtbl : ('a * 'b) t -> ('a, 'b) Hashtbl.t @@ -564,12 +564,12 @@ exception OneShotSequence 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}. - @raise OneShotSequence when used more than once. *) + iterates over the iterator). If you need to iterate + several times on this iterator, use {!persistent}. + @raise OneShotIterator when used more than once. *) 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 (** 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 (** [int_range_by ~step ~start:i ~stop:j] is the range starting at [i], including [j], 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 @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. *) 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 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 *) 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 (** Iterate on the lazy list *) 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 type S = sig @@ -635,7 +635,7 @@ module Set : sig module Make(X : Set.OrderedType) : S with type elt = X.t end -(** {2 Conversion between maps and sequences.} *) +(** {2 Conversion between maps and iterators.} *) module Map : sig module type S = sig @@ -654,21 +654,21 @@ module Map : sig (** @deprecated use {!of_iter} instead *) 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 - (** 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 end -(** {2 Infinite sequences of random values} *) +(** {2 Infinite iterators of random values} *) 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) *) val random_bool : bool t -(** Infinite sequence of random bool values *) +(** Infinite iterator of random bool values *) 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 *) 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}. *) 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 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. @since 0.7 *) @@ -696,7 +696,7 @@ val shuffle_buffer : n:int -> 'a t -> 'a t val sample : n:int -> 'a t -> 'a array (** [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]. @since 0.7 *) @@ -726,13 +726,13 @@ module Infix : sig @since 0.5 *) val (<+>) : 'a t -> 'a t -> 'a t - (** Concatenation of sequences + (** Concatenation of iterators @since 0.5 *) end include module type of Infix -(** {2 Pretty printing of sequences} *) +(** {2 Pretty printing of iterators} *) val pp_seq : ?sep:string -> (Format.formatter -> 'a -> unit) -> Format.formatter -> 'a t -> unit @@ -748,8 +748,8 @@ val to_string : ?sep:string -> ('a -> string) -> 'a t -> string (** {2 Basic IO} - Very basic interface to manipulate files as sequence of chunks/lines. The - sequences take care of opening and closing files properly; every time + Very basic interface to manipulate files as iterator of chunks/lines. The + iterators take care of opening and closing files properly; every time one iterates over an iterator, the file is opened/closed again. 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 from [End_of_file] (which is caught). The file is {b always} properly 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 @param mode default [0o644] @param flags default: [[Open_rdonly]] *) @@ -788,7 +788,7 @@ module IO : sig string -> string t (** Read chunks of the given [size] from the file. The last chunk might be 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 *) val write_to : ?mode:int -> ?flags:open_flag list -> diff --git a/src/bench/bench_persistent.ml b/src/bench/bench_persistent.ml index 0cab98a..e132426 100644 --- a/src/bench/bench_persistent.ml +++ b/src/bench/bench_persistent.ml @@ -77,7 +77,7 @@ module MList = struct (** Build a MList of elements of the Seq. The optional argument indicates the size of the blocks *) let of_seq ?(size=8) seq = - (* read sequence into a MList.t *) + (* read iterator into a MList.t *) let start = make size in let l = ref start in seq (fun x -> l := push x !l); diff --git a/src/bench/bench_persistent_read.ml b/src/bench/bench_persistent_read.ml index 23161ab..278a072 100644 --- a/src/bench/bench_persistent_read.ml +++ b/src/bench/bench_persistent_read.ml @@ -77,7 +77,7 @@ module MList = struct (** Build a MList of elements of the Seq. The optional argument indicates the size of the blocks *) let of_seq ?(size=8) seq = - (* read sequence into a MList.t *) + (* read iterator into a MList.t *) let start = make size in let l = ref start in seq (fun x -> l := push x !l); diff --git a/src/bigarray/IterBigarray.ml b/src/bigarray/IterBigarray.ml index 03d8697..716f12c 100644 --- a/src/bigarray/IterBigarray.ml +++ b/src/bigarray/IterBigarray.ml @@ -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} *) diff --git a/src/bigarray/IterBigarray.mli b/src/bigarray/IterBigarray.mli index de96424..1cf3419 100644 --- a/src/bigarray/IterBigarray.mli +++ b/src/bigarray/IterBigarray.mli @@ -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}