str

Text: length, search, slices, case, padding, trimming, and splitting, with literal strings rather than patterns. Indices count scalars, not bytes, UTF-16 units, or grapheme clusters; no operation splits a scalar, normalizes text, or applies locale-dependent behavior. lin functions run once for each combination of their arguments’ Values.

Write these names after str::, as in str::length.

length

def lin length(text: str): num

Counts Unicode scalar values, not UTF-16 code units or grapheme clusters.

at

def at(text! str, index! num)? str

Returns the scalar at a zero-based index, or an empty Bag beyond the end. The index must be a nonnegative safe integer; otherwise fails with Conflict.

slice

def slice(text! str, start! num, end? num)! str

Returns the half-open scalar interval [start, end). Pass {} for the string’s end. Supplied indices must be nonnegative safe integers, or fail with Conflict. After validation, endpoints clamp to the length; reversed intervals return "".

code_point

def lin code_point(text: str): num

Returns the Unicode scalar value of a one-scalar string: str::code_point("😀") is 128512. Empty text or text with more than one scalar fails with Conflict.

from_code_point

def lin from_code_point(value: num): str

Returns the one-scalar string for a Unicode scalar value, inverting code_point. Values other than integers from U+0000 through U+10FFFF, excluding surrogates U+D800 through U+DFFF, fail with Conflict.

contains

def lin contains(text: str, needle: str): bool

True when the literal needle occurs anywhere in the text; an empty needle always matches.

starts_with

def lin starts_with(text: str, prefix: str): bool

True when the text starts with the literal prefix; an empty prefix always matches.

ends_with

def lin ends_with(text: str, suffix: str): bool

True when the text ends with the literal suffix; an empty suffix always matches.

find

def find(text! str, needle! str)? num

Returns the first matching Unicode scalar index, or an empty Bag when absent. Searching for "" returns zero.

strip_prefix

def strip_prefix(text! str, prefix! str)? str

Removes a matching literal prefix, or returns an empty Bag when unmatched. An empty prefix returns the original text.

strip_suffix

def strip_suffix(text! str, suffix! str)? str

Removes a matching literal suffix, or returns an empty Bag when unmatched. An empty suffix returns the original text.

split

def split(text! str, separator! str)* num -> str

Splits on a literal separator into consecutive zero-based indexed pieces. Preserves empty and repeated pieces: str::split("a,a,", ",") yields {0 -> "a", 1 -> "a", 2 -> ""}. An empty input yields 0 -> "". An empty separator yields one piece per Unicode scalar, or an empty Bag for empty input. Indices describe correspondence, not Bag enumeration order.

join

def join(pieces* num -> str, separator! str)! str

Concatenates pieces in ascending key order with the separator between occurrences; inverts split. Equal keys order by piece; each occurrence repeats its piece. Keys need not be consecutive or integral. An empty Bag yields "". pieces is read as a whole Bag, not one Value at a time.

format

def lin format[set T](value: T): str

Formats any value for readable display. Nested strings are quoted; top-level strings are not. This is display text, not reversible source or archive serialization.

quote

def lin quote(text: str): str

Returns a complete Saka string literal with quotes and escaped contents.

repeat

def lin repeat(text: str, count: num): str

Repeats text a nonnegative safe-integer number of times.

pad_start

def lin pad_start(text: str, width: num, fill: str): str

Pads to a minimum Unicode-scalar width using a nonempty repeated fill. Never splits a scalar; invalid widths or an empty fill fail with Conflict.

pad_end

def lin pad_end(text: str, width: num, fill: str): str

Pads at the end to a minimum Unicode-scalar width using a nonempty repeated fill. Never splits a scalar; invalid widths or an empty fill fail with Conflict.

concat

def lin concat(left: str, right: str): str

Concatenates the two scalar sequences without normalization.

replace

def lin replace(text: str, needle: str, replacement: str): str

Replaces the first literal match, or returns the original text when absent. Replacement text is literal, including $ and backslashes. An empty needle fails with Conflict.

replace_all

def lin replace_all(text: str, needle: str, replacement: str): str

Replaces left-to-right nonoverlapping literal matches, or returns the original text when absent. Replacement text is literal, including $ and backslashes. An empty needle fails with Conflict.

trim

def lin trim(text: str): str

Removes prelude wspace scalars from both ends.

trim_start

def lin trim_start(text: str): str

Removes prelude wspace scalars from the start.

trim_end

def lin trim_end(text: str): str

Removes prelude wspace scalars from the end.

lower_ascii

def lin lower_ascii(text: str): str

Changes only ASCII A–Z to a–z; all other scalars remain unchanged.

upper_ascii

def lin upper_ascii(text: str): str

Changes only ASCII a–z to A–Z; all other scalars remain unchanged.