std.iter

Iterator interface

pub interface Iterator<T>

A cursor: next() yields values until null says the end. That is the whole interface — there is no hasNext beside it that could fall out of step.

mut fn next(): ?T

The next value, or null at the end. mut, because an iterator advances its own position.

fn map<U>(f: fn(T) -> U): Iterator<U>

Each element through f, lazily: nothing runs before someone asks.

fn filter(keep: fn(T) -> bool): Iterator<T>

The elements keep accepts, lazily.

fn take(count: int): Iterator<T>

At most count elements, then the end.

fn skip(count: int): Iterator<T>

Everything after the first count elements.

fn takeWhile(keep: fn(T) -> bool): Iterator<T>

Elements while keep accepts, then the end — unlike filter, which keeps looking.

fn zip<B>(right: Iterator<B>): Iterator<(T, B)>

Pairs, ending when either side does.

fn chain(second: Iterator<T>): Iterator<T>

This sequence, then second.

fn flatMap<U>(f: fn(T) -> Iterator<U>): Iterator<U>

Each element into an iterator of its own, flattened.

stdlib/std/iter.lyr:21

RangeIterator class

pub class RangeIterator :: [Iterator<int>]

An exclusive numeric range, a..b. The inclusive form has its own adapter below: folding a..=b into a..b+1 was the 2.0.1 bug — at the type's maximum the +1 wraps and the loop runs zero times.

current: int

The next value to yield.

end: int

The first value NOT yielded.

pub mut fn next(): ?int

The next value, or null at the end.

stdlib/std/iter.lyr:78

ArrayIterator class

pub class ArrayIterator<T> :: [Iterator<T>]

An array. The index belongs to the iterator, not to the array, so two loops over the same array do not disturb each other.

source: T[]

The array being walked.

index: int

The next position.

pub mut fn next(): ?T

The next value, or null at the end.

stdlib/std/iter.lyr:170

StringIterator class

pub class StringIterator :: [Iterator<char>]

A string, walked over the code points toChars extracted once — charAt per step would make the loop quadratic. The cost is one array per loop.

chars: char[]

The code points, extracted once.

index: int

The next position.

pub mut fn next(): ?char

The next character, or null at the end.

stdlib/std/iter.lyr:189

Iterable interface

pub interface Iterable<T>

What can be walked: for (x in e) calls iter() on anything satisfying this.

A container SAYS how to walk it rather than being the cursor itself — were List<T> its own Iterator<T>, two loops over the same list would push each other along. Every call hands out a FRESH cursor.

fn iter(): Iterator<T>

A fresh cursor over this value.

stdlib/std/iter.lyr:211

over function

pub fn over<T>(xs: T[]): Iterator<T>

A cursor over an array: over(xs).map(f) starts a chain where for (x in xs) starts a loop.

The index belongs to the cursor, so two chains over one array do not disturb each other.

stdlib/std/iter.lyr:228

range function

pub fn range(low: int, high: int): Iterator<int>

The numbers low up to but not including high — what low..high walks in a loop.

stdlib/std/iter.lyr:233

rangeInclusive function

pub fn rangeInclusive(low: int, high: int): Iterator<int>

The numbers low up to and including high — what low..=high walks in a loop.

A separate function rather than range(low, high + 1), for the reason the two adapters are separate: at the type's maximum that + 1 wraps and the chain yields nothing.

stdlib/std/iter.lyr:241

compact function

pub fn compact<T>(xs: (?T)[]): Iterator<T>

The values of an array of optionals that are not null, lazily.

The commonest table with holes in it is a (?T)[] — a fixed number of slots, most of them empty — and this is what makes one chainable: compact(houses).map(rooms).

It takes an ARRAY rather than an iterator, and that is not a convenience. An Iterator<?T> cannot exist: next() answers ?T and spends null on "the end", so an optional element would need ??T to be told apart from it, and ? does not nest. Reading the slots directly is what makes the distinction available at all.

stdlib/std/iter.lyr:254

CompactIterator class

pub class CompactIterator<T> :: [Iterator<T>]

The lazy machinery behind compact.

source: (?T)[]

The slots being read.

index: int

The next slot to look at.

pub mut fn next(): ?T

The next value that is not null, or null at the end of the array.

stdlib/std/iter.lyr:259

MapIterator class

pub class MapIterator<T, U> :: [Iterator<U>]

The lazy machinery behind map.

source: Iterator<T>

The values being transformed.

f: fn(T) -> U

The transformation, applied per element.

pub mut fn next(): ?U

The next transformed value, or null at the end.

stdlib/std/iter.lyr:291

FilterIterator class

pub class FilterIterator<T> :: [Iterator<T>]

The lazy machinery behind filter.

source: Iterator<T>

The values being sifted.

keep: fn(T) -> bool

Decides what passes.

pub mut fn next(): ?T

The next passing value, or null at the end.

stdlib/std/iter.lyr:309

TakeIterator class

pub class TakeIterator<T> :: [Iterator<T>]

The lazy machinery behind take.

source: Iterator<T>

The values being limited.

remaining: int

How many may still pass.

pub mut fn next(): ?T

The next value while the budget lasts, then null.

stdlib/std/iter.lyr:330

SkipIterator class

pub class SkipIterator<T> :: [Iterator<T>]

The lazy machinery behind skip.

source: Iterator<T>

The values being shortened.

pending: int

How many are still to be dropped, at the first next.

pub mut fn next(): ?T

The next value past the dropped front, or null at the end.

stdlib/std/iter.lyr:347

TakeWhileIterator class

pub class TakeWhileIterator<T> :: [Iterator<T>]

The lazy machinery behind takeWhile.

source: Iterator<T>

The values being cut off.

keep: fn(T) -> bool

Decides where the front ends.

done: bool

Set at the first refusal; from then on everything is null.

pub mut fn next(): ?T

The next value of the accepted front, then null forever.

stdlib/std/iter.lyr:367

EnumerateIterator class

pub class EnumerateIterator<T> :: [Iterator<(int, T)>]

The lazy machinery behind enumerate.

source: Iterator<T>

The values being numbered.

index: int

The number the next value gets.

pub mut fn next(): ?(int, T)

The next (position, value) pair, or null at the end.

stdlib/std/iter.lyr:397

enumerate function

pub fn enumerate<T>(source: Iterator<T>): Iterator<(int, T)>

Numbers the elements: a, b, c becomes (0, a), (1, b), (2, c).

stdlib/std/iter.lyr:416

ZipIterator class

pub class ZipIterator<A, B> :: [Iterator<(A, B)>]

The lazy machinery behind zip.

left: Iterator<A>

The first column.

right: Iterator<B>

The second column.

pub mut fn next(): ?(A, B)

The next pair, or null when either side ends.

stdlib/std/iter.lyr:421

ChainIterator class

pub class ChainIterator<T> :: [Iterator<T>]

The lazy machinery behind chain.

first: Iterator<T>

The front half.

second: Iterator<T>

The back half.

onFirst: bool

Whether the front half is still being walked.

pub mut fn next(): ?T

The next value, first half first, or null when both end.

stdlib/std/iter.lyr:442

FlatMapIterator class

pub class FlatMapIterator<T, U> :: [Iterator<U>]

The lazy machinery behind flatMap.

source: Iterator<T>

The values each of which becomes a sequence.

f: fn(T) -> Iterator<U>

Builds the sequence for one value.

current: ?Iterator<U>

The sequence currently being drained, or null before the first and after the last.

pub mut fn next(): ?U

The next value of the current sequence, moving to the next source value when one ends.

stdlib/std/iter.lyr:464

ChunksIterator class

pub class ChunksIterator<T> :: [Iterator<T[]>]

The lazy machinery behind chunks.

source: Iterator<T>

The values being grouped.

size: int

The group size; the last group may be shorter.

pub mut fn next(): ?T[]

The next group, or null when the source is spent.

stdlib/std/iter.lyr:493

chunks function

pub fn chunks<T>(source: Iterator<T>, size: int): Iterator<T[]>

Groups of size back to back; the last one may be shorter, and never empty. A size below one yields nothing rather than panicking, the take convention.

stdlib/std/iter.lyr:518

EmptyIterator class

pub class EmptyIterator<T> :: [Iterator<T>]

The iterator with nothing in it — what an empty selection collapses to.

pub mut fn next(): ?T

Always null.

stdlib/std/iter.lyr:528

fold function

pub fn fold<T, A>(source: Iterator<T>, seed: A, step: fn(A, T) -> A): A

Folds from the left: fold(1..4, 0, (acc, n) => acc + n) is ((0+1)+2)+3.

The most general terminator; count, sum, any and all are special cases of it. They exist separately because fold with a closure is too much ceremony for counting.

stdlib/std/iter.lyr:548

reduce function

pub fn reduce<T>(source: Iterator<T>, step: fn(T, T) -> T): ?T

Folds without a seed: the first element starts the accumulator, so the result carries the element type — and null says the source was empty, the case a seed would have answered.

stdlib/std/iter.lyr:561

first function

pub fn first<T>(source: Iterator<T>): ?T

The first element, or null for an empty source. One next, named for the chain that ends on it.

stdlib/std/iter.lyr:577

count function

pub fn count<T>(source: Iterator<T>): int

How many elements the iterator yields; drains it.

stdlib/std/iter.lyr:582

sum function

pub fn sum(source: Iterator<int>): int

The sum of an int iterator.

stdlib/std/iter.lyr:594

sumFloat function

pub fn sumFloat(source: Iterator<float>): float

The sum of a float iterator.

stdlib/std/iter.lyr:605

any function

pub fn any<T>(source: Iterator<T>, test: fn(T) -> bool): bool

Stops at the first match; the rest is never evaluated.

stdlib/std/iter.lyr:616

all function

pub fn all<T>(source: Iterator<T>, test: fn(T) -> bool): bool

Stops at the first counterexample. An empty iterator yields true, the only convention for which all(a) && all(b) == all(chain(a, b)) holds.

stdlib/std/iter.lyr:630

none function

pub fn none<T>(source: Iterator<T>, test: fn(T) -> bool): bool

Whether nothing matches: !any.

stdlib/std/iter.lyr:643

find function

pub fn find<T>(source: Iterator<T>, test: fn(T) -> bool): ?T

The first element that matches, or null.

stdlib/std/iter.lyr:648

position function

pub fn position<T>(source: Iterator<T>, test: fn(T) -> bool): ?int

The position of the first match. Separate from find, because a (int, T) tuple would cost the common case where only one of the two is needed.

stdlib/std/iter.lyr:662

collectArray function

pub fn collectArray<T>(source: Iterator<T>): T[]

Everything into an array.

Quadratic: a T[] has a fixed length, so every append copies. For large iterators use std.collections.collect, which gathers into a doubling List<T>. It stands here because std.iter must not import std.collections; the dependency runs the other way.

stdlib/std/iter.lyr:681

minValue function

pub fn minValue<T :: [Ordered<T>]>(source: Iterator<T>): ?T

The smallest element, or null for an empty source.

stdlib/std/iter.lyr:692

maxValue function

pub fn maxValue<T :: [Ordered<T>]>(source: Iterator<T>): ?T

The largest element, or null for an empty source.

stdlib/std/iter.lyr:708