Strings

std.string exports String, a move-only owned UTF-8 text value. Like str, it stores strict UTF-8 text without embedded NUL bytes. Use constructor syntax to allocate an owned string from borrowed text.

import {
    String
} from std.string;

fn main() {
    let text = try String("hello");
    let view = text.str();

    assert view == "hello";
}

String("text") returns String throws(AllocError) because allocation can fail. Use String("text", allocator) when construction should use a specific allocator. String.clone("text") still works as a legacy alias, but constructor syntax is the preferred spelling.

String literal escapes are decoded before construction. Unicode scalar escapes such as "\u{2665}" are stored as UTF-8. Use std.unicode when strict validation, fallible decoding, or UTF-16LE transcoding is required. String.length() counts Unicode scalar values for valid string storage; String.size() returns the byte count.

String(bytes.Bytes) validates a byte view as strict UTF-8 text and rejects embedded NUL bytes before copying into owned storage.

append, extend, and += append borrowed text or a borrowed String.

import {
    String
} from std.string;

fn main() {
    let text = try String("hello");
    try text.append(", ");
    try text.extend("world");
    try (text += "!");

    assert text.str() == "hello, world!";
}

text.str() returns a borrowed str view. text.utf8() returns a borrowed bytes.Bytes view over the raw UTF-8 storage. Neither view owns storage, so keep the String alive and avoid mutating it while the view is used.

Call arguments can borrow a String as str or bytes.Bytes without an explicit method call. This does not move the owned string. Stored views remain explicit, so use text.str() or text.utf8() when a view must live in a binding or be returned.

text.utf8() returns the decoded byte storage and size() reports the stored byte count.

import std.bytes;
import {
    String
} from std.string;

fn main() {
    let text = try String("copy");
    let clone = try text.clone();
    let raw = text.utf8();

    assert text.str() == clone.str();
    assert raw.length == 4;
}

text.clone() allocates independent owned storage and returns String throws(AllocError).

Method	Purpose
String(value)	Allocate and copy borrowed str data.
String(value, allocator)	Allocate with an explicit allocator.
String(bytes)	Validate a bytes.Bytes view and allocate owned text.
String(bytes, allocator)	Validate bytes and allocate with an explicit allocator.
String.clone(value)	Legacy alias for String(value).
String.clone(value, allocator)	Legacy alias with allocator.
text.clone()	Clone an existing owned string.
append(value)	Append str or const &String.
extend(value)	Alias-style append for str or const &String.
+=	Append through operator syntax.
text.str()	Return the borrowed str view.
text.utf8()	Return a borrowed byte view.
length()	Return Unicode scalar count from the string view.
size()	Return stored byte size.
capacity()	Return allocated byte capacity.
reserve(capacity)	Ensure storage capacity.
shrink()	Release unused capacity when possible.
clear()	Keep storage but reset the string to empty.
is_empty()	Test byte size.

String frees owned storage in drop.

Use std.bytes.Bytes or [u8] slices for arbitrary byte data. String is not a raw byte container.