Find

Module std.iteration

import std.iteration;

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

pub fn Find<T, I>(mut Cursor: I, Predicate: fn(T) -> bool) -> T?
    where T: Copyable
    where I: TypedIterator<T>

Searches a cursor for its first safe-predicate match.

Stops immediately at a match or first exhaustion. It allocates no intermediate storage; callback invocation and source pulls retain their documented costs. Copyable reference items remain nonretaining aliases with exact access. T: Exact Copyable input item category. I: Structural source cursor inferred from Cursor. Cursor: Traversal state; transfer a non-Copy cursor with move. Predicate: Safe function, called once per examined item. Return: First matching item, or none; borrowed results expire with source backing. Warning: Does not consume items after the match or extend backing lifetime.

Example

module example.find_iterator;
from std.iteration import Find;
fn Matches(Value: i32&) -> bool { return Value == 42; }
fn Main() -> i32 {
    let Values: i32[3] = [1, 42, 99];
    switch Find<i32&>(Values.CreateIterator(), Matches) {
        case .Some { Value = Item } => { if Item != 42 { return 1; } }
        case .None => return 2;
    }
    let Missing: i32[1] = [0];
    if Find<i32&>(Missing.CreateIterator(), Matches) is .Some { Value = _ } { return 3; }
    return 0;
}

Find

pub fn Find<T, I>(mut Cursor: I, Predicate: fn(readonly T&) -> bool) -> T?
    where T: Movable where I: TypedIterator<T>

Consumes a cursor with a safe predicate that borrows each exact item.

Owns each optional carrier during callback evaluation, avoiding non-Copy payload copies. Examined non-returned items receive ordinary destruction. Traversal is ordered and synchronous with no intermediate allocation or lock. T: Exact Movable source item type. I: Structural cursor, inferred from Cursor. Cursor: Owned traversal state, consumed through first exhaustion or short circuit. Predicate: Safe readonly observer; backing validity remains its source contract. Return: Original matching carrier, or none after source exhaustion. Warning: Callback cost and reference backing lifetime remain explicit; no implicit ownership retention.