Calculations and worksheets, decimal display with std::format, and application-declared base dimensions

CMakeLists.txt

@@ -50,6 +50,7 @@ target_sources(formula-cpp INTERFACE
         "${CMAKE_CURRENT_SOURCE_DIR}/include/formula-cpp/detail/type_list.hpp"
         "${CMAKE_CURRENT_SOURCE_DIR}/include/formula-cpp/band.hpp"
         "${CMAKE_CURRENT_SOURCE_DIR}/include/formula-cpp/binning.hpp"
+        "${CMAKE_CURRENT_SOURCE_DIR}/include/formula-cpp/calculation.hpp"
         "${CMAKE_CURRENT_SOURCE_DIR}/include/formula-cpp/citation.hpp"
         "${CMAKE_CURRENT_SOURCE_DIR}/include/formula-cpp/conditional.hpp"
         "${CMAKE_CURRENT_SOURCE_DIR}/include/formula-cpp/conformity.hpp"
@@ -64,13 +65,15 @@ target_sources(formula-cpp INTERFACE
         "${CMAKE_CURRENT_SOURCE_DIR}/include/formula-cpp/escape.hpp"
         "${CMAKE_CURRENT_SOURCE_DIR}/include/formula-cpp/evaluate.hpp"
         "${CMAKE_CURRENT_SOURCE_DIR}/include/formula-cpp/expression.hpp"
+        "${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/least_squares.hpp"
         "${CMAKE_CURRENT_SOURCE_DIR}/include/formula-cpp/lineage.hpp"
         "${CMAKE_CURRENT_SOURCE_DIR}/include/formula-cpp/lookup.hpp"
         "${CMAKE_CURRENT_SOURCE_DIR}/include/formula-cpp/measured.hpp"
         "${CMAKE_CURRENT_SOURCE_DIR}/include/formula-cpp/method.hpp"
+        "${CMAKE_CURRENT_SOURCE_DIR}/include/formula-cpp/number_text.hpp"
         "${CMAKE_CURRENT_SOURCE_DIR}/include/formula-cpp/opaque.hpp"
         "${CMAKE_CURRENT_SOURCE_DIR}/include/formula-cpp/outcome.hpp"
         "${CMAKE_CURRENT_SOURCE_DIR}/include/formula-cpp/overlay.hpp"

README.md

@@ -149,6 +149,28 @@ last two lines are the reason that matters: the same number rounds to 1.2 or
 1.1 depending on the rule the method specifies, and the library makes you say
 which.
 
+### A decimal only where it is exact, a rounding only where you ask
+
+```cpp
+#include <formula-cpp/format.hpp>
+```
+
+```text
+std::format("{}", Rational { 3, 5 })                           0.6
+std::format("{}", Rational { 1, 3 })                           1/3
+std::format("{:/}", Rational { 3, 5 })                         3/5
+std::format("{:.2HalfEven}", Rational { 23653, 200 })          118.26
+std::format("{:.2HalfAwayFromZero}", Rational { 23653, 200 })  118.27
+std::format("{:.2HalfEven}", Rational { 4 })                   4.00
+std::format("{:~.3HalfEven}", Rational { 1, 3 })               ≈0.333
+std::format("{:~.3HalfEven}", Rational { 3, 5 })               0.6
+```
+
+`1/3` has no decimal, so it stays `1/3`: `0.333` would be a different number.
+A rounding names its mode — there is no default — and `~` marks it `≈`.
+Traces and rendered formulas take the same choice; see
+[Displaying numbers](docs/display.md).
+
 ### The library documents itself
 
 `document()` walks a formula for its rendered text, its citations and its
@@ -174,7 +196,7 @@ std::string const trace = formula::render_trace(explained.trace, { .maxSteps = 1
 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 SI unit
+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
@@ -232,11 +254,13 @@ because all of it came from the same line of code.
 | Guide | What it covers |
 |---|---|
 | [Exact numbers](docs/numbers.md) | `Rational`, the rounding modes, why exactness is the default |
-| [Dimensions and units](docs/dimensions.md) | Compile-time dimensional analysis, exact unit conversion |
+| [Dimensions and units](docs/dimensions.md) | Compile-time dimensional analysis, exact unit conversion, and base dimensions the SI does not have, such as money |
 | [Quantities](docs/quantities.md) | Declaring a quantity, `Describe`, measurements that may be absent |
 | [Writing formulas](docs/expressions.md) | Operators, evaluation, environments, overrides |
 | [Citations and rendering](docs/citations.md) | `documented()`, the three dialects, generated documentation |
 | [Tracing and audit trails](docs/tracing.md) | `explain()`, `render_trace()`, sinks, and the zero-cost untraced path |
+| [Displaying numbers](docs/display.md) | Decimals in traces and rendered formulas, exact unless an approximation is asked for, and std::format for Rational and Measured |
+| [Calculations and worksheets](docs/calculations.md) | Named values defined by expressions, a dependency graph checked at compile time, a worksheet that recalculates only what a change reaches, what-if copies, overrides, and a derivation per named value |
 | [Rounding and conditionals](docs/rounding-and-conditionals.md) | Rounding as a node, `when()`, and the traced `numeric_value_of` escape hatch |
 | [Constraints and verdicts](docs/constraints.md) | Validating a result with `constraint()` and `check()`, the four-state outcome, and checking a set without short-circuit |
 | [Lookup tables](docs/lookup-tables.md) | The three table kinds, validation that refuses a gap, and why a miss is not a number |
@@ -273,6 +297,10 @@ and still growing. The public API may change until 1.0.
 | Statistics, precision limits, outlier rejection | shipped |
 | Other samples and other tests: records, context, lineage | shipped |
 | Opaque operations (least squares), bounded retry | shipped |
+| Power, energy and Fahrenheit units | next release |
+| Named base dimensions such as money | next release |
+| Decimals in traces, rendered formulas and `std::format` | next release |
+| Calculations: definitions, dependency graph, incremental worksheets | next release |
 
 ## Requirements
 

cmake/CheckDocumentedDiagnostics.cmake

@@ -28,7 +28,12 @@
 #     where a quote carries one, the header's line 219 must really be `<text>`.
 #     This is the strongest check here -- it verifies the number *means* what
 #     the quote says, not merely that something is there.
-#  3. **Every other quoted line must be neither blank nor comment-only.** The
+#  3. **A quoted MSVC `note: see usage of '<name>'` must name a line that
+#     calls `<name>`** -- the last `::` segment, followed by `(`, on a line
+#     that is not a comment. MSVC points that note at the use, so this is as
+#     exact as the `static_assert` rule: it pins a guide's quote of a refusing
+#     guard to the guard's call.
+#  4. **Every other quoted line must be neither blank nor comment-only.** The
 #     `note: see reference to ...` cascade points at instantiation sites, and
 #     no invariant this script can state says which line one of those must be.
 #     But drift lands them on blank lines and in the middle of prose comments,
@@ -292,6 +297,16 @@ foreach(document ${documents})
                 list(APPEND problems
                      "${documentName}:${lineNumber} quotes a static-assertion error at ${headerName}:${quotedNumber}, but that line is not a static_assert -- it is '${headerLine}'")
             endif()
+        elseif(line MATCHES "see usage of '([A-Za-z_][A-Za-z0-9_:]*)'")
+            # MSVC's `note: see usage of 'formula::detail::name'` points at the
+            # call of that function, so line N must call it: `name(`, in code
+            # -- a comment that names the call is not one.
+            string(REGEX REPLACE "^.*::" "" usedName "${CMAKE_MATCH_1}")
+            string(FIND "${headerLine}" "${usedName}(" usedAt)
+            if(usedAt EQUAL -1 OR headerLine MATCHES "^(///|//|\\*)")
+                list(APPEND problems
+                     "${documentName}:${lineNumber} quotes a use of ${usedName} at ${headerName}:${quotedNumber}, but that line does not call it -- it is '${headerLine}'")
+            endif()
         elseif(headerLine STREQUAL "")
             list(APPEND problems
                  "${documentName}:${lineNumber} quotes ${headerName}:${quotedNumber}, which is a blank line")

cmake/CheckGuideOutput.cmake

@@ -116,10 +116,65 @@ if(blocks EQUAL 0 OR lines EQUAL 0)
         "examines nothing is a check that lies.")
 endif()
 
+# With CALL_TABLES, a table row whose last two cells are code spans, the first
+# of them a `std::format(` call, states what the example prints for that call:
+# the output must hold a line that starts with the call and a space, and ends,
+# after the column's padding, with the row's last cell. docs/display.md's spec
+# table is such a table; its rows are prose around real output, and a row's
+# Output cell could otherwise drift from the checked block beside it. A table
+# row that names `std::format(` in any other form -- an Output cell that lost
+# its backticks, an Example cell that is no longer a code span -- is refused
+# rather than skipped, so that no row drops out of the check unseen.
+set(tableRows 0)
+if(CALL_TABLES)
+    set(rest "${guide}")
+    while(TRUE)
+        string(FIND "${rest}" "\n" newline)
+        if(newline EQUAL -1)
+            break()
+        endif()
+        math(EXPR next "${newline} + 1")
+        string(SUBSTRING "${rest}" ${next} -1 rest)
+        string(FIND "${rest}" "\n" rowEnd)
+        string(SUBSTRING "${rest}" 0 ${rowEnd} row)
+        if(NOT row MATCHES "\\| `(std::format\\([^`]*\\))` \\| `([^`]*)` \\|$")
+            string(FIND "${row}" "std::format(" namesFormat)
+            if(row MATCHES "^\\|" AND NOT namesFormat EQUAL -1)
+                string(APPEND offenders
+                       "\n  a table row names std::format( but not as a call and its output, each a code span: ${row}")
+            endif()
+            continue()
+        endif()
+        set(call "${CMAKE_MATCH_1}")
+        set(written "${CMAKE_MATCH_2}")
+        math(EXPR tableRows "${tableRows} + 1")
+        string(FIND "${haystack}" "\n${call} " callFound)
+        if(callFound EQUAL -1)
+            string(APPEND offenders "\n  a table row whose call the example never prints: ${call}")
+            continue()
+        endif()
+        string(LENGTH "\n${call} " callLength)
+        math(EXPR printedStart "${callFound} + ${callLength}")
+        string(SUBSTRING "${haystack}" ${printedStart} -1 printed)
+        string(FIND "${printed}" "\n" printedEnd)
+        string(SUBSTRING "${printed}" 0 ${printedEnd} printed)
+        string(STRIP "${printed}" printed)
+        if(NOT printed STREQUAL written)
+            string(APPEND offenders "\n  a table row states ${call} as ${written}, but the example prints ${printed}")
+        endif()
+    endwhile()
+    if(tableRows EQUAL 0)
+        message(FATAL_ERROR
+            "guide output check: CALL_TABLES is set, but ${GUIDE} has no table row whose last two cells are a "
+            "`std::format(` call and its output. A check that examines nothing is a check that lies.")
+    endif()
+endif()
+
 if(NOT offenders STREQUAL "")
     message(FATAL_ERROR
         "${GUIDE} quotes output the example does not print as quoted. Re-run the example and copy its output:"
         "${offenders}")
 endif()
 
-message(STATUS "guide output check: ${blocks} blocks of ${lines} quoted lines, each printed by the example as quoted")
+message(STATUS "guide output check: ${blocks} blocks of ${lines} quoted lines, and ${tableRows} table rows, "
+               "each printed by the example as quoted")

cmake/CheckPublicHeaderIncludes.cmake

@@ -13,7 +13,9 @@
 # recorded derivation into text -- separately optional from it.
 # detail/latex_math.hpp qualifies as a part of render.hpp: it builds the
 # `std::string` render.hpp puts inside a LaTeX `\mathrm{...}`, and render.hpp
-# is its only includer, which check 2 keeps true.
+# is its only includer, which check 2 keeps true. format.hpp qualifies too --
+# it specialises std::formatter, which needs <format>, and writes its output
+# with a plain loop, so that it includes nothing else from that list itself.
 #
 # Being named here does not, by itself, permit anything: check 2 below
 # enforces that no other header may reach one of these, which is what stops
@@ -25,6 +27,7 @@ set(exemptHeaders
     "${SOURCE_DIR}/include/formula-cpp/trace.hpp"
     "${SOURCE_DIR}/include/formula-cpp/trace_render.hpp"
     "${SOURCE_DIR}/include/formula-cpp/detail/latex_math.hpp"
+    "${SOURCE_DIR}/include/formula-cpp/format.hpp"
 )
 
 file(GLOB_RECURSE headers "${SOURCE_DIR}/include/*.hpp")
@@ -128,6 +131,7 @@ set(exemptAllowances
     "trace.hpp=vector"
     "trace_render.hpp=string"
     "latex_math.hpp=string"
+    "format.hpp=format"
 )
 
 set(overreaches "")

cmake/CheckVocabularyReach.cmake

@@ -14,7 +14,7 @@
 # through `render`, `document` and the trace under a crossed-over vocabulary,
 # and `render.hpp` refuses a one-argument `render_node` of this library's at
 # compile time. What this script refuses, outside a whole-line comment, in
-# the four headers below:
+# the five headers below:
 #
 #  - `::symbol` as a whole name, which is how `Describe<Q>::symbol` (at any
 #    nesting of template arguments), `N::quantity::symbol` (a CRTP quantity's
@@ -31,6 +31,7 @@
 # the guarantee.
 
 set(surfaces
+    "${SOURCE_DIR}/include/formula-cpp/calculation.hpp"
     "${SOURCE_DIR}/include/formula-cpp/render.hpp"
     "${SOURCE_DIR}/include/formula-cpp/document.hpp"
     "${SOURCE_DIR}/include/formula-cpp/trace.hpp"