Previous Up Next

Module Biocaml_stream (.ml)

module Biocaml_stream: sig .. end

This module is an enhancement of the stdlib's Stream module. It is largely inspired from Batteries's Enum module, but follows the style of Core.

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.

include Biocaml_streamable.S

exception Failure

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.

exception Error of string

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

exception Expected_streams_of_equal_length

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

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.
Raises Stream.Failure if the stream is empty.

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 nth 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_list  : 'a list -> 'a t

Return a stream of elements as occurring in the given list.

val of_string : string -> char t

Return a stream characters as occurring in the given string.

val of_channel : Pervasives.in_channel -> 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 -> Pervasives.in_channel -> 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

val of_lazy  : 'a t lazy_t -> 'a t

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, ...

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

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

val iter2_exn  : 'a t -> 'b t -> f:('a -> 'b -> unit) -> unit

Like iter2 except streams required to be of equal length.
Raises Expected_streams_of_equal_length if the two streams have different lengths, in which case there is no guarantee about which elements were consumed.

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

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

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

val fold2_exn  : 'a t ->
 'b t -> init:'c -> f:('c -> 'a -> 'b -> 'c) -> 'c

Like fold2 except streams required to be of equal length.
Raises Expected_streams_of_equal_length if the two streams have different lengths, in which case there is no guarantee about which elements were consumed.

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

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
... .

val scan  : 'a t -> f:('a -> 'a -> 'a) -> 'a t

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 iter2i_exn  : 'a t ->
 'b t -> f:(int -> int -> 'a -> 'b -> unit) -> unit

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

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

val fold2i_exn  : 'a t ->
 'b t ->
 init:'c -> f:(int -> int -> 'c -> 'a -> 'b -> 'c) -> 'c

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

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, map a stream into another type of stream, or convert a stream into another data structure.

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

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.

val take_while  : 'a t -> f:('a -> bool) -> 'a t

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.

val skip  : 'a t -> n:int -> 'a t

Similar to drop but returns a fresh stream obtained after discarding the n first elements. Being a fresh stream, the count of the returned stream starts from 0. Beware though, that the input and output streams are consuminmg the same resource, so consuming one modify the other.

val skip_while  : 'a t -> f:('a -> bool) -> 'a t

Similar to skip: skip_while xs ~f removes elements from xs and stops when f evals to false on the head element.

val take_whilei  : 'a t -> f:(int -> 'a -> bool) -> 'a t

Indexed variants of the previous prefix/suffix constructors

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

val skip_whilei  : 'a t -> f:(int -> 'a -> bool) -> 'a t

val span  : 'a t ->
 f:('a -> bool) -> 'a t * 'a t

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.

val group  : 'a t -> f:('a -> 'b) -> 'a t t

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.

val group_by  : 'a t ->
 eq:('a -> 'a -> bool) -> 'a t t

Same as group but with a comparison function instead of a mapping.

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

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

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

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

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

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

val combine  : 'a t * 'b t -> ('a * 'b) t

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.

val uncombine  : ('a * 'b) t -> 'a t * 'b t

uncombine is the opposite of combine

val merge  : 'a t ->
 'a t -> cmp:('a -> 'a -> int) -> 'a t

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.

val partition  : 'a t ->
 f:('a -> bool) -> 'a t * 'a t

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.

val uniq  : 'a t -> 'a t

uniq e returns a duplicate of e with repeated values omitted. (similar to unix's uniq command)

val to_list  : 'a t -> 'a list

Result.t's

val result_to_exn  : ('output, 'error) Core.Std.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 Infix: sig .. end