Module: io.buffer

Source: ./io/buffer.reef

Overview

io/buffer - Buffered I/O (BufferedReader / BufferedWriter objects)

Provides buffered reading and writing with configurable buffer sizes. Default buffer size is 8KB (8192 bytes), matching modern standards.

Opens return Result[T, error.Error]: Ok(handle) on success. Read opens (open_buffered_reader(_size)) classify failures as Err(NotFound) if the path doesn't exist, Err(IoError) otherwise (see open_failure_kind). Write/append opens (open_buffered_writer(_size), open_buffered_appender) always classify failures as Err(IoError) — fopen(path, "w"/"a") never creates the file on failure, so existence-based classification can't distinguish "missing parent dir" from "permission denied"; this matches io.file's writeFile/appendFile precedent. writer_write/writer_write_line return Result[bool, error.Error] using the void-success convention (Ok(true) — never Ok(false); a write failure is always Err).

Usage: import io.buffer import core.result as result import core.option as option let reader_res = open_buffered_reader("file.txt") if result.is_ok(reader_res) let reader = result.unwrap_ok(reader_res) loop let lr = reader_read_line(reader) if result.is_err(lr) break end if let opt = result.unwrap_ok(lr) if option.is_none(opt) break end if println(option.unwrap(opt)) end loop reader_close(reader) end if

Objects

BufferedReader

Fields:

proc init()

Methods:

shared fn is_open(): bool

shared fn at_eof(): bool

exclusive proc fill_buffer()

exclusive fn read_line(): result.Result[option.Option[string], error.Error]

exclusive fn read_bytes(count: int): result.Result[option.Option[string], error.Error]

exclusive proc close()

BufferedWriter

Fields:

proc init()

Methods:

shared fn is_open(): bool

exclusive proc flush()

exclusive fn write(data: string): result.Result[bool, error.Error]

exclusive fn write_line(data: string): result.Result[bool, error.Error]

exclusive proc close()

Functions

fn default_buffer_size(): int

Default buffer size: 8KB

fn open_failure_kind(path: string): error.ErrorKind

Classifies a failed fopen() for path when opening for READING: NotFound if the path doesn't exist at all, IoError for any other reason (e.g. permission denied, or a non-directory component in the path). Mirrors io.file.open_failure_kind. Do NOT use this for write/append opens: fopen(path, "w"/"a") never creates the file on failure, so an exists()-recheck would always see the path absent and misclassify every write-open failure (including permission-denied on the parent dir) as NotFound. Write/append opens use a flat IoError instead (matching io.file's writeFile/appendFile/writeBinaryFile precedent).

fn open_buffered_reader(path: string): result.Result[BufferedReader, error.Error]

Open a file for buffered reading with default buffer size (8KB) Ok(reader) on success. Err(NotFound) if the path doesn't exist, Err(IoError) if it exists but cannot be opened for reading.

fn open_buffered_reader_size(path: string, buf_size: int): result.Result[BufferedReader, error.Error]

Open a file for buffered reading with custom buffer size Ok(reader) on success. Err(NotFound) if the path doesn't exist, Err(IoError) if it exists but cannot be opened for reading.

fn reader_is_open(r: BufferedReader): bool

fn reader_at_eof(r: BufferedReader): bool

fn reader_read_line(r: BufferedReader): result.Result[option.Option[string], error.Error]

Read a single line (up to newline or EOF), stripping trailing '\r'. Ok(Some(line)) — a line was read (may be "" for a genuinely blank line). Ok(None) — clean EOF, nothing more to read. Err(IoError) — the reader is not open, or a genuine read error occurred (reef_ferror), never conflated with EOF.

fn reader_read_bytes(r: BufferedReader, count: int): result.Result[option.Option[string], error.Error]

fn open_buffered_writer(path: string): result.Result[BufferedWriter, error.Error]

Open a file for buffered writing (truncate if exists) Ok(writer) on success. Err(IoError) on any fopen failure — write opens never leave a way to tell "missing path" from "permission denied" via exists()-recheck (fopen(path, "w") doesn't create the file on failure), so this is always IoError, never NotFound.

fn open_buffered_writer_size(path: string, buf_size: int): result.Result[BufferedWriter, error.Error]

Open a file for buffered writing with custom buffer size Ok(writer) on success. Err(IoError) on any fopen failure (see open_buffered_writer for why this is never NotFound).

fn open_buffered_appender(path: string): result.Result[BufferedWriter, error.Error]

Open a file for buffered appending Ok(writer) on success. Err(IoError) on any fopen failure (see open_buffered_writer for why this is never NotFound).

fn writer_is_open(w: BufferedWriter): bool

Check if writer is open

fn writer_write(w: BufferedWriter, data: string): result.Result[bool, error.Error]

fn writer_write_line(w: BufferedWriter, data: string): result.Result[bool, error.Error]

Procedures

proc reader_fill_buffer(r: BufferedReader)

Fill buffer from file On a zero-byte read, distinguishes clean EOF from a genuine I/O error via reef_ferror: sets is_eof for the former, had_error (sticky) for the latter.

proc reader_close(r: BufferedReader)

proc writer_flush(w: BufferedWriter)

proc writer_close(w: BufferedWriter)

Generated by reefc doc