Skip to content

std::debug

The Debug interface: a value as a developer reads it, what dbg, io.inspect and an assertion’s values: row write. Every value has a Debug form; Display (std::display) is the user-facing one.

Import with import std::debug.

Interfaces

TypeDisplayDebug
Int, Float, Boolnumeric / variant form: 42, 3.14, True / Falseidentical
Decimalits digits at its scale: 1.50its literal: 1.50d
Unitno Display impl; rendering one is a compile errorUnit
Stringraw text, no quotesits literal, String.to_literal: "..." with \n, \r, \t, \\, \" and \${ escaped and \u{...} for any other character that is not printable
Infallibleuninhabited; can never be callednone

Int, Float and Bool render the same in both, and a Decimal’s Debug adds its literal’s d. For a String the two differ more. Display gives the bare text, so "hello ${name}" doesn’t double-quote. Debug gives the literal, so io.inspect("a\"b") shows the escape; String.to_literal gives the rules for that literal.

Containers recurse through the same interface as the caller: a container’s Display uses Display on its elements, and its Debug uses Debug. Brackets, braces, parentheses and separators are byte-identical between the two; only the per-element function differs.

TypeDisplayDebug
List<T>[Display(v1), Display(v2), ...], [] for empty[Debug(...), ...]
Vector<T>Vector[Display(v1), ...], Vector[] for emptyVector[Debug(...), ...]
Set<T>Set[Display(v1), ...], Set[] for emptySet[Debug(...), ...]
Map<K, V>{Display(k) => Display(v), ...}, {} for empty{Debug(...) => Debug(...), ...}
Maybe<T>Some(Display(v)), NoneSome(Debug(v)), None
Result<T, E>Ok(Display(v)), Err(Display(e))Ok(Debug(v)), Err(Debug(e))
Range<T>Debug(start)..Debug(end), Debug(start)..=Debug(end), Debug(start).. for unbounded integer rangesidentical
Tuple (...)(Display(a), Display(b), ...)(Debug(a), Debug(b), ...)
Anon struct {f: V, ...}{f: Display(v), ...}{f: Debug(v), ...}

Tuples and anonymous structs are syntactic intrinsics with no named type to attach an impl to; they get language-level rendering, as their literal syntax is privileged. Every other built-in type gets a Nomi-side impl in the standard library.

Container impls require their elements to implement the corresponding interface: ${[some_fn]} is an error because functions have no Display impl. Each container impl states the constraint as a bound (impl Display for List<T> where T: Display), which its body needs to render an element, so List<Foo> is Display exactly when Foo is; a missing element impl is reported as the element’s (no impl of `Display` for `Foo` ).

For Maybe and Result, the variant constructor is always rendered (Some(...), None, Ok(...), Err(...)), never unwrapped. Display keeps the variant: the user-facing form of Maybe.None is "None", not the empty string.

interface Debug
    fn inspect(value: self) -> String
end

Protocol for a developer-facing String form of a value.

An impl writes text that looks like the value’s literal: Nomi source that builds the value again where that is possible, and a faithful rendering of its structure where it is not.

io.inspect, dbg, debug logs and Debug.inspect(value) write it. Text for a user is Display’s: string interpolation "${value}" calls Display, not Debug.

dbg expr is a language form, not a member of this interface. It evaluates expr, prints the source location, source text, and Debug.inspect output, then returns the original value. The LSP reports every dbg as a warning because it is for development only. io.inspect(value) is the function for printing the Debug form as part of a program’s behavior.

Debug’s function is inspect and Display’s is to_string, so a type that implements both has two functions with two names.

For a String the two differ: Display.to_string("hello") is hello, and Debug.inspect("hello") is "hello", in quotes as the literal is. For Int, Float, and Bool, Debug.inspect is the same text as Display.to_string, because the literal is the user-facing form.

Every value has a Debug form, with no derive and no impl. The compiler writes a structural Debug for any declared type that does not supply one, so an impl Debug is only for changing how a type renders.

Precedence, highest first: a hand-written impl Debug, then derive Debug, then the structural impl the compiler writes.

An opaque type inspects as its name only, <opaque T>, since a structural form would show the internals opaque hides; write an impl Debug for T in its file to show more. A host type with no impl inspects as its bare name (True as True, Unit as Unit). Values with no declaration have placeholders: <function>, <task>, <channel>, <arm> and <iter>.

fn inspect(value: self) -> String

interface Debug