std.io.stream

File alias

pub type File = int

An open file. Opaque: it is issued by open, create or openAppend, never assembled.

stdlib/std/io/stream.lyr:41

open function

pub fn open(path: string): ?File

Opens an existing file for reading. null when it does not exist or cannot be read — openOrThrow says which.

stdlib/std/io/stream.lyr:80

openOrThrow function

pub fn openOrThrow(path: string): File throws IoError

open, with the reason when the file will not open.

stdlib/std/io/stream.lyr:85

create function

pub fn create(path: string): ?File

Opens a file for writing, creating it or TRUNCATING what is there. null when the path is not writable.

stdlib/std/io/stream.lyr:95

createOrThrow function

pub fn createOrThrow(path: string): File throws IoError

create, with the reason when the file will not open.

stdlib/std/io/stream.lyr:100

openAppend function

pub fn openAppend(path: string): ?File

Opens a file for writing at its END, creating it when it does not exist.

stdlib/std/io/stream.lyr:109

openAppendOrThrow function

pub fn openAppendOrThrow(path: string): File throws IoError

openAppend, with the reason when the file will not open.

stdlib/std/io/stream.lyr:114

readSome function

pub fn readSome(file: File, max: int): ?uint8[]

Reads up to max bytes, waiting for them. Three truths in one answer, the 2.14 convention std.io.net and std.process also speak: bytes are bytes, an EMPTY array is the end of the file, and null is a failure — readSomeOrThrow says which.

Fewer than max bytes is an ordinary answer; call again until the empty array. A max of zero or less PANICS: an empty answer already means the end of the file, so there is no honest value to hand back for it.

Yields while the read is outstanding, so it needs a running std.task.run().

stdlib/std/io/stream.lyr:131

readSomeOrThrow function

pub fn readSomeOrThrow(file: File, max: int): uint8[] throws IoError

readSome, with the reason when the read failed. The end of the file stays the empty array.

stdlib/std/io/stream.lyr:148

write function

pub fn write(file: File, bytes: uint8[]): bool

Writes bytes and waits for them to land. false when the write failed — writeOrThrow says why.

The answer is the OUTCOME, not the handover: a queued write could not report a full disk at the call, and for a file that is the answer that matters. std.process queues its writes for the opposite reason — a child that reads slowly must not stall its writer.

Yields while the write is outstanding, so it needs a running std.task.run().

stdlib/std/io/stream.lyr:164

writeOrThrow function

pub fn writeOrThrow(file: File, bytes: uint8[]): void throws IoError

write, with the reason when it failed.

stdlib/std/io/stream.lyr:178

close function

pub fn close(file: File): void

Closes the handle and releases the notify descriptor. Closing twice closes once. A read or write still outstanding is abandoned, not awaited.

stdlib/std/io/stream.lyr:186

LineReader class

pub class LineReader :: [Iterator<string>]

The lines of an open file, walked as they are read — the shape a file too large to hold needs. Terminators are removed, and a carriage return before the newline goes with it, so CRLF and LF read alike.

It is an Iterator<string>, so the adapters chain onto it. That protocol spends null on "the end", which means a read FAILURE and the end of the file look the same from next() alone — ask failed() after the walk when the difference matters.

Every step may yield, so a walk needs a running std.task.run().

source: File

The open file being walked.

pending: uint8[]

Bytes read and not yet handed out as a line.

at: int

The first unconsumed byte of pending; a cursor rather than a re-slice per line, so a chunk full of short lines costs one copy instead of one per line.

ended: bool

Whether the file has no more bytes to give.

broke: bool

Whether the walk stopped on a failure rather than on the end.

pub mut fn next(): ?string

The next line, or null at the end of the file — and at a failure, which failed() tells apart.

pub fn failed(): bool

Whether the walk ended because a read failed. false after an ordinary end of file.

stdlib/std/io/stream.lyr:205

lineReader function

pub fn lineReader(file: File): LineReader

A walk over the lines of an open file. The handle stays the caller's to close.

stdlib/std/io/stream.lyr:278