string

sealed class string

Available without an import.

Immutable UTF-8 text, spelled string in Wax and available without an import. length, search results, and slice arguments count bytes. Chars iterates Unicode code points; Graphemes groups code points into displayed-character boundaries. Search and equality compare exact bytes without Unicode normalization.

Transforms produce strings without changing the receiver. Slice, ToStringSlice, and ToReadOnlySpan borrow storage; Substring copies it.

This example returns 5: the four code points in café occupy five UTF-8 bytes.

api fn Main() : int32 {
    string text = "café";
    int32 accentOffset = text.IndexOf("é");
    string accent = text.Substring(accentOffset, 2);
    return accent == "é" ? text.length : -1;
}

String.wax:42

Inherits from object. Follow these links for inherited members.

Members

lengthfield

public native readonly int32 length

The number of UTF-8 bytes, excluding any terminator. This is not a character or grapheme count.

String.wax:45

Emptyconst

const string Empty = ""

The empty string, with zero bytes and zero graphemes.

String.wax:47

GetHashCodemethod

public override fn GetHashCode() : uint32

Hashes the UTF-8 content. Equal strings have equal hashes; a hash is not a unique identifier or a persisted checksum.

String.wax:58

Equalsmethod

public override fn Equals(object other) : bool

Returns true when other is a string with identical UTF-8 bytes. Other object types compare unequal.

String.wax:76

Containsmethod

public fn Contains<T>(T needle) : bool where T is StringLike

Tests for an exact, case-sensitive byte sequence. An empty needle is always present. Accepts strings and other StringLike values.

String.wax:88

StartsWithmethod

public fn StartsWith<T>(T prefix) : bool where T is StringLike

Tests for an exact, case-sensitive prefix. An empty prefix matches; a prefix longer than this string does not.

String.wax:97

EndsWithmethod

public fn EndsWith<T>(T suffix) : bool where T is StringLike

Tests for an exact, case-sensitive suffix. An empty suffix matches; a suffix longer than this string does not.

String.wax:107

IndexOfmethod

public fn IndexOf<T>(T needle) : int32 where T is StringLike

Returns the byte offset of the first exact match, or -1 when absent. An empty needle returns 0. Matching is case-sensitive and does not normalize Unicode.

String.wax:117

LastIndexOfmethod

public fn LastIndexOf<T>(T needle) : int32 where T is StringLike

Returns the byte offset of the last exact match, or -1 when absent. An empty needle returns length. Matching is case-sensitive and does not normalize Unicode.

String.wax:126

ByteAtmethod

public fn ByteAt(int32 index) : uint8

Returns the byte at a zero-based UTF-8 byte index. Returns 0 for a negative index or an index at or beyond length.

String.wax:150

CharAtByteOffsetmethod

public fn CharAtByteOffset(int32 offset) : char

Decodes the Unicode code point starting at a UTF-8 byte offset. Returns U+0000 outside the string and U+FFFD when the offset starts inside a multibyte sequence.

String.wax:161

LastCharmethod

public fn LastChar() : char

Returns the final Unicode code point, or U+0000 for an empty string. A code point can be only part of a displayed character.

String.wax:172

FirstBytemethod

public fn FirstByte() : uint8

Returns the first UTF-8 byte, or 0 for an empty string.

String.wax:183

LastBytemethod

public fn LastByte() : uint8

Returns the final UTF-8 byte, or 0 for an empty string. For a multibyte code point this is a continuation byte.

String.wax:188

FirstCharmethod

public fn FirstChar() : char

Returns the first Unicode code point, or U+0000 for an empty string.

String.wax:190

IsEmptymethod

public fn IsEmpty() : bool

Returns true when length is zero.

String.wax:192

Substringmethod

public fn Substring(int32 start, int32 len) : string

Copies a byte range into an independent string. Negative start becomes zero; start >= length returns an empty string. Negative len, or a length past the end, selects the remaining bytes. After clamping, both endpoints must be UTF-8 code-point boundaries or the operation panics. Use Slice for a borrowed view.

String.wax:207

Trimmethod

public fn Trim() : string

Removes leading and trailing Unicode whitespace. Returns this string when unchanged and an empty string when all characters are whitespace.

String.wax:221

TrimStartmethod

public fn TrimStart() : string

Removes leading Unicode whitespace. Returns this string when unchanged.

String.wax:230

TrimEndmethod

public fn TrimEnd() : string

Removes trailing Unicode whitespace. Returns this string when unchanged.

String.wax:238

Replacemethod

public fn Replace(string old, string replacement) : string

Replaces all non-overlapping, case-sensitive matches from left to right. An empty old, no matches, or a result exceeding the maximum byte length returns this string unchanged. Replacement text is not searched again.

String.wax:250

ReplaceFirstmethod

public fn ReplaceFirst(string old, string replacement) : string

Replaces only the first case-sensitive match. An empty old, no match, or a result exceeding the maximum byte length returns this string unchanged.

String.wax:292

Splitmethod

public fn Split(string delimiter) : string[]

Splits on exact, non-overlapping delimiter matches and returns a new array of strings. Preserves empty leading, trailing, and adjacent segments. An empty delimiter returns a one- element array containing this string; an empty input also produces one empty segment.

String.wax:317

PadLeftmethod

public fn PadLeft(int32 charCount, char padChar) : string

Prepends charCount copies of padChar; the count is padding to add, not a target width. A nonpositive count or oversized result returns this string. An invalid Unicode scalar is encoded as U+FFFD.

String.wax:364

PadRightmethod

public fn PadRight(int32 charCount, char padChar) : string

Appends charCount copies of padChar; the count is padding to add, not a target width. A nonpositive count or oversized result returns this string. An invalid Unicode scalar is encoded as U+FFFD.

String.wax:388

InsertAtmethod

public fn InsertAt(int32 index, string value) : string

Inserts value at a UTF-8 byte offset, clamping index to [0, length]. The clamped position must be a code-point boundary or the operation panics. An empty value returns this string without checking the index; an oversized result also returns this string.

String.wax:412

RemoveRangemethod

public fn RemoveRange(int32 start, int32 count) : string

Removes up to count UTF-8 bytes. A nonpositive count or a start at or beyond the end returns this string. Negative start becomes zero and an excessive count is clamped to the remaining bytes. The resulting range must start and end on code-point boundaries or the operation panics.

String.wax:437

Countmethod

public fn Count<T>(T needle) : int32 where T is StringLike

Counts exact, case-sensitive, non-overlapping matches from left to right. An empty needle returns 0.

String.wax:461

CompareTomethod

public fn CompareTo(string other) : int32

Compares UTF-8 bytes lexicographically, returning -1, 0, or 1. A matching prefix sorts before a longer string. This is ordinal, case-sensitive ordering, without locale collation or Unicode normalization.

String.wax:488

ToStringSlicemethod

public fn ToStringSlice() : StringSlice

Borrows a view of all UTF-8 bytes without copying. The scoped view cannot outlive its backing storage.

String.wax:497

ToStringmethod

public override fn ToString() : string

Returns this string unchanged.

String.wax:504

ToReadOnlySpanmethod

public fn ToReadOnlySpan() : ReadOnlySpan<uint8>

Borrows the UTF-8 bytes without a terminator or a copy. The scoped view permits byte reads but cannot mutate the string.

String.wax:518

FromUtf8method

public static fn FromUtf8(ReadOnlySpan<uint8> bytes) : string throws Utf8Error

Validates and copies UTF-8 bytes into an independent string. Throws Utf8Error at the first invalid byte offset, including truncated sequences, overlong encodings, surrogate code points, and values above U+10FFFF. Empty input produces an empty string.

String.wax:530

FromUtf8Lossymethod

public static fn FromUtf8Lossy(ReadOnlySpan<uint8> bytes) : string

Copies UTF-8 bytes, replacing each undecodable byte with U+FFFD and advancing one byte before trying again. Valid sequences are preserved. Empty input produces an empty string; a result exceeding the maximum byte length panics.

String.wax:547

Slicemethod

public fn Slice(int32 start, int32 len) : StringSlice

Borrows the byte range [start, start + len) without copying. Negative arguments, an out- of-range endpoint, or an endpoint inside a UTF-8 code point cause a panic. An empty slice at length is valid. Use Substring for an independent string with clamped arguments.

String.wax:588

Bytesmethod

public fn Bytes() : ByteIterator

Iterates UTF-8 bytes from first to last. An empty string yields no elements.

String.wax:596

Charsmethod

public fn Chars() : CharIterator

Iterates Unicode code points from first to last. Code points are not necessarily whole displayed characters; use Graphemes for those boundaries.

String.wax:603

CharsReversemethod

public fn CharsReverse() : ReverseCharIterator

Iterates Unicode code points from last to first, preserving each code point. This does not reverse grapheme clusters as units.

String.wax:610

Graphemesmethod

public fn Graphemes() : GraphemeIterator

Iterates extended grapheme clusters as borrowed StringSlice views. A cluster may contain several code points, such as a letter plus combining marks. Empty input yields no clusters.

String.wax:617

GraphemeCountmethod

public fn GraphemeCount() : int32

Counts extended grapheme clusters by scanning the string. Returns zero for an empty string; this differs from the UTF-8 byte count in length.

String.wax:624

ToUppermethod

public fn ToUpper() : string

Applies full Unicode uppercase mapping without locale-specific rules. Mapping can expand a code point into several code points and change the byte length. Use ToUpperLocale for locale-specific casing.

String.wax:644

ToLowermethod

public fn ToLower() : string

Applies full Unicode lowercase mapping, including contextual Greek final sigma, without locale-specific rules. Mapping can change the byte length. Use ToLowerLocale for locale- specific casing.

String.wax:694

ToUpperLocalemethod

public fn ToUpperLocale(Locale loc) : string

Applies full Unicode uppercase mapping with the selected locale rules. Locale.Invariant matches ToUpper; Lithuanian, Turkish, and Azeri apply their additional casing rules. Mapping can change the number of code points.

String.wax:820

ToLowerLocalemethod

public fn ToLowerLocale(Locale loc) : string

Applies full Unicode lowercase mapping with the selected locale rules. Locale.Invariant matches ToLower; Lithuanian, Turkish, and Azeri apply their additional casing rules. Mapping can change the number of code points.

String.wax:893