FileStream structv0.1.0

pub struct FileStream {
    // private fields
}

Reach for this only when a stream has to be kept. A File already implements Reader, Writer and Seeker, so anything taking one for the duration of a call takes the file itself:

let sink: &var Writer = file;
WriteAll(sink, contents);

That borrows, and the file is still the caller's afterwards. What it cannot do is outlive the call, because a reference cannot be stored in a field — so a BufferedReader, which keeps its source, needs a value it can hold. Binding the file itself into an interface value would move it, since a File owns its handle and prohibits copying, and the caller would no longer have a file to close. This is the value that fills that gap: it holds the file's address rather than the file, so it can be stored, and the file stays where it is. The address is private, and File::Stream is the only way to obtain one. That is deliberate: a FileStream assembled from an arbitrary pointer would be an unchecked promise about a file that may not exist, and the type is already the least checkable thing in this package without adding a second way to get it wrong. The file must outlive the stream, and must not be moved while one exists — a move relocates the file and leaves the stored address pointing at where it used to be. Nothing here tracks either, which is exactly why this is not the default way to reach a file's streams. A stream over a closed file is not unsafe: every operation refuses with InvalidHandle, because the file itself checks.

Implements Reader

FileStream conforms to Reader.

Read

pub func Read(
    self: &var FileStream,
    into: var char8[..]
) -> uint ! IoError

Reads through the borrowed file.

Returns: how many bytes were read; IsEnd at the end of the file

Source

Implements Writer

FileStream conforms to Writer.

Write

pub func Write(
    self: &var FileStream,
    bytes: char8[..]
) -> uint ! IoError

Writes through the borrowed file.

Returns: how many bytes were taken, which may be fewer than offered

Source

Flush

pub func Flush(self: &var FileStream) -> ! IoError

Flushes the borrowed file, which holds nothing back.

Returns: success when everything written reached the system

Source

Implements Seeker

FileStream conforms to Seeker.

Seek

pub func Seek(
    self: &var FileStream,
    origin: SeekFrom,
    offset: int64
) -> uint64 ! IoError

Seeks the borrowed file.

Returns: the resulting offset from the start

Source