Skip to content

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’s from_fragments, which gets the text as a list of Fragments and returns whatever type the impl chooses, usually a Result. A literal with a ${...} slot calls it when the program runs. A literal without slots, in any quotes, has fixed text, so the compiler calls from_fragments while it checks the program: when it returns a Result, an Err is a compile error and the literal is the Ok value. std::calendar’s Date, std::regex’s Regex and std::sql’s Sql work this way.
  • CheckedLiteral: check reads the literal’s text around its slots while the program is checked, and build makes the value when it runs. The literal is the value in every quote style, slots included, never a Result. check refuses text with a LiteralError, which names the character the compile error points at. std::url’s Url and std::toml’s Toml work 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.

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.

impl Debug for Fragment<T>

fn inspect<T>(value: Fragment<T>) -> String where T: Debug

impl Debug.inspect

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
fn from_fragments(fragments: List<Fragment<I>>) -> R

interface Literal

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.

  • check runs while the program is checked, once per literal. It gets the literal’s static text: the n + 1 pieces around its n slots, in order, empty ones included. An Err is a compile error at the character its LiteralError names. check may not have effects (output, files, the clock, tasks, an application field).
  • check_type is what the compiler runs, in check’s place: the same statics, and a description of the literal’s type: each of its type arguments as Nomi spells it, in order. A Route<{id: Uuid}> literal gets ["{id: Uuid}"], a Url one []. The description is text, not the types themselves, which no value holds. Its default is check(statics), so a type whose text need not agree with its type arguments writes only check.
  • build runs when the program runs and gets the fragments Literal.from_fragments would get. It cannot fail: once check accepts the text, every slot value must build. A build that traps anyway traps where the literal runs. std::literals::testing’s build_each tests 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
fn check(statics: List<String>) -> Result<Unit, LiteralError>

interface CheckedLiteral

fn check_type(statics: List<String>, arguments: List<String>) -> Result<Unit, LiteralError>

interface CheckedLiteral

fn build(fragments: List<Fragment<I>>) -> T

interface CheckedLiteral

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"

impl Display for LiteralError

fn to_string(error: LiteralError) -> String

impl Display.to_string

impl Debug for LiteralError

fn inspect(value: LiteralError) -> String

impl Debug.inspect

impl Equatable for LiteralError

fn equal(a: LiteralError, b: LiteralError) -> Bool

impl Equatable.equal