When To Use std.io
In Zerolang, use std.io for byte reads and writes over caller-owned storage.
The module provides explicit cursor helpers for spans plus fixed reader and
writer values for sequential stream-style code.
Span helpers:
| API | Return | Notes |
|---|---|---|
std.io.copy(dst, src) | usize | Copies as many bytes as fit and returns the count. |
std.io.copyN(dst, src, count) | Maybe<usize> | Copies exactly count bytes when both spans are large enough. |
std.io.read(bytes, offset, dst) | Maybe<usize> | Copies available bytes and returns the next cursor. |
std.io.readExact(bytes, offset, dst) | Maybe<usize> | Fills the destination only when enough input bytes remain. |
std.io.readAt(bytes, offset, dst) | Maybe<usize> | Reads from an explicit offset without owning state. |
std.io.readAll(bytes, dst) | Maybe<Span<u8>> | Copies all input bytes and returns the written prefix. |
std.io.readByte(bytes, offset) | Maybe<u8> | Reads one byte at an explicit cursor. |
std.io.writeByte(buffer, offset, byte) | Maybe<usize> | Writes one byte and returns the next cursor. |
std.io.writeSpan(buffer, offset, bytes) | Maybe<usize> | Writes bytes and returns the next cursor. |
std.io.writeAll(buffer, offset, bytes) | Maybe<usize> | Writes all bytes only when the full input fits. |
std.io.writeAt(buffer, offset, bytes) | Maybe<usize> | Writes at an explicit offset. |
std.io.written(buffer, len) | Span<u8> | Borrows the written prefix, clamped to buffer length. |
std.io.remaining(buffer, offset) | usize | Reports remaining byte capacity from an explicit cursor. |
Line and delimiter helpers:
| API | Return | Notes |
|---|---|---|
std.io.nextLine(bytes, start) | Maybe<Span<u8>> | Borrows the next line without \n or trailing \r. |
std.io.nextLineStart(bytes, start) | usize | Advances to the next line start or end of input. |
std.io.readLine(bytes, start) | Maybe<Span<u8>> | Alias for line-oriented reads using the same line rules. |
std.io.readLineStart(bytes, start) | usize | Advances to the next line start using the same line rules. |
std.io.readUntilDelimiter(bytes, start, delimiter) | Maybe<Span<u8>> | Borrows bytes up to the delimiter or end of input. |
std.io.readUntilDelimiterStart(bytes, start, delimiter) | usize | Advances past the delimiter when found, otherwise to end of input. |
std.io.countLines(bytes) | usize | Counts lines using the same next-line rules. |
Fixed stream helpers:
| API | Return | Notes |
|---|---|---|
std.io.fixedReader(bytes, cursor) | FixedReader | Builds a sequential reader over borrowed bytes. |
std.io.fixedReaderRead(&mut reader, dst) | usize | Reads up to dst length and advances the reader cursor. |
std.io.fixedReaderReadExact(&mut reader, dst) | Bool | Reads exactly dst length or leaves the cursor unchanged. |
std.io.fixedReaderReadLine(&mut reader) | Maybe<Span<u8>> | Borrows the next line and advances the cursor. |
std.io.fixedReaderReadUntilDelimiter(&mut reader, delimiter) | Maybe<Span<u8>> | Borrows bytes up to a delimiter and advances the cursor. |
std.io.fixedReaderReadAll(&mut reader, dst) | Maybe<Span<u8>> | Copies remaining bytes into caller storage. |
std.io.fixedReaderReadAt(&reader, offset, dst) | Maybe<usize> | Reads from an offset without moving the cursor. |
std.io.fixedReaderReadByte(&mut reader) | Maybe<u8> | Reads one byte and advances the cursor. |
std.io.fixedReaderLimit(&reader, count) | FixedReader | Creates a bounded reader view from the current cursor. |
std.io.fixedReaderSeek(&mut reader, cursor) | Bool | Moves the cursor when the target is in range. |
std.io.fixedReaderCursor(&reader) | usize | Reports the cursor. |
std.io.fixedReaderLen(&reader) | usize | Reports input length. |
std.io.fixedReaderRemaining(&reader) | usize | Reports unread bytes. |
std.io.fixedReaderDone(&reader) | Bool | Reports whether the cursor reached the end. |
std.io.fixedWriter(buffer, cursor) | FixedWriter | Builds a sequential writer over caller storage. |
std.io.fixedWriterWrite(&mut writer, bytes) | Bool | Writes bytes and advances the writer cursor. |
std.io.fixedWriterWriteAll(&mut writer, bytes) | Bool | Writes all bytes only when they fit. |
std.io.fixedWriterWriteByte(&mut writer, byte) | Bool | Writes one byte and advances the cursor. |
std.io.fixedWriterWriteAt(&mut writer, offset, bytes) | Bool | Writes at an offset without moving the cursor. |
std.io.fixedWriterView(&writer) | Span<u8> | Borrows the live writer prefix. |
std.io.fixedWriterSeek(&mut writer, cursor) | Bool | Moves the cursor when the target is in range. |
std.io.fixedWriterTruncate(&mut writer, len) | usize | Clamps the live prefix length. |
std.io.fixedWriterClear(&mut writer) | usize | Resets the cursor to zero. |
std.io.fixedWriterCursor(&writer) | usize | Reports the cursor. |
std.io.fixedWriterCapacity(&writer) | usize | Reports storage length. |
std.io.fixedWriterRemaining(&writer) | usize | Reports unwritten capacity. |
Stream composition helpers:
| API | Return | Notes |
|---|---|---|
std.io.copyBuffer(&mut reader, &mut writer, scratch) | usize | Copies until EOF or writer capacity using caller scratch storage. |
std.io.copyReaderN(&mut reader, &mut writer, count, scratch) | Maybe<usize> | Copies exactly count bytes through scratch storage. |
std.io.discard(&mut reader, scratch) | usize | Reads and drops bytes through scratch storage. |
std.io.teeRead(&mut reader, &mut writer, dst) | Maybe<usize> | Reads into dst and writes the same bytes to the writer. |
std.io.multiRead(&mut first, &mut second, dst) | usize | Fills dst from the first reader, then the second. |
Error labels:
| API | Return | Notes |
|---|---|---|
std.io.errorNone() | u32 | No IO error. |
std.io.errorEof() | u32 | End of input. |
std.io.errorShortRead() | u32 | Input ended before an exact read completed. |
std.io.errorShortWrite() | u32 | Output capacity ended before an exact write completed. |
std.io.errorCapacity() | u32 | Caller storage was too small. |
std.io.errorPermission() | u32 | Permission was denied. |
std.io.errorTimeout() | u32 | Operation timed out. |
std.io.errorIo() | u32 | General IO failure. |
std.io.errorName(code) | String | Returns a stable label for a known code. |
Buffered capacity helpers:
| API | Return | Notes |
|---|---|---|
std.io.bufferedReader(buffer) | BufferedReader | Builds a reader descriptor over caller storage. |
std.io.bufferedWriter(buffer) | BufferedWriter | Builds a writer descriptor over caller storage. |
std.io.readerCapacity(&reader) | usize | Reports reader storage capacity. |
std.io.writerCapacity(&writer) | usize | Reports writer storage capacity. |
Metadata labels:
- effects: memory
- allocation behavior: uses caller buffer; no hidden heap
- target support: target-neutral
- error behavior: exact cursor reads and writes return
Maybe.noneorfalseon overflow or insufficient input - ownership notes: borrows or writes caller-owned storage
Example
pub fn main(world: World) -> Void raises { var scratch: [4]u8 = [0_u8; 4] var output: [16]u8 = [0_u8; 16] var reader: FixedReader = std.io.fixedReader("one\ntwo", 0) var writer: FixedWriter = std.io.fixedWriter(output, 0) let line: Maybe<Span<u8>> = std.io.fixedReaderReadLine(&mut reader) let copied: usize = std.io.copyBuffer(&mut reader, &mut writer, scratch) if line.has && copied == 3 && std.mem.eql(std.io.fixedWriterView(&writer), "two") { check world.out.write("io ok\n") }}Design Notes
std.io is a caller-owned buffer surface, not an ambient process I/O layer.
Process stdin/stdout stay behind explicit capabilities such as World streams.