Iterator

Module std.iteration

import std.iteration;

Public declaration contracts and authored examples. A page can document several related symbols. Implementation bodies are excluded.

Iterator

pub concept Iterator<Self>

Defines a zero-allocation mutable cursor that yields optional items.

Cursor values own traversal state and may borrow or own their backing. Each concrete cursor documents retention and item ownership; borrowed items follow their backing range's mutation, move, and destruction rules.

Self: Concrete cursor type supplying the declared Item and Next requirements.

Example

module example.iterator;
from std.iteration import IntegerRange;
from std.collections import Vector;
// A readonly receiver selects the read cursor; its references remain within
// the caller-owned vector lifetime, and the result is an independent sum.
fn SumRead(Values: readonly Vector<i32>&) -> i32 {
    var Cursor = Values.CreateIterator();
    var Total: i32 = 0;
    while Cursor.Next() is .Some { Value = Item } { Total += Item; }
    return Total;
}
fn Main() -> i32 {
    let Values: IntegerRange<i32> = 0..3;
    var Cursor = Values.CreateIterator();
    var Sum = 0;
    while Cursor.Next() is .Some { Value = Item } {
        Sum += Item;
    }
    // WritableIterable has a distinct writable cursor type. Mutate through
    // it, end that borrow, then observe through the readonly cursor contract.
    var MutableValues = Vector<i32>();
    if MutableValues.TryPush(1) is .Err { Error = _ } { return 1; }
    if MutableValues.TryPush(2) is .Err { Error = _ } { return 2; }
    {
        var Writable = MutableValues.CreateWritableIterator();
        while Writable.Next() is .Some { Value = Item } { Item += 1; }
    }
    if SumRead(MutableValues) != 5 { return 3; }
    return Sum - 3;
}

Iterator.Item

associated type Item;

Identifies the value or reference produced by one cursor step.

Iterator.Next

requires fn Next() -> Item?;

Advances once and reports the next item when present. Return: .Some containing one item, or .None after exhaustion.

Iterable

pub concept Iterable<Self>

Defines a borrowed read traversal source. Self: Concrete source type satisfying the structural requirements.

Iterable.IteratorType

associated type IteratorType: Iterator;

Identifies the source's read cursor type.

Iterable.CreateIterator

requires readonly fn CreateIterator() -> IteratorType;

Creates one independent caller-owned read cursor. Return: A zero-allocation cursor borrowing the source's backing lifetime.

WritableIterable

pub concept WritableIterable<Self>

Extends read traversal with explicit writable-reference traversal. Self: Concrete mutable source type satisfying both cursor contracts.

WritableIterable.IteratorType

associated type IteratorType: Iterator;

Identifies the ordinary read cursor.

WritableIterable.WritableIteratorType

associated type WritableIteratorType: Iterator;

Identifies the cursor whose Item is a writable reference.

WritableIterable.CreateIterator

requires readonly fn CreateIterator() -> IteratorType;

Creates a read cursor. Return: Caller-owned zero-allocation cursor.

WritableIterable.CreateWritableIterator

requires fn CreateWritableIterator() -> WritableIteratorType;

Creates a writable cursor. Return: Caller-owned writable cursor.