Strings builtins

28 builtins of Soma 3.2.4 in the category Strings, with their exact signatures, as soma describe --builtins --json prints them.

• concat
• pad_left
• pad_right
• split
• replace
• contains
• starts_with
• ends_with
• lowercase
• uppercase
• trim
• sha256
• hmac_sha256
• random_token
• secure_eq
• format
• fields
• index_of
• substring
• escape_html
• str_len
• str_at
• str_eq
• chr
• ord
• regex_count
• regex_match
• regex_replace

concat

concat(a, b) -> String | concat(a: List, b: List) -> List

Concatenate strings, or join two lists (numeric list + is elementwise, so this is THE list concat).

deterministic · replay: pure

Used in verified programs:

• web/blog_tags, line 28: let needle = concat(",", concat(tag, ","))
• web/feature_flags, line 57: return concat("beta=", concat(to_string(is_on("beta")),
• web/guestbook, line 38: rows = concat(rows, "<li><b>{name}</b>: {message}</li>")
• web/leaderboard, line 81: parts = push(parts, concat(row.player, concat(":", to_string(row.score))))

pad_left

pad_left(s, width: Int, fill?: String) -> String

Left-pad to width characters: pad_left("7", 4, "0") = "0007". Default fill is a space.

deterministic · replay: pure

pad_right

pad_right(s, width: Int, fill?: String) -> String

Right-pad to width characters.

deterministic · replay: pure

split

split(s: String, delim: String) -> List<String>

Split a string on a delimiter into a list of substrings.

deterministic · replay: pure

Used in verified programs:

• agents/tool_dispatcher, line 31: on wordcount(s: String) { to_string(len(split(s, " "))) }
• algorithms/edit_distance, line 14: let ca = split(a, "")
• algorithms/stack, line 34: for ch in split(s, "") {
• algorithms/word_count, line 18: for w in split(trim(text), " ") {

replace

replace(s: String, old: String, new: String) -> String

Replace every occurrence of old with new.

deterministic · replay: pure

Used in verified programs:

• text/anagram, line 19: let low = replace(lowercase(s), " ", "")
• text/template, line 22: out = replace(out, placeholder, vals[i])
• text/tokenizer, line 20: clean = replace(clean, ",", " ")

contains

contains(haystack: String, needle: String) -> Bool | contains(list: List, x) -> Bool | contains(m: Map, key) -> Bool

Substring test; list membership (structural equality); map key membership.

deterministic · replay: pure

Used in verified programs:

• agents/horde_audit, line 43: let risk = if contains(d.text, "terminate at will") { "high" } else { "low" }
• agents/sentiment_router, line 25: if contains(m, "love") || contains(m, "great") || contains(m, "good") { return "positive" }
• agents/triage_agent, line 32: if contains(t, "broken") || contains(t, "down") { return "high" }
• records/json_roundtrip, line 41: assert contains(as_json(), "ada") == true

starts_with

starts_with(s: String, prefix: String) -> Bool

True if s begins with prefix.

deterministic · replay: pure

Used in verified programs:

• energy/load_shedding, line 63: if starts_with(k, "{xf}/") {
• governance/amendment, line 90: if starts_with(k, "{amendment}:") { n = n + 1 }
• governance/sealed_bids, line 93: if starts_with(k, "{tender}:") { n = n + (bid_count.get(k) ?? 0) }
• governance/three_readings, line 106: if starts_with(k, "{ord}:") { n = n + (logged.get(k) ?? 0) }

ends_with

ends_with(s: String, suffix: String) -> Bool

True if s ends with suffix.

deterministic · replay: pure

lowercase

lowercase(s: String) -> String

Lowercase the string (non-strings are stringified first).

deterministic · replay: pure

Used in verified programs:

• agents/sentiment_router, line 24: let m = lowercase(msg)
• agents/triage_agent, line 31: let t = lowercase(text)
• skeleton/triage_agent, line 48: if contains(lowercase(to_string(answer)), "urgent") { return "urgent" }
• text/anagram, line 19: let low = replace(lowercase(s), " ", "")

uppercase

uppercase(s: String) -> String

Uppercase the string (non-strings are stringified first).

deterministic · replay: pure

Used in verified programs:

• agents/tool_dispatcher, line 25: on upper(s: String) { uppercase(s) }
• text/acronym, line 21: out = out + uppercase(substring(w, 0, 1))
• text/title_case, line 19: let head = uppercase(substring(word, 0, 1))

trim

trim(s: String) -> String | trim(s: String, chars: String) -> String

Strip leading and trailing whitespace — or any of the characters in chars (Go's strings.Trim(s, cutset)).

deterministic · replay: pure

Used in verified programs:

• algorithms/word_count, line 18: for w in split(trim(text), " ") {
• web/contact_form, line 21: if trim(name) == "" { errors = push(errors, "name is required") }
• web/guestbook, line 18: if trim(name) == "" { return response(400, map("error", "name required")) }

sha256

sha256(s: String) -> String

SHA-256 of the text, as 64 hex characters (store sha256(salt + password) or better an hmac_sha256 with a server secret, never the password).

deterministic · replay: pure

hmac_sha256

hmac_sha256(key: String, message: String) -> String

HMAC-SHA-256 as hex: sign a session cookie or a webhook payload with a server secret.

deterministic · replay: pure

random_token

random_token(bytes?: Int) -> String

Cryptographically secure random bytes from the OS, as hex (default 32 bytes = 64 characters): session tokens, API keys, salts. random() is NOT for secrets.

not deterministic · replay: nondeterministic: replay reports it as a divergence source

secure_eq

secure_eq(a: String, b: String) -> Bool

Constant-time equality for secrets (tokens, signatures): == returns early and leaks a prefix by timing.

deterministic · replay: pure

format

format(fmt: String, args...) -> String

printf subset: %d %s %f %.2f %8.2f %e %.3e %3d %-8s %05d %% — %e is C-style scientific (6.022000e+23); widths, precision (rounded half away from zero on the decimal text), left-align with '-', zero-pad with '0'.

deterministic · replay: pure

fields

fields(s: String) -> List<String>

Split on any run of whitespace, no empty pieces (Go's strings.Fields; split(s, " ") keeps empties).

deterministic · replay: pure

index_of

index_of(s: String, sub: String) -> Int  |  index_of(xs: List, x) -> Int

Character index of the first occurrence of sub in a String, or the position of the first element equal to x in a List; -1 if absent.

deterministic · replay: pure

Used in verified programs:

• text/caesar, line 24: let pos = index_of(alpha, c)
• text/rot13, line 22: let lp = index_of(lower, c)
• text/substring_search, line 35: return index_of(haystack, needle)

substring

substring(s: String, start: Int, end: Int) -> String

Character-based slice [start, end) — both indexes are clamped to 0..len(s), end exclusive. A negative end gives an empty string; use slice() for indexes relative to the end.

deterministic · replay: pure

Used in verified programs:

• text/acronym, line 21: out = out + uppercase(substring(w, 0, 1))
• text/substring_search, line 24: if substring(haystack, i, i + m) == needle {
• text/title_case, line 19: let head = uppercase(substring(word, 0, 1))

escape_html

escape_html(s: String) -> String

Escape &, <, >, double and single quotes for safe HTML embedding.

deterministic · replay: pure

Used in verified programs:

• web/guestbook, line 19: let entry = map("name", escape_html(name), "message", escape_html(message), "at", now())
• web/site_router, line 19: let safe = escape_html(name)

str_len

str_len(s: String) -> Int

Byte length of a string (cf. len(), which counts characters).

deterministic · replay: pure

str_at

str_at(s: String, i: Int) -> Int

Byte value at index i; errors if out of range.

deterministic · replay: pure

str_eq

str_eq(a: String, b: String) -> Bool

Exact string equality (fast path for [native] code).

deterministic · replay: pure

chr

chr(n: Int) -> String

The character with code point n: chr(65) == "A". Raises kind range outside 0..0x10FFFF or for surrogate code points.

deterministic · replay: pure

ord

ord(s: String) -> Int

Code point of the first character: ord("A") == 65.

deterministic · replay: pure

regex_count

regex_count(text: String, pattern: String) -> Int

Number of non-overlapping matches (Rust regex syntax). Same in [native] (pattern must be a literal there).

deterministic · replay: pure

regex_match

regex_match(text: String, pattern: String) -> Int

1 when the pattern matches anywhere in text, else 0.

deterministic · replay: pure

regex_replace

regex_replace(text: String, pattern: String, replacement: String) -> String

Replace every match; $1 refers to the first capture group.

deterministic · replay: pure