Zero-copy I/O core: memfile-backed inputs, reusable outputs.

Replaces streams throughout the library. Input is a read cursor over either a memory-mapped file (zero-copy, no read syscalls, no buffer copies) or an owned/shared string. Output is a reusable growable buffer: pass the same Output across calls and reset it to avoid repeated allocation. Span is a borrowed pointer+length view, valid only while its parent Input/Output lives.

Types

Input = ref object of RootObj: Read cursor. One of str (string-backed) or map (mmap-backed) keeps the memory alive; keep extends that to derived views (e.g. Output converted via toInput).
IoError = object of CatchableError
MapHandle = ref object size*: int: Owns a read-only file mapping. Closed idempotently.
Output = ref object of RootObj len*: int: Reusable write buffer. buf may over-allocate; len is used.
Span = object p*: pointer len*: int: Borrowed view into Input/Output memory. Copy is a memcpy; the parent must outlive any use.

Procs

proc advance(dst: Output; n: int) {....raises: [IoError], tags: [], forbids: [].}: Commit n bytes written via reserve.
proc basePointer(inp: Input): pointer {....raises: [], tags: [], forbids: [].}
proc byteAt(inp: Input; off: int): byte {....raises: [IoError], tags: [], forbids: [].}
proc close(inp: Input) {....raises: [], tags: [], forbids: [].}: Release the mapping/string reference. Idempotent.
proc closeMap(h: MapHandle) {....raises: [], tags: [], forbids: [].}
proc inputLen(inp: Input): int {....raises: [], tags: [], forbids: [].}
proc inputPos(inp: Input): int {....raises: [], tags: [], forbids: [].}
proc newOutput(cap = 0): Output {....raises: [], tags: [], forbids: [].}
proc openInputBytes(data: openArray[byte]): Input {....raises: [], tags: [], forbids: [].}
proc openInputCopy(p: pointer; length: int): Input {....raises: [], tags: [], forbids: [].}: Input owning a copy of [p, p+length).
proc openInputFile(path: string): Input {....raises: [IOError, OSError], tags: [], forbids: [].}: Zero-copy input over a memory-mapped file.
proc openInputString(s: string): Input {....raises: [], tags: [], forbids: [].}: Input sharing s (no copy; string is refcounted).
proc openInputView(s: Span; keep: RootRef): Input {....raises: [], tags: [], forbids: [].}: Input borrowing a span; keep (usually the parent Input/Output) is retained so the memory outlives this cursor.
proc openMap(path: string): MapHandle {....raises: [IOError, OSError], tags: [], forbids: [].}: Memory-map a file read-only. Empty files map to size 0 (no mmap).
proc outputBytes(dst: Output): Span {....raises: [], tags: [], forbids: [].}: Borrowed view of used bytes.
proc peek(inp: Input; n: int): Span {....raises: [], tags: [], forbids: [].}: Borrowed view of up to n bytes at the cursor (no advance).
proc readAll(inp: Input): string {....raises: [], tags: [], forbids: [].}
proc readByte(inp: Input): byte {....raises: [IoError], tags: [], forbids: [].}
proc readBytes(inp: Input; n: int): string {....raises: [], tags: [], forbids: [].}: Copying read.
proc readSpan(inp: Input; n: int): Span {....raises: [], tags: [], forbids: [].}: Borrowed view of up to n bytes, advancing the cursor.
proc remaining(inp: Input): int {....raises: [], tags: [], forbids: [].}
proc reserve(dst: Output; additional: int): pointer {....raises: [], tags: [], forbids: [].}: Ensure room for additional bytes, return the write pointer at dst.len. Caller must call advance after filling. The pointer is valid only until the next growing operation.
proc reset(dst: Output) {....raises: [], tags: [], forbids: [].}: Reuse the buffer without freeing capacity.
proc seek(inp: Input; pos: int) {....raises: [IoError], tags: [], forbids: [].}
proc skip(inp: Input; n: int) {....raises: [IoError], tags: [], forbids: [].}
proc spanAt(inp: Input; off, n: int): Span {....raises: [IoError], tags: [], forbids: [].}: Borrowed absolute view (bounds-checked).
proc spanEqual(a: Span; s: string): bool {....raises: [], tags: [], forbids: [].}
proc spanLen(s: Span): int {....raises: [], tags: [], forbids: [].}
proc spanToString(s: Span): string {....raises: [], tags: [], forbids: [].}
proc take(dst: Output): string {....raises: [], tags: [], forbids: [].}: Move the used bytes dst as an exact-size string, reusing capacity.
proc toInput(dst: Output): Input {....raises: [], tags: [], forbids: [].}: Zero-copy read view over an Output's used bytes.
proc u16le(s: Span; off: int): int {....raises: [], tags: [], forbids: [].}
proc u32le(s: Span; off: int): uint32 {....raises: [], tags: [], forbids: [].}
proc writeByte(dst: Output; c: char | byte)
proc writeBytes(dst: Output; p: pointer; n: int) {....raises: [], tags: [], forbids: [].}
proc writeStr(dst: Output; s: string) {....raises: [], tags: [], forbids: [].}

archive/io

Types

Procs