The value types.
A Unit is a named registered unit — a name, an exact base-SI magnitude, and
a stored dimension map. foot, meter, newton, beer are all Units; a bare
Unit is one of itself and prints foot [length]. defunit mints Units.
A Quantity is an anonymous computed value — an exact magnitude plus an
ordered display formula (a vector of UnitTerms). Its dimensions are derived
from the formula, never stored, so they can't disagree with it. Every exact
arithmetic result is a Quantity.
An ApproxQuantity is the same as a Quantity but its magnitude is an
arbitrary-precision BigDecimal — for irrational values (planck units,
semitone, Richter) that have no exact rational form. Arithmetic promotes:
the moment any operand is approximate, the result is an ApproxQuantity and the
magnitude math runs under the caller's *math-context* (with-precision /
binding), defaulting to DECIMAL128. Values print under two tags —
#commensura/unit and #commensura/quantity — with a leading ≈ in the payload
marking approximate values, so inexactness is never mistaken for exact.
So: named ⇒ Unit (stores dims), anonymous ⇒ Quantity/ApproxQuantity (store a
formula); dims live in exactly one place. All are callable and implement
Dimensionable/Measured/Formulaic.
The value types. A `Unit` is a *named* registered unit — a name, an exact base-SI magnitude, and a stored dimension map. `foot`, `meter`, `newton`, `beer` are all Units; a bare Unit is one of itself and prints `foot [length]`. `defunit` mints Units. A `Quantity` is an *anonymous* computed value — an exact magnitude plus an ordered display `formula` (a vector of `UnitTerm`s). Its dimensions are *derived* from the formula, never stored, so they can't disagree with it. Every exact arithmetic result is a Quantity. An `ApproxQuantity` is the same as a `Quantity` but its magnitude is an arbitrary-precision `BigDecimal` — for *irrational* values (planck units, `semitone`, Richter) that have no exact rational form. Arithmetic *promotes*: the moment any operand is approximate, the result is an `ApproxQuantity` and the magnitude math runs under the caller's `*math-context*` (`with-precision` / `binding`), defaulting to DECIMAL128. Values print under two tags — `#commensura/unit` and `#commensura/quantity` — with a leading `≈` in the payload marking approximate values, so inexactness is never mistaken for exact. So: named ⇒ Unit (stores dims), anonymous ⇒ Quantity/ApproxQuantity (store a formula); dims live in exactly one place. All are callable and implement `Dimensionable`/`Measured`/`Formulaic`.
(bexp x)e^x as a BigDecimal at the caller's *math-context* (default DECIMAL128); x is
any number, coerced to BigDecimal under that context.
e^x as a BigDecimal at the caller's `*math-context*` (default DECIMAL128); x is any number, coerced to BigDecimal under that context.
(bln x)Natural log of a positive number as a BigDecimal at the caller's *math-context*.
Natural log of a positive number as a BigDecimal at the caller's `*math-context*`.
(dims x)Base-dimension -> integer-exponent map (zero exponents removed).
Base-dimension -> integer-exponent map (zero exponents removed).
(display-string x)The full human-readable payload — value, unit, trailing [dimension] — that is a
unit/quantity's toString and the body of its #commensura/… tagged literal.
The full human-readable payload — value, unit, trailing `[dimension]` — that is a unit/quantity's `toString` and the body of its `#commensura/…` tagged literal.
(display-value x)The value shown to the user: base magnitude ÷ the display formula's factor (a bare unit is 1; a plain number is itself). Used by the printer, intervals, and the reader.
The value shown to the user: base magnitude ÷ the display formula's factor (a bare unit is 1; a plain number is itself). Used by the printer, intervals, and the reader.
(exact-int-root m q)The q-th root of non-negative integer m if m is a perfect q-th power, else nil.
The q-th root of non-negative integer m if m is a perfect q-th power, else nil.
(formula-factor formula)Base magnitude of the compound display unit: the product of each term's factor raised to its
exponent (so display-value = magnitude / formula-factor). 1 for a bare/dimensionless value.
Base magnitude of the compound display unit: the product of each term's factor raised to its exponent (so `display-value = magnitude / formula-factor`). 1 for a bare/dimensionless value.
(formula x)A vector of UnitTerms that describe the components of a measurement.
A vector of UnitTerms that describe the components of a measurement.
(magnitude x)Magnitude in base SI units. Exact for Units/Quantities/plain numbers
(rationalized, so 3.2 -> 16/5); a BigDecimal for ApproxQuantities.
Magnitude in base SI units. Exact for Units/Quantities/plain numbers (`rationalize`d, so 3.2 -> 16/5); a BigDecimal for ApproxQuantities.
(qcompare x y)Three-way compare of two conforming units/quantities/numbers by base-SI magnitude,
returning -1 / 0 / 1 (like clojure.core/compare). This is a physical comparison:
(qcompare (unit "inch" …) (unit "foot" …)) orders by base magnitude, so 12 inch and
1 foot compare equal even though they are not structurally = (which also compares
the display formula). Non-conforming dimensions throw, as with qadd/qsub.
Exact when both operands are precise (compared in the rational tower); when either is
approximate, both magnitudes are coerced to BigDecimal under *math-context* and compared
by value — so equality of irrationals is precision-sensitive, the same boundary as approx
arithmetic.
Three-way compare of two conforming units/quantities/numbers by base-SI `magnitude`, returning -1 / 0 / 1 (like `clojure.core/compare`). This is a *physical* comparison: `(qcompare (unit "inch" …) (unit "foot" …))` orders by base magnitude, so 12 inch and 1 foot compare **equal** even though they are not structurally `=` (which also compares the display formula). Non-conforming dimensions throw, as with `qadd`/`qsub`. Exact when both operands are precise (compared in the rational tower); when either is approximate, both magnitudes are coerced to BigDecimal under `*math-context*` and compared by value — so equality of irrationals is precision-sensitive, the same boundary as approx arithmetic.
(qpow x n)Raise to an integer or rational exponent. A rational exponent scales the dimensions (which
must stay integer) and takes the root of the magnitude — exact when a perfect root, else an
ApproxQuantity. quantity picks Precise vs Approx from the resulting magnitude, since an exact
base can go irrational under a fractional exponent.
Raise to an integer or rational exponent. A rational exponent scales the dimensions (which must stay integer) and takes the root of the magnitude — exact when a perfect root, else an ApproxQuantity. `quantity` picks Precise vs Approx from the resulting magnitude, since an exact base can go irrational under a fractional exponent.
(quantity mag formula)Mint a PreciseQuantity if the magnitude is a ratio or integer, or can be rationalized to an integer. Otherwise, returns an ApproxQuantity.
Mint a PreciseQuantity if the magnitude is a ratio or integer, or can be rationalized to an integer. Otherwise, returns an ApproxQuantity.
(ratio q target)Bare dimensionless count: how many of target fit in q.
Bare dimensionless count: how many of target fit in q.
(ratpow base n)base^n for a magnitude base and rational exponent n: an exact rational when the result is a perfect root, else a BigDecimal at math-context.
base^n for a magnitude base and rational exponent n: an exact rational when the result is a perfect root, else a BigDecimal at *math-context*.
(scalar n)Wrap a plain number as a dimensionless Quantity (idempotent on any quantity).
Wrap a plain number as a dimensionless Quantity (idempotent on any quantity).
(scale q n)Scale a quantity's magnitude by a plain number — what (u/feet 10) does.
Yields an anonymous Quantity (or ApproxQuantity if the input is approximate).
Scale a quantity's magnitude by a plain number — what `(u/feet 10)` does. Yields an anonymous Quantity (or ApproxQuantity if the input is approximate).
(to q target)Re-express q over the target unit basis (dimension-preserving). The physical magnitude is unchanged — only the display formula becomes the target's, so the printed value equals magnitude(q)/factor(target).
Re-express q over the target unit basis (dimension-preserving). The physical magnitude is unchanged — only the display formula becomes the target's, so the printed value equals magnitude(q)/factor(target).
(unit name mag dims)Mint a named registered Unit from a name, base magnitude, and dimensions —
what defunit and the generated builtins call.
Mint a named registered `Unit` from a name, base magnitude, and dimensions — what `defunit` and the generated builtins call.
cljdoc builds & hosts documentation for Clojure/Script libraries
| Ctrl+k | Jump to recent docs |
| ← | Move to previous article |
| → | Move to next article |
| Ctrl+/ | Jump to the search field |