std::literals
Typed literals: a type name written against a string, as
Date"2026-05-04", Regex`\d+` or
Sql"SELECT * FROM users WHERE id = ${id}". The prefix type decides what
the text means by implementing one of two interfaces from this module.
Literal: the literal is a call of the type’sfrom_fragments, which gets the text as a list ofFragments and returns whatever type the impl chooses, usually aResult. A literal with a${...}slot calls it when the program runs. A literal without slots, in any quotes, has fixed text, so the compiler callsfrom_fragmentswhile it checks the program: when it returns aResult, anErris a compile error and the literal is theOkvalue. std::calendar’sDate, std::regex’sRegexand std::sql’sSqlwork this way.CheckedLiteral:checkreads the literal’s text around its slots while the program is checked, andbuildmakes the value when it runs. The literal is the value in every quote style, slots included, never aResult.checkrefuses text with aLiteralError, which names the character the compile error points at. std::url’sUrland std::toml’sTomlwork this way.
A type implements one of the two, never both. Choose CheckedLiteral
when the text alone tells whether every slot value will build, as a URL’s
does: a slot in its path is escaped as one segment whatever it holds.
std::literals::testing’s build_each tests that a build keeps to this.
A program’s own type gets literals from an impl:
import std::literals.{Fragment, Literal} pub struct Box contents: String end impl Literal for Box fn from_fragments(fragments: List<Fragment<String>>) -> Box body = Iter.reduce(fragments, "", fn acc, frag -> case frag .Static(s) -> acc + s .Dynamic(v) -> acc + v end end) Box{contents: body} end end
Then Box"hello ${name}" is a Box. The full rules, including which
module may write these impls, are in spec §18 Typed literals.
Import with import std::literals.
Exports
Section titled “Exports”Types
Interfaces
enum Fragment
Section titled “enum Fragment”enum Fragment<T> Static String Dynamic T end
One piece of a typed literal’s text: a Static run of source text
between slots, or a Dynamic value from a ${...} slot. The list a
handler gets always alternates Static, Dynamic, ..., Static, and its
first and last Static are there even when empty: Box"a ${x}" is
[Static("a "), Dynamic(x), Static("")]. A backtick literal is one
Static. Programs rarely build a Fragment themselves; the literal’s
syntax builds the list, and a handler matches on it.
Fragment.inspect
Section titled “Fragment.inspect”impl Debug for Fragment<T>
fn inspect<T>(value: Fragment<T>) -> String where T: Debug
impl Debug.inspect
interface Literal
Section titled “interface Literal”interface Literal<I, R> fn from_fragments(fragments: List<Fragment<I>>) -> R end
The handler behind a typed literal. T"..." is a call of
T.from_fragments(fragments). I is what each ${...} slot’s value
must be: a concrete type such as String, or an interface such as
Display that each slot implements its own way. R is the literal’s
type, usually Result<T, E> for text that can be wrong, or T itself
for a handler that cannot fail. from_fragments takes no self: the
prefix type picks the handler.
A literal without slots is checked when the program is checked, so its
handler may not have effects, and when the handler returns Result<T, E>
the literal is a T. A literal with a slot is the Result, built when
the program runs.
impl Literal for Date fn from_fragments(fragments: List<Fragment<String>>) -> Result<Date, Error> ... end end
Literal.from_fragments
Section titled “Literal.from_fragments”fn from_fragments(fragments: List<Fragment<I>>) -> R
interface Literal
interface CheckedLiteral
Section titled “interface CheckedLiteral”interface CheckedLiteral<I, T> fn check(statics: List<String>) -> Result<Unit, LiteralError> fn check_type(statics: List<String>, arguments: List<String>) -> Result<Unit, LiteralError> fn build(fragments: List<Fragment<I>>) -> T end
The handler behind a checked literal: a typed literal that is a T in
every quote style, slots included, never a Result.
checkruns while the program is checked, once per literal. It gets the literal’s static text: then + 1pieces around itsnslots, in order, empty ones included. AnErris a compile error at the character itsLiteralErrornames.checkmay not have effects (output, files, the clock, tasks, an application field).check_typeis what the compiler runs, incheck’s place: the same statics, and a description of the literal’s type: each of its type arguments as Nomi spells it, in order. ARoute<{id: Uuid}>literal gets["{id: Uuid}"], aUrlone[]. The description is text, not the types themselves, which no value holds. Its default ischeck(statics), so a type whose text need not agree with its type arguments writes onlycheck.buildruns when the program runs and gets the fragmentsLiteral.from_fragmentswould get. It cannot fail: oncecheckaccepts the text, every slot value must build. Abuildthat traps anyway traps where the literal runs. std::literals::testing’sbuild_eachtests this.
A type implements Literal or CheckedLiteral, never both.
impl CheckedLiteral<Display, Url> for Url fn check(statics: List<String>) -> Result<Unit, LiteralError> ... end fn build(fragments: List<Fragment<Display>>) -> Url ... end end
CheckedLiteral.check
Section titled “CheckedLiteral.check”fn check(statics: List<String>) -> Result<Unit, LiteralError>
interface CheckedLiteral
CheckedLiteral.check_type
Section titled “CheckedLiteral.check_type”fn check_type(statics: List<String>, arguments: List<String>) -> Result<Unit, LiteralError>
interface CheckedLiteral
CheckedLiteral.build
Section titled “CheckedLiteral.build”fn build(fragments: List<Fragment<I>>) -> T
interface CheckedLiteral
struct LiteralError
Section titled “struct LiteralError”struct LiteralError fragment: Int offset: Int message: String end
Why CheckedLiteral.check refused a literal’s text, and where.
fragment is the index of the static the problem is in, and offset
counts code points into it as check received it; an offset at a
static’s end points at the ${ of the slot after it. The compile error
shows message there. When check cannot name a place, fragment 0 and
offset 0 put the error on the literal.
e = LiteralError{fragment: 1, offset: 4, message: "a slot cannot go here"}
assert "${e}" == "a slot cannot go here"
LiteralError.to_string
Section titled “LiteralError.to_string”impl Display for LiteralError
fn to_string(error: LiteralError) -> String
impl Display.to_string
LiteralError.inspect
Section titled “LiteralError.inspect”impl Debug for LiteralError
fn inspect(value: LiteralError) -> String
impl Debug.inspect
LiteralError.equal
Section titled “LiteralError.equal”impl Equatable for LiteralError
fn equal(a: LiteralError, b: LiteralError) -> Bool
impl Equatable.equal