String

Module std.text

import std.text;

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

pub final class String

Owns one immutable valid UTF-8 byte sequence.

String uses the standard default allocator, is non-Copy, and has an allocation-free valid empty initialization. Its physical representation is compiler- private. Views remain valid only while the owner stays live, unmoved, and unconverted to a builder. Automatic deinitialization releases storage once.

Example

module example.string;
from std.io import Print;
from std.text import String;
fn Main() -> i32 {
    var Text = switch String.TryCreate("ready") {
        case .Ok { Value = Value } => break Value;
        case .Err { Error = _ } => {
            return 1;
        }
    };
    if Text.ByteLength != 5 || Text.Capacity < Text.ByteLength {
        return 2;
    }
    var Cursor = Text.CreateIterator();
    switch Cursor.Next() {
        case .Some { Value = Value } => {
            if Value != 'r' { return 3; }
        }
        case .None => return 4;
    }
    Print(Text.View);
    var Builder = Text.IntoStringBuilder();
    Builder.Append('!');
    Text = Builder.FinalizeOrPanic();
    Print(Text.View);
    return 0;
}

String.init

pub init()

Starts an empty owner without allocation.

String.TryCreate

pub static fn TryCreate(Value: str) -> Result<String, AllocationError>

Copies one borrowed valid UTF-8 view into a new owner. Value: UTF-8 bytes borrowed only for the call. Return: Owning String or recoverable allocation failure.

String.View

pub View: str;

Borrows the exact initialized UTF-8 bytes. Return: Nonretaining view invalidated by move, conversion, or deinit.

String.ByteLength

pub ByteLength: usize;

Returns the initialized UTF-8 byte count. Return: Length in bytes, not scalars or grapheme clusters.

String.Capacity

pub Capacity: usize;

Returns the allocator-owned byte capacity. Return: Capacity at least ByteLength; zero for the canonical empty default.

String.CreateIterator

pub readonly fn CreateIterator() -> ScalarIterator

Creates a scalar-value cursor over the current immutable bytes. Return: Allocation-free cursor borrowing this String's storage. Warning: Move, conversion, or deinit invalidates the cursor.

String.IntoStringBuilder

pub fn IntoStringBuilder() -> StringBuilder

Transfers owned storage into a mutable StringBuilder. Return: Builder owning the former allocation without allocation. Post: This String returns to its empty zero-allocation state. Warning: Invalidates every previously borrowed View and scalar cursor.