strings
String inspection, search, and transformation for general text work. Covers length and character-class predicates, case conversion, find/contains/split/join, trim, replace, pad, runtime format templates, and escape helpers for HTML, shell, JSON, and regex. CX strings are UTF-8 and most operations are Unicode-aware: indexing, length, and slicing are codepoint-positioned, case folding follows Unicode tables, and predicates use Unicode categories. For byte-level work see cx-stdlib/bytes; for regex see cx-stdlib/re.
strings:length
[$strings:length] -> int — Count the codepoints (Unicode scalar values) in a string.
[?lib 'cx-stdlib/strings']
[$strings:length "héllo"]
5
strings:length-bytes
[$strings:length-bytes] -> int — Count the UTF-8 bytes in a string.
[?lib 'cx-stdlib/strings']
[$strings:length-bytes "héllo"]
6
strings:is-empty
[$strings:is-empty] -> bool — Report whether a string has zero length.
[?lib 'cx-stdlib/strings']
[$strings:is-empty ""]
true
strings:at
[$strings:at] -> string — Return the single-character substring at a codepoint position; raises if out of bounds.
[?lib 'cx-stdlib/strings']
[$strings:at "héllo" 2]
'é'
strings:slice
[$strings:slice] -> string — Extract a half-open substring by codepoint range; bounds are clamped.
[?lib 'cx-stdlib/strings']
[$strings:slice "héllo" 2 4]
'éll'
strings:reverse
[$strings:reverse] -> string — Reverse a string by extended grapheme cluster (UAX #29), so a combining mark stays on its letter.
[?lib 'cx-stdlib/strings']
[$strings:reverse "héllo"]
'olléh'
strings:graphemes
[$strings:graphemes] -> [sequence string] — Split a string into its extended grapheme clusters (UAX #29) — what a reader sees as one character: a letter with its combining marks, a flag's regional-indicator pair, an emoji ZWJ sequence. The empty string has none.
[?lib 'cx-stdlib/strings']
[$strings:graphemes "Würst"]
(W, 'ü', r, s, t)
strings:windows
[$strings:windows] -> [sequence string] — The substrings of K consecutive code points, in order — a sequence's k-mers. K below 1 or past the length is the empty sequence. A [?for], [?reduce] or [$count] reading the windows holds one at a time, never the list.
[?lib 'cx-stdlib/strings']
[$strings:windows "ACGTA" 2]
(AC, CG, GT, TA)
strings:chunks
[$strings:chunks] -> [sequence string] — The pieces of K consecutive code points, in order, the last shorter — a text in fixed-width lines (reverse-complement's 60-letter lines). K below 1 or an empty string is the empty sequence. A [?for], [?reduce] or [$count] reading the pieces holds one at a time.
[?lib 'cx-stdlib/strings']
[$strings:chunks "ABCDEFG" 3]
(ABC, DEF, G)
strings:code-point
[$strings:code-point] -> int — The Unicode code point (scalar value) of a one-code-point string; a string of zero code points or of more than one refuses CXER2906 as a value.
[?lib 'cx-stdlib/strings']
[$strings:code-point "A"]
65
strings:from-code-point
[$strings:from-code-point] -> string — The one-character string of a Unicode scalar value; a negative int, one past 0x10FFFF or a surrogate (0xD800 to 0xDFFF) refuses CXER2907 as a value.
[?lib 'cx-stdlib/strings']
[$strings:from-code-point 233]
'é'
strings:translate
[$strings:translate] ($s::string, $from::string, $to::string) | ($s::string, $table::map) -> string — Map each character through a table: by position, each code point of $s found in $from becomes the code point at the same position of $to (equal code-point lengths; a repeated $from code point takes its first position); or through a {char: replacement} map whose replacement may be '' (delete). A character the table does not name is kept; a malformed table refuses CXER2908 as a value.
[?lib 'cx-stdlib/strings']
[$strings:translate "GATTACA" "AGCT" "UCGA"]
CUAAUGU
strings:contains
[$strings:contains] -> bool — Report whether a string contains the given substring.
[?lib 'cx-stdlib/strings']
[$strings:contains "foobar" "oba"]
true
strings:find
[$strings:find] -> int — Return the codepoint index of the first occurrence of a substring, or -1 if absent.
[?lib 'cx-stdlib/strings']
[$strings:find "héllo" "llo"]
3
strings:find-from
[$strings:find-from] -> int — Find the first occurrence of a substring at or after a starting index, or -1 if absent.
[?lib 'cx-stdlib/strings']
[$strings:find-from "abcabc" "bc" 3]
5
strings:rfind
[$strings:rfind] -> int — Return the codepoint index of the last (right-to-left) occurrence of a substring, or -1 if absent.
[?lib 'cx-stdlib/strings']
[$strings:rfind "abcabc" "bc"]
5
strings:starts-with
[$strings:starts-with] -> bool — Report whether a string begins with the given prefix.
[?lib 'cx-stdlib/strings']
[$strings:starts-with "foobar" "foo"]
true
strings:ends-with
[$strings:ends-with] -> bool — Report whether a string ends with the given suffix.
[?lib 'cx-stdlib/strings']
[$strings:ends-with "foobar" "bar"]
true
strings:count
[$strings:count] -> int — Count non-overlapping occurrences of a substring.
[?lib 'cx-stdlib/strings']
[$strings:count "aaaa" "aa"]
2
strings:find-all
[$strings:find-all] -> [sequence int] — Return the codepoint indices of every non-overlapping occurrence of a substring.
[?lib 'cx-stdlib/strings']
[$strings:find-all "abcabc" "bc"]
(2, 5)
strings:upper
[$strings:upper] -> string — Upper-case a string using Unicode default case tables (locale-independent).
[?lib 'cx-stdlib/strings']
[$strings:upper "hello"]
HELLO
strings:lower
[$strings:lower] -> string — Lower-case a string using Unicode default case tables (locale-independent).
[?lib 'cx-stdlib/strings']
[$strings:lower "HeLLo"]
hello
strings:title
[$strings:title] -> string — Title-case a string at Unicode UAX #29 word boundaries.
[?lib 'cx-stdlib/strings']
[$strings:title "jean-paul sartre"]
'Jean-Paul Sartre'
strings:capitalize
[$strings:capitalize] -> string — Upper-case the first character (as upper maps it) and leave the rest unchanged; the empty string stays empty.
[?lib 'cx-stdlib/strings']
[$strings:capitalize "ten green bottles"]
'Ten green bottles'
strings:case-fold
[$strings:case-fold] -> string — Produce the canonical case-folded form for case-insensitive comparison.
[?lib 'cx-stdlib/strings']
[$strings:case-fold "STRAßE"]
strasse
strings:swap-case
[$strings:swap-case] -> string — Swap the case of each cased character, upper to lower and lower to upper.
[?lib 'cx-stdlib/strings']
[$strings:swap-case "Hello World"]
'hELLO wORLD'
strings:upper-locale
[$strings:upper-locale] -> string — Upper-case a string with locale-aware rules (e.g. Turkish dotted-i).
[?lib 'cx-stdlib/strings']
[$strings:upper-locale "abc" "en"]
ABC
strings:lower-locale
[$strings:lower-locale] -> string — Lower-case a string with locale-aware rules (e.g. Turkish dotted-i).
[?lib 'cx-stdlib/strings']
[$strings:lower-locale "ABC" "en"]
abc
strings:trim
[$strings:trim] -> string — Strip Unicode whitespace from both ends of a string.
[?lib 'cx-stdlib/strings']
[$strings:trim " hi "]
hi
strings:trim-start
[$strings:trim-start] -> string — Strip Unicode whitespace from the start of a string.
[?lib 'cx-stdlib/strings']
[$strings:trim-start " hi "]
'hi '
strings:trim-end
[$strings:trim-end] -> string — Strip Unicode whitespace from the end of a string.
[?lib 'cx-stdlib/strings']
[$strings:trim-end " hi "]
' hi'
strings:trim-chars
[$strings:trim-chars] -> string — Strip any of the given characters from both ends of a string.
[?lib 'cx-stdlib/strings']
[$strings:trim-chars "<<hi>>" "<>"]
hi
strings:trim-start-chars
[$strings:trim-start-chars] -> string — Strip any of the given characters from the start of a string.
[?lib 'cx-stdlib/strings']
[$strings:trim-start-chars "xxhi" "x"]
hi
strings:trim-end-chars
[$strings:trim-end-chars] -> string — Strip any of the given characters from the end of a string.
[?lib 'cx-stdlib/strings']
[$strings:trim-end-chars "hixx" "x"]
hi
strings:split
[$strings:split] -> [sequence string] — Split a string on each occurrence of a separator, one part more than there are separators (the empty text is one empty part); empty separator splits every character.
[?lib 'cx-stdlib/strings']
[$strings:split "a,b,c" ","]
(a, b, c)
strings:split-limit
[$strings:split-limit] -> [sequence string] — Split a string on a separator into at most max+1 segments.
[?lib 'cx-stdlib/strings']
[$strings:split-limit "a,b,c,d" "," 2]
(a, b, 'c,d')
strings:split-lines
[$strings:split-lines] -> [sequence string] — Split a string into lines on LF, CRLF, or CR; a trailing empty line is dropped.
[?lib 'cx-stdlib/strings']
[$strings:split-lines "a\nb\r\nc\rd"]
(a, b, c, d)
strings:split-whitespace
[$strings:split-whitespace] -> [sequence string] — Split a string on runs of Unicode whitespace, collapsing consecutive whitespace.
[?lib 'cx-stdlib/strings']
[$strings:split-whitespace " a b \t c "]
(a, b, c)
strings:join
[$strings:join] -> string — Concatenate a sequence of scalars, inserting the separator between each — a string as written, any other scalar as its text ([\$concat]); an err member is the answer and a member with no text refuses.
[?lib 'cx-stdlib/strings']
[$strings:join ("a", "b", "c") "-"]
a-b-c
strings:replace
[$strings:replace] -> string — Replace every occurrence of a substring with another.
[?lib 'cx-stdlib/strings']
[$strings:replace "a.b.c" "." "-"]
a-b-c
strings:replace-first
[$strings:replace-first] -> string — Replace only the first occurrence of a substring with another.
[?lib 'cx-stdlib/strings']
[$strings:replace-first "a.b.c" "." "-"]
'a-b.c'
strings:replace-n
[$strings:replace-n] -> string — Replace at most the first n occurrences of a substring with another.
[?lib 'cx-stdlib/strings']
[$strings:replace-n "a.b.c.d" "." "-" 2]
'a-b-c.d'
strings:replace-exactly
[$strings:replace-exactly] -> string — Fail-loud surgical replace: from MUST occur exactly once, else an [err cx-err:CXER2903] value (no silent no-op on a miss, no over-replace on ambiguity). The safety the harness Edit tool gives, for in-CX text edits.
[?lib 'cx-stdlib/strings']
[$strings:replace-exactly "a.b.c" "b" "X"]
'a.X.c'
strings:pad-start
[$strings:pad-start] -> string — Left-pad a string with a fill string until it reaches the target width.
[?lib 'cx-stdlib/strings']
[$strings:pad-start "abc" 10 "0"]
'0000000abc'
strings:pad-end
[$strings:pad-end] -> string — Right-pad a string with a fill string until it reaches the target width.
[?lib 'cx-stdlib/strings']
[$strings:pad-end "abc" 6 "."]
'abc...'
strings:center
[$strings:center] -> string — Center a string within the target width, padding both sides with a fill string.
[?lib 'cx-stdlib/strings']
[$strings:center "hi" 6 "*"]
'**hi**'
strings:repeat
[$strings:repeat] -> string — Concatenate n copies of a string.
[?lib 'cx-stdlib/strings']
[$strings:repeat "ab" 3]
ababab
strings:is-ascii
[$strings:is-ascii] -> bool — Report whether every character is ASCII (empty string is true).
[?lib 'cx-stdlib/strings']
[$strings:is-ascii "hello"]
true
strings:is-digit
[$strings:is-digit] -> bool — Report whether the text is non-empty and every character is a Unicode digit (empty string is false).
[?lib 'cx-stdlib/strings']
[$strings:is-digit "12345"]
true
strings:is-alpha
[$strings:is-alpha] -> bool — Report whether the text is non-empty and every character is a Unicode letter (empty string is false).
[?lib 'cx-stdlib/strings']
[$strings:is-alpha "abcDEF"]
true
strings:is-alphanumeric
[$strings:is-alphanumeric] -> bool — Report whether the text is non-empty and every character is a Unicode letter or digit (empty string is false).
[?lib 'cx-stdlib/strings']
[$strings:is-alphanumeric "abc123"]
true
strings:is-whitespace
[$strings:is-whitespace] -> bool — Report whether the text is non-empty and every character is Unicode whitespace (empty string is false).
[?lib 'cx-stdlib/strings']
[$strings:is-whitespace " \t\n"]
true
strings:is-upper
[$strings:is-upper] -> bool — Report whether the text has a cased letter and every cased character is upper-case (empty or caseless text is false).
[?lib 'cx-stdlib/strings']
[$strings:is-upper "ABC"]
true
strings:is-lower
[$strings:is-lower] -> bool — Report whether the text has a cased letter and every cased character is lower-case (empty or caseless text is false).
[?lib 'cx-stdlib/strings']
[$strings:is-lower "abc"]
true
strings:is-blank
[$strings:is-blank] -> bool — Report whether a string is empty or contains only whitespace.
[?lib 'cx-stdlib/strings']
[$strings:is-blank " "]
true
strings:format
[$strings:format] -> string — Substitute positional and named placeholders in a template with the given args; a placeholder spec takes a fill, an alignment (< > ^), a zero flag, a width, a precision and a type char (d f s b o x X e E), e.g. {:02}, {:*>8}, {:.3f} or {:.4e}; the type chars b, o, x and X write an int or a bigint in base 2, 8 or 16, e.g. {:08b}.
[?lib 'cx-stdlib/strings']
[$strings:format "Hello, {}! You have {} messages." ("Alice", 5)]
'Hello, Alice! You have 5 messages.'
strings:to-radix
[$strings:to-radix] -> string — Write an int or a bigint in a base from 2 to 36 — lowercase digits, no prefix, a negative as - then the magnitude's digits; a base outside 2..36 refuses CXER0100. The reverse is to-int with a base.
[?lib 'cx-stdlib/strings']
[$strings:to-radix 255 2]
'11111111'
strings:escape-html
[$strings:escape-html] -> string — Escape the five HTML metacharacters & < > double-quote and single-quote.
[?lib 'cx-stdlib/strings']
[$strings:escape-html "<a href=\"x\">&'"]
'<a href="x">&''
strings:unescape-html
[$strings:unescape-html] -> string — Decode numeric and HTML5 named character references back to text.
[?lib 'cx-stdlib/strings']
[$strings:unescape-html "a…b—c©"]
'a…b—c©'
strings:escape-shell
[$strings:escape-shell] -> string — Quote a string for safe use as a single POSIX shell argument.
strings:escape-json
[$strings:escape-json] -> string — Apply JSON string escapes to a string.
[?lib 'cx-stdlib/strings']
[$strings:escape-json "a\"b"]
'a\\"b'
strings:escape-regex
[$strings:escape-regex] -> string — Escape regex metacharacters so a string matches literally.
[?lib 'cx-stdlib/strings']
[$strings:escape-regex "a.b*c"]
'a\.b\*c'
strings:to-number
[$strings:to-number] -> [or number bigint absence] — Parse a locale-free numeric string into the number the same numeral reads as in cx source — an int for integer syntax (a bigint past int64), an exact decimal for a fixed-point fraction ("0.10" stays 0.10), a float for an exponent form or a trailing dot ("1e3", "5."); use to-float for an explicit float. Surrounding whitespace is trimmed; a non-numeric input (trailing junk, grouping separators, empty) yields the absence channel () rather than a silent string passthrough, so callers branch with [?else]. For grouping / Unicode digits use cx-stdlib/locale.
[?lib 'cx-stdlib/strings']
[$strings:to-number "3.07"]
3.07
strings:to-int
[$strings:to-int] -> [or int bigint absence] — Parse a locale-free integer string (optional sign, ASCII digits) into an int, or the bigint it spells past int64 (never clamped); fractional or exponent syntax ("3.07", "1e3") and non-numeric input yield the absence channel (). An optional second argument names the base, 2 to 36 (default 10): the digits read case-insensitively after an optional sign and the base's own prefix (0b, 0o, 0x), e.g. [$strings:to-int "ff" 16] is 255; a base outside 2..36 refuses CXER0100.
[?lib 'cx-stdlib/strings']
[$strings:to-int "42"]
42
strings:to-float
[$strings:to-float] -> [or float absence] — Parse any locale-free numeric string into a float ("5" -> 5.0); a non-numeric input yields the absence channel ().
[?lib 'cx-stdlib/strings']
[$strings:to-float "5"]
5.0e0