Package

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
`ptr`	axle_libc_stdin() : ptr
`ptr`	asStream(handle : i64) : ptr View an `i64` address (a stored FILE* handle, or a buffer address from `bufferAddr`) as the opaque `ptr` the `fs::` bindings expect.
`i64`	streamHandle(s : ptr) : i64 Materialise a libc `FILE*` `ptr` as the `i64` handle a stream field holds.
`i64`	clampedTo(len : i64, capacity : i64) : i64 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.
`i64`	copy(src : InputStream, dst : OutputStream) : i64 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.

Method detail

#axle_libc_stdin

axle_libc_stdin() : ptr

#asStream

asStream(handle : i64) : ptr

View an i64 address (a stored FILE* handle, or a buffer address from
bufferAddr) as the opaque ptr the fs:: bindings expect.

#streamHandle

streamHandle(s : ptr) : i64

Materialise a libc FILE* ptr as the i64 handle a stream field holds.

#clampedTo

clampedTo(len : i64, capacity : i64) : i64

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

copy(src : InputStream, dst : OutputStream) : i64 ! IOException

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.

Parameters

src stream drained from its current position to EOF

dst stream the bytes are written to

Returns total bytes copied

Throws

IOException 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

constructor(path : string)

Wrap a path; opens no handle until a method is called.

Parameters

path filesystem path the file operations target

Methods

Type	Method and description
`bool`	exists(self) : bool
`i64`	length(self) : i64
`void`	delete(self) : void
`FileInputStream`	openRead(self) : FileInputStream
`FileOutputStream`	openWrite(self) : FileOutputStream
`FileOutputStream`	openAppend(self) : FileOutputStream
`void`	close(self) : void

Method detail

#exists

exists(self) : bool

#length

length(self) : i64

#delete

delete(self) : void ! IOException

#openRead

openRead(self) : FileInputStream ! FileNotFoundException

#openWrite

openWrite(self) : FileOutputStream ! IOException

#openAppend

openAppend(self) : FileOutputStream ! IOException

#close

close(self) : void ! IOException

C class FileInputStream

Byte-oriented read stream backed by a libc FILE*. Implements
InputStream, so it can be read as text via BufferedReader.

handle holds the FILE* as an i64 (0 once closed). Async reads
offload the blocking call to a worker thread.

Constructors

Type	Method and description
	constructor(path : string) Open `path` for binary reading.

Method detail

#constructor

constructor(path : string) ! FileNotFoundException

Open path for binary reading.

Parameters

path filesystem path to open

Throws

FileNotFoundException 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
`FileInputStream`	fromFile(file : File) : FileInputStream
`i32`	read(self) : i32
`i64`	readBytes(self, buf : i8[], offset : i64, len : i64) : i64
`i64`	skip(self, n : i64) : i64
`i64`	available(self) : i64
`void`	close(mut self) : void

Method detail

#fromFile

fromFile(file : File) : FileInputStream ! FileNotFoundException

#read

read(self) : i32 ! IOException

#readBytes

readBytes(self, buf : i8[], offset : i64, len : i64) : i64 ! IOException

#skip

skip(self, n : i64) : i64 ! IOException

#available

available(self) : i64

#close

close(mut self) : void ! IOException

C class FileOutputStream

Byte-oriented write stream backed by a libc FILE*. Implements
OutputStream, 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

constructor(path : string, mode : FileOpenMode) ! IOException

Open path for binary writing.

Parameters

path filesystem path to open

mode FileOpenMode::APPEND writes past the end;
any other mode truncates

Throws

IOException if the path cannot be opened.

Methods

Type	Method and description
`FileOutputStream`	fromFile(file : File) : FileOutputStream
`void`	write(self, b : i32) : void
`void`	writeBytes(self, buf : i8[], offset : i64, len : i64) : void
`void`	flush(self) : void
`void`	close(mut self) : void

Method detail

#fromFile

fromFile(file : File) : FileOutputStream ! IOException

#write

write(self, b : i32) : void ! IOException

#writeBytes

writeBytes(self, buf : i8[], offset : i64, len : i64) : void ! IOException

#flush

flush(self) : void ! IOException

#close

close(mut self) : void ! IOException

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

constructor(data : i8[], len : i64)

Wrap data treating the first len bytes as the stream content.

Parameters

data backing buffer; not copied — caller must not mutate it

len number of valid bytes in data; a count past the
buffer end is clamped to it, so a miscount reads short
rather than out of bounds

Methods

Type	Method and description
`ByteArrayInputStream`	fromString(s : string) : ByteArrayInputStream
`i32`	read(mut self) : i32
`i64`	readBytes(mut self, buf : i8[], offset : i64, len : i64) : i64
`i64`	skip(mut self, n : i64) : i64
`i64`	available(self) : i64
`void`	reset(mut self) : void
`void`	close(self) : void

Method detail

#fromString

fromString(s : string) : ByteArrayInputStream

#read

read(mut self) : i32 ! IOException

#readBytes

readBytes(mut self, buf : i8[], offset : i64, len : i64) : i64 ! IOException

#skip

skip(mut self, n : i64) : i64 ! IOException

#available

available(self) : i64

#reset

reset(mut self) : void

#close

close(self) : void ! IOException

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

constructor()

Start with a 16-byte initial capacity; the buffer grows on demand.

Methods

Type	Method and description
`void`	write(mut self, b : i32) : void
`void`	writeBytes(mut self, buf : i8[], offset : i64, len : i64) : void
`void`	flush(self) : void
`void`	close(self) : void
`i8[]`	toByteArray(self) : i8[]
`string`	toString(self) : string
`i64`	size(self) : i64
`void`	reset(mut self) : void

Method detail

#write

write(mut self, b : i32) : void ! IOException

#writeBytes

writeBytes(mut self, buf : i8[], offset : i64, len : i64) : void ! IOException

#flush

flush(self) : void ! IOException

#close

close(self) : void ! IOException

#toByteArray

toByteArray(self) : i8[]

#toString

toString(self) : string

#size

size(self) : i64

#reset

reset(mut self) : void

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 and must not be used afterwards.

Method detail

#constructor

constructor(input : FileInputStream)

Take ownership of input's open handle. input is left inert and
must not be used afterwards.

Parameters

input source stream whose open handle is taken over

Methods

Type	Method and description
`BufferedReader`	open(path : string) : BufferedReader
`bool`	hasMoreLines(mut self) : bool
`string`	readLine(mut self) : string
`void`	close(mut self) : void

Method detail

#open

open(path : string) : BufferedReader ! FileNotFoundException

#hasMoreLines

hasMoreLines(mut self) : bool

#readLine

readLine(mut self) : string ! IOException

#close

close(mut self) : void ! IOException

C class BufferedWriter

Text writer over a FileOutputStream. The usual pattern is
new 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 inert and must not be used afterwards.

Method detail

#constructor

constructor(output : FileOutputStream)

Take ownership of output's open handle. output is left inert
and must not be used afterwards.

Parameters

output source stream whose open handle is taken over

Methods

Type	Method and description
`void`	write(self, content : string) : void
`void`	writeLine(self, content : string) : void
`void`	flush(self) : void
`void`	close(mut self) : void

Method detail

#write

write(self, content : string) : void ! IOException

#writeLine

writeLine(self, content : string) : void ! IOException

#flush

flush(self) : void ! IOException

#close

close(mut self) : void ! IOException

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 inert and must not be used afterwards.

Method detail

#constructor

constructor(output : FileOutputStream)

Take ownership of output's open handle. output is left inert
and must not be used afterwards.

Parameters

output source stream whose open handle is taken over

Methods

Type	Method and description
`void`	print(self, text : string) : void
`void`	println(self, text : string) : void
`void`	printf(self, format : string) : void
`void`	flush(self) : void
`void`	close(mut self) : void

Method detail

#print

print(self, text : string) : void ! IOException

#println

println(self, text : string) : void ! IOException

#printf

printf(self, format : string) : void ! IOException

#flush

flush(self) : void ! IOException

#close

close(mut self) : void ! IOException

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) lets
hasNextLine 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

constructor()

Bind to the process-wide stdin handle with an empty pushback.

Methods

Type	Method and description
`string`	nextLine(self) : string
`bool`	hasNextLine(mut self) : bool
`i32`	nextI32(self) : i32
`i64`	nextI64(self) : i64
`f64`	nextF64(self) : f64
`void`	close(mut self) : void

Method detail

#nextLine

nextLine(self) : string ! IOException

#hasNextLine

hasNextLine(mut self) : bool

#nextI32

nextI32(self) : i32 ! IOException, ParseException

#nextI64

nextI64(self) : i64 ! IOException, ParseException

#nextF64

nextF64(self) : f64 ! IOException, ParseException

#close

close(mut self) : void ! IOException

T trait InputStream

Byte-oriented readable stream. Extends Closeable so a
try-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-supplied
i8[] 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
`i32`	read(self) : i32 Next byte 0..255, or -1 at EOF.
`i64`	readBytes(self, buf : i8[], offset : i64, len : i64) : i64 Read up to `len` bytes into `buf[offset .. offset+len)`.
`i64`	skip(self, n : i64) : i64 Skip up to `n` bytes forward in the stream.
`i64`	available(self) : i64 Lower bound on bytes readable without blocking. Returns 0 when the stream is closed or at EOF.
`void`	close(self) : void Release the stream. Idempotent. Redeclared from `Closeable` so a polymorphic `stream.close()` dispatches against `InputStream`'s own contract row.

Method detail

#read

read(self) : i32 ! IOException

Next byte 0..255, or -1 at EOF.

#readBytes

readBytes(self, buf : i8[], offset : i64, len : i64) : i64 ! IOException

Read up to len bytes into buf[offset .. offset+len).

Parameters

buf destination buffer

offset first destination index

len maximum bytes to read

Returns bytes read, or -1 at EOF

#skip

skip(self, n : i64) : i64 ! IOException

Skip up to n bytes forward in the stream.

Parameters

n maximum bytes to skip

Returns bytes actually skipped

#available

available(self) : i64

Lower bound on bytes readable without blocking.
Returns 0 when the stream is closed or at EOF.

#close

close(self) : void ! IOException

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 a
try-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
`void`	write(self, b : i32) : void Write the low 8 bits of `b` as one byte.
`void`	writeBytes(self, buf : i8[], offset : i64, len : i64) : void Write `buf[offset .. offset+len)` to the stream.
`void`	flush(self) : void Flush any buffered bytes to the underlying sink.
`void`	close(self) : void Release the stream. Idempotent. Redeclared from `Closeable` so a polymorphic `stream.close()` dispatches against `OutputStream`'s own contract row.

Method detail

#write

write(self, b : i32) : void ! IOException

Write the low 8 bits of b as one byte.

Parameters

b source value; only its low 8 bits are emitted

#writeBytes

writeBytes(self, buf : i8[], offset : i64, len : i64) : void ! IOException

Write buf[offset .. offset+len) to the stream.

Parameters

buf source buffer

offset first source index

len number of bytes to write

#flush

flush(self) : void ! IOException

Flush any buffered bytes to the underlying sink.

#close

close(self) : void ! IOException

Release the stream. Idempotent. Redeclared from Closeable so a
polymorphic stream.close() dispatches against OutputStream's
own contract row.