Library

Module

Module type

Parameter

Class

Class type

Streams.

In general, functions that return a stream return a "fresh" stream, meaning that their count is set to 0.

`type 'a t = 'a Stream.t`

Type of streams holding values of type `'a`

.

Return a stream containing all elements of given data structure. Exact semantics depend on implementation. For example, elements in stream may or may not be ordered.

Return a data structure containing all elements in given stream, fully consuming the stream. Exact semantics depend on implementation. For example, duplicate elements in input may be ignored if the data structure is a set.

Raised when asking for an element of an empty stream, and by `Genlex`

parsers when none of the first components of the stream patterns is accepted.

Raised by `Genlex`

parsers when the first component of a stream pattern is accepted, but one of the following components is rejected.

Raised by operations working on more than one stream where all streams are expected to be of the same length.

Raised when an operation needs more elements from a stream than available.

`val next : 'a t -> 'a option`

Return first element in given stream if any and remove it from the stream.

`val next_exn : 'a t -> 'a`

Return first element in given stream and remove it from the stream.

`val peek : 'a t -> 'a option`

Return first element of given stream without removing it from the stream, or `None`

if the stream is empty.

`val npeek : 'a t -> int -> 'a list`

`npeek s n`

returns a list of the first `n`

elements in stream `s`

, or all of its remaining elements if less than `n`

elements are available. The elements are not removed from the stream.

`val junk : 'a t -> unit`

Discard first element of given stream or do nothing if the stream is empty.

`val count : 'a t -> int`

Return number of elements discarded from given stream.

`val is_empty : 'a t -> bool`

True if the stream is empty, else false.

###### Constructors

`val from : (int -> 'a option) -> 'a t`

`from f`

returns a stream whose `n`

th element is determined by calling `f n`

, which should return `Some x`

to indicate value `x`

or `None`

to indicate the end of the stream. The stream is infinite if `f`

never returns None.

`val of_channel : Core_kernel.In_channel.t -> char t`

Return a stream of characters by reading from the input channel. WARNING: Semantics unclear if the channel is closed before the stream reads all of its input. For example, the stream appears to return values although the channel has been closed.

```
val strings_of_channel :
?buffer_size:int ->
Core_kernel.In_channel.t ->
string t
```

Return a stream of strings from the input. Each string has length at most `buffer_size`

.

`val range : ?until:int -> int -> int t`

`range p until:q`

creates a stream of integers `[p, p+1, ..., q]`

. If `until`

is omitted, the enumeration is not bounded. Behaviour is not-specified once `max_int`

has been reached.

`val empty : unit -> 'a t`

The empty stream.

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

`init n f`

returns the stream `f 0; f 1; ... f (n-1)`

.

`val singleton : 'a -> 'a t`

`singleton x`

returns a stream containing the single value `x`

.

`val unfold : 'a -> f:('a -> ('b * 'a) option) -> 'b t`

`unfold a0 f`

returns the stream `b0; b1; ...; bn`

, where

`Some (b0, a1) = f a0`

,`Some (b1, a2) = f a1`

,- ...
`Some (bn, a(n+1)) = f an`

,`None = f a(n+1)`

The stream is infinite if `f`

never returns None.

`val unfoldi : 'a -> f:(int -> 'a -> ('b * 'a) option) -> 'b t`

Indexed variant of `unfold`

###### Iterators

Unless otherwise stated, functions in this section normally consume the entire stream. The exception is if a caller supplied function raises an exception, but that is not the normal intention of supplied functions.

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

`iter xs ~f`

calls in turn `f x0`

, `f x1`

, ...

Like `iter`

but operates on two streams. Stops when either stream becomes empty.

Like `iter2`

except streams required to be of equal length.

`val fold : 'a t -> init:'b -> f:('b -> 'a -> 'b) -> 'b`

`fold xs ~init ~f`

returns `f (...(f (f init x0) x1)...) xn`

, that is for the stream `a0; a1; ...; an`

does the following calculations:

- b1 = f init a0
- b2 = f b1 a1
- ...
- bn = f b(n-1) a(n-1)

and returns `bn`

Like `fold`

but operates on two streams. Processing continues until either stream becomes empty.

Like `fold2`

except streams required to be of equal length.

Like `fold`

but all intermediate values are returned, not just the final value. If given stream `s`

is `a0; a1; ...`

, then ```
scanl f
init s
```

is the stream containing

- b0 = init
- b1 = f b0 a0
- b2 = f b1 a1
- ... .

`scan`

is similar to `scanl`

but without the `init`

value: if `s`

contains `x0`

, `x1`

, `x2`

..., `scan s ~f`

contains

- y0 = x0
- y1 = f y0 x1
- y2 = f y1 x2
- ...

For instance, `scan (1 -- 10) ~f:( * )`

will produce an enumeration containing the successive values of the factorial function. Returns an empty stream if the input stream is empty as well.

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

Indexed variants of the previous higher-order functions. The index provided to the `~f`

argument is the count of the stream, that is the number of discarded elements before the reaching the current one. For functions iterating on two streams, the `~f`

is thus provided two indices, since the current count may differ from one stream to another.

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

`val reduce : 'a t -> f:('a -> 'a -> 'a) -> 'a`

`reduce xs ~f`

returns `f (...(f (f x1 x2) x3)...) xn`

`val sum : int t -> int`

`sum xs`

returns the sum of the integers contained in `xs`

`val fsum : float t -> float`

`fsum xs`

returns the sum of the floats contained in `xs`

###### Scanners

Operations that scan a stream for various purposes. Unlike iterators, these operations are not inherently meant to consume streams, although they do partially or fully, due to the nature of streams.

`val exists : 'a t -> f:('a -> bool) -> bool`

`exists s ~f`

returns `true`

if there is some `x`

in `s`

such that `f x`

is true. The stream is consumed through and including `x`

.

`val for_all : 'a t -> f:('a -> bool) -> bool`

`for_all s ~f`

returns `true`

if `f x`

is true for every `x`

in `s`

.

`val find : 'a t -> f:('a -> bool) -> 'a option`

`find e ~f`

returns either `Some x`

where `x`

is the first element of `e`

such that `f x`

returns `true`

, consuming the stream up to and including the found element, or `None`

if no such element exists in the stream, consuming the whole stream in the search.

Since `find`

(eagerly) consumes a prefix of the stream, it can be used several times on the same stream to find the next element.

`val find_exn : 'a t -> f:('a -> bool) -> 'a`

Same as `find`

except that it raises an exception `Not_found`

instead of returning `None`

.

`val find_map : 'a t -> f:('a -> 'b option) -> 'b option`

Similar to `find`

###### Converters

Extract a subset of a stream or map a stream into another type of stream.

`take xs ~n`

builds a fresh stream from `xs`

containing the `d`

first elements of `xs`

where `d = min n l`

and `l`

is the length of `xs`

. As it is fresh, the count of the resulting stream starts from `0`

whatever the count of `xs`

is.

Same as `take`

but takes elements from the input enum as long as `f`

evaluates to `true`

.

`val drop : 'a t -> n:int -> unit`

`drop xs ~n`

is equivalent to calling `n`

times `junk`

on `xs`

.

`val drop_while : 'a t -> f:('a -> bool) -> unit`

Similar to `drop`

: `drop_while xs ~f`

removes elements from `xs`

and stops when `f`

evals to false on the head element.

Similar to `drop`

but returns the stream in input (useful in chained composition).

Similar to `skip`

: `skip_while xs ~f`

removes elements from `xs`

and stops when `f`

evals to false on the head element.

Indexed variants of the previous prefix/suffix constructors

`val drop_whilei : 'a t -> f:(int -> 'a -> bool) -> unit`

`span test e`

produces two streams `(hd, tl)`

, such that `hd`

is the same as `take_while test e`

and `tl`

is the same as `skip_while test e`

.

`group xs f`

applies `f`

to the elements of `xs`

and distribute them according to the return value of `f`

. Let `ys`

= ```
group xs
f
```

, then `xs`

= `concat ys`

and in each stream `s`

of `ys`

, all values give the same value with `f`

.

Same as `group`

but with a comparison function instead of a mapping.

Given a stream with items `x0, x1, x2, x3,...`

, the returned stream will be pairs of items `(x0,x1), (x2,x3), ...`

.

`combine`

transforms a pair of streams into a stream of pairs of corresponding elements. If one stream is short, excess elements of the longer stream are ignored.

`merge test (a, b)`

merge the elements from `a`

and `b`

into a single stream. At each step, `test`

is applied to the first element of `a`

and the first element of `b`

to determine which should get first into the resulting stream. If `a`

or `b`

runs out of elements, the process will append all elements of the other stream to the result.

`partition e ~f`

splits `e`

into two streams, where the first stream have all the elements satisfying `f`

, the second stream is opposite. The order of elements in the source stream is preserved.

`uniq e`

returns a duplicate of `e`

with repeated values omitted. (similar to unix's `uniq`

command)

###### Data Interchange

Convert/create a stream to/from another data structure.

`val of_list : 'a list -> 'a t`

`val to_list : 'a t -> 'a list`

`val of_array : 'a array -> 'a t`

`val to_array : 'a t -> 'a array`

`val of_hashtbl : ('a, 'b) Core_kernel.Hashtbl.t -> ('a * 'b) t`

`val to_hashtbl : ('a * 'b) t -> ('a, 'b) Core_kernel.Hashtbl.t`

`val of_map : ('a, 'b, 'c) Core_kernel.Map.t -> ('a * 'b) t`

`val to_map : ('a * 'b) t -> ('a, 'b) Core_kernel.Map.Poly.t`

`val of_set : ('a, 'b) Core_kernel.Set.t -> 'a t`

`val to_set : 'a t -> 'a Core_kernel.Set.Poly.t`

`val of_string : string -> char t`

###### Result.t's

```
val result_to_exn :
('output, 'error) Core_kernel.Result.t t ->
error_to_exn:('error -> exn) ->
'output t
```

Convert exception-less stream to exception-ful stream. Resulting stream raises exception at first error seen.

`module Result : sig ... end`

Higher-order functions for streams of results

`module Or_error : sig ... end`

Specialisation of `CFStream_stream`

.Result for ```
'a
Or_error.t
```

`module Infix : sig ... end`