Item Streams

Explicit item streams

std::stream provides single-consumer streams outside pipeline syntax. A Reader advances through next_item, can expose a final result or context, and can be closed explicitly.

Compose transformations

import std::stream
let $source = std::stream::from_iterable [2, 4, 7]
let $scaled = std::stream::map $source fn ($n: Integer): Integer { $n * 5 }
let $selected = std::stream::filter $scaled fn ($n: Integer): Boolean { $n >= 20 }
let $items = std::stream::collect $selected
echo $items...

20 35

map and filter defer work until a consumer asks for items. collect deliberately materializes the remaining items. Re-reading a consumed stream does not restart it. Closing an adapter releases its owned operation and upstream resources according to that adapter's ownership contract.

Unit is data, too

A custom iterator returns actual () to signal completion. When a stream needs to carry a unit item, use its boxed representation: Item(value: ()). A boxed Reader distinguishes this from the end of the stream. Native arrays retain unit items when adapted through from_iterable.

Custom sources

A Reader can be created with callbacks for the next item, final result, closing, and context. Keep callbacks small and explicit about errors. Resources and errors remain subject to the same ownership and propagation rules as other code.

Use language pipelines for concise stage syntax. Use explicit streams when a library needs to return a lazy sequence, preserve final metadata, or control its consumption and closing policy. JSON and network adapters use these same Readers.

---

Related: Iteration protocol · Pipelines · JSON