devkit 1.20210517 · OCaml Package

Extensions to Enum

include module type of Enum with type 'a t = 'a Enum.t

type 'a t = 'a Enum.t

Final functions

These functions consume the enumeration until it ends or an exception is raised by the first argument function.

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

iter f e calls the function f with each elements of e in turn.

val iter2 : ('a -> 'b -> unit) -> 'a t -> 'b t -> unit

iter2 f e1 e2 calls the function f with the next elements of e and e2 repeatedly until one of the two enumerations ends.

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

fold f v e returns v if e is empty, otherwise f aN (... (f a2 (f a1 v)) ...) where a1..N are the elements of e.

val fold2 : ('a -> 'b -> 'c -> 'c) -> 'c -> 'a t -> 'b t -> 'c

fold2 is similar to fold but will fold over two enumerations at the same time until one of the two enumerations ends.

Indexed functions : these functions are similar to previous ones except that they call the function with one additional argument which is an index starting at 0 and incremented after each call to the function.

val iteri : (int -> 'a -> unit) -> 'a t -> unit

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

val foldi : (int -> 'a -> 'b -> 'b) -> 'b -> 'a t -> 'b

val fold2i : (int -> 'a -> 'b -> 'c -> 'c) -> 'c -> 'a t -> 'b t -> 'c

Useful functions

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

find f e returns the first element x of e such that f x returns true, consuming the enumeration up to and including the found element, or, raises Not_found if no such element exists in the enumeration, consuming the whole enumeration in the search.

Since find consumes a prefix of the enumeration, it can be used several times on the same enumeration to find the next element.

val is_empty : 'a t -> bool

is_empty e returns true if e does not contains any element.

val peek : 'a t -> 'a option

peek e returns None if e is empty or Some x where x is the next element of e. The element is not removed from the enumeration.

val get : 'a t -> 'a option

get e returns None if e is empty or Some x where x is the next element of e, in which case the element is removed from the enumeration.

val next : 'a t -> 'a

next e returns the next element of e (and removes it from enumeration).

raises No_more_elements
if enumeration is empty

val push : 'a t -> 'a -> unit

push e x will add x at the beginning of e.

val junk : 'a t -> unit

junk e removes the first element from the enumeration, if any.

val clone : 'a t -> 'a t

clone e creates a new enumeration that is copy of e. If e is consumed by later operations, the clone will not get affected.

val force : 'a t -> unit

force e forces the application of all lazy functions and the enumeration of all elements, exhausting the enumeration.

An efficient intermediate data structure of enumerated elements is constructed and e will now enumerate over that data structure.

Lazy constructors

These functions are lazy which means that they will create a new modified enumeration without actually enumerating any element until they are asked to do so by the programmer (using one of the functions above).

When the resulting enumerations of these functions are consumed, the underlying enumerations they were created from are also consumed.

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

map f e returns an enumeration over (f a1, f a2, ... , f aN) where a1...N are the elements of e.

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

mapi is similar to map except that f is passed one extra argument which is the index of the element in the enumeration, starting from 0.

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

filter f e returns an enumeration over all elements x of e such as f x returns true.

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

filter_map f e returns an enumeration over all elements x such as f y returns Some x , where y is an element of e.

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

append e1 e2 returns an enumeration that will enumerate over all elements of e1 followed by all elements of e2.

val concat : 'a t t -> 'a t

concat e returns an enumeration over all elements of all enumerations of e.

Constructors

In this section the word shall denotes a semantic requirement. The correct operation of the functions in this interface are conditional on the client meeting these requirements.

exception No_more_elements

This exception shall be raised by the next function of make or from when no more elements can be enumerated, it shall not be raised by any function which is an argument to any other function specified in the interface.

val empty : unit -> 'a t

The empty enumeration : contains no element

val make : 
  next:(unit -> 'a) ->
  count:(unit -> int) ->
  clone:(unit -> 'a t) ->
  'a t

This function creates a fully defined enumeration.

the next function shall return the next element of the enumeration or raise No_more_elements if the underlying data structure does not have any more elements to enumerate.
the count function shall return the actual number of remaining elements in the enumeration.
the clone function shall create a clone of the enumeration such as operations on the original enumeration will not affect the clone.

For some samples on how to correctly use make, you can have a look at implementation of ExtList.enum.

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

from next creates an enumeration from the next function. next shall return the next element of the enumeration or raise No_more_elements when no more elements can be enumerated. Since the enumeration definition is incomplete, a call to clone or count will result in a call to force that will enumerate all elements in order to return a correct value.

val init : int -> (int -> 'a) -> 'a t

init n f creates a new enumeration over elements f 0, f 1, ..., f (n-1)

Counting

val count : 'a t -> int

count e returns the number of remaining elements in e without consuming the enumeration.

Depending of the underlying data structure that is implementing the enumeration functions, the count operation can be costly, and even sometimes can cause a call to force.

val fast_count : 'a t -> bool

For users worried about the speed of count you can call the fast_count function that will give an hint about count implementation. Basically, if the enumeration has been created with make or init or if force has been called on it, then fast_count will return true.

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

same as Enum.find, but found element is peeked, not junked

val list_loop : 'a list -> 'a t

returns
enum that indefinitely runs over given (non-empty) list

val of_dynarray : ?start:int -> ?n:int -> 'a DynArray.t -> 'a Enum.t

returns
enum over DynArray slice (default: whole array)

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

take n e

returns
enum consuming first n elements of e

val align : ('a -> 'a -> int) -> 'a t -> 'a t -> 'a t

merge two enums of same type

val join : 
  ?left:bool ->
  ?right:bool ->
  ?multi:bool ->
  ('a -> 'b -> int) ->
  'a t ->
  'b t ->
  ('a option * 'b option) t

parameter multi
repeat input value from the left enum multiple times to output as many pairs as there are matching equal consecutive values in the right enum

val join_assoc : 
  ?left:bool ->
  ?right:bool ->
  ?multi:bool ->
  ('a -> 'a -> int) ->
  ('a * 'b) t ->
  ('a * 'c) t ->
  ('a * 'b option * 'c option) t

include module type of ExtEnum_merge

val join_inner_by : 
  ('a -> 'b -> int) ->
  ('c -> 'a) ->
  ('d -> 'b) ->
  'c Enum.t ->
  'd Enum.t ->
  ('c * 'd) Enum.t

val join_inner_by_key : 
  ('a -> 'a -> int) ->
  ('b -> 'a) ->
  'b Enum.t ->
  'b Enum.t ->
  ('b * 'b) Enum.t

val join_left_by : 
  ('a -> 'b -> int) ->
  ('c -> 'a) ->
  ('d -> 'b) ->
  'c Enum.t ->
  'd Enum.t ->
  ('c * 'd option) Enum.t

val join_left_by_key : 
  ('a -> 'a -> int) ->
  ('b -> 'a) ->
  'b Enum.t ->
  'b Enum.t ->
  ('b * 'b option) Enum.t

val join_right_by : 
  ('a -> 'b -> int) ->
  ('c -> 'a) ->
  ('d -> 'b) ->
  'c Enum.t ->
  'd Enum.t ->
  ('c option * 'd) Enum.t

val join_right_by_key : 
  ('a -> 'a -> int) ->
  ('b -> 'a) ->
  'b Enum.t ->
  'b Enum.t ->
  ('b option * 'b) Enum.t

val join_full_by : 
  ('a -> 'b -> int) ->
  ('c -> 'a) ->
  ('d -> 'b) ->
  'c Enum.t ->
  'd Enum.t ->
  [> `Both of 'c * 'd | `Left of 'c | `Right of 'd ] Enum.t

val join_full_by_key : 
  ('a -> 'a -> int) ->
  ('b -> 'a) ->
  'b Enum.t ->
  'b Enum.t ->
  [> `Both of 'b * 'b | `Left of 'b | `Right of 'b ] Enum.t

val join_inner_multi_by : 
  ('a -> 'b -> int) ->
  ('c -> 'a) ->
  ('d -> 'b) ->
  'c Enum.t ->
  'd Enum.t ->
  ('c * 'd) Enum.t

val join_inner_multi_by_key : 
  ('a -> 'a -> int) ->
  ('b -> 'a) ->
  'b Enum.t ->
  'b Enum.t ->
  ('b * 'b) Enum.t

val join_left_multi_by : 
  ('a -> 'b -> int) ->
  ('c -> 'a) ->
  ('d -> 'b) ->
  'c Enum.t ->
  'd Enum.t ->
  ('c * 'd option) Enum.t

val join_left_multi_by_key : 
  ('a -> 'a -> int) ->
  ('b -> 'a) ->
  'b Enum.t ->
  'b Enum.t ->
  ('b * 'b option) Enum.t

val join_right_multi_by : 
  ('a -> 'b -> int) ->
  ('c -> 'a) ->
  ('d -> 'b) ->
  'c Enum.t ->
  'd Enum.t ->
  ('c option * 'd) Enum.t

val join_right_multi_by_key : 
  ('a -> 'a -> int) ->
  ('b -> 'a) ->
  'b Enum.t ->
  'b Enum.t ->
  ('b option * 'b) Enum.t

val join_full_multi_by : 
  ('a -> 'b -> int) ->
  ('c -> 'a) ->
  ('d -> 'b) ->
  'c Enum.t ->
  'd Enum.t ->
  [> `Both of 'c * 'd | `Left of 'c | `Right of 'd ] Enum.t

val join_full_multi_by_key : 
  ('a -> 'a -> int) ->
  ('b -> 'a) ->
  'b Enum.t ->
  'b Enum.t ->
  [> `Both of 'b * 'b | `Left of 'b | `Right of 'b ] Enum.t

val join_assoc_inner : 
  ('a -> 'b -> int) ->
  ('a * 'c) Enum.t ->
  ('b * 'd) Enum.t ->
  ('a * 'c * 'd) Enum.t

val join_assoc_left : 
  ('a -> 'b -> int) ->
  ('a * 'c) Enum.t ->
  ('b * 'd) Enum.t ->
  ('a * 'c * 'd option) Enum.t

val join_assoc_right : 
  ('a -> 'a -> int) ->
  ('a * 'b) Enum.t ->
  ('a * 'c) Enum.t ->
  ('a * 'b option * 'c) Enum.t

val join_assoc_full : 
  ('a -> 'a -> int) ->
  ('a * 'b) Enum.t ->
  ('a * 'c) Enum.t ->
  ('a * [> `Both of 'b * 'c | `Left of 'b | `Right of 'c ]) Enum.t

val join_assoc_inner_multi : 
  ('a -> 'b -> int) ->
  ('a * 'c) Enum.t ->
  ('b * 'd) Enum.t ->
  ('a * 'c * 'd) Enum.t

val join_assoc_left_multi : 
  ('a -> 'b -> int) ->
  ('a * 'c) Enum.t ->
  ('b * 'd) Enum.t ->
  ('a * 'c * 'd option) Enum.t

val join_assoc_right_multi : 
  ('a -> 'a -> int) ->
  ('a * 'b) Enum.t ->
  ('a * 'c) Enum.t ->
  ('a * 'b option * 'c) Enum.t

val join_assoc_full_multi : 
  ('a -> 'a -> int) ->
  ('a * 'b) Enum.t ->
  ('a * 'c) Enum.t ->
  ('a * [> `Both of 'b * 'c | `Left of 'b | `Right of 'c ]) Enum.t

val merge : ('a -> 'b -> int) -> 'a t -> 'b t -> ('a option * 'b option) t

merge two enums of different types

val merge_assoc : 
  ('a -> 'a -> int) ->
  ('a * 'b) t ->
  ('a * 'c) t ->
  ('a * 'b option * 'c option) t

merge two enums over key-value pairs

val group : 
  ('acc -> 'a -> bool) ->
  ('acc -> 'a -> 'acc) ->
  'acc ->
  'a t ->
  'acc t

group equal fold zero e accumulates elements of e with fold, first element is folded with zero, at each subsequent step equal is checked, and new accumulator is started once it returns false

val group_assoc : 
  ('a -> 'a -> bool) ->
  ('b -> 'c -> 'b) ->
  'b ->
  ('a * 'c) t ->
  ('a * 'b) t

group_assoc equal fold zero e accumulates (with fold) values in e with matching key as determined by comparison function equal, first value is folded with zero, e.g.:

List.of_enum @@ Enum.group_assoc (=) (+) 0 @@ List.enum ["a",1; "a",2; "b",3; "b",4; "a", 1; "a", 10] = ["a", 3; "b", 7; "a", 11; ]

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

uniq f e replaces every consecuitive sequence of elements from e comparing equal by the given comparison function f with the first element from that sequence

val count_unique : ('a -> 'a -> bool) -> 'a t -> ('a * int) t

count_unique f e replaces every consecutive sequence of elements from e comparing equal by the given comparison function f with the first element from that sequence and the number of duplicates

val sub : ?eq:('b -> 'b -> bool) -> 'a t -> ('a -> 'b) -> ('b * 'a t) option

sub e f extracts a subenum (consecutive sequence of the elements from e) that map to the same value of f

val iter_while : ('a -> bool) -> 'a t -> unit

iter_while f e calls f for each element of e until it returns false or e is exhausted

package devkit

Final functions

Useful functions

Lazy constructors

Constructors

Counting