std.iter

Provides the adapters and terminators of every iterator.

The adapters — map, filter, take, zip, chain, flatMap, peekable, rev, cycle and more — are lazy, each a struct of its own (MapIter, FilterIter, …), monomorphized and allocation-free. The terminators — count, fold, find, sum, product, average, min, max, minBy, maxBy, join, toArray, collect and more — walk the iterator to an answer. The prelude names this module, so its members reach every iterator without an import; where a type is written, the structs are named through it, as iter.MapIter<I, U>.

The protocol itself (Iterator, Iterable, DoubleEnded, Step, FromIterator), the ranges and the iterators of std.core's own types live in std.core.

Examples

import std.io { println };

let squares = (1..=10).filter((n) => n % 2 == 0).map((n) => n * n).toArray();
println(squares.length());
println((1..=4).fold(0, (sum, n) => sum + n));
println(["a", "b", "c"].iter().join("-"));

5
10
a-b-c

Types

MapIter struct — Yields the values of an iterator, each passed through f; made by it.map(f).

FilterIter struct — Yields the values of an iterator for which p holds; made by it.filter(p).

TakeIter struct — Yields the first n values of an iterator, or all of them where it has fewer; made by it.take(n).

SkipIter struct — Yields the values of an iterator after its first n; made by it.skip(n).

TakeWhileIter struct — Yields the values of an iterator up to, not including, the first for which p does not hold; made by it.takeWhile(p).

SkipWhileIter struct — Yields the values of an iterator from the first for which p does not hold on; made by it.skipWhile(p).

StepByIter struct — Yields the first value of an iterator, then every nth after it; made by it.stepBy(n).

EnumerateIter struct — Yields each value of an iterator paired with its position, counted from 0; made by it.enumerate().

InspectIter struct — Yields the values of an iterator unchanged, calling f on each as it passes; made by it.inspect(f).

ZipIter struct — Yields pairs of the values two iterators hold at the same position; made by it.zip(other).

ChainIter struct — Yields the values of one iterator, then those of another; made by it.chain(other).

MapNotNullIter struct — Yields the results of f on the values of an iterator, leaving out every null; made by it.mapNotNull(f).

FlatMapIter struct — Yields the values of what f returns for each value of an iterator, one after the other; made by it.flatMap(f).

FlattenIter struct — Yields the values of the iterables an iterator gives, one after the other; made by it.flatten().

DedupIter struct — Yields the values of an iterator with each run of consecutive values for which same holds given once; made by it.dedupBy(same) and it.dedup().

ScanIter struct — Yields init, then each value f makes of the previous one and the next value of an iterator; made by it.scan(init, f).

PeekableIter struct — Yields the values of an iterator and lets PeekableIter.peek look at the next one without taking it; made by it.peekable().

RevIter struct — Yields the values of a DoubleEnded iterator from its back; made by it.rev().

CycleIter struct — Yields the values of an iterator over and over; made by it.cycle().

Extensions

extend<I :: [Iterator]> I

pub fn map<U, E :: [Error]>(f: fn(I.Item) -> U throws E): MapIter<I, U, E>

Returns an iterator over the values, each passed through f.

Lazy: f runs as values are pulled. See MapIter.

pub fn filter<E :: [Error]>(p: fn(I.Item) -> bool throws E): FilterIter<I, E>

Returns an iterator over the values for which p holds.

pub fn take(n: int): TakeIter<I>

Returns an iterator over the first n values, or all of them where there are fewer.

A zero or negative n gives an empty iterator.

pub fn skip(n: int): SkipIter<I>

Returns an iterator over the values after the first n.

A zero or negative n skips nothing.

pub fn takeWhile<E :: [Error]>(p: fn(I.Item) -> bool throws E): TakeWhileIter<I, E>

Returns an iterator over the values up to, not including, the first for which p does not hold.

pub fn skipWhile<E :: [Error]>(p: fn(I.Item) -> bool throws E): SkipWhileIter<I, E>

Returns an iterator over the values from the first for which p does not hold on.

pub fn stepBy(n: int): StepByIter<I>

Returns an iterator over the first value, then every nth after it.

Panics

When n is less than 1.

pub fn enumerate(): EnumerateIter<I>

Returns an iterator over (position, value) pairs, positions counted from 0.

pub fn inspect<E :: [Error]>(f: fn(I.Item) -> void throws E): InspectIter<I, E>

Returns an iterator over the values unchanged, calling f on each as it is pulled.

pub fn zip<B :: [Iterable]>(other: B): ZipIter<I, B.Iter>

Returns an iterator over pairs of this iterator's values and other's at the same position.

other is any Iterable. The pairs end where either side ends.

pub fn chain<B :: [Iterator<Item = I.Item>]>(other: B): ChainIter<I, B>

Returns an iterator over the values, then those of other, an iterator of the same item type.

pub fn mapNotNull<U, E :: [Error]>(f: fn(I.Item) -> ?U throws E): MapNotNullIter<I, U, E>

Returns an iterator over the results of f on the values, leaving out every null.

pub fn flatMap<B :: [Iterable], E :: [Error]>(
    f: fn(I.Item) -> B throws E
): FlatMapIter<I, B, B.Iter, E>

Returns an iterator over the values of the iterables f returns for each value, one after the other.

pub fn dedupBy<E :: [Error]>(same: fn(I.Item, I.Item) -> bool throws E): DedupIter<I, E>

Returns an iterator that gives each run of consecutive values for which same holds once.

The first value of a run is kept.

pub fn scan<A, E :: [Error]>(init: A, f: fn(A, I.Item) -> A throws E): ScanIter<I, A, E>

Returns an iterator over init, then each running value f makes of the previous one and the next value.

pub fn peekable(): PeekableIter<I>

Returns an iterator over the values that can PeekableIter.peek at the next one.

pub fn count(): int throws I.Error

Returns how many values there are, walking them all.

Errors

Throws what a pull of the iterator throws.

pub fn fold<A, E :: [Error]>(
    init: A,
    f: fn(A, I.Item) -> A throws E
): A throws Join<I.Error, E>

Combines the values from init with f and returns the last result.

Returns init where there are no values.

Errors

Throws what a pull of the iterator or f throws.

pub fn reduce<E :: [Error]>(
    f: fn(I.Item, I.Item) -> I.Item throws E
): ?I.Item throws Join<I.Error, E>

Combines the values with f, starting from the first, and returns the last result.

Returns null where there are no values, and the only value where there is one.

Errors

Throws what a pull of the iterator or f throws.

pub fn first(): ?I.Item throws I.Error

Returns the first value, or null where there is none.

Errors

Throws what a pull of the iterator throws.

pub fn last(): ?I.Item throws I.Error

Returns the last value, or null where there is none, walking them all.

Errors

Throws what a pull of the iterator throws.

pub fn nth(n: int): ?I.Item throws I.Error

Returns the value at position n, counted from 0, or null where there is none.

A negative n returns null without pulling.

Errors

Throws what a pull of the iterator throws.

pub fn any<E :: [Error]>(p: fn(I.Item) -> bool throws E): bool throws Join<I.Error, E>

Returns whether p holds for some value.

Stops at the first value it holds for; false where there are none.

Errors

Throws what a pull of the iterator or p throws.

pub fn all<E :: [Error]>(p: fn(I.Item) -> bool throws E): bool throws Join<I.Error, E>

Returns whether p holds for every value.

Stops at the first value it does not hold for; true where there are none.

Errors

Throws what a pull of the iterator or p throws.

pub fn none<E :: [Error]>(p: fn(I.Item) -> bool throws E): bool throws Join<I.Error, E>

Returns whether p holds for no value.

Stops at the first value it holds for; true where there are none.

Errors

Throws what a pull of the iterator or p throws.

pub fn firstWhere<E :: [Error]>(
    p: fn(I.Item) -> bool throws E
): ?I.Item throws Join<I.Error, E>

Returns the first value for which p holds, or null where there is none.

Errors

Throws what a pull of the iterator or p throws.

pub fn find<E :: [Error]>(p: fn(I.Item) -> bool throws E): ?int throws Join<I.Error, E>

Returns the index, counted from 0, of the first value for which p holds, or null where there is none — as a text's and a slice's find give an index. firstWhere gives the value.

Errors

Throws what a pull of the iterator or p throws.

pub fn minBy<K :: [TotalOrder], E :: [Error]>(
    key: fn(I.Item) -> K throws E
): ?I.Item throws Join<I.Error, E>

Returns the value whose key is least, or null where there is none.

Of values with equal keys, the first wins. key is called once per value.

Errors

Throws what a pull of the iterator or key throws.

pub fn maxBy<K :: [TotalOrder], E :: [Error]>(
    key: fn(I.Item) -> K throws E
): ?I.Item throws Join<I.Error, E>

Returns the value whose key is greatest, or null where there is none.

Of values with equal keys, the first wins. key is called once per value.

Errors

Throws what a pull of the iterator or key throws.

pub inline fn forEach<E :: [Error]>(
    f: fn(I.Item) -> void throws E
): void throws Join<I.Error, E>

Calls f on every value, in order.

The function is inline: a lambda written at the call is set in place, so a return in it leaves the enclosing function, and break and continue reach the enclosing loops.

Errors

Throws what a pull of the iterator or f throws.

pub fn toArray(): I.Item[] throws I.Error

Returns the values in a new array, in order.

Collects in one pass through the array's FromIterator.

Errors

Throws what a pull of the iterator throws.

extend<I :: [Iterator<Item = B>], B :: [Iterable]> I

pub fn flatten(): FlattenIter<I, B, B.Iter>

Returns an iterator over the values of the iterables this iterator gives, one after the other.

extend<I :: [Iterator<Item = T>], T :: [Equatable]> I

pub fn dedup(): DedupIter<I, never>

Returns an iterator that gives each run of consecutive equal values once.

extend<I :: [DoubleEnded]> I

pub fn rev(): RevIter<I>

Returns an iterator over the values from the back.

extend<I :: [Iterator, Clone]> I

pub fn cycle(): CycleIter<I>

Returns an iterator over the values, repeated without end.

Each round starts from a clone of this iterator as it was; an empty iterator yields nothing.

extend<I :: [Iterator<Item = int>]> I

pub fn average(): ?float throws I.Error

Returns the arithmetic mean of the values, or null where there are none.

The values are summed as float, so the sum does not overflow.

Errors

Throws what a pull of the iterator throws.

extend<I :: [Iterator<Item = float>]> I

pub fn average(): ?float throws I.Error

Returns the arithmetic mean of the values, or null where there are none.

Errors

Throws what a pull of the iterator throws.

extend<I :: [Iterator<Item = T>], T :: [Num]> I

pub fn sum(): T throws I.Error

Returns the sum of the values; zero where there are none.

Errors

Throws what a pull of the iterator throws.

pub fn product(): T throws I.Error

Returns the product of the values; one where there are none.

Errors

Throws what a pull of the iterator throws.

extend<I :: [Iterator<Item = T>], T :: [Ordered]> I

pub fn min(): ?T throws I.Error

Returns the least value, or null where there is none.

Of equal values, the first wins.

Errors

Throws what a pull of the iterator throws.

pub fn max(): ?T throws I.Error

Returns the greatest value, or null where there is none.

Of equal values, the first wins.

Errors

Throws what a pull of the iterator throws.

extend<I :: [Iterator<Item = T>], T :: [Display]> I

pub fn join(sep: string): string throws I.Error

Returns the display texts of the values joined into one string, with sep between each two.

Returns the empty string where there are no values.

Errors

Throws what a pull of the iterator throws.

extend<I :: [Iterator]> I

pub fn collect<C :: [FromIterator<I.Item>]>(): C throws I.Error

Collects the values into a new value of the expected type, built through its FromIterator.

The target type comes from the context: let names: Set<string> = words.iter().collect();.

Errors

Throws what a pull of the iterator throws.