TryExtend

Module std.iteration

import std.iteration;

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

TryExtend

pub fn TryExtend<T, I, A>(Destination: mut Vector<T, A>&, mut Cursor: I)
    -> Result<void, VectorInsertionError<T>>
    where T: Movable where I: CollectibleIterator<T> where A: Allocator, Defaultable, Movable

Consumes a cursor and appends converted items to an owned Vector.

Source values transfer through their optional carriers. Borrowed items copy into value T only when ordinary conversion permits it; borrowing never silently moves a non-Copy referent. Pulls and appends occur in source order, stopping at the first none or insertion failure. May allocate through the destination's allocator. No pre-count, intermediate collection, lock or public unsafe block is introduced. Cursor state is consumed on both outcomes. T: Destination element supporting the ordinary source-item conversion and move. I: Structural cursor proving an implicit Item-to-T conversion. A: Explicit destination allocator type. Destination: Exclusively writable Vector; retains every successful append on failure. Cursor: Owned traversal state; move a non-Copy cursor explicitly. Return: Ok, or insertion error owning the first rejected T and its allocation reason. Warning: Structural mutation invalidates destination cursors; source must not borrow invalidated storage.

Example

module example.extend_cursor;
from std.collections import Vector;
from std.iteration import TryExtend;
fn Main() -> i32 {
    var Values = Vector<i32>();
    if Values.TryPush(10) is .Err { Error = _ } { return 1; }
    // Borrowed i16 items widen into owned i32 without changing the input.
    let More: i16[2] = [20_i16, 12_i16];
    switch TryExtend(Values, More.CreateIterator()) {
        case .Ok => { }
        case .Err { Error = Failure } => {
            if Failure.Reason == .SizeOverflow { return 3; }
            return 4;
        }
    }
    if Values.Length != 3 || More[0] != 20 || More[1] != 12 { return 2; }
    return Values.At(0) + Values.At(1) + Values.At(2) - 42;
}