StringBuilder

A growable buffer for building a string in steps.

Module: Text

Struct

struct StringBuilder {
    data:     *char8;
    length:   uint;
    capacity: uint;
}

The mutable counterpart to String. Appending to a String allocates on every step, since each transformation returns a fresh one; accumulation happens here instead. The builder keeps spare capacity and doubles it when it runs out, which is what the third field buys over a String, and what makes a run of appends cost an amortized constant rather than a reallocation each time.

The fields are an implementation detail — read them with Data, Length, and Capacity.

Ownership

A builder owns its block and has to be passed to Free exactly once, on the same terms as a String. The exception is IntoString, which hands the block over to the String it returns and leaves the builder empty and owning nothing — after that only the String has to be freed, and Free on the drained builder is a harmless no-op.

Take the result with IntoString once the builder is finished with, and with ToString when the builder has to stay usable — that one copies, and leaves both to be freed.

Methods

Construction

Method	Description
New	Creates an empty builder, without allocating.
WithCapacity	Creates an empty builder with room reserved.
Free	Releases the block the builder owns.

Accessors

Method	Description
Data	The pointer to the bytes written so far.
Length	How many bytes have been written.
Capacity	How many bytes fit before the block grows.
IsEmpty	Whether anything has been written.

Building

Method	Description
Append	Writes a byte, a literal, or a string.
Reserve	Makes room for N more bytes.
Grow	Grows the block to hold at least N bytes.
Shrink	Drops the capacity the builder is not using.
Clear	Forgets the contents but keeps the block.

Conversion

Method	Description
ToString	Copies the contents out into a String.
IntoString	Hands the block over to a String, without a copy.

Example

import Std::Io::PrintLine;
import Text::{ String, StringBuilder };

func Main() -> int {
    var builder = StringBuilder::New();

    for i in 0..3 {
        builder.Append("ab");
        builder.Append(c8'-');
    }

    PrintLine(builder.Length()); // 9

    var text = builder.IntoString(); // "ab-ab-ab-", and the builder is empty
    text.Free();
    return 0;
}

See also

• Text — the module overview
• String — the immutable string a builder produces