v0.4.0

StringBuilder v0.1.0

A growable buffer for building a string in steps.

Package: 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 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;
}