Skip to content

Tutorial

This tutorial teaches formula-cpp step by step. It assumes you know modern C++ -- C++20 and C++23, constexpr, std::expected, class-type template arguments -- and nothing about this library.

Before you start

You need a C++23 compiler (MSVC, clang-cl, Clang, GCC 14 or AppleClang), CMake 3.23 or newer, and CPM.cmake to fetch the library. Chapter 1 shows the CMake lines.

Two tracks

The core track builds one program: the calculation of a concrete specimen's compressive strength, from the load that crushed it and the specimen's size. Each chapter starts from the previous chapter's program, so read the core track in order.

The advanced track covers the rest of the library in independent chapters. Read the ones you need, in any order, once you have finished the core track.

Every program in this tutorial is built and run by the library's test suite, and every output shown is what that program prints. Every standard cited is an invented Example Standard.

Core track

  1. First formula -- one formula, evaluated and checked.
  2. Units and dimensions -- sides, areas and unit conversion; a mistake that does not compile.
  3. Exact numbers -- why the results are exact, and how to round them for reading.
  4. Missing and entered values -- a measurement nobody took, and a value typed in.
  5. Rounding -- rounding where the method says, in the mode it names.
  6. Constraints -- rules a specimen must meet, and the four outcomes of checking one.
  7. Citations, rendering and documentation -- where a formula comes from, written out as text, LaTeX and a symbol table.
  8. Tracing -- how each number was reached, step by step.
  9. Calculations and worksheets -- the whole test as one calculation, recalculated as inputs change.

Advanced track

  • Chapter 10: Lookup tables -- values from a published table, and what happens outside it.
  • Chapter 11: Methods and overlays -- one method, several variants, and a jurisdiction's changes.
  • Chapter 12: Series -- one quantity at several ages, calculated element by element.
  • Chapter 13: Statistics -- means and spreads of several specimens, and outliers rejected.
  • Chapter 14: Records -- values from a reference sample or an earlier test.
  • Chapter 15: Opaque operations and bounded retry -- a least-squares fit, and a retest repeated at most a fixed number of times.