Skip to content

stdlib.io

I/O Library

Generated from v0.60.1. 5 source files, 115 documented symbols.

buffer.xi

fn buf_reader_new(fd: Int) -> BufReader

Wrap an fd; BufReader holds the fd and an internal buffer. Params: fd - the file descriptor (FILE* as Int). Returns: a buffered reader over fd. Complexity: O(1).

  • Postcondition: result.inner == fd
fn br_read_line(r: &mut BufReader) -> Result[Str, Str]

Read one line through the buffer. Params: r - the reader. Returns: Ok(line without the trailing newline), Err on read failure. Complexity: O(n) where n is the line length.

  • Postcondition: result is Ok(_)
fn br_read_bytes(r: &mut BufReader, n: Int) -> Result[Vec[UInt8], Str]

Read exactly n bytes. Params: r - the reader; n - the byte count (clamped to >= 0). Returns: Ok(bytes read; fewer than n only at EOF), Err on read failure. Complexity: O(n).

  • Postcondition: result is Ok(_)
fn br_read_until(r: &mut BufReader, delim: UInt8) -> Result[Vec[UInt8], Str]

Read bytes up to a delimiter (inclusive). Params: r - the reader; delim - the delimiter byte. Returns: Ok(bytes including the delimiter), Err on read failure. Complexity: O(n) where n is the number of bytes read.

  • Postcondition: result is Ok(_)
fn br_peek(r: &mut BufReader, n: Int) -> Result[Vec[UInt8], Str]

Look ahead n bytes without consuming. Params: r - the reader; n - the byte count (clamped to >= 0). Returns: Ok(bytes staged in the internal buffer), Err on read failure. Complexity: O(n).

  • Postcondition: result is Ok(_)
fn br_seek(r: &mut BufReader, pos: Int)

Move the underlying read position. Params: r - the reader; pos - the byte offset from the start. Complexity: O(1) syscall.

  • Precondition: pos >= -2147483648 && pos <= 2147483647
  • Precondition: r.inner != 0
fn br_tell(r: &BufReader) -> Int

Current read position. Params: r - the reader. Returns: the byte offset of the underlying stream. Complexity: O(1) syscall.

  • Precondition: r.inner != 0
fn buf_writer_new(fd: Int) -> BufWriter

Wrap an fd; BufWriter holds the fd and an internal buffer. Params: fd - the file descriptor (FILE* as Int). Returns: a buffered writer over fd. Complexity: O(1).

  • Postcondition: result.inner == fd
fn bw_write(w: &mut BufWriter, data: &Vec[UInt8]) -> Result[Unit, Str]

Buffer bytes for writing. Params: w - the writer; data - the bytes to buffer. Returns: Ok(()) on success. Complexity: O(n) where n is the data length.

  • Postcondition: result is Ok(_)
fn bw_write_str(w: &mut BufWriter, s: Str) -> Result[Unit, Str]

Buffer a string for writing. Params: w - the writer; s - the string. Returns: Ok(()) on success. Complexity: O(n) where n is the string length.

  • Postcondition: result is Ok(_)
fn bw_flush(w: &mut BufWriter) -> Result[Unit, Str]

Flush buffered bytes to the fd. Params: w - the writer. Returns: Ok(()) on success, Err if fewer bytes than buffered were written. Complexity: O(n) where n is the buffer length.

  • Postcondition: result is Ok(_) => w.buf.len() == 0
fn bw_into_inner(w: &mut BufWriter) -> Int

Flush and return the underlying fd. Params: w - the writer (consumed). Returns: the file descriptor. Complexity: O(n) where n is the buffer length.

  • Postcondition: result == w.inner

console.xi

fn console_read_line() -> Result[Str, Str]

Read a line from standard input. Returns: Ok(line without the trailing newline), Err on EOF or failure. Complexity: O(n) where n is the line length.

  • Postcondition: result is Err(_) => result.value.len() > 0
fn console_read_char() -> Option[Char]

Read one character without echo. Returns: Some(char) read from stdin, None at EOF. Complexity: O(1).

fn console_read_key() -> Option[Char]

Read one raw key press. Returns: Some(char) for the key, None at EOF. Raw mode is not exposed by the runtime; this reads one buffered character. Complexity: O(1).

fn console_write(s: Str)

Write a string to standard output. Params: s - the string. Complexity: O(n).

  • Precondition: true
fn console_write_line(s: Str)

Write a string followed by a newline. Params: s - the string. Complexity: O(n).

  • Precondition: true
fn console_write_error(s: Str)

Write a string to standard error. Params: s - the string. Complexity: O(n).

fn console_clear()

Clear the terminal screen. Complexity: O(1) shell invocation.

  • Precondition: true
fn console_set_title(title: Str)

Set the terminal window title. Params: title - the new title. Complexity: O(1) shell invocation.

fn console_get_size() -> (Int, Int)

Terminal dimensions; tuple is (rows, cols). Returns: a documented simulation of (24, 80). Complexity: O(1).

fn console_is_tty() -> Bool

Whether standard output is an interactive terminal. Returns: false (the runtime does not expose isatty). Complexity: O(1).

  • Postcondition: result == false
fn console_password(prompt: Str) -> Result[Str, Str]

Read input without echo. Params: prompt - the prompt to display. Returns: Ok(line) without echo, Err on EOF. Complexity: O(n) where n is the line length.

  • Postcondition: result is Err(_) => result.value.len() > 0
fn console_read_until_eof() -> Result[Str, Str]

Read all remaining standard input. Returns: Ok(all bytes until EOF), Err on a read failure. Complexity: O(N) where N is the total input size.

  • Postcondition: result is Ok(_)
fn console_flush()

Flush standard output. Complexity: O(1) syscall.

  • Precondition: true

fs.xi

fn fs_read(path: Str) -> Result[Vec[UInt8], Str]

Read the whole file as bytes. Params: path - the file path. Returns: Ok(file bytes), Err on failure. Complexity: O(n) where n is the file size.

  • Postcondition: result is Err(_) => result.value.len() > 0
fn fs_write(path: Str, data: &Vec[UInt8]) -> Result[Unit, Str]

Write bytes, truncating an existing file (binary mode). Params: path - the file path; data - the bytes to write. Returns: Ok(()) on success, Err on failure. Complexity: O(n) where n is the data length.

  • Postcondition: result is Err(_) => result.value.len() > 0
fn fs_append(path: Str, data: &Vec[UInt8]) -> Result[Unit, Str]

Append bytes to a file (binary mode). Params: path - the file path; data - the bytes to append. Returns: Ok(()) on success, Err on failure. Complexity: O(n) where n is the data length.

  • Postcondition: result is Err(_) => result.value.len() > 0
fn fs_read_text(path: Str) -> Result[Str, Str]

Read a file as UTF-8 text. Params: path - the file path. Returns: Ok(file content), Err on failure. Complexity: O(n) where n is the file size.

  • Postcondition: result is Err(_) => result.value.len() > 0
fn fs_write_text(path: Str, s: Str) -> Result[Unit, Str]

Write a text string to a file. Params: path - the file path; s - the content. Returns: Ok(()) on success, Err on failure. Complexity: O(n) where n is the content length.

  • Postcondition: result is Err(_) => result.value.len() > 0
fn fs_copy(src: Str, dst: Str) -> Result[Unit, Str]

Copy a file to a new path. Params: src - the source path; dst - the destination path. Returns: Ok(()) on success, Err on failure. Complexity: O(n) where n is the source size.

  • Postcondition: result is Err(_) => result.value.len() > 0
fn fs_move(src: Str, dst: Str) -> Result[Unit, Str]

Move or rename a file. Params: src - the source path; dst - the destination path. Returns: Ok(()) on success, Err on failure. Complexity: O(1) syscall (atomic rename via the runtime shim; an existing dst is replaced, matching POSIX rename semantics on both platforms).

  • Postcondition: result is Err(_) => result.value.len() > 0
fn fs_exists(path: Str) -> Bool

Whether the path exists. Params: path - the path. Returns: true if the path can be opened for reading. Complexity: O(1).

fn fs_is_file(path: Str) -> Bool

Whether the path is a regular file. Params: path - the path. Returns: true if the path is a regular file. Complexity: O(1).

  • Postcondition: result == true => fs_exists(path)
fn fs_is_dir(path: Str) -> Bool

Whether the path is a directory. Params: path - the path. Returns: true if the path is a directory. Complexity: O(1).

  • Postcondition: result == true => fs_exists(path)
fn fs_size(path: Str) -> Result[Int, Str]

File size in bytes. Params: path - the file path. Returns: Ok(size in bytes), Err on failure. Complexity: O(1).

  • Postcondition: result is Ok(_) => result.value >= 0
  • Postcondition: result is Err(_) => result.value.len() > 0
fn fs_mtime(path: Str) -> Result[Int, Str]

Last modification time as a Unix timestamp. Params: path - the file path. Returns: Ok(mtime in seconds since the epoch), Err on failure. Complexity: O(1).

  • Postcondition: result is Err(_) => result.value.len() > 0
fn fs_read_range(path: Str, offset: Int, len: Int) -> Result[Vec[UInt8], Str]

Read len bytes starting at offset. Params: path - the file path; offset - the start offset; len - the count. Returns: Ok(bytes read; fewer only at EOF), Err on failure. Complexity: O(len).

  • Postcondition: result is Ok(_) && len >= 0 => result.value.len() <= len
  • Postcondition: result is Ok(_) && len <= 0 => result.value.len() == 0
  • Postcondition: result is Err(_) => result.value.len() > 0
fn fs_write_range(path: Str, offset: Int, data: &Vec[UInt8]) -> Result[Int, Str]

Write bytes at an offset, returning bytes written. Params: path - the file path; offset - the start offset; data - the bytes. Returns: Ok(bytes written), Err on failure. Complexity: O(n) where n is the data length.

  • Postcondition: result is Ok(_) => result.value >= 0
  • Postcondition: result is Ok(_) => result.value <= data.len()
fn fs_touch(path: Str) -> Result[Unit, Str]

Create an empty file if missing, update mtime. Params: path - the file path. Returns: Ok(()) on success, Err on failure. Complexity: O(1).

  • Postcondition: result is Err(_) => result.value.len() > 0
fn fs_temp_dir() -> Str

Return a usable temporary directory path. Returns: the system temporary directory. Complexity: O(1).

  • Postcondition: result.len() >= 0

io.xi

type IOError

=== Error type ===

Field Type
message Str
code Int

enum SeekFrom

=== SeekFrom ===

  • Start(_0: Int)
  • End(_0: Int)
  • Current(_0: Int)

fn print(msg: Str)

=== Console ===

  • Precondition: true

fn println(msg: Str)

Write a line to standard output.

  • Precondition: true

fn read_line() -> Str

Read one line from standard input (newline stripped).

  • Postcondition: result.len() >= 0

fn read_int() -> Result[Int, Str]

Read and parse an Int from standard input; Err on bad input.

fn read_float() -> Result[Float64, Str]

Read and parse a Float64 from standard input; Err on bad input.

fn parse_int(s: Str) -> Result[Int, Str]

Parse a decimal integer (optional leading +/- sign, ASCII digits only). Deterministic core of read_int, exposed for parsing without stdin.

fn parse_float(s: Str) -> Result[Float64, Str]

Parse a decimal float (optional sign, one optional '.', ASCII digits; no exponent support). Deterministic core of read_float.

fn read_file(path: Str) -> Result[Str, IOError]

=== File system ===

  • Precondition: path.len() > 0
  • Postcondition: result is Ok(_) => result.len() >= 0

fn write_file(path: Str, content: Str) -> Result[Unit, IOError]

Write (create/truncate) a file; Err with the OS message.

  • Precondition: path.len() > 0
  • Postcondition: result is Ok(_) => file_exists(path)

fn append_file(path: Str, content: Str) -> Result[Unit, IOError]

Append to a file, creating it when missing; Err.

  • Precondition: path.len() > 0
  • Postcondition: result is Ok(_) => file_exists(path)

fn file_exists(path: Str) -> Bool

True when the path exists (file or directory).

fn is_dir(path: Str) -> Bool

True when the path exists and is a directory.

fn create_dir(path: Str) -> Result[Unit, IOError]

Create a directory (with missing parents); Err on failure.

  • Precondition: path.len() > 0
  • Precondition: !file_exists(path)
  • Postcondition: result is Ok(_) => is_dir(path)

fn list_dir(path: Str) -> Result[Vec[Str], IOError]

Directory entry names, or Err with the OS message.

  • Precondition: path.len() > 0
  • Precondition: is_dir(path)
  • Postcondition: result is Ok(_) => result.len() >= 0

fn remove_file(path: Str) -> Result[Unit, IOError]

Delete a file; Err with the OS message.

  • Precondition: path.len() > 0
  • Postcondition: result is Ok(_) => !file_exists(path)

fn copy_file(src: Str, dst: Str) -> Result[Unit, IOError]

Copy a file's contents to a new path; Err.

  • Precondition: src.len() > 0
  • Precondition: dst.len() > 0
  • Precondition: src != dst
  • Precondition: file_exists(src)
  • Postcondition: result is Ok(_) => file_exists(dst)

fn rename(src: Str, dst: Str) -> Result[Unit, IOError]

Rename or move a path; Err with the OS message.

  • Precondition: src.len() > 0
  • Precondition: dst.len() > 0
  • Postcondition: result is Ok(_) => !file_exists(src) && file_exists(dst)

fn exit(code: Int)

=== Process ===

  • Precondition: code >= 0

fn args() -> Vec[Str]

Process arguments.

  • Postcondition: result.len() >= 0

fn env_var(name: Str) -> Option[Str]

Environment variable value, or None when unset.

  • Precondition: name.len() > 0

fn time_now() -> Int

=== Time ===

  • Precondition: true

fn sleep(ms: Int)

Sleep for ms milliseconds.

  • Precondition: ms >= 0

fn open(path: Str, mode: Str) -> Result[Int, IOError]

Open path with the stdio mode ("r", "w", "a", ...) and return the FILE* handle as Int -- the handle type BufReader.new and other stdio-backed APIs expect (stdin_file()/stdout_file()/stderr_file() cover the standard streams). Close with io.close when done.

  • Precondition: path.len() > 0
  • Precondition: mode.len() > 0

fn close(handle: Int) -> Result[Unit, IOError]

Close a FILE handle previously returned by io.open or the stdio _file() accessors.

  • Precondition: handle != 0

type BufReader

=== Buffered I/O ===

Field Type
inner Int
buf Vec[UInt8]

Invariants: - inner >= 0

fn new(reader: Int) -> BufReader

Wrap a file descriptor in a buffered reader.

  • Postcondition: result.inner == reader

fn read_line(self: Self, buf: &mut Str) -> Result[Int, IOError]

Read one line into buf; Ok(bytes) including the newline, 0 at EOF.

  • Precondition: inner >= 0
  • Postcondition: result is Ok(_) => result >= 0

fn lines(self: Self) -> Vec[Str]

All remaining lines (newlines stripped).

  • Postcondition: result.len() >= 0

type BufWriter

Buffered writer over a file descriptor.

Field Type
inner Int
buf Vec[UInt8]

fn new(writer: Int) -> BufWriter

Wrap a file descriptor in a buffered writer.

  • Postcondition: result.inner == writer

type Metadata

=== File metadata ===

Field Type
size Int
is_file Bool
is_dir Bool
modified Int
created Int
permissions Int

fn metadata(path: Str) -> Result[Metadata, IOError]

File metadata (size, timestamps, permissions), or Err.

  • Precondition: path.len() > 0
  • Postcondition: result is Ok(_) => result.size >= 0

fn set_permissions(path: Str, perm: Int) -> Result[Unit, IOError]

Set POSIX permission bits; Err on failure.

  • Precondition: path.len() > 0
  • Precondition: perm >= 0

fn stdin() -> Int

=== Standard streams === Numeric file descriptors (for fd-based APIs: pipe/dup/close).

  • Postcondition: result >= 0

fn stdout() -> Int

File descriptor for standard output.

  • Postcondition: result >= 0

fn stderr() -> Int

File descriptor for standard error.

  • Postcondition: result >= 0

fn stdin_file() -> Int

FILE* handle of the standard input stream.

  • Precondition: true
  • Postcondition: result != 0

fn stdout_file() -> Int

FILE* handle of the standard output stream.

  • Precondition: true
  • Postcondition: result != 0

fn stderr_file() -> Int

FILE* handle of the standard error stream.

  • Precondition: true
  • Postcondition: result != 0

type Cursor

=== Memory I/O ===

Field Type
data Vec[UInt8]
pos Int

Invariants: - pos >= 0 - pos <= data.len()

fn new(data: Vec[UInt8]) -> Cursor

In-memory cursor over a byte vector.

  • Postcondition: self.pos == 0

fn into_inner(self: Self) -> Vec[UInt8]

Consume the cursor and return its bytes.

  • Postcondition: result.len() == self.data.len()

fn join_paths(base: Str, child: Str) -> Str

=== Path operations ===

  • Postcondition: result.len() >= base.len()

fn parent_path(path: Str) -> Option[Str]

Parent directory of the path, or None.

  • Postcondition: result is Some(_) => result.value.len() > 0

fn file_name(path: Str) -> Option[Str]

Final component of the path, or None.

  • Postcondition: result is Some(_) => result.value.len() > 0

fn extension(path: Str) -> Option[Str]

Extension after the final dot of the file name, or None.

  • Postcondition: result is Some(_) => result.value.len() > 0

fn is_absolute(path: Str) -> Bool

True when the path is absolute.

fn read_line_trim() -> Str

read_line_trim reads a line from stdin and trims trailing whitespace (including \r, \n). Delegates to read_line + trim. Complexity: O(n) where n is line length.

  • Postcondition: result.len() >= 0

fn read_all_stdin() -> Str

read_all_stdin reads the entire standard input stream until EOF and returns the concatenated content. Returns "" if stdin is empty. Complexity: O(N) where N is total bytes read. Each call to read_line allocates up to 4096 bytes; memory usage peaks at ~2x input size.

  • Postcondition: result.len() >= 0

fn stdin_read_line() -> Str

stdin_read_line is an alias for read_line.

  • Postcondition: result.len() >= 0

fn flush_stdout()

flush_stdout is a no-op: the Xiom runtime does not expose fflush via externs, but stdio is line-buffered by default so explicit flushing is rarely required.

fn write_file_bytes(path: Str, data: &Vec[UInt8]) -> Result[Unit, IOError]

write_file_bytes writes raw bytes to a file, truncating if it exists. Complexity: O(n) where n = data.len().

fn read_file_bytes(path: Str) -> Result[Vec[UInt8], IOError]

read_file_bytes reads a file and returns its raw bytes. Complexity: O(n) where n = file size.

  • Postcondition: result is Ok(_) => result.len() >= 0

fn file_size(path: Str) -> Option[Int]

file_size returns the size of a file in bytes, or None if the path cannot be stated.

  • Postcondition: result is Some(_) => result.value >= 0

fn file_modified_time(path: Str) -> Option[Int]

file_modified_time returns the last modification time of a file as a Unix timestamp, or None if the path cannot be stated.

fn move_file(src: Str, dst: Str) -> Result[Unit, IOError]

move_file renames (moves) a file or directory from src to dst. Alias for rename. Complexity: O(1) OS call.

fn dir_exists(path: Str) -> Bool

dir_exists returns true if the path exists and is a directory.

fn create_dir_all(path: Str) -> Result[Unit, IOError]

create_dir_all creates the directory and all missing parent directories along the path. Returns Ok(()) on success. Complexity: O(d) where d = directory depth.

fn list_dir_recursive(path: Str) -> Result[Vec[Str], IOError]

list_dir_recursive recursively collects all file and directory paths under the given root directory. Returns the full paths relative to root. Complexity: O(N) where N = total entries.

  • Postcondition: result is Ok(_) => result.len() >= 0

fn read_file_lines(path: Str) -> Result[Vec[Str], IOError]

read_file_lines reads a file and returns its lines as a Vec[Str]. Trailing newline characters are stripped. Complexity: O(n).

  • Postcondition: result is Ok(_) => result.len() >= 0

fn write_file_lines(path: Str, lines: &Vec[Str]) -> Result[Unit, IOError]

write_file_lines writes a Vec[Str] to a file, one line per entry. Lines are separated by '\n'. Complexity: O(n).

fn append_line(path: Str, line: Str) -> Result[Unit, IOError]

append_line appends a single line (followed by '\n') to a file. If the file does not exist it will be created. Complexity: O(n) where n = line length.

pipe.xi

fn pipe_create() -> (Int, Int)

Create a pipe; tuple is (read_fd, write_fd). Returns: (read_fd, write_fd), or (-1, -1) on failure. Complexity: O(1) syscall.

fn pipe_read(fd: Int, buf: &mut Vec[UInt8]) -> Result[Int, Str]

Read available bytes into buf. Params: fd - the pipe fd; buf - the destination buffer. Returns: Ok(bytes read), Err on failure. Complexity: O(n) syscall.

  • Postcondition: result is Ok(_) => result.value >= 0
  • Postcondition: result is Err(_) => result.value.len() > 0
fn pipe_write(fd: Int, data: &Vec[UInt8]) -> Result[Int, Str]

Write bytes to the pipe. Params: fd - the pipe fd; data - the bytes. Returns: Ok(bytes written), Err on failure. Complexity: O(n) syscall.

  • Postcondition: result is Ok(_) => result.value >= 0
  • Postcondition: result is Err(_) => result.value.len() > 0
fn pipe_close(fd: Int)

Close a pipe descriptor. Params: fd - the pipe fd. Complexity: O(1) syscall.

  • Precondition: fd >= 0
fn pipe_is_open(fd: Int) -> Bool

Whether a descriptor is still valid. Params: fd - the pipe fd. Returns: true while the fd is non-negative (documented simulation). Complexity: O(1).

fn pipe_read_line(fd: Int) -> Result[Str, Str]

Read a line from a pipe. Params: fd - the pipe fd. Returns: Ok(line without the trailing newline), Err on failure. Complexity: O(n) where n is the line length.

  • Postcondition: result is Ok(_)
fn pipe_write_line(fd: Int, s: Str) -> Result[Unit, Str]

Write a line to a pipe. Params: fd - the pipe fd; s - the line. Returns: Ok(()) on success, Err on a short or failed write. Complexity: O(n) where n is the line length.

  • Postcondition: result is Err(_) => result.value.len() > 0
fn pipe_available(fd: Int) -> Int

Bytes currently buffered in the pipe. Params: fd - the pipe fd. Returns: 0 (the runtime does not expose FIONREAD). Complexity: O(1).

  • Postcondition: result >= 0
fn pipe_read_timeout(fd: Int, ms: Int) -> Result[Int, Str]

Read with a timeout, returning bytes read. Params: fd - the pipe fd; ms - the timeout in milliseconds. Returns: Ok(bytes read) even if the timeout elapsed, Err on failure. Complexity: O(ms) polls.

  • Postcondition: result is Ok(_) => result.value >= 0
  • Postcondition: result is Err(_) => result.value.len() > 0
fn pipe_write_timeout(fd: Int, data: &Vec[UInt8], ms: Int) -> Result[Int, Str]

Write with a timeout, returning bytes written. Params: fd - the pipe fd; data - the bytes; ms - the timeout. Returns: Ok(bytes written), Err on failure. Complexity: O(ms) polls.

  • Postcondition: result is Ok(_) => result.value >= 0
  • Postcondition: result is Err(_) => result.value.len() > 0