9.3
58.6 Numbers and Units
The format-integer, format-decimal, and related formatters return strings. Numeric label constructors return text Visuals. Live displays instead read a scene value when sampled. Units are display data, not a physical-dimension calculation system.
See also Text Content and Layout, Relations and Live Layout.
58.6.1 Numeric Displays
Numeric displays provide number-shaped text and numerical transitions without introducing a mutable value tracker. Static constructors return ordinary text-visual? values. parameter-display and rolling-number-display format the current scalar scene parameter independently at each sampled frame. Both are fixed-structure relation-visual? values with an explicit scalar dependency.
procedure
(numeric-display-anchor? value) → boolean?
value : any/c
Recognizes 'left, 'center, 'right,
'decimal, and 'sign.
58.6.1.1 Formatting Strings and Units
procedure
(format-integer value [ #:grouping? grouping? #:show-sign? show-sign? #:unit unit]) → string? value : exact-integer? grouping? : boolean? = #f show-sign? : boolean? = #f unit : string? = ""
Formats an exact integer with an optional leading plus sign, comma grouping,
and trailing literal unit. For example,
(format-integer -1234567 #:grouping? #t) returns
"-1,234,567".
procedure
(format-decimal value [ #:decimal-places decimal-places #:grouping? grouping? #:show-sign? show-sign? #:unit unit]) → string? value : finite-real? decimal-places : exact-nonnegative-integer? = 2 grouping? : boolean? = #f show-sign? : boolean? = #f unit : string? = ""
Formats a finite real with exactly decimal-places fractional digits,
rounding once before the integral and fractional fields are separated. It keeps
trailing zeroes. The procedure raises an exception if multiplying the magnitude
by its requested decimal factor would overflow.
Formatting is independent of text rendering.
Examples:
> (format-integer -1234567 #:grouping? #t) "-1,234,567"
> (format-decimal 5 #:decimal-places 2) "5.00"
procedure
(unit symbol [#:power power]) → numeric-unit?
symbol : string? power : exact-integer? = 1
Creates one semantic upright unit factor. power must be nonzero.
Negative powers represent denominator factors; for example,
(unit "s" #:power -2) formats as "s⁻²".
procedure
(numeric-unit? value) → boolean?
value : any/c
Recognizes an immutable semantic unit created by unit or
unit-product.
procedure
(unit-product first rest ...) → numeric-unit?
first : numeric-unit? rest : numeric-unit?
Concatenates unit factors in declared order. This is display data, not a
dimension-calculation system.
procedure
(format-unit value) → string?
value : (or/c string? numeric-unit?)
Returns a literal unit unchanged or turns semantic factors into Unicode upright
text, such as "m·s⁻²".
Unit factors preserve their declared order.
Example:
> (format-unit (unit-product (unit "m") (unit "s" #:power -2))) "m·s⁻²"
procedure
(format-scientific value [ #:significant-figures figures #:show-sign? show-sign? #:unit unit]) → string? value : finite-real? figures : exact-positive-integer? = 3 show-sign? : boolean? = #f unit : (or/c string? numeric-unit?) = ""
Formats a normalized decimal mantissa and a signed ASCII e exponent. It
uses ordinary text rather than typeset exponent geometry so it remains stable
in every supported text renderer.
procedure
(format-significant value [ #:significant-figures figures #:notation notation #:grouping? grouping? #:show-sign? show-sign? #:unit unit]) → string? value : finite-real? figures : exact-positive-integer? = 3 notation : (or/c 'auto 'fixed 'scientific) = 'auto grouping? : boolean? = #f show-sign? : boolean? = #f unit : (or/c string? numeric-unit?) = ""
Rounds to a requested number of significant figures. 'auto selects
scientific notation for large values and values below 0.001.
procedure
(format-rational value [ #:max-denominator maximum #:mixed? mixed? #:show-sign? show-sign? #:unit unit]) → string? value : finite-real? maximum : exact-positive-integer? = 1000 mixed? : boolean? = #f show-sign? : boolean? = #f unit : (or/c string? numeric-unit?) = ""
Chooses the nearest fraction among positive denominators through
maximum, then reduces it. This gives legible deterministic output for
inexact animated samples; it is not symbolic rational arithmetic.
procedure
(format-complex value [ #:decimal-places decimal-places #:grouping? grouping? #:show-sign? show-sign? #:imaginary-unit imaginary-unit #:unit unit]) → string? value : (or/c finite-real? finite-complex?) decimal-places : exact-nonnegative-integer? = 2 grouping? : boolean? = #f show-sign? : boolean? = #f imaginary-unit : string? = "i" unit : (or/c string? numeric-unit?) = ""
Formats Cartesian components as, for example, "3.00 - 0.50i".
There is deliberately no polar or symbolic simplification mode.
58.6.1.2 Static Numeric Visuals
procedure
(integer value #:id id [ #:center center #:font-size font-size #:font-family font-family #:font-style font-style #:font-weight font-weight #:color color #:horizontal-alignment horizontal-alignment #:vertical-alignment vertical-alignment #:grouping? grouping? #:show-sign? show-sign? #:unit unit]) → text-visual? value : exact-integer? id : symbol? center : vec2? = origin font-size : (and/c finite-real? positive?) = 1/2 font-family : text-font-family? = 'default font-style : text-font-style? = 'normal font-weight : text-font-weight? = 'normal color : any/c = "black" horizontal-alignment : text-horizontal-alignment? = 'center vertical-alignment : text-vertical-alignment? = 'center grouping? : boolean? = #f show-sign? : boolean? = #f unit : string? = ""
Creates an ordinary one-line integer display. Its placement and text styling
have the same meaning as for plain-text.
procedure
(decimal-number value #:id id [ #:center center #:font-size font-size #:font-family font-family #:font-style font-style #:font-weight font-weight #:color color #:horizontal-alignment horizontal-alignment #:vertical-alignment vertical-alignment #:decimal-places decimal-places #:grouping? grouping? #:show-sign? show-sign? #:unit unit]) → text-visual? value : finite-real? id : symbol? center : vec2? = origin font-size : (and/c finite-real? positive?) = 1/2 font-family : text-font-family? = 'default font-style : text-font-style? = 'normal font-weight : text-font-weight? = 'normal color : any/c = "black" horizontal-alignment : text-horizontal-alignment? = 'center vertical-alignment : text-vertical-alignment? = 'center decimal-places : exact-nonnegative-integer? = 2 grouping? : boolean? = #f show-sign? : boolean? = #f unit : string? = ""
Creates a fixed-place decimal display. In contrast to the generic
numeric-label, an exact integer still receives the requested decimal
point and trailing zeroes here.
procedure
(scientific-number value #:id id [ #:center center #:significant-figures figures #:unit unit #:font-size font-size #:font-family font-family #:color color]) → text-visual? value : finite-real? id : symbol? center : vec2? = origin figures : exact-positive-integer? = 3 unit : (or/c string? numeric-unit?) = "" font-size : (and/c finite-real? positive?) = 1/2 font-family : text-font-family? = 'default color : any/c = "black"
Creates a static label using format-scientific.
procedure
(significant-number value #:id id [ #:center center #:significant-figures figures #:notation notation #:unit unit #:font-size font-size #:font-family font-family #:color color]) → text-visual? value : finite-real? id : symbol? center : vec2? = origin figures : exact-positive-integer? = 3 notation : (or/c 'auto 'fixed 'scientific) = 'auto unit : (or/c string? numeric-unit?) = "" font-size : (and/c finite-real? positive?) = 1/2 font-family : text-font-family? = 'default color : any/c = "black"
Creates a static label using format-significant.
procedure
(rational-number value #:id id [ #:center center #:max-denominator maximum #:mixed? mixed? #:unit unit #:font-size font-size #:font-family font-family #:color color]) → text-visual? value : finite-real? id : symbol? center : vec2? = origin maximum : exact-positive-integer? = 1000 mixed? : boolean? = #f unit : (or/c string? numeric-unit?) = "" font-size : (and/c finite-real? positive?) = 1/2 font-family : text-font-family? = 'default color : any/c = "black"
Creates a static label using format-rational.
procedure
(complex-number value #:id id [ #:center center #:decimal-places decimal-places #:imaginary-unit imaginary-unit #:unit unit #:font-size font-size #:font-family font-family #:color color]) → text-visual? value : (or/c finite-real? finite-complex?) id : symbol? center : vec2? = origin decimal-places : exact-nonnegative-integer? = 2 imaginary-unit : string? = "i" unit : (or/c string? numeric-unit?) = "" font-size : (and/c finite-real? positive?) = 1/2 font-family : text-font-family? = 'default color : any/c = "black"
Creates a static Cartesian-complex label using format-complex.
procedure
(numeric-label value #:id id [ #:center center #:kind kind #:decimal-places decimal-places #:significant-figures figures #:notation notation #:max-denominator maximum #:mixed? mixed? #:grouping? grouping? #:show-sign? show-sign? #:imaginary-unit imaginary-unit #:unit unit #:font-size font-size #:font-family font-family #:font-style font-style #:font-weight font-weight #:color color #:horizontal-alignment horizontal-alignment #:vertical-alignment vertical-alignment]) → text-visual? value : (or/c finite-real? finite-complex?) id : symbol? center : vec2? = origin
kind :
(or/c 'auto 'integer 'decimal 'scientific 'significant 'rational 'complex) = 'auto decimal-places : exact-nonnegative-integer? = 2 figures : exact-positive-integer? = 3 notation : (or/c 'auto 'fixed 'scientific) = 'auto maximum : exact-positive-integer? = 1000 mixed? : boolean? = #f grouping? : boolean? = #f show-sign? : boolean? = #f imaginary-unit : string? = "i" unit : (or/c string? numeric-unit?) = "" font-size : (and/c finite-real? positive?) = 1/2 font-family : text-font-family? = 'default font-style : text-font-style? = 'normal font-weight : text-font-weight? = 'normal color : any/c = "black" horizontal-alignment : text-horizontal-alignment? = 'center vertical-alignment : text-vertical-alignment? = 'center
At 'auto, creates integer output for an exact integer, fixed decimal
output for another finite real, and Cartesian output for a finite complex value.
The explicit #:kind choices select the corresponding formatter.
58.6.1.3 Parameter-Driven Displays
procedure
(parameter-display source #:id id [ #:center center #:kind kind #:decimal-places decimal-places #:significant-figures figures #:notation notation #:max-denominator maximum #:mixed? mixed? #:grouping? grouping? #:show-sign? show-sign? #:imaginary-unit imaginary-unit #:unit unit #:anchor anchor #:font-size font-size #:font-family font-family #:font-style font-style #:font-weight font-weight #:color color #:vertical-alignment vertical-alignment]) → relation-visual? source : (or/c symbol? scene-parameter?) id : symbol? center : vec2? = origin
kind :
(or/c 'integer 'decimal 'scientific 'significant 'rational 'complex) = 'decimal decimal-places : exact-nonnegative-integer? = 2 figures : exact-positive-integer? = 3 notation : (or/c 'auto 'fixed 'scientific) = 'auto maximum : exact-positive-integer? = 1000 mixed? : boolean? = #f grouping? : boolean? = #f show-sign? : boolean? = #f imaginary-unit : string? = "i" unit : (or/c string? numeric-unit?) = "" anchor : numeric-display-anchor? = 'right font-size : (and/c finite-real? positive?) = 1/2 font-family : text-font-family? = 'default font-style : text-font-style? = 'normal font-weight : text-font-weight? = 'normal color : any/c = "black" vertical-alignment : text-vertical-alignment? = 'center
Reads source from each sampled scene state and formats its finite real
or Cartesian-complex value. A 'decimal display has exactly its
requested decimal places; an 'integer display rounds a finite real to
the nearest integer. Scientific, significant, rational, and complex kinds use
the correspondingly named formatter. The source must be installed with
scene-set-value before the relation is resolved. Its dependency and
built-in serializable specification are inspectable with
relation-visual-dependencies and
relation-visual-cacheability. Because the display has fixed child
structure, its decimal 'whole and 'fraction paths remain
addressable as its value changes.
The #:anchor choice fixes one stable reference as the text width changes. 'left, 'center, and 'right are the normal text anchors. 'sign forces a visible sign and anchors its left edge. 'decimal creates a small resolved group containing local 'whole and 'fraction children on opposite sides of the fixed decimal point. They are separate text runs, so kerning is not attempted across that join.
procedure
(rolling-number-display source #:id id [ #:center center #:integer-digits integer-digits #:decimal-places decimal-places #:show-sign? show-sign? #:unit unit #:anchor anchor #:font-size font-size #:font-family font-family #:font-style font-style #:font-weight font-weight #:color color #:vertical-alignment vertical-alignment]) → derived-visual? source : (or/c symbol? scene-parameter?) id : symbol? center : vec2? = origin integer-digits : exact-positive-integer? = 3 decimal-places : exact-nonnegative-integer? = 0 show-sign? : boolean? = #f unit : (or/c string? numeric-unit?) = "" anchor : numeric-display-anchor? = 'right font-size : (and/c finite-real? positive?) = 1/2 font-family : text-font-family? = 'modern font-style : text-font-style? = 'normal font-weight : text-font-weight? = 'normal color : any/c = "black" vertical-alignment : text-vertical-alignment? = 'center
Creates a fixed-slot odometer-style display. The source must produce a
nonnegative finite real smaller than (expt 10 integer-digits). Each
slot clips its current and next glyphs and rolls in the last tenth of its digit
interval before a carry. The result is calculated directly from the sampled
number, including at a frame rendered out of order; it stores no bitmap or prior
numeric state. Digit advances use a nominal monospaced width, so a font with
tabular figures gives the best alignment.