.TH "Seq" 3o 2023-02-12 OCamldoc "OCaml library"
.SH NAME
Seq \- Sequences (functional iterators).
.SH Module
Module   Seq
.SH Documentation
.sp
Module
.BI "Seq"
 : 
.B sig end

.sp
Sequences (functional iterators)\&.
.sp
The type 
.ft B
\&'a Seq\&.t
.ft R
is a delayed list, i\&.e\&. a list where some
evaluation is needed to access the next element\&. This makes it possible
to build infinite sequences, to build sequences as we traverse them, and
to transform them in a lazy fashion rather than upfront\&.

.sp
.B "Since"
4.07

.sp

.sp
.sp
.I type 
.B 'a
.I t 
= 
.B unit -> 'a node

.sp
The type of delayed lists containing elements of type 
.ft B
\&'a
.ft R
\&.
Note that the concrete list node 
.ft B
\&'a node
.ft R
is delayed under a closure,
not a 
.ft B
lazy
.ft R
block, which means it might be recomputed every time
we access it\&.

.sp
.I type 
.B 'a
.I node 
=
 | Nil
 | Cons
.B of 
.B 'a * 'a t
 
.sp
A fully\-evaluated list node, either empty or containing an element
and a delayed tail\&.

.sp

.I val empty 
: 
.B 'a t
.sp
The empty sequence, containing no elements\&.

.sp

.I val return 
: 
.B 'a -> 'a t
.sp
The singleton sequence containing only the given element\&.

.sp

.I val cons 
: 
.B 'a -> 'a t -> 'a t
.sp

.ft B
cons x xs
.ft R
is the sequence containing the element 
.ft B
x
.ft R
followed by
the sequence 
.ft B
xs
.ft R


.sp
.B "Since"
4.11

.sp

.I val append 
: 
.B 'a t -> 'a t -> 'a t
.sp

.ft B
append xs ys
.ft R
is the sequence 
.ft B
xs
.ft R
followed by the sequence 
.ft B
ys
.ft R


.sp
.B "Since"
4.11

.sp

.I val map 
: 
.B ('a -> 'b) -> 'a t -> 'b t
.sp

.ft B
map f seq
.ft R
returns a new sequence whose elements are the elements of
.ft B
seq
.ft R
, transformed by 
.ft B
f
.ft R
\&.
This transformation is lazy, it only applies when the result is traversed\&.
.sp
If 
.ft B
seq = [1;2;3]
.ft R
, then 
.ft B
map f seq = [f 1; f 2; f 3]
.ft R
\&.

.sp

.I val filter 
: 
.B ('a -> bool) -> 'a t -> 'a t
.sp
Remove from the sequence the elements that do not satisfy the
given predicate\&.
This transformation is lazy, it only applies when the result is
traversed\&.

.sp

.I val filter_map 
: 
.B ('a -> 'b option) -> 'a t -> 'b t
.sp
Apply the function to every element; if 
.ft B
f x = None
.ft R
then 
.ft B
x
.ft R
is dropped;
if 
.ft B
f x = Some y
.ft R
then 
.ft B
y
.ft R
is returned\&.
This transformation is lazy, it only applies when the result is
traversed\&.

.sp

.I val concat 
: 
.B 'a t t -> 'a t
.sp
concatenate a sequence of sequences\&.

.sp
.B "Since"
4.13

.sp

.I val flat_map 
: 
.B ('a -> 'b t) -> 'a t -> 'b t
.sp
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\&.

.sp

.I val concat_map 
: 
.B ('a -> 'b t) -> 'a t -> 'b t
.sp
Alias for 
.ft B
Seq\&.flat_map
.ft R
\&.

.sp
.B "Since"
4.13

.sp

.I val fold_left 
: 
.B ('a -> 'b -> 'a) -> 'a -> 'b t -> 'a
.sp
Traverse the sequence from left to right, combining each element with the
accumulator using the given function\&.
The traversal happens immediately and will not terminate on infinite
sequences\&.
.sp
Also see 
.ft B
List\&.fold_left
.ft R


.sp

.I val iter 
: 
.B ('a -> unit) -> 'a t -> unit
.sp
Iterate on the sequence, calling the (imperative) function on every element\&.
The traversal happens immediately and will not terminate on infinite
sequences\&.

.sp

.I val unfold 
: 
.B ('b -> ('a * 'b) option) -> 'b -> 'a t
.sp
Build a sequence from a step function and an initial value\&.
.ft B
unfold f u
.ft R
returns 
.ft B
empty
.ft R
if 
.ft B
f u
.ft R
returns 
.ft B
None
.ft R
,
or 
.ft B
fun () \-> Cons (x, unfold f y)
.ft R
if 
.ft B
f u
.ft R
returns 
.ft B
Some (x, y)
.ft R
\&.
.sp
For example, 
.ft B
unfold (function [] \-> None | h::t \-> Some (h,t)) l
.ft R
is equivalent to 
.ft B
List\&.to_seq l
.ft R
\&.

.sp
.B "Since"
4.11

.sp