gleam/iterator

Types

Iterator

An iterator is a lazily evaluated sequence of element.

Iterators are useful when working with collections that are too large to fit in memory (or those that are infinite in size) as they only require the elements currently being processed to be in memory.

As a lazy data structure no work is done when an iterator is filters, mapped, etc, instead a new iterator is returned with these transformations applied to the stream. Once the stream has all the required transformations applied it can be evaluated using functions such as fold and take.

pub opaque type Iterator(element)

Step

</>

pub type Step(element, accumulator) {
  Next(element: element, accumulator: accumulator)
  Done
}

Constructors

Next(element: element, accumulator: accumulator)
Done

Functions

append

</>

pub fn append(
  to first: Iterator(a),
  suffix second: Iterator(a),
) -> Iterator(a)

Append two iterators, producing a new iterator.

This function does not evaluate the elements of the iterators, the computation is performed when the resulting iterator is later run.

Examples

> [1, 2] |> from_list |> append([3, 4] |> from_list) |> to_list
[1, 2, 3, 4]

cycle

</>

pub fn cycle(iterator: Iterator(a)) -> Iterator(a)

Create an iterator that repeats a given iterator infinitely.

Examples

> [1, 2] |> from_list |> cycle |> take(6)
[1, 2, 1, 2, 1, 2]

drop

</>

pub fn drop(
  from iterator: Iterator(a),
  up_to desired: Int,
) -> Iterator(a)

Evaluate and discard the first N elements in an iterator, returning a new iterator.

If the iterator does not have enough elements an empty iterator is returned.

This function does not evaluate the elements of the iterator, the computation is performed when the iterator is later run.

Examples

> [1, 2, 3, 4, 5] |> from_list |> drop(up_to: 3) |> to_list
[4, 5]

> [1, 2] |> from_list |> drop(up_to: 3) |> to_list
[]

filter

</>

pub fn filter(
  iterator: Iterator(a),
  for predicate: fn(a) -> Bool,
) -> Iterator(a)

Create an iterator from an existing iterator and a predicate function.

The new iterator will contain elements from the first iterator for which the given function returns True.

This function does not evaluate the elements of the iterator, the computation is performed when the iterator is later run.

Examples

> import gleam/int
> [1, 2, 3, 4] |> from_list |> filter(int.is_even) |> to_list
[2, 4]

find

</>

pub fn find(
  in haystack: Iterator(a),
  one_that is_desired: fn(a) -> Bool,
) -> Result(a, Nil)

Find the first element in a given iterator for which the given function returns True.

Returns Error(Nil) if the function does not return True for any of the elements.

Examples

> find(from_list([1, 2, 3]), fn(x) { x > 2 })
Ok(3)

> find(from_list([1, 2, 3]), fn(x) { x > 4 })
Error(Nil)

> find(from_list([]), fn(x) { True })
Error(Nil)

flat_map

</>

pub fn flat_map(
  over iterator: Iterator(a),
  with f: fn(a) -> Iterator(b),
) -> Iterator(b)

Create an iterator from an existing iterator and a transformation function.

Each element in the new iterator will be the result of calling the given function on the elements in the given iterator and then flattening the results.

This function does not evaluate the elements of the iterator, the computation is performed when the iterator is later run.

Examples

> [1, 2] |> from_list |> flat_map(fn(x) { from_list([x, x + 1]) }) |> to_list
[1, 2, 2, 3]

flatten

</>

pub fn flatten(iterator: Iterator(Iterator(a))) -> Iterator(a)

Flatten an iterator of iterator of iterators, creating a new iterator.

This function does not evaluate the elements of the iterator, the computation is performed when the iterator is later run.

Examples

> [[1, 2], [3, 4]] |> list.map(from_list) |> flatten |> to_list
[1, 2, 3, 4]

fold

</>

pub fn fold(
  over iterator: Iterator(a),
  from initial: b,
  with f: fn(a, b) -> b,
) -> b

Reduce an iterator of elements into a single value by calling a given function on each element in turn.

If called on an iterator of infinite length then this function will never return.

If you do not care about the end value and only wish to evaluate the iterator for side effects consider using the run function instead.

Examples

> [1, 2, 3, 4]
> |> from_list
> |> fold(from: 0, with: fn(element, acc) { element + acc })
10

from_list

</>

pub fn from_list(list: List(a)) -> Iterator(a)

Create an iterator the yields each element in a given list.

Examples

> from_list([1, 2, 3, 4]) |> to_list
[1, 2, 3, 4]

map

</>

pub fn map(
  over iterator: Iterator(a),
  with f: fn(a) -> b,
) -> Iterator(b)

Create an iterator from an existing iterator and a transformation function.

Each element in the new iterator will be the result of calling the given function on the elements in the given iterator.

This function does not evaluate the elements of the iterator, the computation is performed when the iterator is later run.

Examples

> [1, 2, 3] |> from_list |> map(fn(x) { x * 2 }) |> to_list
[2, 4, 6]

range

</>

pub fn range(from start: Int, to stop: Int) -> Iterator(Int)

Create an iterator of ints, starting at a given start int and stepping by one to a given end int.

Examples

> range(from: 1, to: 5) |> to_list
[1, 2, 3, 4]

> range(from: 1, to: -2) |> to_list
[1, 0, -1]

> range(from: 0, to: 0) |> to_list
[]

repeat

</>

pub fn repeat(x: a) -> Iterator(a)

Create an iterator that returns the same value infinitely.

Examples

> repeat(10)
> |> take(4)
> |> to_list
[10, 10, 10, 10]

repeatedly

</>

pub fn repeatedly(f: fn() -> a) -> Iterator(a)

Create an iterator that yields values created by calling a given function repeatedly.

run

</>

pub fn run(iterator: Iterator(a)) -> Nil

Evaluate all elements in a given stream. This function is useful for when you wish to trigger any side effects that would occur when evaluating the iterator.

step

</>

pub fn step(iterator: Iterator(a)) -> Step(a, Iterator(a))

Eagerly access the first value of an interator, returning a Next that contains the first value and the rest of the iterator.

If called on an empty iterator, Done is returned.

Examples

> assert Next(head, tail) =
>   [1, 2, 3, 4]
>   |> from_list
>   |> step
> head
1
> tail |> to_list
[2, 3, 4]

> []
> |> from_list
> |> step
Done

take

</>

pub fn take(
  from iterator: Iterator(a),
  up_to desired: Int,
) -> List(a)

Evaluate a desired number of elements from an iterator and return them in a list.

If the iterator does not have enough elements all of them are returned.

Examples

> [1, 2, 3, 4, 5] |> from_list |> take(up_to: 3)
[1, 2, 3]

> [1, 2] |> from_list |> take(up_to: 3)
[1, 2]

to_list

</>

pub fn to_list(iterator: Iterator(a)) -> List(a)

Evaluate an iterator and return all the elements as a list.

If called on an iterator of infinite length then this function will never return.

Examples

[1, 2, 3] |> from_list |> map(fn(x) { x * 2 }) |> to_list [2, 4, 6]

unfold

</>

pub fn unfold(
  from initial: a,
  with f: fn(a) -> Step(b, a),
) -> Iterator(b)

Create an iterator from a given function and accumulator.

The function is called on the accumulator and return either Done, indicating the iterator has no more elements, or Next which contains a new element and accumulator. The element is yielded by the iterator and the new accumulator is used with the function to compute the next element in the sequence.

Examples

> unfold(from: 5, with: fn(n) {
>  case n {
>    0 -> Done
>    n -> Next(element: n, accumulator: n - 1)
>  }
> })
> |> to_list
[5, 4, 3, 2, 1]