String builder

// A `String` cannot grow: it can be cleared or replaced whole, but never appended to, so building
// text a piece at a time out of Strings alone would copy everything built so far at every step.
// `StringBuilder` is the tool for that job. It keeps one growing buffer, appends into it, and asks
// the allocator for a larger one only when the room runs out. `Length` is the text so far and
// `Capacity` the room for it. The room doubles each time it runs out, so most appends copy just
// the bytes being added, and the rare move to a bigger buffer gets rarer as the text grows.
//
// Each append can fail, because growing the buffer can, so each returns `! TextError`. When the
// text is finished, `IntoString` hands the buffer over as a String without copying it.
import Allocator::{ Allocator, SystemAllocator };
import Io::PrintLine;
import Text::{ StringBuilder, TextError };

// Joins words into a list a person would write: "a, b and c". The builder is borrowed `&var`,
// so the caller's builder is the one that grows. Watch the room: 16, then 32, then 64.
func Join(builder: &var StringBuilder, words: char8[..][..]) -> ! TextError {
    for i in 0..words.length {
        if i > 0 {
            let separator = i == words.length - 1 ? " and " : ", ";
            builder.Append(separator)?;
        }
        builder.Append(words[i])?;
        PrintLine("added {}: {} bytes, room for {}", words[i], builder.Length(),
            builder.Capacity());
    }
}

func Main() -> ! TextError {
    var system = SystemAllocator();
    let allocator: Allocator = system;

    // A new builder has allocated nothing yet. Its buffer appears with the first append.
    var builder = StringBuilder(allocator);
    let colours: char8[..][5] = ["red", "orange", "yellow", "green", "blue"];
    Join(builder, colours)?;

    // Single characters go in with `AppendScalar`, which encodes any character as UTF-8.
    builder.Append(" ")?;
    builder.AppendScalar('✓')?;

    // `View` looks at the text so far without taking it.
    PrintLine("view    {}", builder.View());

    // `IntoString` hands the buffer itself to a String. The builder is left empty, ready to
    // build something else.
    let sentence = builder.IntoString();
    PrintLine("string  {}", sentence);
    PrintLine("builder now holds {} bytes", builder.Length());
}