BufferWriter structv0.1.0

pub struct BufferWriter {
    // private fields
}

Holds well-formed UTF-8 at every moment. A write either appends its whole run or changes nothing, so what has been written is always the concatenation of the runs that succeeded. Copying is not prohibited, but a copy is a second cursor over the same storage rather than a second buffer, so writes through one are invisible to the other and the two will overwrite each other. Borrow it as &var TextWriter and let it be the one writer over its room. The room it was built over must outlive it. It stores the slice, and nothing here tracks that.

Constructors

BufferWriter

pub func BufferWriter(room: var char8[..]) -> BufferWriter

A writer over room, filling from its start. Nothing in room is read or cleared: what has not been written is not part of the text, and Written never reaches it. Cannot fail. Runs in constant time and allocates nothing.

Returns: a writer holding no text yet

Source

Methods

Written

pub func Written(self: &BufferWriter) -> char8[..]

The text written so far. Well-formed UTF-8, and exactly the runs that succeeded: a refused write left nothing behind to appear here. The result borrows the writer's room and must not outlive it. Borrows the writer. Cannot fail; runs in constant time and allocates nothing.

Returns: the bytes written, which are valid UTF-8

Source

Length

pub func Length(self: &BufferWriter) -> uint

How many bytes of text the writer holds. Borrows the writer. Cannot fail; runs in constant time and allocates nothing.

Returns: the byte count, which is not a character count

Source

Remaining

pub func Remaining(self: &BufferWriter) -> uint

How many more bytes will fit. A caller sizing a write can ask, but need not: a write that does not fit is refused whole rather than truncated, so asking first is an optimization and never a correctness requirement. Borrows the writer. Cannot fail; runs in constant time and allocates nothing.

Returns: the remaining capacity in bytes

Source

Clear

pub func Clear(self: &var BufferWriter)

Discards the text written so far, keeping the room. The bytes are not overwritten, because they are no longer text as far as this writer is concerned and nothing can reach them: Written stops at the length. A caller clearing secrets wants ZeroizeBlock from Rux/Memory on the room itself. Borrows the writer exclusively. Cannot fail; runs in constant time and allocates nothing.

Source

Implements TextWriter

BufferWriter conforms to TextWriter.

Write

pub func Write(
    self: &var BufferWriter,
    bytes: char8[..]
) -> ! FormatError

Appends bytes, whole or not at all. Reports InsufficientCapacity when the run does not fit, and TextFailure(InvalidUtf8) when it is not well-formed UTF-8. In both cases the buffer is exactly as it was, so a caller may write the same run to a larger destination without first undoing a partial one. Capacity is decided before validity, since a run that cannot land is not worth reading. These are the only two failures this writer produces. There is no destination beyond the buffer, so a WriterFailure cannot arise, and the other TextFailure reasons belong to allocation and to boundary arithmetic, neither of which a fixed buffer performs.

Returns: success when the complete run was appended

Source