std/io
std/io — byte-stream I/O in pure Axle over libc stdio.
InputStream / OutputStream — the byte-stream contracts.
File — a path facade (no open handle).
FileInputStream / FileOutputStream — libc-FILE*-backed byte streams.
ByteArrayInputStream / …OutputStream — in-memory streams.
BufferedReader / BufferedWriter / PrintWriter — text over a file stream.
Scanner — conventional stdin reader.
Polymorphism is at the trait boundary: a fn drain(s : InputStream)
accepts any concrete stream above. Streaming only: there is no
whole-file readAll / writeAll, so a large file never has to live in
memory at once. The open mode is one of the OPEN_READ / OPEN_WRITE /OPEN_APPEND flags, never a text spelling, so I/O stays byte-exact.
Entry: the fs:: libc bindings and std/text byte bridges resolve
by cross-module use.
Exit: the classes above are declared and exported as std/io.
Free functions
| Type | Method and description |
|---|---|
| axle_libc_stdin() : ptr |
| asStream(handle : i64) : ptr View an i64 address (a stored FILE* handle, or a buffer address frombufferAddr) as the opaque ptr the fs:: bindings expect. |
| streamHandle(s : ptr) : i64 Materialise a libc FILE* ptr as the i64 handle a stream field holds. |
| clampedTo(len : i64, capacity : i64) : i64 A byte count bounded to [0, capacity] — the range a stream may treatas valid. A negative count reads as empty, and one past the buffer end reads short rather than out of bounds. ByteArrayInputStream clamps itslength with it, so every later read, skip and available inherits thebound once rather than each re-testing it. |
| copy(src : InputStream, dst : OutputStream) : i64 Stream every remaining byte from src to dst through one fixed-sizebuffer, so no more than that buffer is ever resident and a large source is copied in constant memory. Takes any pair of concrete streams. |
Method detail
#axle_libc_stdin
#asStream
View an i64 address (a stored FILE* handle, or a buffer address frombufferAddr) as the opaque ptr the fs:: bindings expect.
#streamHandle
Materialise a libc FILE* ptr as the i64 handle a stream field holds.
#clampedTo
A byte count bounded to [0, capacity] — the range a stream may treat
as valid. A negative count reads as empty, and one past the buffer end
reads short rather than out of bounds. ByteArrayInputStream clamps its
length with it, so every later read, skip and available inherits the
bound once rather than each re-testing it.
#copy
Stream every remaining byte from src to dst through one fixed-size
buffer, so no more than that buffer is ever resident and a large source
is copied in constant memory. Takes any pair of concrete streams.
src stream drained from its current position to EOFdst stream the bytes are written toIOException if either stream raises one.C class File
A File wraps a filesystem path and owns no open handle: each method
opens, operates and closes within its own scope, or hands back an open
stream the caller is responsible for closing. Content is streamed, so
there is no whole-file read/write shortcut.
Constructors
| Type | Method and description |
|---|---|
| constructor(path : string) Wrap a path; opens no handle until a method is called. |
Method detail
#constructor
Wrap a path; opens no handle until a method is called.
path filesystem path the file operations targetMethods
| Type | Method and description |
|---|---|
| exists(self) : bool Whether anything at all (file or directory) exists at this path — the answer Path::exists gives to the same path.Asked of the path's kind rather than by opening it: whether the path names something is a question about the path, and a directory answers it yes. Whether that something can be read is a later question, asked by openRead. |
| length(self) : i64 Size of the file in bytes; 0 if it cannot be opened or is non-seekable. A directory is not a file and answers 0. |
| delete(self) : void Remove the file from disk. |
| openRead(self) : FileInputStream Open the file for byte-exact reading at position 0. |
| openWrite(self) : FileOutputStream Open the file for byte-exact writing, truncating existing content. |
| openAppend(self) : FileOutputStream Open the file for byte-exact writing in append mode (creates if absent). |
| close(self) : void A path wrapper holds no open handle, so close() is a no-op thatsatisfies the Closeable contract. |
Method detail
#exists
Whether anything at all (file or directory) exists at this path — the
answer Path::exists gives to the same path.
Asked of the path's kind rather than by opening it: whether the path
names something is a question about the path, and a directory answers
it yes. Whether that something can be read is a later question, asked
by openRead.
#length
Size of the file in bytes; 0 if it cannot be opened or is
non-seekable. A directory is not a file and answers 0.
#delete
Remove the file from disk.
IOException if the file cannot be removed.#openRead
Open the file for byte-exact reading at position 0.
FileInputStream the caller must closeFileNotFoundException if the path cannot be opened.#openWrite
Open the file for byte-exact writing, truncating existing content.
FileOutputStream the caller must closeIOException if the path cannot be opened for writing.#openAppend
Open the file for byte-exact writing in append mode (creates if
absent).
FileOutputStream positioned past the last byteIOException if the path cannot be opened for appending.#close
A path wrapper holds no open handle, so close() is a no-op that
satisfies the Closeable contract.
C class FileInputStream
Byte-oriented read stream backed by a libc FILE*. ImplementsInputStream, so it can be read as text via BufferedReader.handle holds the FILE* as an i64 (0 once closed).
Constructors
| Type | Method and description |
|---|---|
| constructor(path : string) Open path for binary reading. |
Method detail
#constructor
Open path for binary reading.
path filesystem path to openFileNotFoundException if the path names no readable file.A directory is reported by that same exception with its
own message: the open fails for either, and "file not found"
about a path that is right there sends the caller looking
for the wrong thing. The kind is asked only when the open
failed.
Methods
| Type | Method and description |
|---|---|
| fromFile(file : File) : FileInputStream Open the file named by file.path for binary reading. |
| read(self) : i32 Next byte 0..255, or -1 at EOF / once closed. |
| readBytes(self, mut buf : i8[], offset : i64, len : i64) : i64 Read up to len bytes into buf[offset .. offset+len). |
| skip(self, n : i64) : i64 Skip up to n bytes forward by seeking. |
| available(self) : i64 Bytes remaining between the current position and EOF. Returns 0 when closed. |
| close(mut self) : void Close the handle; idempotent once closed. |
Method detail
#fromFile
Open the file named by file.path for binary reading.
file a File wrapper whose path is openedFileNotFoundException if the path cannot be opened.#read
Next byte 0..255, or -1 at EOF / once closed.
IOException never — the body raises nothing. fgetc answersthe EOF sentinel for a read error just as for end of file, so
a failure at this granularity is reported as -1 rather than
thrown;
readBytes is where the two are told apart (feof).The declared set mirrors the
InputStream row.#readBytes
Read up to len bytes into buf[offset .. offset+len).
buf destination bufferoffset first destination indexlen maximum bytes to readIOException if the stream is closed or a read error occurs.#skip
Skip up to n bytes forward by seeking.
n maximum bytes to skipIOException if the stream is closed.#available
Bytes remaining between the current position and EOF.
Returns 0 when closed.
#close
Close the handle; idempotent once closed.
C class FileOutputStream
Byte-oriented write stream backed by a libc FILE*. ImplementsOutputStream, so it can be written as text via PrintWriter.handle holds the FILE* as an i64 (0 once closed).
Constructors
| Type | Method and description |
|---|---|
| constructor(path : string, mode : FileOpenMode) Open path for binary writing. |
Method detail
#constructor
Open path for binary writing.
path filesystem path to openmode FileOpenMode::APPEND writes past the end;any other mode truncates
IOException if the path cannot be opened.Methods
| Type | Method and description |
|---|---|
| fromFile(file : File) : FileOutputStream Open the file named by file.path for binary writing (truncate). |
| write(self, b : i32) : void Write the low 8 bits of b as one byte. |
| writeBytes(self, buf : i8[], offset : i64, len : i64) : void Write buf[offset .. offset+len) to the stream. |
| flush(self) : void Flush libc's buffer to disk. |
| close(mut self) : void Flush then close the handle; idempotent once closed. |
Method detail
#fromFile
Open the file named by file.path for binary writing (truncate).
file a File wrapper whose path is openedIOException if the path cannot be opened.#write
Write the low 8 bits of b as one byte.
b source value; only its low 8 bits are emittedIOException if the stream is closed.#writeBytes
Write buf[offset .. offset+len) to the stream.
buf source bufferoffset first source indexlen number of bytes to writeIOException if the stream is closed or a partial write occurs.#flush
Flush libc's buffer to disk.
#close
Flush then close the handle; idempotent once closed.
C class ByteArrayInputStream
In-memory read stream over an i8[] buffer. Pure Axle — no OS
handle. read() returns -1 at EOF without throwing (the -1 sentinel
matches the fgetc convention).
Fields: data is the backing buffer; cursor is the next-read
index; len is the number of valid bytes in data.
Constructors
| Type | Method and description |
|---|---|
| constructor(data : i8[], len : i64) Wrap data treating the first len bytes as the stream content. |
Method detail
#constructor
Wrap data treating the first len bytes as the stream content.
data backing buffer; not copied — the stream takes it andreleases it, so the caller's binding ends here
len number of valid bytes in data; a count past thebuffer end is clamped to it, so a miscount reads short
rather than out of bounds
Methods
| Type | Method and description |
|---|---|
| fromString(s : string) : ByteArrayInputStream Build a ByteArrayInputStream from a string's byte content.The bytes are copied into a fresh i8[] so the source stringcan be freed independently. |
| read(mut self) : i32 Next byte 0..255, or -1 at end of data (no throw). |
| readBytes(mut self, mut buf : i8[], offset : i64, len : i64) : i64 Copy up to len bytes into buf[offset .. offset+len). |
| skip(mut self, n : i64) : i64 Advance the cursor up to n bytes. |
| available(self) : i64 Bytes remaining between the cursor and the end of the buffer. Returns 0 at EOF. |
| reset(mut self) : void Rewind the cursor to byte 0. |
| close(self) : void No-op: no OS handle to release. |
Method detail
#fromString
Build a ByteArrayInputStream from a string's byte content.
The bytes are copied into a fresh i8[] so the source string
can be freed independently.
s source string; its bytes become the stream content#read
Next byte 0..255, or -1 at end of data (no throw).
#readBytes
Copy up to len bytes into buf[offset .. offset+len).
buf destination bufferoffset first destination indexlen maximum bytes to copylen is 0)IOException if the window reaches past buf, which is acaller miscount rather than a stream condition and so is
refused as the file streams refuse it.
#skip
Advance the cursor up to n bytes.
n maximum bytes to skipIOException never — present to satisfy the trait.#available
Bytes remaining between the cursor and the end of the buffer.
Returns 0 at EOF.
#reset
Rewind the cursor to byte 0.
#close
No-op: no OS handle to release.
C class ByteArrayOutputStream
In-memory write stream backed by a growable i8[]. Pure Axle — no
OS handle.buf is the backing store; len counts bytes written so far; cap
is the allocated capacity. __grow doubles capacity until the new
minimum fits. toByteArray / toString materialise the written
content; reset resets the write cursor without freeing the buffer.
Constructors
| Type | Method and description |
|---|---|
| constructor() Start with a 16-byte initial capacity; the buffer grows on demand. |
Method detail
#constructor
Start with a 16-byte initial capacity; the buffer grows on demand.
Methods
| Type | Method and description |
|---|---|
| write(mut self, b : i32) : void Append the low 8 bits of b as one byte. |
| writeBytes(mut self, buf : i8[], offset : i64, len : i64) : void Append buf[offset .. offset+len) to the stream. |
| flush(self) : void No-op: in-memory; nothing to flush to an OS sink. |
| close(self) : void No-op: no OS handle; the backing buffer is freed with the object. |
| toByteArray(self) : i8[] Copy the written bytes into a fresh i8[]. |
| toString(self) : string Materialise the written bytes as an owned UTF-8 string.The backing store is handed to the seam directly: bytesToStringcopies into a fresh allocation of its own, so an intermediate array would only add a second allocation and a second pass over the bytes. |
| size(self) : i64 Bytes written so far. |
| reset(mut self) : void Discard written bytes; keep the allocated capacity. |
Method detail
#write
Append the low 8 bits of b as one byte.
b source value; only its low 8 bits are appendedIOException never — present to satisfy the trait.#writeBytes
Append buf[offset .. offset+len) to the stream.
buf source bufferoffset first source indexlen number of bytes to copy inIOException if the window reaches past buf, which is acaller miscount rather than a stream condition and so is
refused as the file streams refuse it.
#flush
No-op: in-memory; nothing to flush to an OS sink.
#close
No-op: no OS handle; the backing buffer is freed with the object.
#toByteArray
Copy the written bytes into a fresh i8[].
0 .. len-1#toString
Materialise the written bytes as an owned UTF-8 string.
The backing store is handed to the seam directly: bytesToString
copies into a fresh allocation of its own, so an intermediate array
would only add a second allocation and a second pass over the bytes.
0 .. len-1#size
Bytes written so far.
reset#reset
Discard written bytes; keep the allocated capacity.
C class BufferedReader
Line-oriented text reader over a FileInputStream. The usual pattern
is new BufferedReader(new FileInputStream(path)); the reader steals
the source stream's handle, leaving the source inert.
The bytes arrive a block at a time into buf; pos indexes the next
byte still unread in it and filled counts the bytes the last refill
actually produced, so the block's valid window is buf[pos .. filled).
Constructors
| Type | Method and description |
|---|---|
| constructor(input : FileInputStream) Take ownership of input's open handle. input is left inert andmust not be used afterwards. |
Method detail
#constructor
Take ownership of input's open handle. input is left inert and
must not be used afterwards.
input source stream whose open handle is taken overMethods
| Type | Method and description |
|---|---|
| open(path : string) : BufferedReader Open path for line-oriented reading directly, without a separateFileInputStream. The usual one-liner. |
| hasMoreLines(mut self) : bool Whether another byte is available before EOF, without consuming it. |
| readLine(mut self) : string Read one line (up to but excluding '\n'); "" at EOF. A '\r' immediately followed by '\n' is a CRLF terminator and is dropped; a lone '\r' is line content, as is a '\r' that ends the file. |
| close(mut self) : void Close the handle; idempotent once closed. |
Method detail
#open
Open path for line-oriented reading directly, without a separateFileInputStream. The usual one-liner.
path filesystem path to open for readingFileNotFoundException if the path cannot be opened.#hasMoreLines
Whether another byte is available before EOF, without consuming it.
#readLine
Read one line (up to but excluding '\n'); "" at EOF. A '\r'
immediately followed by '\n' is a CRLF terminator and is dropped;
a lone '\r' is line content, as is a '\r' that ends the file.
IOException never — carried because hasMoreLines and thisshare a refill that cannot distinguish a read error from EOF,
so a failed read answers "" rather than throwing.
#close
Close the handle; idempotent once closed.
C class BufferedWriter
Text writer over a FileOutputStream. The usual pattern isnew BufferedWriter(new FileOutputStream(path, FileOpenMode::WRITE));
the writer steals the source stream's handle, leaving the source inert.
Constructors
| Type | Method and description |
|---|---|
| constructor(output : FileOutputStream) Take ownership of output's open handle. output is left inertand must not be used afterwards. |
Method detail
#constructor
Take ownership of output's open handle. output is left inert
and must not be used afterwards.
output source stream whose open handle is taken overMethods
| Type | Method and description |
|---|---|
| write(self, content : string) : void Write content verbatim, with no trailing newline. |
| writeLine(self, content : string) : void Write content followed by a '\n'. |
| flush(self) : void Flush libc's buffer to disk. |
| close(mut self) : void Flush then close the handle; idempotent once closed. |
Method detail
#write
Write content verbatim, with no trailing newline.
content text written verbatim to the streamIOException if the stream is closed.#writeLine
Write content followed by a '\n'.
content text written before the appended newlineIOException if the stream is closed.#flush
Flush libc's buffer to disk.
#close
Flush then close the handle; idempotent once closed.
C class PrintWriter
Print-style text writer over a FileOutputStream — the file-output
sibling of Console. Constructed like BufferedWriter, stealing the
source stream's handle.
Constructors
| Type | Method and description |
|---|---|
| constructor(output : FileOutputStream) Take ownership of output's open handle. output is left inertand must not be used afterwards. |
Method detail
#constructor
Take ownership of output's open handle. output is left inert
and must not be used afterwards.
output source stream whose open handle is taken overMethods
| Type | Method and description |
|---|---|
| print(self, text : string) : void Write text verbatim, with no trailing newline. |
| println(self, text : string) : void Write text followed by a '\n'. |
| printf(self, format : string) : void No varargs: writes the format string verbatim (the file-output sibling of Console::print). |
| flush(self) : void Flush libc's buffer to disk without closing. |
| close(mut self) : void Flush then close the handle; idempotent once closed. |
Method detail
Write text verbatim, with no trailing newline.
text text written verbatim to the streamIOException if the stream is closed.#println
Write text followed by a '\n'.
text text written before the appended newlineIOException if the stream is closed.#printf
No varargs: writes the format string verbatim (the file-output
sibling of Console::print).
format format string written verbatim; no substitutionIOException if the stream is closed.#flush
Flush libc's buffer to disk without closing.
#close
Flush then close the handle; idempotent once closed.
C class Scanner
Conventional stdin reader over the libc stdin FILE*. One Scanner
per program is the usual shape; the default ctor binds to the
process stdin handle. A one-byte pushback slot (peeked) letshasNextLine look ahead for EOF without consuming the byte the next
read must return.
Constructors
| Type | Method and description |
|---|---|
| constructor() Bind to the process-wide stdin handle with an empty pushback. |
Method detail
#constructor
Bind to the process-wide stdin handle with an empty pushback.
Methods
| Type | Method and description |
|---|---|
| nextLine(mut self) : string Read the next line (excluding the terminator); "" at EOF. A trailing CR is dropped so a CRLF terminator chomps cleanly. |
| hasNextLine(mut self) : bool Whether another line is available before EOF. Peeks one byte into the pushback slot so the following read still returns it. |
| nextI32(mut self) : i32 Read the next line and parse it as a base-10 i32. |
| nextI64(mut self) : i64 Read the next line and parse it as a base-10 i64. |
| nextF64(mut self) : f64 Read the next line and parse it as an IEEE-754 f64. |
| close(mut self) : void Release the scanner. The process-wide stdin handle is shared, soclose() does not fclose it; it only marks this Scanner inert. |
Method detail
#nextLine
Read the next line (excluding the terminator); "" at EOF. A
trailing CR is dropped so a CRLF terminator chomps cleanly.
IOException if the scanner has been closed.#hasNextLine
Whether another line is available before EOF. Peeks one byte into
the pushback slot so the following read still returns it.
#nextI32
Read the next line and parse it as a base-10 i32.
IOException if input is exhausted before a line is read.ParseException if the line is not a valid integer.#nextI64
Read the next line and parse it as a base-10 i64.
IOException if input is exhausted before a line is read.ParseException if the line is not a valid integer.#nextF64
Read the next line and parse it as an IEEE-754 f64.
IOException if input is exhausted before a line is read.ParseException if the line is not a valid number.#close
Release the scanner. The process-wide stdin handle is shared, soclose() does not fclose it; it only marks this Scanner inert.
T trait InputStream
Byte-oriented readable stream. Extends Closeable so atry-with-resources pattern closes the stream on exit.read() returns the next byte as 0..255, or -1 at EOF; the i32
return type is intentional — a signed i8 cannot distinguish -1
(EOF) from byte 0xFF. readBytes bulk-reads into a caller-suppliedi8[] slice [offset, offset+len), returning the count read or -1 at
EOF. skip advances the position by up to n bytes. available is a
non-blocking lower bound on bytes readable without blocking.
| Type | Method and description |
|---|---|
| read(self) : i32 Next byte 0..255, or -1 at EOF. |
| readBytes(self, mut buf : i8[], offset : i64, len : i64) : i64 Read up to len bytes into buf[offset .. offset+len). |
| skip(self, n : i64) : i64 Skip up to n bytes forward in the stream. |
| available(self) : i64 Lower bound on bytes readable without blocking. Returns 0 when the stream is closed or at EOF. |
| close(self) : void Release the stream. Idempotent. Redeclared from Closeable so apolymorphic stream.close() dispatches against InputStream'sown contract row. |
Method detail
#read
Next byte 0..255, or -1 at EOF.
#readBytes
Read up to len bytes into buf[offset .. offset+len).
buf destination bufferoffset first destination indexlen maximum bytes to read#skip
Skip up to n bytes forward in the stream.
n maximum bytes to skip#available
Lower bound on bytes readable without blocking.
Returns 0 when the stream is closed or at EOF.
#close
Release the stream. Idempotent. Redeclared from Closeable so a
polymorphic stream.close() dispatches against InputStream's
own contract row.
T trait OutputStream
Byte-oriented writable stream. Extends Closeable so atry-with-resources pattern closes the stream on exit.write(b) emits the low 8 bits of b. writeBytes bulk-writes from
a caller-supplied i8[] slice [offset, offset+len). flush pushes
any libc or in-memory buffer to the underlying sink.
| Type | Method and description |
|---|---|
| write(self, b : i32) : void Write the low 8 bits of b as one byte. |
| writeBytes(self, buf : i8[], offset : i64, len : i64) : void Write buf[offset .. offset+len) to the stream. |
| flush(self) : void Flush any buffered bytes to the underlying sink. |
| close(self) : void Release the stream. Idempotent. Redeclared from Closeable so apolymorphic stream.close() dispatches against OutputStream'sown contract row. |
Method detail
#write
Write the low 8 bits of b as one byte.
b source value; only its low 8 bits are emitted#writeBytes
Write buf[offset .. offset+len) to the stream.
buf source bufferoffset first source indexlen number of bytes to write#flush
Flush any buffered bytes to the underlying sink.
#close
Release the stream. Idempotent. Redeclared from Closeable so a
polymorphic stream.close() dispatches against OutputStream's
own contract row.