std/io

Library guide · API index and notation

This page is generated from the bundled library in this checkout. Signatures and adjacent source comments are reproduced below; the linked guide explains usage, storage, failures, and platform support.

import "std/io"

Names used in signatures

Unqualified names denote this package’s types (including other source files in the same package), language built-ins, or generic parameters such as T. Qualified names use the import aliases below. These aliases belong to the library source; import a dependency yourself to use its alias in your program.

ErrorKind

Enum · Source

Structural, statically dispatched contracts (no traits or runtime vtable): Reader: read(&mut self, &mut[u8]) -> usize!Error. Writer: write(&mut self, &[u8]) -> usize!Error. Counts, including Error.transferred, refer to this call’s slice prefix. A nonempty successful read of zero bytes means EOF. A successful write of zero bytes is converted to WriteZero by completion helpers. An empty request succeeds without touching a device. Interrupted errors may carry progress. A provider must never report or access more bytes than the supplied slice.

pub enum ErrorKind {
    UnexpectedEof, WriteZero, Interrupted, BufferFull, OutOfBounds,
    InvalidInput, InvalidProgress, Other, WouldBlock, TimedOut, Cancelled,
    Closed, ConnectionReset, ConnectionRefused, BrokenPipe, PermissionDenied
}

Error

Struct · Source

pub struct Error {
    pub kind: ErrorKind
    pub transferred: usize
    // Opaque adapter-defined device/platform code, zero for portable errors.
    pub code: i32
}

Error.format

Function · Source

Only fixed kind names and numeric metadata; never input or native messages.

pub fn format<F>(&self, output: &mut F) -> void!Error

failure

Function · Source

pub fn failure(kind: ErrorKind, transferred: usize) -> Error

MemoryReader

Struct · Source

pub struct MemoryReader {
    // Private implementation fields omitted.
}

MemoryReader.new

Function · Source

pub fn new(data: &[u8]) -> MemoryReader from(data)

MemoryReader.position

Function · Source

pub fn position(&self) -> usize

MemoryReader.remaining

Function · Source

pub fn remaining(&self) -> &[u8]

MemoryReader.read

Function · Source

pub fn read(&mut self, destination: &mut[u8]) -> usize!Error

MemoryReader.seek

Function · Source

Seeking is an optional capability, independent of the reader contract. Absolute positions through the end are accepted; failure does not move.

pub fn seek(&mut self, position: usize) -> usize!Error

MemoryReader.poll_read

Function · Source

pub fn poll_read(&mut self, destination: &mut[u8]) -> Poll!Error

MemoryWriter

Struct · Source

pub struct MemoryWriter {
    // Private implementation fields omitted.
}

MemoryWriter.new

Function · Source

pub fn new(data: &mut[u8]) -> MemoryWriter from(data)

MemoryWriter.position

Function · Source

pub fn position(&self) -> usize

MemoryWriter.remaining

Function · Source

pub fn remaining(&self) -> usize

MemoryWriter.written

Function · Source

pub fn written(&self) -> &[u8]

MemoryWriter.write

Function · Source

pub fn write(&mut self, source: &[u8]) -> usize!Error

MemoryWriter.poll_write

Function · Source

pub fn poll_write(&mut self, source: &[u8]) -> Poll!Error

Cursor

Struct · Source

A cursor reads and overwrites an initialized, fixed-size caller buffer. It never extends storage; seeking past its end fails without changing state.

pub struct Cursor {
    // Private implementation fields omitted.
}

Cursor.new

Function · Source

pub fn new(data: &mut[u8]) -> Cursor from(data)

Cursor.position

Function · Source

pub fn position(&self) -> usize

Cursor.bytes

Function · Source

pub fn bytes(&self) -> &[u8]

Cursor.seek

Function · Source

pub fn seek(&mut self, position: usize) -> usize!Error

Cursor.read

Function · Source

pub fn read(&mut self, destination: &mut[u8]) -> usize!Error

Cursor.write

Function · Source

pub fn write(&mut self, source: &[u8]) -> usize!Error

read_once

Function · Source

Validate an adapter’s returned progress before using it as a slice offset. Empty operations never invoke the adapter, even if it is currently failing.

pub fn read_once<R>(reader: &mut R, destination: &mut[u8]) -> usize!Error

write_once

Function · Source

pub fn write_once<W>(writer: &mut W, source: &[u8]) -> usize!Error

read_up_to

Function · Source

Fill until the slice is full or EOF is reached. EOF is successful here. Failure reports the total initialized prefix, not merely the final call.

pub fn read_up_to<R>(reader: &mut R, destination: &mut[u8]) -> usize!Error

read_exact

Function · Source

pub fn read_exact<R>(reader: &mut R, destination: &mut[u8]) -> usize!Error

write_all

Function · Source

Completion is blocking: Interrupted retries, including after partial progress. A persistent interruption can therefore block indefinitely, like the device.

pub fn write_all<W>(writer: &mut W, source: &[u8]) -> usize!Error

LimitReader

Struct · Source

A bounded reader consumes at most limit bytes, counting error progress too. The limit is a synthetic EOF; its exhausted state never touches the reader.

pub struct LimitReader<R> {
    // Private implementation fields omitted.
}

LimitReader.new

Function · Source

pub fn new(reader: &mut R, limit: usize) -> LimitReader<R> from(reader)

LimitReader.remaining

Function · Source

pub fn remaining(&self) -> usize

LimitReader.read

Function · Source

pub fn read(&mut self, destination: &mut[u8]) -> usize!Error

skip

Function · Source

Discard exactly count bytes using caller storage. EOF before count is an error. The scratch buffer may be empty only when count is zero.

pub fn skip<R>(reader: &mut R, count: usize, scratch: &mut[u8]) -> usize!Error

CopyReport

Struct · Source

pub struct CopyReport {
    pub read: usize
    pub written: usize
    // False when the explicit limit was reached without probing for EOF.
    pub eof: bool
}

CopyError

Struct · Source

pub struct CopyError {
    pub read: usize
    pub written: usize
    pub cause: Error
}

copy

Function · Source

Copy at most limit bytes through scratch; counts never exceed limit. On failure, read - written bytes were consumed but not delivered. A read error with progress first attempts to deliver that prefix, then returns the error. If that write also fails, its error takes precedence; both counts survive.

pub fn copy<R, W>(reader: &mut R, writer: &mut W, scratch: &mut[u8], limit: usize) -> CopyReport!CopyError

BufferedReader

Struct · Source

Caller-backed buffering. The reader owns no allocation and holds exclusive borrows of both device and buffer. No read-ahead is discarded by read().

pub struct BufferedReader<R> {
    // Private implementation fields omitted.
}

BufferedReader.new

Function · Source

pub fn new(reader: &mut R, storage: &mut[u8]) -> BufferedReader<R>!Error from(reader, storage)

BufferedReader.buffered

Function · Source

pub fn buffered(&self) -> &[u8]

BufferedReader.read

Function · Source

pub fn read(&mut self, destination: &mut[u8]) -> usize!Error

BufferedWriter

Struct · Source

Accepted bytes belong to this adapter until flush succeeds. Dropping it does not perform I/O: pending bytes are discarded. Call flush and handle its Result before releasing the device. Failed flush preserves the unwritten suffix.

pub struct BufferedWriter<W> {
    // Private implementation fields omitted.
}

BufferedWriter.new

Function · Source

pub fn new(writer: &mut W, storage: &mut[u8]) -> BufferedWriter<W>!Error from(writer, storage)

BufferedWriter.pending

Function · Source

pub fn pending(&self) -> &[u8]

BufferedWriter.capacity

Function · Source

pub fn capacity(&self) -> usize

BufferedWriter.write

Function · Source

pub fn write(&mut self, source: &[u8]) -> usize!Error

BufferedWriter.flush

Function · Source

pub fn flush(&mut self) -> usize!Error

PollState

Enum · Source

Polling contracts are separate: poll_read/poll_write return after one device attempt. Pending may include prefix progress. It never means EOF or an error; the caller decides when to retry, with no scheduler or implicit busy loop.

pub enum PollState {
    Ready, Pending, Eof
}

Poll

Struct · Source

pub struct Poll {
    pub transferred: usize
    pub state: PollState
}

poll_read_once

Function · Source

pub fn poll_read_once<R>(reader: &mut R, destination: &mut[u8]) -> Poll!Error

poll_write_once

Function · Source

pub fn poll_write_once<W>(writer: &mut W, source: &[u8]) -> Poll!Error

seek

Function · Source

Optional absolute seek capability; generic read/write helpers never require it.

pub fn seek<S>(stream: &mut S, position: usize) -> usize!Error

ReadReport

Struct · Source

Read a bounded whole stream. A one-byte probe distinguishes exact capacity from exhaustion (including zero-capacity empty streams). The probe byte is consumed and discarded. Errors retain destination[..transferred]; bytes beyond that prefix have no output contract. Interrupted progress is retained.

pub struct ReadReport {
    pub read: usize
    pub eof: bool
}

read_bounded

Function · Source

pub fn read_bounded<R>(reader: &mut R, destination: &mut[u8]) -> ReadReport!Error

LineEnd

Enum · Source

Line bytes include the terminating LF (and any preceding CR). No decoding, allocation, read-ahead, or discarded bytes. Full means the buffer filled without LF; EOF has not been probed. Continue with another buffer to resume.

pub enum LineEnd {
    Newline, Eof, Full
}

Line

Struct · Source

pub struct Line {
    pub count: usize
    pub end: LineEnd
}

read_line

Function · Source

Empty storage returns Full without reading. Eof with count=0 is end of input; Eof with count>0 is a final unterminated line. Errors retain the initialized prefix in transferred, even if its last byte is LF. Only Interrupted retries.

pub fn read_line<R>(reader: &mut R, destination: &mut[u8]) -> Line!Error