package batteries

  1. Overview
  2. Docs
package batteries
Legend:
Library
Module
Module type
Parameter
Class
Class type
include module type of struct include BatSeq end

A sequence represents a collection of elements, for which you never construct the complete representation.

Basically you should use a sequence when you would prefer using a list or a lazy-list but constructing the whole list explicitly would explode your memory.

All functions returning a sequence operates in time and space O(1).

Note that if you want a ``consumable sequence'', you should prefer using enumerations (from module BatEnum).

  • author Jeremie Dimino
type 'a t = 'a Seq.t

A sequence is a computation which returns a list-like node

and 'a node = 'a Seq.node =
  1. | Nil
  2. | Cons of 'a * 'a t
include BatInterfaces.Mappable with type 'a mappable = 'a t
type 'a mappable = 'a t

The data structure, e.g. 'a List.t

val enum : 'a t -> 'a BatEnum.t

enum s returns the enumeration of all element of s.

Since enumerations are consumable and sequence are not, it is not possible to have the inverse operations, i.e. of_enum

Base operations
val length : 'a t -> int

Return the number of elements of the given sequence. This may never return if the sequence is infinite.

val is_empty : 'a t -> bool

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

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

append s1 s2 returns the sequence which first returns all elements of s1 then all elements of s2.

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

concat s returns the sequence which returns all the elements of all the elements of s, in the same order.

val flatten : 'a t t -> 'a t

Same as concat.

Constructors
val nil : 'a t

nil = fun () -> Nil

val empty : 'a t

the empty sequence, containing no elements

  • since 3.3.0
val return : 'a -> 'a t

the singleton sequence, containing only the given element

  • since 3.3.0
val cons : 'a -> 'a t -> 'a t

cons e s = fun () -> Cons(e, s)

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

make n e returns the sequence of length n where all elements are e

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

init n f returns the sequence returning the results of f 0, f 1.... f (n-1).

val of_list : 'a list -> 'a t

Convenience function to build a seq from a list.

  • since 2.2.0
val unfold : ('b -> ('a * 'b) option) -> 'b -> 'a t

Build a sequence from a step function and an initial value. unfold f u returns empty if f u returns None, or fun () -> Cons (x, unfold f y) if f u returns Some (x, y).

For example, unfold (function [] -> None | h::t -> Some (h,t)) l is equivalent to List.to_seq l.

  • since 3.3.0
val flat_map : ('a -> 'b t) -> 'a t -> 'b t

Map each element to a subsequence, then return each element of this sub-sequence in turn. This transformation is lazy, it only applies when the result is traversed.

  • since 3.3.0
val concat_map : ('a -> 'b t) -> 'a t -> 'b t

Alias for flat_map.

  • since 3.4.0
Iterators
val iter : ('a -> unit) -> 'a t -> unit

iter f s applies f to all the elements of the sequence. Eager.

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

iteri f s is the same as iter f s, but f is given the index of each element (starting at 0).

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

iter2 f s1 s2 iterates on elements of s1 and s2 pairwise, and stops when it meets the end of s1 or s2

  • since 2.2.0
val map : ('a -> 'b) -> 'a t -> 'b t

map f s returns the sequence where elements are elements of s mapped with f. Lazy.

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

mapi f s lazily maps elements of s into a new sequence, using f. f is also given elements' indexes.

  • since 2.2.0
val map2 : ('a -> 'b -> 'c) -> 'a t -> 'b t -> 'c t

map2 f s1 s2 returns a sequence of elements, resulting from combininig elements of s1 and s2 at the same index using f. The result is as long as the shortest argument.

  • since 2.2.0
val fold_left : ('a -> 'b -> 'a) -> 'a -> 'b t -> 'a

fold_left f a (cons b0 (... bn)) is f (... (f (f a b0) b1) ...) bn. Tail-recursive, eager.

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

fold_right f (cons a0 (cons a1 (cons a2 ...))) b is f a0 (f a1 (f a2 ...)). Not tail-recursive, eager.

val equal : ?eq:('a -> 'a -> bool) -> 'a t -> 'a t -> bool

equal ~eq s1 s2 compares elements of s1 and s2 pairwise using eq

  • since 2.2.0
Sequence scanning

Most functions in the following sections have a shortcut semantic similar to the behavior of the usual (&&) and (||) operators : they will force the sequence until they find an satisfying element, and then return immediately.

For example, for_all will only diverge if the sequence begins with an infinite number of true elements --- elements for which the predicate p returns true.

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

for_all p (cons a0 (cons a1 ...)) checks if all elements of the given sequence satisfy the predicate p. That is, it returns (p a0) && (p a1) && .... Eager, shortcut.

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

exists p (cons a0 (cons a1 ...)) checks if at least one element of the sequence satisfies the predicate p. That is, it returns (p a0) || (p a1) || .... Eager, shortcut.

val mem : 'a -> 'a t -> bool

mem a l is true if and only if a is equal to an element of l. Eager, shortcut.

Sequence searching
val find : ('a -> bool) -> 'a t -> 'a option

find p s returns the first element of s such as p e returns true, if any. Eager, shortcut.

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

find_map p s finds the first element of s for which p e returns Some r, if any. Eager, short-cut.

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

filter p s returns the sequence of elements of s satisfying p. Lazy.

Note filter is lazy in that it returns a lazy sequence, but each element in the result is eagerly searched in the input sequence. Therefore, the access to a given element in the result will diverge if it is preceded, in the input sequence, by infinitely many false elements (elements on which the predicate p returns false).

Other functions that may drop an unbound number of elements (filter_map, take_while, etc.) have the same behavior.

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

filter_map f s returns the sequence of elements filtered and mapped by f. Lazy.

Association sequences
val assoc : 'a -> ('a * 'b) t -> 'b option

assoc a s returns the value associated with key a in the sequence of pairs s. Eager, shortcut.

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

take n s returns up to the n first elements from sequence s, if available. Lazy.

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

drop n s returns s without the first n elements, or the empty sequence if s have less than n elements. Lazy.

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

take_while f s returns the first elements of sequence s which satisfy the predicate f. Lazy.

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

drop_while f s returns the sequence s with the first elements satisfying the predicate f dropped. Lazy.

Sequence of pairs
val split : ('a * 'b) t -> 'a t * 'b t

split s = (map fst s, map snd s). Lazy.

Printing
val print : ?first:string -> ?last:string -> ?sep:string -> ('a BatInnerIO.output -> 'b -> unit) -> 'a BatInnerIO.output -> 'b t -> unit

Print the contents of a sequence

val to_buffer : ?first:string -> ?last:string -> ?sep:string -> ('a -> string) -> Buffer.t -> (unit -> 'a node) -> unit

Convert a sequence to a string in the given buffer; eager.

  • since 2.10.0
val to_string : ?first:string -> ?last:string -> ?sep:string -> ('a -> string) -> 'a t -> string

Convert the sequence to a string; eager.

  • since 2.10.0
val of_string : ?first:string -> ?last:string -> ?sep:string -> (string -> 'a) -> string -> 'a t

Create a sequence by parsing a string.

  • since 2.10.0
module Infix = BatSeq.Infix
include module type of Infix
val (--) : int -> int -> int BatSeq.t
val (--^) : int -> int -> int BatSeq.t
val (--.) : (float * float) -> float -> float BatSeq.t
val (---) : int -> int -> int BatSeq.t
val (--~) : char -> char -> char BatSeq.t
val (//) : 'a BatSeq.t -> ('a -> bool) -> 'a BatSeq.t
val (/@) : 'a BatSeq.t -> ('a -> 'b) -> 'b BatSeq.t
val (@/) : ('a -> 'b) -> 'a BatSeq.t -> 'b BatSeq.t
val (//@) : 'a BatSeq.t -> ('a -> 'b option) -> 'b BatSeq.t
val (@//) : ('a -> 'b option) -> 'a BatSeq.t -> 'b BatSeq.t
module Exceptionless = BatSeq.Exceptionless
include module type of struct include BatSeq.Exceptionless end
val hd : 'a BatSeq.t -> 'a option
val tl : 'a BatSeq.t -> 'a BatSeq.t option
val first : 'a BatSeq.t -> 'a option
val last : 'a BatSeq.t -> 'a option
val at : 'a BatSeq.t -> int -> 'a option
val reduce : ('a -> 'a -> 'a) -> 'a BatSeq.t -> 'a option
val max : 'a BatSeq.t -> 'a option
val min : 'a BatSeq.t -> 'a option
val combine : 'a BatSeq.t -> 'b BatSeq.t -> ('a * 'b) BatSeq.t
OCaml

Innovation. Community. Security.

GitHub Discord Twitter Peertube RSS
About
Changelog Releases Industrial Users Academic Users Why OCaml
Ecosystem
Packages Community Events OCaml Planet Jobs
Resources
Install OCaml Get Started Platform Tools Language Manual Standard Library API Books Exercises Papers OCaml Playground Logo
Policies
Carbon Footprint Governance Privacy Code of Conduct