WhereIterator

Module std.iteration

import std.iteration;

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

WhereIterator

pub final class WhereIterator<T, I>
    where T: Copyable
    where I: TypedIterator<T>, Movable

Owns lazy filtering state that forwards exact accepted item categories.

Each Next searches until a matching item or exhaustion. An infinite source with no match may never return. Predicate runs once per examined item; no intermediate container is allocated. Reference items preserve readonly or writable access and borrow their original backing owner. Traversal and the callback require their documented synchronization; no lock is introduced. T: Exact Copyable input value/reference type. I: Owned structural cursor returning T?.

Example

module example.where_iterator;
from std.iteration import Where, Count;
fn Positive(Value: i32&) -> bool { return Value > 0; }
fn Main() -> i32 {
    let Values: i32[4] = [-1, 20, 0, 22];
    var Cursor = Where<i32&>(Values.CreateIterator(), Positive);
    var Total: i32 = 0;
    while Cursor.Next() is .Some { Value = Item } { Total += Item; }
    let Remaining = Count(move(Cursor));
    if Total != 42 || Remaining != 0 { return 1; }
    return 0;
}

WhereIterator.Next

pub fn Next() -> T?

Searches for the next predicate match, preserving its exact item type. Return: Matching item or none after first source exhaustion. Warning: Cost includes each discarded item and callback; backing lifetimes are unchanged.

Where

pub fn Where<T, I>(mut Source: I, Predicate: fn(T) -> bool) -> WhereIterator<T, I>
    where T: Copyable
    where I: TypedIterator<T>, Movable

Creates a lazy filter without examining its source. T: Exact Copyable item category, supplied explicitly. I: Structural source cursor, inferred from Source. Source: Cursor state; explicitly move a non-Copy cursor. Predicate: Safe function; writable references are permitted only if T already grants them. Return: Caller-owned adapter, allocating no intermediate storage. Warning: Callback cost and backing invalidation remain unchanged.