StringBuilder structv0.1.0

pub struct StringBuilder {
    // private fields
}

Move-only: it explicitly prohibits copying and owns its block. Holds well-formed UTF-8 at every moment.

Constructors

StringBuilder

pub func StringBuilder(allocator: Allocator) -> StringBuilder

A builder that has allocated nothing. allocator is borrowed for the call and kept. Cannot fail. Runs in constant time and allocates nothing.

Returns: an empty builder that has taken no storage yet

Source

Associated functions

WithCapacity

pub func WithCapacity(
    allocator: Allocator,
    capacity: uint
) -> StringBuilder ! TextError

A builder with room for capacity bytes already taken. Worth using when the size is known or can be guessed well: appends that stay within the room never reallocate. Fails with OutOfMemory when the room cannot be had.

Returns: an empty builder with room for that many bytes already taken

Source

Methods

Length

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

How many bytes are in use.

Returns: how many bytes have been appended

Source

Capacity

pub func Capacity(self: &StringBuilder) -> uint

How many bytes the block holds.

Returns: how many bytes fit before the next growth

Source

IsEmpty

pub func IsEmpty(self: &StringBuilder) -> bool

Whether nothing has been appended.

Returns: whether nothing has been appended

Source

Bytes

pub func Bytes(self: &StringBuilder) -> char8[..]

The bytes in use, borrowed.

Returns: the appended bytes, borrowed

Source

View

pub func View(self: &StringBuilder) -> StringView

A view over what has been appended so far. Free, and needs no checking: everything the builder accepts is whole characters, so what it holds is well-formed at every moment rather than only once it is finished.

Returns: a borrowed view of what has been appended

Source

Reserve

pub func Reserve(
    self: &var StringBuilder,
    additional: uint
) -> ! TextError

Makes sure there is room for additional more bytes. Reports OutOfMemory when the room cannot be had and LengthOverflow when the size needed cannot be expressed, having in both cases changed nothing: a builder that fails to grow still holds what it held.

Returns: nothing when the room is available, or why not

Source

AppendValidated

pub func AppendValidated(
    self: &var StringBuilder,
    bytes: char8[..]
) -> ! TextError

Appends bytes the caller vouches are UTF-8. The bytes must be well-formed UTF-8 and must not end part-way through a character. The builder's promise that it holds text at every moment rests on this, and everything reading from it relies on that promise.

Returns: nothing when the bytes were appended, taken as valid without checking, or why not

Source

Append

pub func Append(
    self: &var StringBuilder,
    view: StringView
) -> ! TextError

pub func Append(
    self: &var StringBuilder,
    text: char8[..]
) -> ! TextError

Appends text. Text was checked before it existed, so nothing is checked again and nothing can fail but the storage.

Returns: nothing when the text was appended, or why not

Source

AppendBytes

pub func AppendBytes(
    self: &var StringBuilder,
    bytes: char8[..]
) -> ! TextError

Appends bytes when they are UTF-8, and reports InvalidUtf8 when they are not. Costs a pass over the bytes. Append of a view costs none, which is the reason views exist.

Returns: nothing when the bytes were appended, after checking they are valid UTF-8, or why not

Source

AppendScalar

pub func AppendScalar(
    self: &var StringBuilder,
    scalar: char32
) -> ! TextError

Appends one character. Reports InvalidUtf8 for a value that is not a scalar value — a surrogate half, or one past U+10FFFF -- which is what keeps a builder from holding something that is not text.

Returns: nothing when the scalar's encoding was appended, or why not

Source

AppendAscii

pub func AppendAscii(
    self: &var StringBuilder,
    byte: char8
) -> ! TextError

Appends one ASCII byte. Reports InvalidUtf8 for a byte above 0x7F, since a single byte above that is never a whole character; AppendScalar is what appends one that takes more than a byte.

Returns: nothing when the byte was appended, or why not

Source

Clear

pub func Clear(self: &var StringBuilder)

Forgets everything appended, keeping the room. The block is kept, so a builder used in a loop allocates once rather than once per pass.

Source

Release

pub func Release(self: &var StringBuilder)

Gives the block back and leaves a builder that owns nothing.

Source

ToString

pub func ToString(self: &StringBuilder) -> String ! TextError

A copy of what has been appended, as a string of its own. The builder is untouched and may be appended to again. IntoString is what hands the block over instead of copying it, and is what to use when the builder is finished with.

Returns: a copy of what has been appended, leaving the builder as it was

Source

IntoString

pub func IntoString(self: &var StringBuilder) -> String

Hands the block over as a string, leaving the builder owning nothing. Copies nothing: the string that comes back is the builder's block, which is why the builder must give it up. The block usually has room to spare, and the string remembers how much so that the allocator gets back the layout it handed out. Cannot fail. Runs in constant time and allocates nothing.

Returns: what has been appended, taking the builder's storage rather than copying

Source

Implements TextWriter

StringBuilder conforms to TextWriter.

Write

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

Appends bytes to the builder. The bytes are validated here, which AppendValidated does not do: that one names bytes a caller has already checked and takes their validity as a precondition. A writer cannot, because what reaches it came from a value that may have produced anything, and the builder's promise to hold text at every moment is what everything reading from it relies on. Reports TextFailure(InvalidUtf8) for bytes that are not well-formed UTF-8, and TextFailure(OutOfMemory) when the builder cannot make room. In both cases nothing was appended: validity is decided before any byte moves, so the builder is exactly as it was and a caller may retry elsewhere without first undoing a partial write. A WriterFailure is impossible here, since there is no destination beyond the allocator, and InsufficientCapacity cannot arise because a builder grows.

Returns: success when the complete run was appended

Source

Destructor

func ~StringBuilder(self: &var StringBuilder)

Gives the block back. Runs when the builder dies. A builder whose block was handed over by IntoString owns nothing, so this is then a no-op rather than a second release.

Source

Related

MinimumBuilderCapacity

pub const MinimumBuilderCapacity: uint = 16;

The room a builder takes when it first needs any. Small enough that a builder for a short string wastes little, large enough that short strings never grow twice.

Source