String

String is the built in immutable text value. It requires no import, stores UTF-8, and provides Unicode aware indexing, literal search, casing, and text composition. Every operation returns a new value or a scalar result; the original text is unchanged.

Declaration and conversion

let title: String = "Aner research"
let measurement = String(42)
let enabled = String(true)
let combined = title + ": " + measurement
print(combined)

String(value) accepts an Int64, Float64, Bool, or String. Conversion is explicit; concatenation accepts two Strings and does not convert numbers automatically. Booleans become "true" or "false". Int64 conversion preserves its exact decimal value. Float64 conversion requires a finite value and uses a locale independent shortest round trip representation; a whole valued float can omit a decimal point. This conversion is not a dataset serialization format. Objects, collections, null, credentials, and opaque native handles cannot be converted through this constructor.

A let binding cannot be reassigned. A var binding can be assigned a new String, without changing any previously assigned value. Methods do not mutate either binding.

Double quoted literals support \", \\, \n, \r, and \t. Literal Unicode characters are written directly in the UTF-8 source. Unescaped line breaks and ASCII control characters below U+0020 are rejected. Interpolation, raw literals, and Unicode escape syntax are not implemented.

Unicode and indexing contract

len(), get(index), slice(start, end), and the result of find(needle) use Unicode scalar values, rather than encoded bytes or displayed grapheme clusters. Indices have type Int64, start at zero, and must be nonnegative.

let text = "café 🧪"
print(text.len())       // 6 Unicode scalar values
print(text.byte_len())  // 10 UTF-8 bytes
print(text.get(3))      // é
print(text.slice(0, 4)) // café
print(text.find("🧪"))  // 5

get(index) returns a String containing exactly one Unicode scalar value and requires index < len(). There is no separate Char datatype. slice(start, end) uses a half open interval and requires 0 <= start <= end <= len(); equal endpoints return an empty String. Negative indices never count from the end.

A combining mark counts separately from its base letter. A displayed emoji sequence can also contain several scalar values. These methods do not provide grapheme cluster editing. No method silently normalizes text: composed and decomposed forms remain different values unless their encoded text is equal.

The native text operations validate UTF-8 before processing. Malformed input produces a runtime error rather than replacement characters, partial scalar values, or byte based fallback.

Search, splitting, and composition

Search is case sensitive and matches literal text. It does not interpret regular expressions or apply locale collation.

• find(needle) returns the first scalar index, or -1 when absent. An empty needle returns 0.
• contains, starts_with, and ends_with accept empty search text and return true for it.
• count(needle) counts nonoverlapping matches and requires a nonempty needle.
• split(separator) requires a nonempty literal separator and preserves empty fields, including leading and trailing fields. Splitting an empty String yields one empty field.
• replace(old, new) requires nonempty old and replaces all nonoverlapping occurrences. Inserted replacement text is not searched again.
• separator.join(parts) accepts a List whose every element is a String. Mixed Lists, null elements, and opaque values are rejected before producing a result. An empty List produces an empty String.

let fields = "sample,,control,".split(",")
print(fields)                // List("sample", "", "control", "")
print(" | ".join(fields))    // sample |  | control |
print("banana".count("ana")) // 1
print("banana".replace("ana", "X")) // bXna

repeat(count) requires a nonnegative Int64. Zero repetitions produce an empty String. concat(other) and + concatenate two Strings with the same validation and result limits. compare(other) returns -1, 0, or 1 using case sensitive ordinal ordering of Unicode scalar values. Valid UTF-8 preserves this ordering under byte comparison. There is no locale aware or natural number ordering.

Whitespace and casing

trim(), trim_start(), and trim_end() remove Unicode White_Space characters from the selected ends. They preserve internal whitespace. The property follows the bundled Unicode 17.0.0 Character Database; it does not treat every invisible formatting character as whitespace.

lower() and upper() apply full default Unicode case mappings, including length changing mappings and the context sensitive final sigma rule. casefold() applies full default case folding for caseless comparison. These operations use bundled Unicode 17.0.0 full case mappings and case folding data, and do not depend on the operating system's locale. They provide no language specific tailoring, locale parameter, or normalization.

print("  Straße  ".trim().upper()) // STRASSE
print("Straße".casefold() == "STRASSE".casefold()) // true

Case folding can change the text and its length. It does not make canonically equivalent composed and decomposed spellings equal. Preserve the original String when the displayed spelling is needed.

Methods

Arguments may be positional or named with the following labels. Receiver methods require a statically known String; use cast<String>(value) to recover that type from Any after inspecting it.

Time and space complexity

Let n be receiver UTF-8 bytes, m the other String or search pattern bytes, s replacement bytes, r result bytes, k result fields or joined parts, and p the sum of joined part bytes. Space includes newly owned results and auxiliary buffers beyond evaluated arguments.

Search uses a prefix table algorithm rather than repeated naive substring comparisons. Unicode table versions and bounded numeric widths are fixed for these bounds. A String occupies O(n) persistent storage. Current interpreter value evaluation can additionally copy owned String arguments; that copy is linear in their bytes. These native operation bounds do not imply a process memory quota or constant time indexing.

Error behavior and limits

Invalid UTF-8, invalid indices or intervals, empty split/count/replacement patterns, non String join elements, negative repetition, nonfinite Float64 conversion, and exceeded text limits produce R3201, located at the call or operator. Static receiver and argument type mismatches are rejected before execution.

Native text operations admit at most 16 MiB per input String or produced String and at most 262,144 split fields. The shared object heap's List object, value slot, and stored String budgets also apply to split results and join inputs. Bounds are checked before producing an oversized result. These per operation bounds are separate from overall process memory. A runtime failure follows the normal program or persistent session error contract.

Run the complete String example with:

aner check examples/string_basic.aner
aner examples/string_basic.aner

See Type inspection for the distinction between value type and element storage datatype.