std/io

Types

IoError

pub type IoError = {
    pub text String
}

An I/O failure not tied to any OS error code.

IoError.message

pub fn IoError.message(self) -> String

BytesReader

pub type BytesReader = {
    // private fields omitted
}

A Reader over bytes already held in memory.

BytesReader.new

pub fn BytesReader.new(data: Bytes) -> BytesReader

BytesReader.read

pub fn BytesReader.read(mut self, into: &mut Array[u8], max: usize) -> usize!

BytesWriter

pub type BytesWriter = {
    // private fields omitted
}

A Writer that accumulates into an in-memory buffer.

Passing a BytesWriter to writeAll/copy moves it, so its buffer cannot be read back afterward with .bytes() (a real use-after-move, since this type is concrete). Call .write(...) directly instead of going through writeAll/copy when the buffer needs inspecting afterward.

BytesWriter.new

pub fn BytesWriter.new() -> BytesWriter

BytesWriter.write

pub fn BytesWriter.write(mut self, data: Bytes) -> usize!

BytesWriter.bytes

pub fn BytesWriter.bytes(self) -> Bytes

Everything written so far.

BufReader

pub type BufReader = {
    // private fields omitted
}

A Reader with a look-ahead buffer, so a caller can read up to a delimiter without reading past it. HTTP/1.1 and any other line- or record-oriented protocol needs this: the plain Reader interface cannot say "stop here".

BufReader is itself a Reader, so it composes with readAll and copy.

BufReader.new

pub fn BufReader.new(r: Reader) -> BufReader

Wraps r. Nothing is read until the first call.

BufReader.buffered

pub pure noalloc fn BufReader.buffered(self) -> usize

Bytes held in the buffer, not yet handed to the caller.

BufReader.readUntil

pub fn BufReader.readUntil(mut self, delim: Bytes) -> Bytes?!

Everything up to and including the first delim, removed from the buffer. At end of input with bytes left over, returns them without the delimiter; None once the source is drained and the buffer is empty. An empty delim is an error, since it would never make progress.

BufReader.readLine

pub fn BufReader.readLine(mut self) -> String?!

One line without its terminator, which may be "\n" or "\r\n". None once the source is drained and the buffer is empty; a final line with no terminator is still returned.

BufReader.read

pub fn BufReader.read(mut self, into: &mut Array[u8], max: usize) -> usize!

Appends up to max buffered or freshly read bytes to into; satisfies Reader, so a BufReader can stand in for the source it wraps.

Interfaces

Reader

pub interface Reader {
    fn read(mut self, into: &mut Array[u8], max: usize) -> usize!
}

Source of bytes. read appends up to max bytes to into and returns how many; 0 with no error means end of input (POSIX read semantics).

Law: the returned n must satisfy n <= max, and into must grow by exactly n elements. readAll/copy check this and fail with IoError when it does not hold.

Writer

pub interface Writer {
    fn write(mut self, data: Bytes) -> usize!
}

Sink for bytes. write may send fewer bytes than given (a short write); writeAll loops until all of data is sent.

Law: the returned n must satisfy n <= data.len(). writeAll/copy check this and fail with IoError when it does not hold.

Functions

readAll

pub fn readAll[R: Reader](mut r: R) -> Bytes!

Reads r until end of input and returns everything read; fails once the input turns out to exceed defaultReadLimit bytes, and readUpTo takes another limit.

Unsound if r is a mut r: R forwarded from the caller's own generic function and this (or writeAll/copy) is called more than once on it: R is exempt from move tracking, so each call silently gets its own copy instead of a use-after-move error.

readUpTo

pub fn readUpTo[R: Reader](mut r: R, limit: usize) -> Bytes!

Same as readAll, but fails with IoError once more than limit bytes have arrived instead of reading on.

writeAll

pub fn writeAll[W: Writer](mut w: W, data: Bytes) -> Void!

Writes all of data to w, calling write again after each short write.

Unsound on a mut w: W forwarded from the caller's own generic function when called more than once on it (a header then a body, say): see readAll's note.

copy

pub fn copy[R: Reader, W: Writer](mut r: R, mut w: W) -> usize!

Copies every byte from r to w and returns the total copied.

A single call is safe (this loops via w.write directly, not writeAll, specifically to avoid the hazard below). But like readAll/writeAll, calling copy itself more than once on a mut w: W or mut r: R forwarded from the caller's own generic function is unsound: see readAll's note.

Constants

defaultReadLimit

pub const defaultReadLimit: usize = 268435456

The most bytes readAll collects before it fails.