Skip to the content
Diaspar

Decision D043 · accepted; not implemented

Two printed forms of a value, Show and Display; BigInt in the core, a number with the literal 12big

A record of the language's design, as it stood on 2026-11-18: written for the people who build Diaspar, and kept as it was written. Its code is a sketch, not a program of the site, and an older record may show syntax that a later one changed. It names files of the language's source, which is not public yet.

Status: accepted (2026-11-18, by the author: every recommendation of the questions below, except that BigInt moves into the core now, that it is a number to = and to the total order with this decision, and that every type of std that needs a Display gets one with this change). Not implemented. Extends D010, D013, D022 and D038. To be implemented after step 1 of the migration wave (variants as values, D010 §3c), which changes the same printer and the same deriver.

The question

user=> (use std.math.bigint)
user=> (def bi (bigint.parse "10000000000000000000001100000000000000000000000000000000111100000000000000000000000000001"))
user.bi
user=> (+ bi 111)
(std.math.bigint.parse "10000000000000000000001100000000000000000000000000000000111100000000000000000000000000112")
user=> (print bi)
(std.math.bigint.parse "10000000000000000000001100000000000000000000000000000000111100000000000000000000000000001")
nil
user=> f"{bi} wei"
"(std.math.bigint.parse \"10000000000000000000001100000000000000000000000000000000111100000000000000000000000000001\") wei"

A value has one text of its own. std.core has one protocol, Show, and pr-str, str, print, f-strings and the REPL all call it. So a type's author chooses between text that reads back as code and text for people, and gets the same one everywhere. BigInt chose the code, and its digits are reached only with bigint.to-string.

The built-in kinds already have two texts. A string is quoted by pr-str and bare in str; a decimal is 1.10dec in pr-str and the REPL and 1.10 in str (D038). The runtime's printer carries a flag for it, and no user or library type can use it.

std shows the need in another way: seven functions under five names give "the text for people" (bigint.to-string, decimal.to-string, color.text, style.text, syntax.span-text, time.format, time.iso), and about sixty f-strings in std and the compiler write {(pr-str x)} to get the other form.

Two questions follow. How does a type say both texts? And how is a BigInt written so that its readable text is short and reads back, in code and in data (D033: data.read takes literals only)?

Decision

  1. A value has two forms. The readable form is how code writes the value; the display form is its text for people. For most values they are the same text.
  2. Two protocols. Show gives the readable form, as today, and stays derivable. A new protocol, Display, gives the display form and is written by hand. A type without Display displays as its readable form.
  3. pr-str, the REPL, test reports and diagnostics use the readable form; str, print and {x} in f-strings use the display form. Inside a collection or a record every value is readable, in both forms.
  4. A BigInt has a literal, 12big, which is its readable form; its display form is its digits. An integer literal that does not fit 64 bits stays an error, and the error names the suffix.
  5. BigInt is a type of the core and a number. The type moves to std.core, as Decimal did; std.math.bigint keeps the operations. = and the total order compare integers, floats, decimals and BigInts by exact value: (= 5big 5) is true.
  6. The types of std that have a text for people implement Display now, and a value that implements Error displays as its message.
(def bi 10000000000000000000001100000000000000000000000000000000111100000000000000000000000000001big)

(+ bi 111)          ; the REPL: 10000000000000000000001100000000000000000000000000000000111100000000000000000000000000112big
(pr-str 12big)      ; "12big"
(str 12big)         ; "12"
(print 12big)       ; 12
f"{12big} wei"      ; "12 wei"
f"{12big:?} wei"    ; "12big wei": the readable form in an f-string
f"{1234567big:,}"   ; "1,234,567": a format spec formats a BigInt as an integer
(str #[12big "a" 1.10dec])   ; "#[12big \"a\" 1.10dec]": inside a collection, readable
(data.read (data.write #{:supply 12big}))   ; #{:supply 12big}

(= 5big 5)                   ; true: numbers are compared by value
(get #{5 :five} 5big)        ; :five: one key
(sort #[2big 1.5 1dec 0])    ; (0 1dec 1.5 2big)
(+ 5big 1)                   ; 6big: arithmetic keeps the kind
(str (time.seconds 1.25))    ; "1.25 s"
f"cannot read the config: {e}"   ; the error's message

(deftype Money [amount currency] opaque: true derive: #[Show])
(extend-type Money Display
  (display [(Money amount: currency:)] f"{amount} {currency}"))

(def price (Money amount: 19.90dec currency: "EUR"))
price                    ; the REPL: (Money amount: 19.90dec currency: "EUR")
(print "Total:" price)   ; Total: 19.90 EUR
f"{price:>12}"           ; "   19.90 EUR"
(str #[price])           ; "#[(Money amount: 19.90dec currency: \"EUR\")]"

The rules

1. The two forms

  • The readable form is the value as code writes it: a literal ("a\n", 1.10dec, 12big, :k), a construction ((Point x: 1 y: 2), Mode.Fast), or a call that builds the value ((std.term.style.parse "bold red")). "Printing follows construction" (D030, D010 §3c) is about this form. A value that no code can write prints as #<…>: a function, an atom, an opaque type (D010 §4).
  • The display form is text for a person who reads a program's output: a message, a report, a file. It promises nothing about reading back.
  • They differ for a string (its characters, without quotes and escapes), a decimal (1.10), a BigInt (12), and every type that implements Display. For every other value the display form is the readable form: (str :k) is ":k", (str #[1 2]) is "#[1 2]", (str (Point x: 1 y: 2)) is "(Point x: 1 y: 2)", as today.
  • str joins the display forms of its arguments, and nil adds nothing to it ((str "x" nil) is "x", Clojure's rule), while print writes nil: unchanged.

2. Who uses which

Readable form Display form
pr-str str
the REPL's results, repl.show, show.format (D017) print, term.print
f"{x:?}", f"{x=}" f"{x}", f"{x:>10}"
test reports: the values of a failed is, diffs, counterexamples, expect and snapshots (D016) string.join and the other functions that take text and call str
values quoted in the runtime's and std's messages ("got …") error-message: an error's Error.message, which is now also what str gives for it
the expected output of documentation examples (D041): it is what the REPL prints
every value inside a collection or a record, whichever form is asked for

data.write uses neither protocol (rule 8).

3. The protocols

(defprotocol Show
  "A value's readable form, as code writes it: pr-str, the REPL, test reports and diagnostics call show."
  (show [x])
  derive: derive-show)

(defprotocol Display
  "A value's text for people: str, print and f-strings call display."
  (display [x]))

The readable form of a value is, in this order: the printer's own text for a built-in kind (decimals and BigInts among them); Show.show when its type implements Show; for an opaque type #<Name>; otherwise the construction, with every field readable. This is today's order.

The display form of a value is, in this order: the printer's own text for a string, a decimal, a BigInt, a position and a Failure; Display.display when its type implements Display; Error.message when its type implements Error; otherwise the readable form.

  • Display falls back to Show, never the other way. So str and print take any value, and a type that implements only Show prints through it everywhere, as today: no program changes its output by this decision except through BigInt, the types of "Display in std" below, and errors. The readable form never becomes the text for people.
  • An error displays as its message (question 6). Error.message is already the text for people of an error type, so str uses it when the type gives no Display: f"cannot read the config: {e}" says what the diagnostic's headline would say, as Python's str(e) and Rust's Display of an error do. A Failure displays as the error it holds. So error-message and str agree on every value, except an error type that implements both protocols, where each gives its own. The readable form of an error stays its construction, in the REPL and in test reports.
  • One exception, for a readable form that says nothing: an opaque type with Display and without Show prints readably as #<Name text>, #<Money 19.90 EUR>, with its display text. A test report that compares two such values shows the difference, where #<Money> and #<Money> would not.
  • The protocols are what a type implements; pr-str and str are what code calls. (implements? Display x) says whether the type of x has a text of its own, as (implements? Show x) does today; it is false for a string or a number, whose forms are the printer's. Calling Display.display on a value without an implementation is the usual "no implementation" error.
  • Both methods return a string, and an implementation that raises does not make printing fail. A display that raises is passed over, and the value prints in its readable form; a show that raises is passed over as it is today, and the value prints as if its type had none. Diagnostics and test reports print values, and must not fail while they do.
  • = and hashing do not look at either form (D022).

4. Collections and records: what is inside is readable

Display applies to the value that is asked for, never to what it holds. The elements of a vector, a list, a set and a map, the fields of a record, and the value of an atom are written in their readable form, also under str and print:

(str "a")                 ; "a"
(str #["a" "b c"])        ; "#[\"a\" \"b c\"]", not "#[a b c]"
(print #{:price 1.10dec}) ; #{:price 1.10dec}
(str (Ok value: 12big))   ; "(Ok value: 12big)"
(string.join ", " #[1big 2big])   ; "1, 2": each element is asked for itself

A collection has no text for people of its own, so its display form is its readable form, and a readable form is readable all the way down: it stays unambiguous (#["a b" "c"] has two elements) and reads back. This is what the printer does today for strings and decimals. Text for people from a collection is made by the program, which knows the separator: (string.join ", " xs).

5. f-strings

  • {x} is the display form, with or without a format spec. A spec for text (width, alignment, a precision that cuts) applies to the display text of any value: f"{price:>12}".
  • A new presentation type, ?, takes the readable form and then formats it as text: f"expected a string, got {v:?}", f"{name:>12?}". It is Rust's {:?}, in the place where Python's mini-language puts a type (D022). f"{v:?}" is f"{(pr-str v)}".
  • {x=} keeps the readable form, as D022 shows it and as Python's = does: it is for debugging.
  • The number types of a spec (d, x, ,, .2f and the rest) format integers, floats, decimals and BigInts. Given any other value they are the error they are today: a spec does not reach into Display.

Python's spelling, {x!r}, is not available: ! is part of a name here (swap!), so x!r is one symbol.

6. Derivation

  • derive: #[Show] writes the construction with every field readable, as today. It matters for an opaque type, whose fields are otherwise not printed (D010 §4); a record that is not opaque prints so without it.
  • Display has no deriver: derive: #[Display] is the error any such protocol gives today, "Display has no deriver", with the help "implement it with extend-type". A text for people is a decision about the domain, which a deriver cannot make. Rust derives Debug and not Display for the same reason.
  • A type may derive Show and implement Display by hand, as Money above: this is why they are two protocols and not two methods of one (see "Rejected alternatives").

7. What an implementation should print

Advice in the documentation of the two protocols, checked by nothing:

  • Show: code that builds an equal value wherever it is read, so names are written by their full path: (std.term.style.parse "bold red"). When no such code exists, #<Name …>.
  • Display: the text a user of the program would write for the value: 19.90 EUR, bold red, 2026-11-15T09:30:00.250Z. No type name, no quotes around the whole.
  • A display that needs the readable form of a part calls pr-str on it; one that calls str on the value itself does not end.

8. Data

data.write (D033; pr-data today) writes literals and constructions and calls neither Show nor Display, as pr-data calls no Show today: what it writes is decided by the reader that must read it, not by a type's author. A BigInt is written as its literal and a decimal as its literal, by the writer itself. data.read reads both. A value with no such text (a function, an atom, an opaque type without a literal) is not data; what data.write does with one is D033's to say, and an error is the answer that fits it.

The BigInt literal

12big   -3big   0big   1_000_000_000_000_000_000_000_000big
0xFFFF_FFFF_FFFF_FFFF_FFFFbig   0b1010big       ; the radix forms of integers (D034)

(type 5big)                       ; BigInt: a BigInt also when it fits 64 bits
(+ 9223372036854775807big 1)      ; 9223372036854775808big
(match n 0big :zero _ :other)     ; a literal pattern, compared with =
  1. The suffix is big. A BigInt literal is an integer literal (D034: digits with _ between them, or 0x, 0o, 0b), with an optional sign, followed by big. A point or an exponent is an error with the help "a BigInt is whole: 12big; a decimal is 1.5dec". The value is always a BigInt.

  2. Why big. D038 chose dec over C#'s m because it says what it is, and big is the same kind of suffix: a short word in lower case. Julia writes big"12" and big(12). No integer in any radix ends in big (i and g are not hexadecimal digits), so the reader needs no rule for 0xabig: it is 0xa as a BigInt.

  3. Printing. The readable form is the decimal digits and the suffix, -12big, without separators, whatever radix the literal was written in; the display form is the digits. The printer writes both itself, as it writes decimals: the runtime already knows the type and already turns a BigInt into digits for a decimal's coefficient. std.math.bigint loses its Show; bigint.to-string stays, for its radix:.

  4. Format specs format a BigInt as an integer, exactly: f"{n:,}", f"{n:x}", f"{n:>40}", f"{n:.2f}".

  5. Data. data.write writes 12big and data.read reads it: a BigInt becomes data, as a decimal is. Today (pr-data n) is #<BigInt>, and the text Show gives is a call, which data.read refuses.

  6. An integer literal that does not fit 64 bits stays an error, and gains a note and the way out:

    error: integer literal `9223372036854775808` is out of range
      --> ledger.dias:3:14
       = note: an integer has 64 bits: -9223372036854775808 to 9223372036854775807
       = help: for an integer of any size, write a BigInt: 9223372036854775808big

    Integers never grow into BigInts: arithmetic that overflows is an error (D013), and a literal follows the same rule. A BigInt equals the integer of its value ("A BigInt is a number" below), but it is not an integer: quot, rem, inc, the bit operations, an index, int? and the pattern (Int) take integers only, and arithmetic keeps the kind it was given. A literal that changed kind with one more digit would move that difference from the place where it is written to the place where it fails. 0.1 does not become a decimal either: the suffix is the choice. The same holds in a data file, read by the same reader.

  7. The overflow error names the literal too. (* 9223372036854775807 2) keeps raising Overflow, "*: integer overflow", and gains the help "for integers of any size use a BigInt: 9223372036854775807big, or (bigint.of n)".

  8. How it is read. The reader reads 12big as (std.core.%bigint "12"), which the expander resolves to std.math.bigint, loading the module, exactly as 1.10dec reaches std.decimal: the type is the core's and the code that builds one is its home module's ("BigInt in the core"). The literal is static data (D033). The formatter keeps the token as written (D031), and the highlighter colours it as a number.

  9. Quoted, it is the value: '12big is the BigInt and '(1 2big) holds one, as '1 is 1. This is not so for a decimal today (the third item below), and is fixed for both.

Found on the way, in the build of main 7b2dfc02:

  • 0x1dec is the error "invalid decimal", because the reader looks at the suffix before the radix; 0x1DEC is 7660. A number that starts with 0x is hexadecimal whatever it ends with.
  • f"{n:,}" with a BigInt, or with any record, raises "name: expected a string, symbol or keyword, got type BigInt": std.rt.format builds its own message with (name (type v)), which a record's type does not take. std.decimal has the right function for the same job.
  • '1.10dec is the list (std.core.%decimal "1.10"), the reader's form, not a decimal: (type '1.10dec) is :list.

The three are items of the implementation plan.

BigInt in the core

Decimal is the model (D038, "Where it lives"): the type in std.core, known to the reader, the printer and the runtime; the operations in a module of their own.

  • What moves. The definition, (deftype BigInt [sign limbs] opaque: true), from std/math/bigint.dias to std/core.dias, beside Decimal. BigInt becomes a name of the prelude: the type pattern (BigInt), a field's of: BigInt, and what (type 5big) gives need no import.
  • What stays in std.math.bigint: everything else. of, parse, to-string, to-int, fits-int?, to-float, bit-length, quot, rem, quot-rem, div-floor, mod, pow, pow-mod, gcd, isqrt, abs, signum, negate, zero?, even?, odd?, bigint?, BigIntError, and the methods of Add, Sub, Mul and Neg for the type. (use std.math.bigint) and bigint.parse read as before.
  • One name. std.math.bigint.BigInt and std.math's re-export std.math.BigInt go; the type is BigInt, as a decimal's is Decimal.
  • std.math.bigint is the type's home. The expander already has the notion for std.decimal (core-type-homes), and it now means two things:
    • The orphan rule (D010 §6). Add and BigInt both belong to std.core, so by the rule only std.core could implement the one for the other. The home module may. Nothing else changes: a program may implement its own protocol for BigInt, as for any type of the core, and may not implement Add or Display for it, as it could not before.
    • The private constructor (D010 §4). BigInt stays opaque, since its representation must stay canonical (no zero limb at the top, the sign 0 exactly for zero). The home module constructs it and takes it apart; to every other module, std.core included, its fields are closed. Decimal is not opaque today, and anyone may write (Decimal coefficient: "x" scale: -1); this rule would let it be (see "Open").
  • Who loads the home. A BigInt's operators are methods that std.math.bigint defines, so a program that can hold a BigInt has the module: the literal loads it (rule 8 of the literal), and std.ffi and std.decimal import it, as today.
  • Ord and Show leave std.math.bigint. The runtime orders and prints numbers itself, BigInts now among them; there is no (extend-type Decimal Ord …) either. bigint.compare-big stays.
  • The runtime. DSP_TYPE_BIGINT is the flag of the type registered as std.core.BigInt (it is std.math.bigint.BigInt today, in support/tables.c); the layout is unchanged, a sign and a vector of 30-bit limbs, least significant first. Today the flag only lets a decimal read its coefficient. With this decision it is what makes a BigInt a number to the runtime: printing, =, the total order, compare and <, the word "BigInts" in an operator's message. Arithmetic stays in Diaspar, through the protocols; a fast path in C can come later without a change of meaning.
  • The compiler's own references: back/emit/ffi.dias names the type for the stubs of :u64, and eval/host.dias lists the core's types for the evaluator, BigInt now beside Decimal.
  • The seed takes two regenerations, as Decimal did: the compiler that builds the new std must already know the home, so the expander's rule goes in first, and the type moves after the seed has it.

A BigInt is a number

D013: "numbers are one kind, compared by mathematical value, exactly". Decimals joined them on 2026-11-18 (D038); BigInts join them here. The sentence of D038 "a BigInt stays a kind of its own" is replaced.

(= 5big 5)                                   ; true
(= 5big 5.0)                                 ; true
(= 5big 5.00dec)                             ; true
(= 9007199254740993big 9007199254740992.0)   ; false: no rounding, as D013's example with an integer
(= 100000000000000000000big 1e20)            ; true: this float is exactly that number
(= 100000000000000000000big 100000000000000000000dec)   ; true

(get #{5 :five} 5big)                        ; :five
#set[1 1.0 1dec 1big]                        ; #set[1]: one element, the first that was put in
(distinct #[1 1big 1.0])                     ; (1)
(sort #[2big 1.5 1dec 0 -3big])              ; (-3big 0 1dec 1.5 2big)
(< 0.5 1big)                                 ; true
(compare 5big 5)                             ; 0
(zero? 0big)                                 ; true
(match n 0 :zero _ :other)                   ; :zero for 0, 0.0, 0dec and 0big
(match 5big (Int) :int (BigInt) :big)        ; :big: a type pattern asks for the type

(type 5big)                                  ; BigInt
(int? 5big)                                  ; false
(number? 5big)                               ; true, and (number? 1dec) too
(+ 5big 1)                                   ; 6big: no demotion
(+ 9223372036854775807 1)                    ; error: integer overflow; no promotion
(+ 5big 1.5)                                 ; error: + does not mix BigInts and floats
(+ 5big 1.10dec)                             ; 6.10dec: exact, as today

The rules

  1. Numbers are integers, floats, decimals and BigInts. Each of them except NaN and the two infinities is one rational number, and = asks whether two of them are the same number. Nothing is converted and nothing is rounded: a float is compared by its exact binary value, as it already is with an integer (D013) and with a decimal (D038).
  2. The total order is the order of those numbers. compare, <, >, <=, >=, sort, distinct, and the order of the keys of maps and of sets place every number by its value, whatever its kind. NaN is as it is today: equal to itself, after every number in the total order, false under <, and refused by compare.
  3. Equal numbers are one key of a map and one element of a set. Which of them is kept is what is kept today for 1 and 1.0: the one put in first.
  4. Equal numbers hash equally (D013). Maps and sets are ordered today and the runtime has no hash of a value; when it has one, it is a function of the number, not of its representation, as Python's is for int, float, Decimal and Fraction.
  5. A literal pattern is =, so 5 matches 5big and 5big matches 5 (D038 has it for decimals). A type pattern, (Int) or (BigInt), asks for the type.
  6. The kinds stay apart everywhere else. type, int?, float? and bigint.bigint? tell them apart; number? is true for all four (it is false for a decimal and for a BigInt today). Arithmetic keeps the kind of its operands: an integer result that does not fit 64 bits is an Overflow, a BigInt result that fits stays a BigInt, a BigInt and a float do not add (as a decimal and a float do not: equality and order lose nothing, an operation would), a BigInt and a decimal give a decimal. quot, rem, mod, inc, dec, even?, odd?, the bit operations and an index take integers; the BigInt's are std.math.bigint's.

It is transitive, and consistent with the order

D038 rejected "decimals equal integers but not floats" because 1dec = 1 = 1.0 ≠ 1dec has no total order. That cannot happen here, for one reason: every comparison between two kinds is exact, so = is the equality of the numbers themselves, which is an equivalence, and the order is theirs, which is total. A rule that compared any pair through a rounded conversion (a BigInt as its nearest float, say) would break it; none does.

integer float decimal BigInt
integer the words exact (D013) by scale (D038) new: by limbs
float IEEE values; NaN = NaN the float's exact digits (D038) new: the same digits
decimal by value (D038) by value: compare and < do it today, = is new
BigInt by limbs: the representation is canonical

The runtime already has the comparisons: to support/decimal.c a BigInt is a coefficient with the scale 0, so a BigInt with an integer, a decimal or a float goes through the code that compares a decimal with them. What changes is where it is called from: =, the rank of a BigInt in the total order (2, a number; it is 15, a record), and compare and < with a float.

It also ends a disagreement that exists today (the build of main 1165dcbc):

(= 1dec (bigint.of 1))         ; false
(compare 1dec (bigint.of 1))   ; 0
(= (bigint.of 1) 1)            ; false
(compare (bigint.of 1) 1)      ; 0
(= 100000000000000000000dec 1e20)                               ; true
(= 100000000000000000000dec (bigint.parse "100000000000000000000"))   ; false, and compare says 0
(< 0.5 (bigint.of 1))          ; error: < does not mix numbers and BigInt values
(get #{1 :a} (bigint.of 1))    ; nil
(zero? (bigint.of 0))          ; false

Tests state it as properties over generated numbers of the four kinds: = is reflexive, symmetric and transitive; (= a b) exactly when (compare a b) is 0; compare is antisymmetric and transitive; sort of a mixed vector is ordered by the exact values; a map finds a key by any number equal to it.

The FFI's :u64

An unsigned 64-bit value comes from C as "an integer up to 2⁶³−1, and a BigInt above" (design/ffi.md §3, accepted): one C type, two kinds, chosen by the size of the value. While a BigInt was a kind of its own, code that compared such a result had to know on which side of 2⁶³ it fell. Now it does not:

;; vk-buffer-size, file-size and handle-id stand for bound C functions that return :u64
(= (vk-buffer-size b) (ffi.u64-max))   ; true when it is 2^64-1: both are BigInts, as before
(= (file-size f) 4096)                 ; true: an integer result
(= (handle-id h) 4096big)              ; true: the same number
(get sizes (file-size f))              ; one key, whether the size crossed 2^63 or not
(< (file-size f) (ffi.u64-max))        ; true

The representation does not change: a result up to 2⁶³−1 is an integer, so that it indexes, counts and passes to quot as every other integer; above, a BigInt. A :u64 parameter takes an integer from 0 or a BigInt up to 2⁶⁴−1, as today. (ffi.u64-max) is written 18446744073709551615big, and diaspar bind writes such constants so.

Other languages

Language Integers of the two sizes With a float As keys
Python one type 1 == 1.0 == Decimal(1) == Fraction(1), exact: Decimal("0.1") == 0.1 is false one key: the hash of a number is defined on its value
Clojure (= 1 1N) is true (= 1 1.0) is false; == is the second operator D013 avoids 1 and 1N are one key
JavaScript 1n == 1 is true, 1n === 1 false; 1n < 2 works 1n == 1.0 is true a Map keeps 1n and 1 apart
Julia big(1) == 1 big(1) == 1.0; isequal and hash agree one key
Ruby, Elixir one integer type 1 == 1.0 is true, 1.eql?(1.0) and 1 === 1.0 false 1 and 1.0 are two keys

Python and Julia are the two whose ==, order and hash all go by the exact value across every numeric type, and it is what D013 chose. From memory, not checked again.

Display in std

Every type of std was looked at (about 170 deftype and defenum forms, and the runtime's own types). The question for each: is there one text a person would write for a value of it? Where std already has a function that gives that text, the answer was there. All of the following comes with this change (question 10).

The printer's own, for the kinds it knows without a protocol:

Value Readable form Display form
a string "a\n" its characters (as today)
Decimal 1.10dec 1.10 (as today)
BigInt 12big 12
a position, as traces hold them #<at src/app.dias:12:7> src/app.dias:12:7
Failure its construction the display form of the error it holds

By the rule for errors (rule 3): the message, with no code per type. The 23 types of std that implement Error today: Message, RuntimeError, BadArgument, SyntaxError and ReadError of the core; BenchError, BigIntError, CodePointError, FsError, GenError, IoError, JsonError, MathError, ParseError, ProcessError, PropError, RandomError, RawError, StatsError, StyleError, TermError, UsageError, ValueError, and the reader's ReadError. Every error type of a program gets the same.

By an extend-type T Display in the type's module, each one line over a function that exists:

Type Readable form Display form The function
std.term.style.Style (std.term.style.parse "bold red"), its Show, kept bold red on #ff8000 style.text
std.term.color.Color Color.BrightRed, (Color.Rgb r: 255 g: 128 b: 0) bright-red, #ff8000, color(208), default color.text
std.time.Time (Time epoch-nanos: …) 2026-11-15T09:30:00.250Z time.iso
std.time.Duration (Duration nanos: 1250000000) 1.25 s, 850 ns, 2 min 5 s time.format with its defaults
std.lang.syntax.Span its construction src/app.dias:12:7 syntax.span-text
std.doc.Place its construction std/string.dias:12 place-text, private to std.doc.term today; it moves to std.doc
  • A duration's display form rounds to three significant digits. That is right for text for people and wrong for anything else, which the readable form and time.to-nanos serve; Go prints a duration the same way, Rust gave Duration no Display for this reason. It is the one choice in the list that is not forced.
  • The functions stay, for what str cannot say: time.format has digits: and micro:, bigint.to-string a radix:; style.text and color.text are what parse reads back. decimal.to-string is str now and can go when its callers are changed.

None, and why:

Types Why not
std.time.Instant a reading of the monotonic clock is a number that means nothing outside its process
handles and resources: fs.File, fs.Lock, fs.ScratchDir, raw.Terminal, term.Counter, ffi.Memory, ffi.Pin, ffi.Callback, the handles ffi.defhandle makes, random.Generator, an atom a handle is not text; a file is not its path, which f.path gives where the type has it
the terminal's docs: style.Span, term.Link, term.Sym their text depends on the stream, and a doc is as often a string or a vector, which str cannot serve: term.render-plain is the one way
enums without fields: Round.HalfUp, Align.Left, Mode, Status, EntryKind, KeyKind, Underline, … the name is the readable form; a word for people is the program's choice, in the program's language
the operations of effects: FsOp, ClockOp, TermOp, ProcessOp, EnvOp, AllocOp requests to a handler, never shown to a user
records of settings and results: the themes, Config, Options, CommandSpec, Field, Metadata, process.Output, LinearRegression, Comparison, the test runner's Result and Run, the distributions of std.random, the documentation's Item and Module several values and no one text; their modules render them, with a theme
syntax and layout: Syn, Part, Node, Group, the markup's Inline and Block written by the formatter and the renderers, which take a width
term.input's KeyCode and Event the names of keys are the line editor's keymap vocabulary, private to it
Ok, Err they hold a value, and what is held is readable (rule 4)

Not types yet. A path, a URL, a version and a UUID are strings in std today. When one becomes a type, its Show is the call that builds it and its Display the text: (fs.path "/tmp/a") and /tmp/a.

Prior art

Checked on 2026-11-18 where a source is named in "Sources".

Two forms.

Language Readable, for debugging For people When the second is absent Derived
Rust Debug: {:?}, dbg!, unwrap's message Display: {}, to_string a compile error Debug only
Python __repr__: repr, the REPL, !r, {x=} __str__: str, print, f-strings str uses repr a dataclass writes __repr__
Elixir Inspect: inspect, IEx String.Chars: to_string, #{} Protocol.UndefinedError for a tuple, a map, a struct Inspect, with only: and except:
Swift CustomDebugStringConvertible: debugPrint, String(reflecting:) CustomStringConvertible: print, "\(x)" each uses the other, then reflection neither; reflection prints fields
Lean 4 Repr: #eval ToString: s!"{x}" an error Repr only
Haskell, OCaml Show (and Read); ppx_deriving show nothing standard — yes
Clojure print-method: pr, pr-str, the REPL str, through toString toString of the object records print readably
Julia show(io, x), repr; show with a MIME type for the REPL print, string, "$x" print uses show the default show is the construction
Racket write, and print for the REPL display one prop:custom-write takes the mode #:transparent
Common Lisp prin1, ~s, *print-readably* princ, ~a one print-object reads *print-escape* —
Kotlin, Java, C# one toString the same — data classes, records

The two-protocol shape is Rust's, Elixir's and Lean's; the fallback from the text for people to the readable one is Python's and Julia's. Elixir's Inspect documents the three shapes a readable form takes, and they are the three of rule 1: the literal syntax, #Name<…>, and "the expression syntax, User.new(13, "Jane", "Earth")".

A collection under the form for people.

Language A list of strings
Python str(["a"]) is ['a']: elements by repr. PEP 3140 (2008), elements by str, was rejected as too large a change before a beta, and not taken up again
Swift print(["a"]) is ["a"]: elements by debugDescription
Clojure (str ["a"]) is ["a"]
Julia print(["a"]) is ["a"]
Rust Vec has no Display: {} does not compile, {:?} prints ["a"]
Elixir no String.Chars for a tuple or a map; a list is taken for character data
Kotlin, Java [a]: elements by toString, so ["a, b", "c"] prints [a, b, c]
Racket, Common Lisp (display '("a b" "c")) is (a b c): the mode goes down

Where a type has two separate hooks (Rust, Python, Swift, Elixir, Julia, Clojure), the elements stay readable or the collection has no form for people at all. Where one mode goes down into the elements (Racket, Common Lisp) or there is one form (Java, Kotlin), two different collections print the same text. PEP 3140's complaint was [Decimal("3")] where a person wants [3]. Here the readable form of a number is its literal, so the cost of the rule is a suffix: #[3dec], #[12big].

Integers of any size.

Language Literal A literal too large for the machine integer Prints
Clojure 12N (and 1.10M) reads as a BigInt; + raises on overflow, +' promotes pr-str gives 12N, str gives 12
JavaScript 12n a Number literal loses digits silently the console 12n, String(12n) is 12; JSON.stringify(12n) throws
Julia big"12", big(12) becomes Int128, then BigInt; arithmetic wraps 12
Python, Ruby, Elixir, Haskell, Common Lisp, Racket none needed: integers have any size — digits
Rust, Swift, Kotlin, Java, C#, Scala, OCaml, Dart none: a function over text a compile error digits

Clojure and Julia read a large literal as a BigInt, and both draw the same complaint: Clojure's users ask why N is optional when M is required, Julia's why big(…) is needed only for a number that is not big. In Clojure every arithmetic function takes a BigInt, so the kind of a literal matters less than it does here, where quot, an index and the bit operations take integers only.

What changes in existing decisions

The first three are marked in their files with this decision; the rest are restated when it is implemented.

  • D013: §1's kinds: numbers are integers, floats, decimals and BigInts ("a BigInt is a kind of its own" is replaced). §2: a BigInt has a literal; the out-of-range literal and the overflow name it; overflow stays an error.
  • D038: "a BigInt stays a kind of its own" and (= 1dec (bigint.of 1)) being false are replaced; "str gives 1.10" becomes "its display form is 1.10", with no change in behaviour.
  • design/std-math.md §7: "an explicit, opaque type … never = to an integer" and "Printing" are replaced; the open items "Literals" and "std.math.BigInt" are closed.
  • D010: §1 "printing by default" and §4 "opaque types do not print their fields" are about the readable form; §6's orphan rule and §4's private constructor have the exception of a core type's home module, which Decimal already uses; §7's standard derivers: Show is derived, Display is not. §3c is unchanged: an enum's values print by their names in both forms until the enum implements Display.
  • D030, "Printing follows construction": it is the readable form; str of a type with Display gives its text.
  • D022: {x} is the display form; the type ?; {x=} is the readable form; specs format BigInts. Ord for numbers is the runtime's, BigInts included; "+ does not mix numbers and BigInt values" becomes "+ does not mix BigInts and floats", the one pair that does not mix.
  • D005: an error value, and a Failure, display as the message.
  • D034: the integer literal gains the suffix; 0x… is always hexadecimal.
  • D033: 12big is data; data.write calls neither protocol.
  • D028: "no bignums" holds for the integer; a BigInt is a record of the core that the runtime knows by its flag, as a decimal is.
  • D017, D016, D041, D014: the REPL, test reports, examples and quoted values use the readable form: no change, now stated.
  • D009: print writes display forms; str joins them.
  • design/ffi.md §3: the type is BigInt of the core; a :u64 result compares by value with any number.

Migration

  • Printing. Nothing in user code breaks: an extend-type T Show keeps deciding both forms until T gains a Display. What changes under str, print and {x}: a BigInt, the six types of the list, and an error value given to them directly (its message, where it was its construction). A search of std, the compiler, the tests and the examples finds one such use of an error, error-message's own fallback, and no test that prints a Time, a Duration, a Style, a Color, a Span or a Place that way; the test run decides.
  • Equality. A program that relied on a BigInt never being = to an integer changes meaning: a map with the keys 5 and (bigint.of 5) has one key. In the repository: tests/cases/decimal-equality.dias expects (= 1dec (bigint.of 1)) to be false, and tests/dias/math-bigint.dias and tests/dias/decimal.dias state the old rule in places; they are rewritten with the properties of "A BigInt is a number".
  • The name. std.math.bigint.BigInt and std.math.BigInt become BigInt: std/math.dias's re-export, the import in tests/dias/math-bigint.dias, back/emit/ffi.dias, support/tables.c, and the documents.
  • std: std.core gains BigInt and Display, and the comment on Show is rewritten; std/math/bigint.dias loses the type, its Show and its Ord; the six modules of the list gain a Display; std.rt.format gains ? and BigInts; std.lang.reader, std.lang.highlight and std.rt.reading gain the literal; number? is true for decimals and BigInts. The {(pr-str x)} of std and the compiler may become {x:?} whenever their files are touched.
  • Texts that change are a BigInt's: tests/dias/math-bigint.dias (the two assertions on pr-str and str), tests/cases/param-as.dias with its snapshot, and tests/ffi/scalars.dias, where the FFI's message becomes 18446744073709551616big is out of range (0 to 18446744073709551615). The messages of operators change their word for the kind ("BigInt values" becomes "BigInts"). They are recorded again.
  • diaspar bind writes a C constant above 2⁶³−1 as (def NAME (bigint.parse "18446744073709551615")) and adds a use; it writes 18446744073709551615big instead, and the bindings are generated again. std.ffi's u64-max is written so too.
  • The seed is regenerated twice: after the expander knows the home of std.core.BigInt, and after the move and the rest.

Rejected alternatives

Alternative Where Why not
One protocol with two methods, show and a display that defaults to it — an extend-type block is one implementation (D010 §6), so a type could not derive show and write display, the commonest pair
One method with a mode argument Racket's prop:custom-write, Common Lisp's print-object every implementation branches on the mode or ignores it, and deriving has the same problem
The literal alone: 12big in every form — (print n) and f"{n} wei" would print the suffix; decimals already print two ways, and Money, a date, a path need both
str raises for a value without Display Elixir, Rust at compile time str and print are used on any value, for debugging first of all (D009)
Elements of a collection in the display form Racket, Common Lisp, Java, PEP 3140 two different collections print the same text; today's printer, Python, Swift, Clojure and Julia keep the elements readable
Show falls back to Display Swift text for people in a test report or a data dump, taken for code
A deriver for Display — it could only print the construction, which is Show
Display takes the format spec Python's __format__, Rust's Formatter not needed for this; a Format protocol can be added when dates want {t:%Y-%m-%d}, without changing Display
{x!r} Python ! is part of a name
A second print function, pr or prn Clojure one print (D009); (print (pr-str x)) and f"{x:?}" say it
Renaming Show to Debug or Inspect Rust, Elixir the readable form is not only for debugging here: the REPL, data and tests rely on it; Show is Haskell's and Lean's word for exactly this, and the name is in use
The suffix N or n Clojure, JavaScript a letter where D038 chose a word; see question 3
A large literal reads as a BigInt Clojure, Julia rule 6 of the literal
Integers of any size, promoted on overflow Python, Ruby, Elixir, Common Lisp it would need neither the literal nor the suffix, and D013 and D028 decided against it; not reopened here
BigInt a kind of its own, (= 5big 5) false this decision as proposed; std.math.bigint until now with a literal it is D038's trap of 1 and 1dec as two keys; compare already said 0 where = said false; the FFI gives one C type in two kinds
A BigInt that fits 64 bits becomes an integer Python, Ruby and Lisp, where the two are one type the kind of a result would depend on its size, which is promotion in the other direction: (quot (- a b) 2) would work or fail by the values
The type stays in std.math.bigint, known to the runtime by name this decision as proposed a number of the language whose type pattern needs an import, where Decimal needs none; one more name for the runtime to know outside the core
Display only for BigInt and Style now, the rest one by one this decision as proposed the functions exist and each is a line; done once, str means the same across std
A tagged literal, #big "12" Clojure's #inst, EDN # opens data literals (D008); a mechanism for one type, where the decimal has a suffix

Implementation plan

It starts after step 1 of the migration wave has landed: that step rewrites the same branches of print.c and the same show-clause of std.core's deriver, and records the same snapshots again.

Each step is a change that leaves the tree green, and each begins with its tests, which fail before the code is written. Every case runs compiled and on the evaluator: the two share the runtime's printer and its comparisons, so they agree by construction, and the differential harness shows that they do.

  1. The three bugs, which need nothing else and can go in at once:
    • 0x1dec: the reader tests the radix before the suffix (std.lang.reader's token-node); a reader test and tests/cases, with 0x1DEC, 0xdec and 0x1decdec, all three hexadecimal.
    • f"{n:,}" with a record: std.rt.format's type-word as std.decimal's; a test of the message for a record, an enum's value and a type.
    • '1.10dec: quote gives the decimal, where it makes its datum from the reader's form; tests of '1.10dec, '(1 2.5dec), a quasiquote that holds one, and a macro given 1.10dec (which still sees the reader's form and syntax.decimal-text). The BigInt literal uses the same place in step 5.
  2. The home of a core type, in the expander only. core-type-homes gains std.core.BigInt, and check-opaque (front/expand/resolve.dias) takes the home for the type's module, as the orphan check (front/expand/protocols.dias) does. The runtime sets DSP_TYPE_BIGINT for either name. Tests: an opaque type of the core built and matched in its home, refused elsewhere, in the expander's tests. Then the seed is regenerated: the next step's std needs a compiler that knows this.
  3. BigInt moves, and is a number.
    • Tests first: tests/cases/bigint-number.dias with the examples of "A BigInt is a number" (both tiers); in tests/dias/math-bigint.dias, the properties over generated integers, floats, decimals and BigInts (= an equivalence, = exactly when compare is 0, compare antisymmetric and transitive, sort, one key in maps and sets, distinct, NaN and the infinities against BigInts); tests/cases/decimal-equality.dias and tests/dias/decimal.dias rewritten; tests/ffi/scalars.dias gains the comparisons of "The FFI's :u64"; the runtime's unit tests for the comparisons in C; all of it under ASan and UBSan, as the decimal's.
    • std/core.dias gets the type; std/math/bigint.dias loses it with its Ord; std/math.dias loses the re-export; number?.
    • The runtime (support/order.c, arith.c, decimal.c, tables.c): the rank of a BigInt is a number's; =, the total order, compare and < send a pair with a BigInt to the code that compares a decimal with an integer, a BigInt or a float; the operators' messages say "BigInts".
    • The compiler: back/emit/ffi.dias and eval/host.dias name std.core.BigInt; a literal pattern with a BigInt.
  4. Display.
    • Tests first: tests/cases/show-display.dias, the table of rule 2 as expect forms (a type with Show only, Display only, both, neither, each of them opaque and not, an error type with and without Display, a Failure, a position; a collection of each; f-strings with {x}, {x:?}, {x=}, a width; a display that raises); compiler/tests/repl.dias; a deriver's error for derive: #[Display].
    • The runtime (support/print.c, protocols.c, diaspar.h's methods of the core): a slot for Display beside dsp_proto_show; show_by_protocol takes the form asked for and tries Display, then Error.message, when it is the display form (the readable argument is already 0 only for the value asked for); the display forms of a position and of a Failure; #<Name text>.
    • std.core: the protocol, and the documentation of str, pr-str, print and error-message. std.rt.format: the type ?. The compiler lists Display beside Show in back/lower.dias, middle/prune.dias and eval/host.dias.
    • The six extend-type … Display of the list, each with a test in its module's tests; place-text moves to std.doc.
  5. The literal and a BigInt's printing.
    • Tests first: tests/cases/bigint-literal.dias and the reader's tests (the forms, the radix forms, the errors and their help, 0xabig); tests/cases/error-integer-range.dias and the overflow's help; the transcript of "The question" in compiler/tests/repl.dias; the formatter and the highlighter on the token; the data round trip in std/tests/rt-reading.dias; format specs on BigInts against CPython's integers, as D022's tests do; '12big.
    • std.lang.reader, std.lang.syntax (a bigint-text beside decimal-text), std.rt.reading, std.lang.highlight, std.lang.fmt; resolve.dias sends std.core.%bigint to std.math.bigint, as %decimal to std.decimal; the constant is static data, as a decimal's.
    • The runtime prints a BigInt (show_bigint beside show_decimal, over coef_digits); std.math.bigint loses its Show; std.rt.format formats BigInts.
    • diaspar bind and std.ffi write the literal; the generated bindings are generated again.
  6. The seed is regenerated, the changed texts are recorded again, and the decisions listed above are restated.

Steps 3, 4 and 5 do not depend on one another after step 2; this order puts the change of meaning (equality) first, alone in its commit.

Questions for the author

Answered on 2026-11-18: 1 to 6 and 9 as recommended; 7: yes, and with this decision, not a separate one; 8: BigInt moves into the core now, as Decimal did; 10: every type that needs a Display gets one now ("Display in std"). The text above is written to the answers; the questions are kept as they were asked.

  1. Two protocols, Show (readable, derived) and a new one for people (by hand), with the fallback one way? Recommended: yes.
  2. The name of the new protocol. Recommended: Display, Rust's word, next to Haskell's Show. The two words are close in English, which is the cost; the pair is told apart by "show the code, display the text". The alternatives: ToString with a method to-string (Lean, Rust's blanket trait; std already says bigint.to-string and decimal.to-string), or Text.
  3. The suffix. Recommended: big, for D038's reason. N is Clojure's and EDN's and stands out after digits; n is JavaScript's and the most widely known. Either letter also keeps hexadecimal literals easy to read (0xFFn against 0xFFbig).
  4. An integer literal out of range: an error with the help, not a BigInt? Recommended: yes.
  5. {x:?} in f-strings? Recommended: yes. It can be left out without touching the rest; then the readable form is {(pr-str x)}.
  6. An error's text. Should str of a value that implements Error and not Display be its Error.message, as Python's str(e) and Rust's Display for errors? error-message is this chain already. Recommended: yes, as its own small change after this one, so that f"cannot read the config: {e}" says what the diagnostic would say. It is part of step 4 of the plan, since answer 10 asks for every Display now.
  7. Does a BigInt join the numbers for =? The decimal work has just made decimals equal to integers and floats by value and left BigInt a kind of its own. With a literal, (= 5big 5) being false and 5 and 5big being two map keys is the trap that decision names; and the FFI already returns "an integer up to 2⁶³−1, a BigInt above" for one C type. Recommended: yes, as a separate decision. Answered: yes, here.
  8. Does BigInt move into the core as Decimal did (the type in the prelude, the operations in std.math.bigint)? Recommended: not now; the literal does not need it. Answered: now.
  9. #<Name text> for an opaque type with Display and no Show? Recommended: yes.
  10. Which library types get a Display with this change? Recommended: BigInt and Style only; Color, Time, Duration and Span one by one. Answered: all that need one, now.

Open

Not decided here; none blocks the plan.

  • JSON. std.json decodes an integer beyond 64 bits as the nearest float, and has no encoding for a BigInt. With BigInt in the core, the exact answers are a BigInt each way, as D038 reads a decimal from the number's text.
  • Decimal opaque. The home rule of step 2 lets Decimal be opaque as BigInt is, which would close (Decimal coefficient: "x" scale: -1).
  • Integer functions on BigInts. quot, rem, mod, inc, dec, even? and odd? take integers only, and / has no method for a BigInt; std.math.bigint has its own. Whether the core's become protocols is design/std-math.md's open item, more visible now that (zero? 0big) and (max 1big 3) work and (even? 2big) does not.
  • A duration's display form rounds ("Display in std"); if an exact one is wanted instead, it is a change of one line.
  • A Format protocol that receives the spec, for dates.

Sources