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.
Storage invariant, which every operation keeps and every unsafe block here relies on: length <= capacity;
data is null exactly when capacity is zero, and otherwise addresses a block of capacity bytes from
allocator whose first length bytes are initialized, well-formed UTF-8.
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.
| Name | Type | Description |
|---|---|---|
allocator | Allocator | where the storage comes from |
Returns: an empty builder that has taken no storage yet
Associated functions
WithCapacity
pub func WithCapacity(
allocator: Allocator,
capacity: uint
) -> StringBuilder
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. Terminates the program when the room cannot be had.
| Name | Type | Description |
|---|---|---|
allocator | Allocator | where the storage comes from |
capacity | uint | how many bytes to reserve up front |
Returns: an empty builder with room for that many bytes already taken
Methods
Length
pub func Length(&self) -> uint
How many bytes are in use.
Returns: how many bytes have been appended
Capacity
pub func Capacity(&self) -> uint
How many bytes the block holds.
Returns: how many bytes fit before the next growth
IsEmpty
pub func IsEmpty(&self) -> bool
Whether nothing has been appended.
Returns: whether nothing has been appended
Bytes
pub func Bytes(&self) -> char8[..]
The bytes in use, borrowed.
Returns: the appended bytes, borrowed
View
pub func View(&self) -> 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
Reserve
pub func Reserve(&var self, additional: uint)
Makes sure there is room for additional more bytes.
Terminates the program when the room cannot be had or the size needed cannot be expressed; TryReserve
reports both instead.
| Name | Type | Description |
|---|---|---|
additional | uint | how many more bytes to make room for |
TryReserve
pub func TryReserve(
&var self,
additional: uint
) throws AllocError
Makes sure there is room for additional more bytes, or throws why there is none.
Throws Unsupported when the size needed cannot be expressed, and otherwise whatever the allocator refused
with, having in both cases changed nothing: a builder that fails to grow still holds what it held.
| Name | Type | Description |
|---|---|---|
additional | uint | how many more bytes to make room for |
Returns: nothing, or throws the allocator's refusal
AppendValidated
pub func AppendValidated(&var self, bytes: char8[..])
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. Terminates the program when the builder cannot grow.
| Name | Type | Description |
|---|---|---|
bytes | char8[..] | the bytes to act on, taken as valid without checking |
Append
pub func Append(&var self, view: StringView)
pub func Append(&var self, text: char8[..])
Appends what view spans.
The view was checked when it was made, so nothing is checked again. Terminates the program when the builder
cannot grow.
| Overload | Summary |
|---|---|
pub func Append(&var self, view: StringView) | Appends what view spans. |
pub func Append(&var self, text: char8[..]) | Appends text. |
| Name | Type | Description |
|---|---|---|
view | StringView | the borrowed text to act on |
text | char8[..] | the text to act on |
AppendBytes
pub func AppendBytes(
&var self,
bytes: char8[..]
) throws 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.
| Name | Type | Description |
|---|---|---|
bytes | char8[..] | the bytes to act on |
Returns: nothing when the bytes were appended, after checking they are valid UTF-8, or why not
AppendScalar
pub func AppendScalar(
&var self,
scalar: char32
) throws 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.
| Name | Type | Description |
|---|---|---|
scalar | char32 | the Unicode scalar value |
Returns: nothing when the scalar's encoding was appended, or why not
AppendAscii
pub func AppendAscii(
&var self,
byte: char8
) throws 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.
| Name | Type | Description |
|---|---|---|
byte | char8 | the byte |
Returns: nothing when the byte was appended, or why not
Clear
pub func Clear(&var self)
Forgets everything appended, keeping the room. The block is kept, so a builder used in a loop allocates once rather than once per pass.
Release
pub func Release(&var self)
Gives the block back and leaves a builder that owns nothing.
ToString
pub func ToString(&self) -> String
A copy of what has been appended, as a string of its own.
The builder is untouched and may be appended to again. TakeString is what hands the block over instead of
copying it, and is what to use when the builder is finished with. Terminates the program when the copy cannot
be made.
Returns: a copy of what has been appended, leaving the builder as it was
TakeString
pub func TakeString(&var self) -> 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
Implements TextWriter
StringBuilder conforms to TextWriter.
Write
pub func Write(
&var self,
bytes: char8[..]
) throws 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 then 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. Terminates the program when the builder cannot make room. A
WriterFailure is impossible here, since there is no destination beyond the allocator, and
InsufficientCapacity cannot arise because a builder grows.
| Name | Type | Description |
|---|---|---|
bytes | char8[..] | the UTF-8 run to append, whole |
Returns: success when the complete run was appended
Destructor
func ~StringBuilder(&var self)
Gives the block back.
Runs when the builder dies. A builder whose block was handed over by TakeString owns nothing, so this is
then a no-op rather than a second release.
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.