Text
Text is an immutable sequence of Unicode scalars. Indices, lengths, and
widths count scalars rather than bytes or UTF-16 code units. Operations do not
implicitly normalize text or apply locale-sensitive rules.
Constants and shape
empty
The empty text value, equivalent to "".
length
Returns the number of Unicode scalars in O(n).
isEmpty
Returns True only for empty text. This is constant-time at the API boundary.
uncons
Returns the first scalar and remaining text as Just, or Nothing for empty
text. This is constant-time at the API boundary.
Access and slicing
at
Returns the scalar at a zero-based index. Negative and out-of-range indices
return Nothing. The cost is linear in the traversed prefix.
take
Returns at most the first count scalars. Negative counts clamp to zero. The
cost is linear in the returned prefix.
drop
Skips at most the first count scalars. Negative counts clamp to zero. The
cost is linear in the skipped prefix.
slice
Drops start scalars and then takes count scalars. Negative starts and counts
clamp to zero. The cost is linear in the traversed prefix and output.
Construction
append
Returns the first text followed by the second. The cost is linear in the resulting text size.
appendChar
Appends one scalar to the end of the text.
fromChars
Constructs text from scalars in list order in O(n).
repeat
Repeats text count times. Non-positive counts return empty in O(1)
time and temporary space. For positive counts, time and temporary space are
linear in the repetition count plus the output size.
concat
Concatenates fragments in list order without a repeated pairwise-append chain. The cost is linear in fragment count and total output.
join
Places the delimiter between adjacent fragments and concatenates them. No delimiter appears before the first or after the last fragment.
Conversion and traversal
toChars
Returns the Unicode scalars in source order in O(n).
reverse
Reverses by Unicode scalar, not by grapheme cluster, in O(n).
Search
startsWith
Tests whether the second argument begins with the prefix supplied first. An
empty prefix always matches. The cost is O(m) in the prefix length.
endsWith
Tests whether the second argument ends with the suffix supplied first. An empty suffix always matches. The implementation traverses the text to find the suffix boundary.
contains
Tests whether the second argument contains the needle supplied first. An empty
needle matches. Naive search is O(n × m) worst case.
find
Returns the scalar index of the first left-to-right match, or Nothing. An
empty needle returns Just 0. Naive search is O(n × m) worst case.
Splitting
split
Splits the second argument at non-overlapping occurrences of the delimiter supplied first. An empty delimiter produces one text value per scalar.
Example: split "" "ab" produces ["a", "b"].
lines
Splits lines at LF, CRLF, or CR. Line terminators are excluded. Empty input
returns [], and a trailing terminator does not add a final empty line.
words
Splits at runs of Unicode whitespace and omits empty words. Traversal is
O(n).
Replacement and cleanup
replaceAll
Replaces non-overlapping matches of the first argument with the second in the
third argument, scanning left to right. An empty needle returns the input
unchanged. Naive replacement is O(n × m) plus output work.
trim
Removes Unicode whitespace from both ends in O(n).
trimStart
Removes Unicode whitespace from the beginning and leaves trailing whitespace unchanged.
trimEnd
Removes Unicode whitespace from the end and leaves leading whitespace unchanged.
Padding
padLeft
Prepends the padding scalar until the text reaches the requested scalar width. If the text is already wide enough, it is returned unchanged.
padRight
Appends the padding scalar until the text reaches the requested scalar width. If the text is already wide enough, it is returned unchanged.
Literal spelling and escapes are defined by the lexical grammar. Use Char for single-scalar classification and case mapping.
map
Transforms Unicode scalars and returns Text. The callback is the first argument
and must return Char. The implementation converts to scalars, maps once, and
rebuilds Text in linear time. For another element type, use the Prelude's generic
map change (Text::toChars text) to produce a List.