File

File :: # (opaque)

Read file bytes incrementally and seek within files.

Whole-file operations and filesystem metadata are available on Path.

open_reader! : Path => Try(
    Reader,
    [
        PathErr(
            IOErr,
            Path,
        ),
    ],
)

Open a file for buffered reading using the default buffer capacity.

Failing to open reports the path, using the same PathErr as the whole-file operations so both combine in one error type.

reader = File.open_reader!("LICENSE")?
line = reader.read_line!()?

open_reader_with_capacity! : Path, U64 => Try(
    Reader,
    [
        PathErr(
            IOErr,
            Path,
        ),
    ],
)

Open a file for buffered reading using a specific buffer capacity.

SeekFrom : [Start(U64), Current(I64), End(I64)]

A byte offset from the start, current logical position, or end of a file.

Reader

File.Reader :: # (opaque)

Represents a buffered file reader.

The file is automatically closed when the last reference to the reader is dropped. It wraps an opaque host-side BufReader<File> handle. Aliases share one cursor, including bytes buffered by line or binary reads.

to_inspect : Reader -> Str

Render the reader without exposing its host handle.

read_line! : Reader => Try(List(U8), _)

Read bytes up to and including the next newline from this buffered reader.

Returns an empty list at EOF.

read_up_to! : Reader, U64 => Try(List(U8), [FileErr(IOErr)])

Read at most max_bytes bytes. Short reads are valid, even before EOF. For a positive maximum, an empty list means EOF. Zero performs no I/O. Returned bytes remain valid after later reads or seeks.

read_exactly! : Reader, U64 => Try(List(U8), [FileErr(IOErr), FileUnexpectedEOF])

Read exactly count bytes, or report FileUnexpectedEOF. Zero succeeds without I/O. Errors may consume bytes; partial data is not returned and the cursor is not restored.

position! : Reader => Try(U64, [FileErr(IOErr)])

Return the byte position of the next read, accounting for buffered bytes.

seek! : Reader, SeekFrom => Try(U64, [FileErr(IOErr)])

Move the shared cursor and return its new absolute byte position. Seeking past EOF does not extend the file. Invalid offsets and sources that cannot seek report FileErr. A failed seek need not restore the cursor. Aliases of this reader observe the same cursor.

chunks : Reader, U64 -> Try(Stream(Try(List(U8), [FileErr(IOErr)])), [InvalidChunkSize])

Lazily read nonempty chunks of at most max_bytes from this reader. Zero is rejected immediately with InvalidChunkSize. Construction does no I/O; each pull reads from the current shared cursor. Chunk boundaries do not correspond to records, newlines, or text encoding boundaries. EOF ends the stream; a read error yields one Err item, then ends. Follow the returned continuation when pulling. To resume after EOF and a seek, create a new stream. Retained chunks remain valid. The stream keeps the file open while it retains a reader. Its terminal continuation holds no reader. Process chunks individually to bound memory; Stream.collect! accumulates every chunk and does not propagate Err items.