StringBuilder

Module std.text

import std.text;

Public declaration contracts and authored examples. A page can document several related symbols. Implementation bodies are excluded.

StringBuilder

pub final class StringBuilder

Owns reusable mutable UTF-8 construction storage.

The zero-argument initializer allocates nothing. Recoverable Try operations are all-or-nothing while Reserve/Append store sticky failure for interpolation. Every mutation attempt invalidates prior views. Finalization transfers storage to immutable String and resets the builder; automatic deinit releases any remaining capacity.

Example

module example.string_builder;
from std.io import Print;
from std.text import StringBuilder;
fn Main() -> i32 {
    var Builder = switch StringBuilder.TryCreate(16) {
        case .Ok { Value = Value } => break Value;
        case .Err { Error = _ } => return 1;
    };
    if Builder.ByteLength != 0 || Builder.Capacity < 16 {
        return 2;
    }
    if Builder.TryReserve(24) is .Err { Error = _ } {
        return 3;
    }
    if Builder.TryAppend("discarded") is .Err { Error = _ } {
        return 4;
    }
    Builder.Clear();
    if Builder.View != "" || Builder.ByteLength != 0 ||
        Builder.Capacity < 24 {
        return 5;
    }
    Builder.Reserve(32);
    if Builder.TryAppend("ready") is .Err { Error = _ } {
        return 6;
    }
    if Builder.TryAppend('!') is .Err { Error = _ } {
        return 7;
    }
    Builder.Append(" now");
    var Text = switch Builder.TryFinalize() {
        case .Ok { Value = Value } => break Value;
        case .Err { Error = _ } => return 8;
    };
    Print(Text.View);

    var Reused = Text.IntoStringBuilder();
    Reused.Append('!');
    Text = Reused.FinalizeOrPanic();
    Print(Text.View);
    return 0;
}

StringBuilder.init

pub init()

Starts an empty owner without allocation.

StringBuilder.TryCreate

pub static fn TryCreate(MinimumCapacity: usize)
        -> Result<StringBuilder, AllocationError>

Creates an empty builder with at least a requested byte capacity. MinimumCapacity: Minimum writable UTF-8 byte capacity. Return: Builder or recoverable allocation failure.

StringBuilder.View

pub View: str;

Borrows the currently initialized UTF-8 prefix. Return: Nonretaining view invalidated by every mutation attempt.

StringBuilder.ByteLength

pub ByteLength: usize;

Returns initialized byte count. Return: UTF-8 bytes, not scalar count.

StringBuilder.Capacity

pub Capacity: usize;

Returns allocator-owned byte capacity. Return: Capacity at least ByteLength.

StringBuilder.TryReserve

pub fn TryReserve(MinimumCapacity: usize)
        -> Result<void, AllocationError>

Recoverably ensures one minimum byte capacity. MinimumCapacity: Required lower bound. Return: Success or the stored/new AllocationError with strong guarantee. Warning: Invalidates all prior View values even on failure or sticky no-op.

StringBuilder.Reserve

pub fn Reserve(MinimumCapacity: usize) -> void

Ensures capacity or records sticky failure for later finalization. MinimumCapacity: Required lower bound. Return: No value; later sticky mutations become no-ops. Warning: May allocate and invalidates all prior View values.

StringBuilder.TryAppend

pub fn TryAppend(Value: str) -> Result<void, AllocationError>

Recoverably appends one complete borrowed UTF-8 view. Value: Entry bytes borrowed only for the call; overlap is supported. Return: Success or AllocationError without changing a healthy prefix. Warning: May allocate and invalidates all prior View values.

StringBuilder.TryAppend

pub fn TryAppend(Value: char) -> Result<void, AllocationError>

Recoverably appends one Unicode scalar as canonical UTF-8. Value: Valid Unicode scalar value. Return: Success or AllocationError without changing a healthy prefix. Warning: May allocate and invalidates all prior View values.

StringBuilder.fn

pub const fn Append(Value: str) -> void

Appends one UTF-8 view or records sticky allocation failure. Value: Entry bytes borrowed only for the call; overlap is supported. Return: No value; sticky state is observed by Try/finalization operations. Warning: May allocate and invalidates all prior View values.

StringBuilder.fn

pub const fn Append(Value: char) -> void

Appends one Unicode scalar or records sticky allocation failure. Value: Valid Unicode scalar encoded canonically as UTF-8. Return: No value; sticky state is observed by finalization. Warning: May allocate at runtime and invalidates all prior View values.

StringBuilder.Clear

pub fn Clear() -> void

Removes every initialized byte while retaining capacity.

A healthy builder remains healthy and empty. After sticky allocation failure, Clear is a no-op and preserves the stored AllocationError for the next Try operation or finalization; it never recovers a failed builder.

Return: No value after the healthy reset or sticky no-op. Warning: Invalidates all prior View values, including after a sticky no-op.

StringBuilder.fn

pub const fn TryFinalize() -> Result<String, AllocationError>

Transfers successful bytes to String or returns sticky failure. Return: Owning String, or exact sticky AllocationError after releasing storage. Post: This builder returns to its empty zero-allocation state on every path. Note: Constant evaluation transfers evaluator-owned UTF-8 bytes; exceeding compiler resource limits fails evaluation rather than falling back to runtime.

StringBuilder.FinalizeOrPanic

pub fn FinalizeOrPanic() -> String

Transfers successful bytes to String or fatal-panics after cleanup. Return: Owning immutable String when no sticky failure occurred. Post: This builder returns to its empty zero-allocation state before return or panic. Warning: Failure is non-unwinding and skips pending cleanup after this operation has released its own storage.