Types and conversion builtins

10 builtins of Soma 3.2.4 in the category Types and conversion, with their exact signatures, as soma describe --builtins --json prints them.

• len
• to_string
• to_int
• to_float
• to_json
• from_json
• type_of
• is_type
• is_a
• fail

len

len(x: String|List|Map) -> Int

Characters of a string, elements of a list, or entries of a map.

deterministic · replay: pure

Used in verified programs:

• aerospace/launch_commit, line 62: let total = len(lcc_names())
• agents/approval_gate, line 49: map("status", "done", "version", version, "count", len(history))
• agents/horde_audit, line 35: return map("reviewed", len(verdicts), "high", len(high), "failed", len(failures))
• agents/horde_rounds, line 59: assert len(Market.report()) == 3

to_string

to_string(x) -> String

Render any value with its display formatting.

deterministic · replay: pure

Used in verified programs:

• agents/approval_gate, line 36: let id = to_string(next_id())
• agents/bounded_retry, line 25: let id = to_string(next_id())
• agents/budget_guard, line 30: let id = to_string(next_id())
• agents/guarded_agent, line 40: let id = to_string(next_id())

to_int

to_int(x) -> Int

Convert to Int (floats truncate, strings parse, BigInt-exact); returns () on failure.

deterministic · replay: pure

Used in verified programs:

• games/blackjack, line 25: _ -> to_int(rank)
• text/run_length, line 48: let reps = to_int(num)
• web/leaderboard, line 60: {method: "GET", path: "/top/" + n} -> leaders(to_int(n))

to_float

to_float(x) -> Float

Convert to Float; returns () if a string fails to parse.

deterministic · replay: pure

Used in verified programs:

• math/integration, line 25: let h = (b - a) / to_float(n)
• math/monte_carlo_pi, line 26: return 4.0 * to_float(inside) / to_float(samples)
• math/series, line 26: term = term / to_float(k)
• math/statistics, line 22: return to_float(sum(xs)) / to_float(len(xs))

to_json

to_json(x) -> String

Serialize a value as JSON (strings escaped, NaN/inf become null).

deterministic · replay: pure

Used in verified programs:

• records/json_roundtrip, line 19: return to_json(make())
• web/guestbook, line 20: book.push(to_json(entry))
• web/webhook_log, line 19: events.push(to_json(ev))

from_json

from_json(s: String) -> Any

Parse a JSON string into a Map/List/scalar; maps and lists pass through. Invalid JSON RAISES (kind "json") — wrap LLM output in try { from_json(s) }.

deterministic · replay: pure

Used in verified programs:

• records/json_roundtrip, line 23: return from_json(as_json())
• services/payments_approval, line 122: let p = from_json(body)
• services/refund_agent, line 110: let j = try { from_json(raw) }
• services/warehouse_reservations, line 137: let b = from_json(body)

type_of

type_of(x) -> String

Type name: "Int" (any size), "Float", "String", "Bool", "List", "Map", "Function", "Variant", or "Unit".

deterministic · replay: pure

Used in verified programs:

• records/shapes_typed, line 43: assert type_of(circle(1)) == "Map"
• services/refund_agent, line 111: if j.error != () || type_of(j.value) != "Map" { return Escalate { reason: "unreadable decision" } }

is_type

is_type(value: Map, type_name: String) -> Bool

True if a record's _type field equals type_name, or if value is a variant of that name or of the sum type of that name (is_a(Box { w: 1 }, "Box") and is_a(Box { w: 1 }, "Shape")); read a variant's fields with match.

deterministic · replay: pure

Used in verified programs:

• records/shapes_typed, line 31: return is_type(shape, "Circle")

is_a

is_a(value: Map, type_name: String) -> Bool

Alias of is_type.

deterministic · replay: pure

Used in verified programs:

• data/record_pipeline, line 36: assert is_a(Person { name: "x", dept: "d", salary: 1, level: 1 }, "Person") == true
• math/complex, line 60: assert is_a(Complex { re: 1.0, im: 0 }, "Complex")
• records/json_roundtrip, line 29: return is_a(reparse(), "Profile")
• records/shapes_typed, line 18: if is_a(shape, "Circle") { return "circle" }

fail

fail(kind: String, detail?) -> never | fail(r: TryResult) -> never

Raise a domain error. try { f() } yields {value, error, kind, detail}: branch on r.kind ("not_found", "invalid_transition", "guard_failed", "invariant", a require … else Tag tag, …); fail(r) re-raises a caught error unchanged.

deterministic · replay: pure

Used in verified programs:

• services/payments_approval, line 67: if amounts.get(id) != () { fail("conflict", "payment {id} already exists") }
• services/refund_agent, line 55: if o == () { fail("not_found", "order {order_id}") }
• services/warehouse_reservations, line 88: if skus.get(id) != () { fail("conflict", "reservation {id} exists") }
• skeleton/turnstile_any_edge, line 44: _ -> fail("UnknownAction", "'{action}' is not coin, push or kick")