vercel-labs--zerolang/docs/articles/modules/io.md

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.none or false on 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.