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.
| Alias | Package | Source file |
|---|---|---|
bytes |
core/bytes |
io.dodo |
mem |
core/mem |
io.dodo |
num |
core/num |
io.dodo |
ErrorKind
Enum · Source
Byte streams implement the Reader and Writer interfaces below. Any type with matching methods does; helpers take them as bounded generic parameters (statically dispatched) and
&mut dyn Reader/&mut dyn Writervalues work wherever the concrete stream type should not be part of a signature. 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
Reader
Interface · Source
A source of bytes: fills a prefix of
destinationand returns its length.
pub interface Reader {
fn read(&mut self, destination: &mut[u8]) -> usize!Error
}
Writer
Interface · Source
A sink of bytes: consumes a prefix of
sourceand returns its length.
pub interface Writer {
fn write(&mut self, source: &[u8]) -> usize!Error
}
ReadWriter
Interface · Source
A two-way stream such as a socket or serial port.
&mut dyn ReadWriterconverts to&mut dyn Reader, its first parent.
pub interface ReadWriter: Reader + Writer {}
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>(reader: &mut R, destination: &mut[u8]) -> usize!Error
write_once
Function · Source
pub fn write_once<W: Writer>(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>(reader: &mut R, destination: &mut[u8]) -> usize!Error
read_exact
Function · Source
pub fn read_exact<R: Reader>(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>(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: Reader> {
// 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>(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: Reader, W: Writer>(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: Reader> {
// 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: Writer> {
// 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>(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>(reader: &mut R, destination: &mut[u8]) -> Line!Error