HewStandard Library

Module std::stream

Stream and Sink — bounded, FIFO data channels.

Streams and sinks are language intrinsics for passing typed data between producers and consumers, including across actor boundaries.

Contract slice frozen here:

Current stdlib scope:

Example

import std::stream;

fn main() {
    let (sink, input) = stream.pipe(16);

    sink.write("hello");
    sink.write("world");
    sink.close();  // optional — would auto-close on drop

    for await item in input {
        println(item);
    }
}

Contents

Functions

Function pipe

pub fn pipe(capacity: i64) -> (Sink<string>, Stream<string>)

Create a bounded in-memory string pipe with the given capacity.

This is the convenience text ABI lane over the same bounded, blocking, backpressured contract as bytes_pipe(). Returns a (Sink<string>, Stream<string>) pair for writing and reading.

Function bytes_pipe

pub fn bytes_pipe(capacity: i64) -> (Sink<bytes>, Stream<bytes>)

Create a bounded in-memory bytes pipe with the given capacity.

This is the canonical first-class Stream/Sink foundation for binary items. Returns a (Sink<bytes>, Stream<bytes>) pair for writing and reading.

Function from_file

pub fn from_file(path: string) -> Result<Stream<string>, string>

Open a file as a readable Stream.

Returns Err with the OS error message if the file cannot be opened. This stage only freezes constructor/open errors; read-time failures after a stream is opened remain wrapper-specific and out of scope for the core Stream/Sink contract. Prefer try_from_file for a structured Result<Stream<string>, fs.IoError>. Import std::fs as well if you want to match on IoError variants.

Examples

let file = stream.from_file("data.txt")?;
for await line in file.lines() { println(line); }

Function try_from_file

pub fn try_from_file(path: string) -> Result<Stream<string>, fs.IoError>

Open a file as a readable Stream<string>.

This preserves from_file's runtime behaviour while returning fs.IoError instead of a raw OS message string. Import std::fs when matching on the returned error value so you can use the existing unqualified IoError::Variant(...) constructor/pattern style.

Function to_file

pub fn to_file(path: string) -> Result<Sink<string>, string>

Open a file as a writable Sink.

Returns Err with the OS error message if the file cannot be created. This stage only freezes constructor/open errors; write-time failures after a sink is opened remain wrapper-specific and out of scope for the core Stream/Sink contract. Prefer try_to_file for a structured Result<Sink<string>, fs.IoError>. Import std::fs as well if you want to match on IoError variants.

Examples

let sink = stream.to_file("output.txt")?;
sink.write("hello");
// sink auto-closes when dropped

Function try_to_file

pub fn try_to_file(path: string) -> Result<Sink<string>, fs.IoError>

Open a file as a writable Sink<string>.

This preserves to_file's runtime behaviour while returning fs.IoError instead of a raw OS message string. Import std::fs when matching on the returned error value so you can use the existing unqualified IoError::Variant(...) constructor/pattern style.

Function forward

pub fn forward(source: Stream<string>, dest: Sink<string>)

Pipe all items from a stream into a sink, then close both.

This is the streaming equivalent of io.Copy — it reads from the source until EOF and writes each item to the destination.

Examples

let file = stream.from_file("data.txt")?;
let body = req.respond_stream(200, "text/plain")?;
stream.forward(file, body);  // streams file directly to HTTP response

Types

Struct StreamPair

Internal paired channel handle.