File structv0.1.0

pub struct File {
    // private fields
}

Move-only: the handle closes exactly once, through Close or through its destructor. Close is the error-visible path; destruction discards the outcome, which is fine for a file that was read and a silent loss for one that was written.

Associated functions

Open

pub func Open(
    allocator: Allocator,
    path: Path,
    options: OpenOptions
) -> File ! IoError

Opens path under options. The allocator is borrowed for the platform form of the path and holds nothing afterward. A failure says why in the platform's own terms, translated.

Returns: the open file

Source

Methods

IsOpen

pub func IsOpen(self: &File) -> bool

Whether the handle is still open.

Returns: whether the file is open

Source

Close

pub func Close(self: &var File) -> ! IoError

Closes the handle and reports what the platform said. Closing twice is not an error here: the second call is a no-op reporting success, because the first already gave the handle back. This is the error-visible path; a written file deserves it.

Returns: success when the descriptor was released; closing twice is not an error

Source

Sync

pub func Sync(self: &var File) -> ! IoError

Forces everything written through to the storage device. Not "handed to the kernel" but "acknowledged by the device": the promise that holds through a power failure, and the one a caller who just wrote something they cannot lose actually wants.

Returns: success when the system reported the data durable

Source

Size

pub func Size(self: &var File) -> uint64 ! IoError

The file's length in bytes. On the Unix systems this is measured by seeking to the end and back, which moves the shared kernel position for a moment; a reader racing this on the same open file may see it. The stat-based answer arrives with the metadata work.

Returns: the file's size in bytes

Source

SetLength

pub func SetLength(
    self: &var File,
    length: uint64
) -> ! IoError

Sets the file's length: shrinking discards what was past the new end, growing leaves a hole. The position does not move. A position past the new end stays where it was, and the next write there grows the file again — the same rule as seeking past the end.

Returns: success when the file is that size; extending reads back as zeros

Source

Stream

pub func Stream(self: *var File) -> FileStream

A stored borrow of this file, for a value that must keep a stream beyond one call. For anything that only needs a stream for the duration of a call, borrow the file directly as let sink: &var Writer = file; instead: that is checked, and this is not. The file must outlive the result and must not be moved while it exists. See FileStream.

Returns: a stream over this file, holding its address, which is what makes it storable

Source

Metadata

pub func Metadata(self: &File) -> Metadata ! IoError

Describes this open file. Answers about the file the handle holds, so nothing can rename or replace the name out from under the query the way a path-based one can.

Returns: what the system knows about the open file

Source

Implements Reader

File conforms to Reader.

Read

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

Reads what one attempt yields into into; a short count is not an error and the end is EndOfStream.

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

Source

Implements Writer

File conforms to Writer.

Write

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

Writes what one attempt takes of bytes; a short count means call again, which WriteAll does.

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

Source

Flush

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

Nothing: these writes hold nothing back. Durability is Sync, which is a different promise.

Returns: success when everything written reached the system

Source

Implements Seeker

File conforms to Seeker.

Seek

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

Moves the position offset bytes from origin and reports where it landed. A position before the start of the file is refused by the platform; one past the end is allowed, and a later write there leaves a hole. A handle opened for appending still seeks — but its writes land at the end regardless, because append is a property of the writes, not of the position.

Returns: the resulting offset from the start

Source

Destructor

func ~File(self: &var File)

Closes with the outcome discarded: the safety net, not the contract.

Source

Related

OpenOptions

pub struct OpenOptions {
    pub write: bool;
    pub truncate: bool;
    pub create: bool;
    pub createNew: bool;
    // private fields
}

What an open may do, and what it does about existence. read, write and append say what may happen through the handle; create, createNew and truncate say what happens to the file itself. append positions every write at the end, whatever was written in between, which is the property log writers need and write alone does not have.

Source

Fields

Constructors

OpenOptions

pub func OpenOptions() -> OpenOptions

Nothing at all: the caller states every intention.

Returns: options that permit nothing, which must be added to before opening

Source

Associated functions

Reading

pub func Reading() -> OpenOptions

Reading an existing file.

Returns: options that open an existing file for reading

Source

Writing

pub func Writing() -> OpenOptions

Writing a file from its beginning: created if missing, emptied if not.

Returns: options that create or truncate a file for writing

Source

Appending

pub func Appending() -> OpenOptions

Adding to a file's end: created if missing, appended to if not.

Returns: options that create or open a file and write at its end

Source