A unit on every computed trace value, and a 128-bit Rational

CHANGELOG.md

@@ -6,6 +6,46 @@ change is recorded here.
 
 ## [Unreleased]
 
+### Added
+
+- **`formula::Int128`** (`int128.hpp`), a signed 128-bit integer with one API on every compiler: the compiler's own
+  128-bit integer computes where it has one (GCC, Clang), portable `constexpr` code everywhere else (cl, clang-cl).
+  It converts to no built-in integer implicitly or explicitly; `to_int64()` and `to_uint64()` say when a value does
+  not fit. `std::format` writes it in decimal, and `std::numeric_limits<formula::Int128>` states its limits as a
+  built-in signed integer's are.
+
+### Changed
+
+- **Every computed value in a trace shows a unit.** A value scaled by a pure number, and a sum or difference of
+  values shown in one unit, read in that unit: the outlier-rejection limit `#2 * #3 = 1239/500000` is now
+  `#2 * #3 = 1239/500 g`. A negation and an absolute value read in their operand's unit, and a conditional and a
+  precision limit in the unit of the step they restate. An offset unit is never borrowed for a sum, difference,
+  scaling or negation: the difference of two Celsius readings reads in `K`. Any other dimensioned value is shown in
+  the coherent unit, followed by its spelling from the base units (`427/125000000 kg^2`, `60000000 kg/(m s^2)`), and
+  so is a value in a unit that has no symbol. A dimensionless value is still a bare number. A trace text pinned in
+  a test changes wherever it showed a dimensioned value bare. `Step::unit` of a scaled, summed, negated,
+  absolute-value, conditional or precision-limit step now holds the unit it borrowed, so code that reads steps sees the unit the
+  trace text names.
+- A snap's permitted values, a binning's classes, a lookup's bands and rows and a curve's rows, declared in a unit
+  that has no symbol, are written in the coherent unit with its spelling, as the value beside them is, rather than
+  as numbers in a scale the line does not name.
+- **`Rational` stores its numerator and denominator in `formula::Int128`**, so `Rational::Int` is `Int128` and a
+  `Rational` is 32 bytes. Realistic laboratory statistics that overflowed 64 bits now answer: the sample variance of
+  masses read to 6 decimal places of a gram, rejection by standard deviations at that resolution, and a cylinder's
+  strength at every diameter measured (`docs/numeric-headroom.md`). Code that stored `numerator()` or `denominator()`
+  in a built-in integer must narrow with `to_int64()`. The `_r` literal, `Rational::from_decimal`'s exponents and
+  rounding's decimal places keep their limits of 18.
+- `rounded_sqrt` computes in 128 bits, and answers at more places before it reports `Overflow`.
+- `NumberTextCapacity` is 128, so that a 39-digit numerator over a 39-digit denominator fits a `NumberText`.
+- `band(Rational, Rational)` and `breakpoint(Rational)` refuse a bound or key that does not fit their 64-bit fields:
+  in a constant expression it fails to compile, naming `formula_band_bound_out_of_range` or
+  `formula_breakpoint_key_out_of_range`; reached at run time, it ends the program, because a `Band` or a
+  `Breakpoint` is a template argument, built at compile time, and has no way to carry a failure.
+- `Step` gains `lookupKeyHigh`, bits 64 to 127 of the count a sample-size lookup selected with, so that a miss on a
+  count above 2^64 - 1 names the whole count. Code that reads `lookupKey` for such a step reads both.
+- `Rational`'s converting constructor takes every built-in integer type of at most 64 bits except `bool`, exactly,
+  `std::uint64_t` now among them; a wider built-in integer is refused. A constructor from `Int128` is added.
+
 ## [0.3.0] - 2026-10-01
 
 The third release. It gives a shorter spelling to everything the examples repeated, and takes no

CMakeLists.txt

@@ -72,6 +72,7 @@ target_sources(formula-cpp INTERFACE
         "${CMAKE_CURRENT_SOURCE_DIR}/include/formula-cpp/format.hpp"
         "${CMAKE_CURRENT_SOURCE_DIR}/include/formula-cpp/formula.hpp"
         "${CMAKE_CURRENT_SOURCE_DIR}/include/formula-cpp/function.hpp"
+        "${CMAKE_CURRENT_SOURCE_DIR}/include/formula-cpp/int128.hpp"
         "${CMAKE_CURRENT_SOURCE_DIR}/include/formula-cpp/least_squares.hpp"
         "${CMAKE_CURRENT_SOURCE_DIR}/include/formula-cpp/lineage.hpp"
         "${CMAKE_CURRENT_SOURCE_DIR}/include/formula-cpp/lookup.hpp"
@@ -210,7 +211,7 @@ if(FORMULA_BUILD_TESTS AND FORMULA_BUILD_EXAMPLES AND FORMULA_TOOLS)
         add_test(NAME census.exact-sizes
             COMMAND "${Python3_EXECUTABLE}" "${PROJECT_SOURCE_DIR}/tools/census/exact_sizes.py")
         set_tests_properties(census.exact-sizes PROPERTIES PASS_REGULAR_EXPRESSION
-            "at 6 dp: the exact variance does not fit 64 bits in 374 of 1000 in kg2 \\(SI\\), in 0 of 1000 in g2 \\(declared. widest 45 bits\\)[\r\n]+[^\r\n]*at d = 101 \\(64 bits\\), 103 \\(64 bits\\), 107 \\(64 bits\\), 109 \\(64 bits\\), 113 \\(64 bits\\), 119 \\(64 bits\\), 121 \\(64 bits\\), 127 \\(64 bits\\), 131 \\(64 bits\\), 137 \\(64 bits\\), 139 \\(64 bits\\), 143 \\(64 bits\\), 149 \\(64 bits\\), 151 \\(64 bits\\), 157 \\(64 bits\\), 161 \\(64 bits\\), 163 \\(64 bits\\)[\r\n]+[^\r\n]*in MPa \\(declared\\) it does not fit at 0 of 63 \\(widest 44 bits\\)")
+            "at 6 dp: the exact variance does not fit 128 bits in 0 of 1000 in kg2 \\(SI. widest 65 bits\\), in 0 of 1000 in g2 \\(declared. widest 45 bits\\)[\r\n]+[^\r\n]*in Pa \\(SI\\) the exact strength does not fit 128 bits at 0 of 63 \\(widest 64 bits\\)[\r\n]+[^\r\n]*in MPa \\(declared\\) it does not fit at 0 of 63 \\(widest 44 bits\\)")
     endif()
     add_test(NAME docs.numeric-headroom
         COMMAND "${CMAKE_COMMAND}" ${censusPageArguments} -P "${PROJECT_SOURCE_DIR}/cmake/CheckCensusPage.cmake")

README.md

@@ -234,18 +234,21 @@ std::print("{}", formula::render_trace(explained.trace, { .maxSteps = 10 }));
 4. #3 = 3/5 [Water/cement ratio, Example Standard 1:2020, 5.4.2, (3)]
 ```
 
-Every value is shown in the unit it was declared in, not the coherent unit
-the arithmetic actually ran on — that is `9/50` cubic metres above, and nobody
-typed cubic metres. When the environment overrides the result instead of
-letting the formula derive it, `explained.trace` comes back empty — nothing
-ran, so nothing was recorded — and `explained.outcome.is_overridden()` says
-so instead: an overridden number shows *that a person entered it*, a
-different fact from how it was reached and arguably a more important one.
-See [the tracing guide](docs/tracing.md) for the detail. Tracing costs
-nothing when nobody asks for it: a sink is
-passed by value, and the untraced path — `evaluate()`, `checked_evaluate()` —
-defaults to one that does nothing, adding no instruction the evaluator would
-not already emit once the call inlines, measured on all four compilers this
+Every value is shown in the unit written after it: an input in the unit it was
+declared in, not the coherent unit the arithmetic actually ran on — that is
+`9/50` cubic metres above, and nobody typed cubic metres. A computed value
+borrows the unit of the values it was computed from where that is safe, and is
+otherwise shown in the coherent unit, spelt from the base units (`kg/m^3`);
+only a dimensionless value, like the ratio above, is a bare number. When the
+environment overrides the result instead of letting the formula derive it,
+`explained.trace` comes back empty — nothing ran, so nothing was recorded —
+and `explained.outcome.is_overridden()` says so instead: an overridden number
+shows *that a person entered it*, a different fact from how it was reached and
+arguably a more important one. See [the tracing guide](docs/tracing.md) for
+the detail. Tracing costs nothing when nobody asks for it: a sink is passed by
+value, and the untraced path — `evaluate()`, `checked_evaluate()` — defaults
+to one that does nothing, adding no instruction the evaluator would not
+already emit once the call inlines, measured on all four compilers this
 library targets. See [the tracing guide](docs/tracing.md).
 
 ### A published table that a value falls outside of gives no number at all

cmake/CheckCensusPage.cmake

@@ -74,7 +74,7 @@ census_block(regression regressionTable)
 
 # ---- The census twins ---------------------------------------------------------------
 set(examplesTable "| program | numerator bits | denominator bits | intermediate bits | headroom |\n|---|---|---|---|---|\n")
-set(censusLine "overflow census: numerator ([0-9]+) bits, denominator ([0-9]+) bits, intermediate ([0-9]+) bits, unsigned ([0-9]+) bits; headroom ([0-9]+) of 63")
+set(censusLine "overflow census: numerator ([0-9]+) bits, denominator ([0-9]+) bits, intermediate ([0-9]+) bits, unsigned ([0-9]+) bits; headroom ([0-9]+) of 127")
 
 function(twin_row label program outVariable)
     execute_process(

docs/calculations.md

@@ -545,9 +545,9 @@ In it, a calculated value it reads is one step, marked `calculated`:
 daily_load = fridge_kwh + oven_kwh + heater_kwh = 13.3 kWh
   1. fridge_kwh = 4.8 kWh, calculated
   2. oven_kwh = 2.5 kWh, calculated
-  3. #1 + #2 = 26280000
+  3. #1 + #2 = 7.3 kWh
   4. heater_kwh = 6 kWh, calculated
-  5. #3 + #4 = 47880000
+  5. #3 + #4 = 13.3 kWh
 ```
 
 The blocks of the calculated values it reads follow it, the last calculated
@@ -559,7 +559,7 @@ the fridge's energy reads. The inputs read come last, one line each:
 fridge_kwh = fridge_kw * fridge_h = 4.8 kWh
   1. fridge_kw = 0.4 kW, calculated
   2. fridge_h = 12 h
-  3. #1 * #2 = 17280000
+  3. #1 * #2 = 17280000 m^2 kg/s^2
 fridge_kw = fridge_w = 0.4 kW
   1. fridge_w = 400 W
 inputs
@@ -594,9 +594,11 @@ Asking for `Q` brings it up to date, as `checked_calculate` does, and counts as
 it does; recording the blocks calculates nothing again. Here nothing was out
 of date, and the example checks that neither counter moved.
 
-A computed step states its value in the coherent unit of its dimension, as
-every trace does: the fridge's 4.8 kWh reads `17280000` there, in joules,
-under a header in kilowatt-hours.
+A computed step states its value in the unit its trace step is shown in, as
+every trace does: a unit borrowed from the steps it read where that is safe,
+and otherwise the coherent unit of its dimension, spelt from its base units. A
+power times a time borrows neither one's unit, so the fridge's 4.8 kWh reads
+`17280000 m^2 kg/s^2` there, in joules, under a header in kilowatt-hours.
 
 ## A value typed in by hand
 
@@ -629,7 +631,7 @@ std::string const gridText = formula::render_derivation(gridCost, { .maxSteps =
 grid_cost = net_draw * price = 62.5 EUR
   1. net_draw = 250 kWh, entered by hand
   2. price = 0.25 EUR/kWh
-  3. #1 * #2 = 62.5
+  3. #1 * #2 = 62.5 EUR
 net_draw = 250 kWh, entered by hand in place of monthly_load - self_used
 ... 1 further step not shown
 ```

docs/dimensions.md

@@ -445,14 +445,14 @@ which is why a dimension should only ever be built with `base_dimension` and
 the operators.
 
 **In a coherent unit, the name is the symbol.** A computed step in a trace
-carries no unit symbol of its own (see
-[Tracing and audit trails](tracing.md#reading-a-derivation)), but where the
-trace does spell a coherent unit out -- for an opaque operation's output that
-no input's unit fits ([Opaque operations and bounded retry](opaque-and-retry.md))
--- a named base is written by its name, ahead of the SI units on its side of
-the slash: `EUR s^2/(m^2 kg)` for euros per joule, then `1/JPY`, `EUR/JPY`,
-`EUR^(1/2)`. The money comes first because a tariff is read as money per
-energy.
+that has no unit to borrow from the steps it read is shown in the coherent
+unit, and the trace spells that unit out after its number (see
+[Tracing and audit trails](tracing.md#reading-a-derivation)) -- as it does for
+an opaque operation's output that no input's unit fits
+([Opaque operations and bounded retry](opaque-and-retry.md)). A named base is
+written by its name, ahead of the SI units on its side of the slash:
+`EUR s^2/(m^2 kg)` for euros per joule, then `1/JPY`, `EUR/JPY`, `EUR^(1/2)`.
+The money comes first because a tariff is read as money per energy.
 
 ## Limits
 
@@ -498,7 +498,8 @@ filled by hand is checked by none of them.
 
 `Unit`'s `magnitudeNumerator`, `magnitudeDenominator`,
 `offsetNumerator`, `offsetDenominator` and the four fields of `Bounds` are all
-`std::int64_t`, the same width as `Rational`'s own numerator and denominator.
+`std::int64_t`. `Rational`'s own numerator and denominator are 128-bit, so every
+value these fields state converts to one exactly.
 
 Conversion is built on `formula::Rational` and the `checked_` arithmetic
 functions, so it inherits their overflow behaviour and rounding limits