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
- 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.
- Two protocols.
Showgives the readable form, as today, and stays derivable. A new protocol,Display, gives the display form and is written by hand. A type withoutDisplaydisplays as its readable form. pr-str, the REPL, test reports and diagnostics use the readable form;str,printand{x}in f-strings use the display form. Inside a collection or a record every value is readable, in both forms.- 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. BigIntis a type of the core and a number. The type moves tostd.core, asDecimaldid;std.math.bigintkeeps the operations.=and the total order compare integers, floats, decimals and BigInts by exact value:(= 5big 5)is true.- The types of
stdthat have a text for people implementDisplaynow, and a value that implementsErrordisplays 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 implementsDisplay. 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. strjoins the display forms of its arguments, andniladds nothing to it ((str "x" nil)is"x", Clojure's rule), whileprintwritesnil: 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.
Displayfalls back toShow, never the other way. Sostrandprinttake any value, and a type that implements onlyShowprints through it everywhere, as today: no program changes its output by this decision except throughBigInt, the types of "Displayinstd" below, and errors. The readable form never becomes the text for people.- An error displays as its message (question 6).
Error.messageis already the text for people of an error type, sostruses it when the type gives noDisplay:f"cannot read the config: {e}"says what the diagnostic's headline would say, as Python'sstr(e)and Rust'sDisplayof an error do. AFailuredisplays as the error it holds. Soerror-messageandstragree 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
Displayand withoutShowprints 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-strandstrare what code calls.(implements? Display x)says whether the type ofxhas 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. CallingDisplay.displayon 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
displaythat raises is passed over, and the value prints in its readable form; ashowthat 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:?}"isf"{(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,,,.2fand the rest) format integers, floats, decimals and BigInts. Given any other value they are the error they are today: a spec does not reach intoDisplay.
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.Displayhas 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 derivesDebugand notDisplayfor the same reason.- A type may derive
Showand implementDisplayby hand, asMoneyabove: 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
displaythat needs the readable form of a part callspr-stron it; one that callsstron 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 =
-
The suffix is
big. A BigInt literal is an integer literal (D034: digits with_between them, or0x,0o,0b), with an optional sign, followed bybig. 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. -
Why
big. D038 chosedecover C#'smbecause it says what it is, andbigis the same kind of suffix: a short word in lower case. Julia writesbig"12"andbig(12). No integer in any radix ends inbig(iandgare not hexadecimal digits), so the reader needs no rule for0xabig: it is0xaas a BigInt. -
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.bigintloses itsShow;bigint.to-stringstays, for itsradix:. -
Format specs format a BigInt as an integer, exactly:
f"{n:,}",f"{n:x}",f"{n:>40}",f"{n:.2f}". -
Data.
data.writewrites12biganddata.readreads it: a BigInt becomes data, as a decimal is. Today(pr-data n)is#<BigInt>, and the textShowgives is a call, whichdata.readrefuses. -
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: 9223372036854775808bigIntegers 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.1does not become a decimal either: the suffix is the choice. The same holds in a data file, read by the same reader. -
The overflow error names the literal too.
(* 9223372036854775807 2)keeps raisingOverflow, "*: integer overflow", and gains the help "for integers of any size use a BigInt: 9223372036854775807big, or (bigint.of n)". -
How it is read. The reader reads
12bigas(std.core.%bigint "12"), which the expander resolves tostd.math.bigint, loading the module, exactly as1.10decreachesstd.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. -
Quoted, it is the value:
'12bigis the BigInt and'(1 2big)holds one, as'1is 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:
0x1decis the error "invalid decimal", because the reader looks at the suffix before the radix;0x1DECis 7660. A number that starts with0xis 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.formatbuilds its own message with(name (type v)), which a record's type does not take.std.decimalhas the right function for the same job.'1.10decis 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), fromstd/math/bigint.diastostd/core.dias, besideDecimal.BigIntbecomes a name of the prelude: the type pattern(BigInt), a field'sof: 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 ofAdd,Sub,MulandNegfor the type.(use std.math.bigint)andbigint.parseread as before. - One name.
std.math.bigint.BigIntandstd.math's re-exportstd.math.BigIntgo; the type isBigInt, as a decimal's isDecimal. std.math.bigintis the type's home. The expander already has the notion forstd.decimal(core-type-homes), and it now means two things:- The orphan rule (D010 §6).
AddandBigIntboth belong tostd.core, so by the rule onlystd.corecould implement the one for the other. The home module may. Nothing else changes: a program may implement its own protocol forBigInt, as for any type of the core, and may not implementAddorDisplayfor it, as it could not before. - The private constructor (D010 §4).
BigIntstays 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.coreincluded, its fields are closed.Decimalis not opaque today, and anyone may write(Decimal coefficient: "x" scale: -1); this rule would let it be (see "Open").
- The orphan rule (D010 §6).
- Who loads the home. A BigInt's operators are methods that
std.math.bigintdefines, so a program that can hold a BigInt has the module: the literal loads it (rule 8 of the literal), andstd.ffiandstd.decimalimport it, as today. OrdandShowleavestd.math.bigint. The runtime orders and prints numbers itself, BigInts now among them; there is no(extend-type Decimal Ord …)either.bigint.compare-bigstays.- The runtime.
DSP_TYPE_BIGINTis the flag of the type registered asstd.core.BigInt(it isstd.math.bigint.BigInttoday, insupport/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,compareand<, 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.diasnames the type for the stubs of:u64, andeval/host.diaslists the core's types for the evaluator,BigIntnow besideDecimal. - The seed takes two regenerations, as
Decimaldid: the compiler that builds the newstdmust 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
- 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). - 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 bycompare. - 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
1and1.0: the one put in first. - 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,DecimalandFraction. - A literal pattern is
=, so5matches5bigand5bigmatches5(D038 has it for decimals). A type pattern,(Int)or(BigInt), asks for the type. - The kinds stay apart everywhere else.
type,int?,float?andbigint.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 anOverflow, 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 arestd.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-nanosserve; Go prints a duration the same way, Rust gaveDurationnoDisplayfor this reason. It is the one choice in the list that is not forced. - The functions stay, for what
strcannot say:time.formathasdigits:andmicro:,bigint.to-stringaradix:;style.textandcolor.textare whatparsereads back.decimal.to-stringisstrnow 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; "strgives1.10" becomes "its display form is1.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
Decimalalready uses; §7's standard derivers:Showis derived,Displayis not. §3c is unchanged: an enum's values print by their names in both forms until the enum implementsDisplay. - D030, "Printing follows construction": it is the readable form;
strof a type withDisplaygives its text. - D022:
{x}is the display form; the type?;{x=}is the readable form; specs format BigInts.Ordfor 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:
12bigis data;data.writecalls 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:
printwrites display forms;strjoins them. - design/ffi.md §3: the type is
BigIntof the core; a:u64result compares by value with any number.
Migration
- Printing. Nothing in user code breaks: an
extend-type T Showkeeps deciding both forms untilTgains aDisplay. What changes understr,printand{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 ofstd, the compiler, the tests and the examples finds one such use of an error,error-message's own fallback, and no test that prints aTime, aDuration, aStyle, aColor, aSpanor aPlacethat way; the test run decides. - Equality. A program that relied on a BigInt never being
=to an integer changes meaning: a map with the keys5and(bigint.of 5)has one key. In the repository:tests/cases/decimal-equality.diasexpects(= 1dec (bigint.of 1))to be false, andtests/dias/math-bigint.diasandtests/dias/decimal.diasstate the old rule in places; they are rewritten with the properties of "A BigInt is a number". - The name.
std.math.bigint.BigIntandstd.math.BigIntbecomeBigInt:std/math.dias's re-export, the import intests/dias/math-bigint.dias,back/emit/ffi.dias,support/tables.c, and the documents. std:std.coregainsBigIntandDisplay, and the comment onShowis rewritten;std/math/bigint.diasloses the type, itsShowand itsOrd; the six modules of the list gain aDisplay;std.rt.formatgains?and BigInts;std.lang.reader,std.lang.highlightandstd.rt.readinggain the literal;number?is true for decimals and BigInts. The{(pr-str x)}ofstdand 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 onpr-strandstr),tests/cases/param-as.diaswith its snapshot, andtests/ffi/scalars.dias, where the FFI's message becomes18446744073709551616big 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 bindwrites a C constant above 2⁶³−1 as(def NAME (bigint.parse "18446744073709551615"))and adds ause; it writes18446744073709551615biginstead, and the bindings are generated again.std.ffi'su64-maxis 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.
- 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'stoken-node); a reader test andtests/cases, with0x1DEC,0xdecand0x1decdec, all three hexadecimal.f"{n:,}"with a record:std.rt.format'stype-wordasstd.decimal's; a test of the message for a record, an enum's value and a type.'1.10dec:quotegives 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 given1.10dec(which still sees the reader's form andsyntax.decimal-text). The BigInt literal uses the same place in step 5.
- The home of a core type, in the expander only.
core-type-homesgainsstd.core.BigInt, andcheck-opaque(front/expand/resolve.dias) takes the home for the type's module, as the orphan check (front/expand/protocols.dias) does. The runtime setsDSP_TYPE_BIGINTfor 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'sstdneeds a compiler that knows this. BigIntmoves, and is a number.- Tests first:
tests/cases/bigint-number.diaswith the examples of "A BigInt is a number" (both tiers); intests/dias/math-bigint.dias, the properties over generated integers, floats, decimals and BigInts (=an equivalence,=exactly whencompareis 0,compareantisymmetric and transitive,sort, one key in maps and sets,distinct, NaN and the infinities against BigInts);tests/cases/decimal-equality.diasandtests/dias/decimal.diasrewritten;tests/ffi/scalars.diasgains 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.diasgets the type;std/math/bigint.diasloses it with itsOrd;std/math.diasloses 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,compareand<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.diasandeval/host.diasnamestd.core.BigInt; a literal pattern with a BigInt.
- Tests first:
Display.- Tests first:
tests/cases/show-display.dias, the table of rule 2 asexpectforms (a type withShowonly,Displayonly, both, neither, each of them opaque and not, an error type with and withoutDisplay, aFailure, a position; a collection of each; f-strings with{x},{x:?},{x=}, a width; adisplaythat raises);compiler/tests/repl.dias; a deriver's error forderive: #[Display]. - The runtime (
support/print.c,protocols.c,diaspar.h's methods of the core): a slot forDisplaybesidedsp_proto_show;show_by_protocoltakes the form asked for and triesDisplay, thenError.message, when it is the display form (thereadableargument is already 0 only for the value asked for); the display forms of a position and of aFailure;#<Name text>. std.core: the protocol, and the documentation ofstr,pr-str,printanderror-message.std.rt.format: the type?. The compiler listsDisplaybesideShowinback/lower.dias,middle/prune.diasandeval/host.dias.- The six
extend-type … Displayof the list, each with a test in its module's tests;place-textmoves tostd.doc.
- Tests first:
- The literal and a BigInt's printing.
- Tests first:
tests/cases/bigint-literal.diasand the reader's tests (the forms, the radix forms, the errors and their help,0xabig);tests/cases/error-integer-range.diasand the overflow's help; the transcript of "The question" incompiler/tests/repl.dias; the formatter and the highlighter on the token; the data round trip instd/tests/rt-reading.dias; format specs on BigInts against CPython's integers, as D022's tests do;'12big. std.lang.reader,std.lang.syntax(abigint-textbesidedecimal-text),std.rt.reading,std.lang.highlight,std.lang.fmt;resolve.diassendsstd.core.%biginttostd.math.bigint, as%decimaltostd.decimal; the constant is static data, as a decimal's.- The runtime prints a BigInt (
show_bigintbesideshow_decimal, overcoef_digits);std.math.bigintloses itsShow;std.rt.formatformats BigInts. diaspar bindandstd.ffiwrite the literal; the generated bindings are generated again.
- Tests first:
- 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.
- Two protocols,
Show(readable, derived) and a new one for people (by hand), with the fallback one way? Recommended: yes. - The name of the new protocol. Recommended:
Display, Rust's word, next to Haskell'sShow. 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:ToStringwith a methodto-string(Lean, Rust's blanket trait;stdalready saysbigint.to-stringanddecimal.to-string), orText. - The suffix. Recommended:
big, for D038's reason.Nis Clojure's and EDN's and stands out after digits;nis JavaScript's and the most widely known. Either letter also keeps hexadecimal literals easy to read (0xFFnagainst0xFFbig). - An integer literal out of range: an error with the help, not a BigInt? Recommended: yes.
{x:?}in f-strings? Recommended: yes. It can be left out without touching the rest; then the readable form is{(pr-str x)}.- An error's text. Should
strof a value that implementsErrorand notDisplaybe itsError.message, as Python'sstr(e)and Rust'sDisplayfor errors?error-messageis this chain already. Recommended: yes, as its own small change after this one, so thatf"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 everyDisplaynow. - 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 and5and5bigbeing 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. - Does
BigIntmove into the core asDecimaldid (the type in the prelude, the operations instd.math.bigint)? Recommended: not now; the literal does not need it. Answered: now. #<Name text>for an opaque type withDisplayand noShow? Recommended: yes.- Which library types get a
Displaywith this change? Recommended:BigIntandStyleonly;Color,Time,DurationandSpanone by one. Answered: all that need one, now.
Open
Not decided here; none blocks the plan.
- JSON.
std.jsondecodes 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. Decimalopaque. The home rule of step 2 letsDecimalbe opaque asBigIntis, which would close(Decimal coefficient: "x" scale: -1).- Integer functions on BigInts.
quot,rem,mod,inc,dec,even?andodd?take integers only, and/has no method for a BigInt;std.math.biginthas 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 ("
Displayinstd"); if an exact one is wanted instead, it is a change of one line. - A
Formatprotocol that receives the spec, for dates.
Sources
- Python: PEP 3140, "str(container) should call str(item), not repr(item)": status Rejected, "this would cause too much disturbance too close to beta".
- Elixir 1.20: Protocols (
String.Charsand a tuple), Inspect (the three shapes, deriving). - Swift: forums.swift.org/t/36166: an array prints its elements by
debugDescription. - Julia 1.12: Integers and Floating-Point Numbers (literals too large become
Int128, thenBigInt; overflow wraps;big"…"), and discourse.julialang.org/t/28941. - Clojure: ask.clojure.org 8510,
+'. - JavaScript: v8.dev/features/bigint.
- The rest (Rust, Lean, Haskell, OCaml, Racket, Common Lisp, Kotlin, Java, C#) from their documentation as known, not checked again.