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.

stdlib/std/iter.lyr:18

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:27

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:119

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:138

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:160

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:178

map function

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

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

stdlib/std/iter.lyr:196

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:201

filter function

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

Only the elements keep accepts, lazily.

stdlib/std/iter.lyr:222

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:227

take function

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

The first count elements, lazily. A negative count yields nothing rather than panicking: it is an empty selection, not a broken promise.

stdlib/std/iter.lyr:245

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:250

skip function

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

Everything after the first count elements, lazily. A negative count skips nothing.

stdlib/std/iter.lyr:270

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:275

takeWhile function

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

The longest front keep accepts; it ends at the FIRST refusal, even if true would come again — that is what separates it from filter.

stdlib/std/iter.lyr:306

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:311

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:330

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:335

zip function

pub fn zip<A, B>(left: Iterator<A>, right: Iterator<B>): Iterator<(A, B)>

Walks both in step and ends with the shorter one.

The one surplus call on left is the price of both sides sharing the same interface; avoiding it would need a peek on Iterator<T> that exists nowhere else.

stdlib/std/iter.lyr:359

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:364

chain function

pub fn chain<T>(first: Iterator<T>, second: Iterator<T>): Iterator<T>

First everything of first, then everything of second, lazily.

stdlib/std/iter.lyr:386

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:391

flatMap function

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

Each element becomes a sequence, and the sequences run back to back — lazily on both levels: flatMap(lines, words) reads no second line before the first is drained.

stdlib/std/iter.lyr:421

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:426

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:451

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:461

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:481

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:494

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:510

count function

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

How many elements the iterator yields; drains it.

stdlib/std/iter.lyr:515

sum function

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

The sum of an int iterator.

stdlib/std/iter.lyr:527

sumFloat function

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

The sum of a float iterator.

stdlib/std/iter.lyr:538

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:549

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:563

none function

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

Whether nothing matches: !any.

stdlib/std/iter.lyr:576

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:581

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:595

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:614

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:625

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:641