Skip to content

Comparison of Alternatives

There are plenty of other open source C++ units libraries, many quite well established. However, the tradeoffs required to use these libraries can be so significant that many people can’t or won’t use them. For example: the compiler errors may be inscrutable or overwhelming; the compilation process may become unacceptably slow; or, the required C++ standard may simply be too new for a user.

Au is an accessible, production-tested alternative. We provide a number of rare or outright novel features, with a small compile time footprint — and we’re compatible with every C++ version back to the mature and widely available C++14 standard. Key features include:

  • Fully unit-safe APIs, on both entry and exit.
  • The “safety surface”: conversions that adapt to the overflow risk based on both conversion magnitude, and storage type.
  • Highly composable “quantity maker” APIs make it easy to both compose new units, and apply unit prefixes, on the fly.
  • Human-readable and concise compiler errors, via strong typenames for units.
  • The Zero type: novel, fluent handling of construction, comparison, and sign handling for quantities.
  • Ease of migration (both to and from Au): with minimal setup, we support bidirectional implicit conversions with equivalent types from any other units library.
  • Support for single-header-file delivery, but with easy customization of units and features to include.
  • Proven track record supporting embedded applications as first class citizens, via such features as our safe handling of integer Rep, treating all Reps on equal footing, and our easy ability to exclude expensive <iostream> support.
  • Intelligent, unit-aware functions for rounding and computing inverses.
  • Minimal friction by using a single, short namespace: everything’s in au::.

Alternatives considered here

We’ll consider several of the most prominent alternatives in more detail. While there are many more libraries, the ones we consider here are included for being especially pioneering or popular (or both). Here, we list those libraries, indicate which version we considered, and say a few words about why we included it in the analysis.

  • Boost Units (version: 1.82.0)
    • One of the longest-standing C++ unit libraries, and the most prominent pre-C++14 option.
  • nholthaus/units (version: 2.3.3)
    • Kicked off the revolution in modern (that is, post-C++11 watershed) units libraries.
    • Its laser-sharp focus on accessibility and low friction have made it probably the most widely used C++ units library to date.
  • bernedom/SI (version: 2.5.1)
    • A newer, C++17-compatible offering with a large number of GitHub stars.
  • mp-units (version: 2.0.0)
    • A library designed to take full advantage of ultra-modern (that is, post-C++20 watershed) features, such as concepts and non-template type parameters (NTTPs).
    • mp-units is leading the efforts towards a standard C++ units library, both by field testing new API designs, and by coordinating with the authors of other leading units libraries.

Detailed comparison matrices

Here’s a more detailed comparison to the alternatives listed above. We’ll use the following legend1:

Legend Lacks feature /
poor support
Fair /
basic support
Good /
solid support
Best support
(of libraries considered here)

Obtaining the library

These are the first criteria to consider. They will tell you whether you can even use the library at all, and if so, how hard it will be to obtain.

Boost nholthaus bernedom/SI mp-units Au
C++ Version Compatibility

The minimum C++ standard required to use the library.

C++98 C++14 C++17 C++20 C++14
Ease of Acquisition

Ease of including this library in projects using a wide variety of build environments

Part of boost Single, self-contained header Available on conan Available on conan and vcpkg

Supports single-header delivery, with features:

  • Easy to customize units and I/O support
  • Version-stamped for full reproducibility

Note

These ratings are written with all users and projects in mind. Keep in mind that what matters for you is your project.

For example: mp-units gets low accessibility ratings because of its steep C++20 minimum requirement, and its dependence on a package manager to make the installation easy. However, if your project is already compatible with C++20, and already uses conan, then these “low” ratings would be completely irrelevant for you.

Generic developer experience

Next: how will this library change the generic developer experience? Leaving aside any library features, conventions, or implementation strategies, there are two main impacts to developer experience.

  1. Your program will take longer to compile, because the compiler is doing more work to produce essentially the same program.

  2. You will get more compiler errors that developers will need to understand and fix.

These costs can bring significant benefits, but we still want them to be as small as possible.

Boost nholthaus bernedom/SI mp-units Au
Compilation Speed

The extra time the library adds to compiling a translation unit, compared to no units library.

  • Poor: typically adds several seconds per translation unit
  • Fair: enough that end users tend to notice
  • Good: not "subjectively noticeable"
Very slow, but can be greatly improved by removing I/O support and most units
  • Includes `fwd.hh` headers
  • Possibly "best" overall, but will need to assess all libraries on the same code
Compiler Error Readability

The ability to understand errors when the library catches a mistake it was designed to catch.

  • Poor: Excessively long, nested types
  • Fair: Short, but dimension names lacking
  • Good: Brief typenames with user-facing unit names
Infamously challenging Positional dimensions Alias for unit template
  • Strong unit typenames appear in errors
  • Short namespace minimizes clutter
  • Detailed troubleshooting guide

Library features

At this point, you’ve assessed:

  • whether you can use each library at all;
  • how hard it will be to add to your project;
  • and, what costs you’ll pay in developer experience if you do.

Now we’re ready to compare the libraries “as units libraries” — that is, in terms of their core features.

Note

The features are listed, very roughly, in order of importance. Counting up the colors in each column won’t give an accurate picture. The rows near the top matter more — sometimes, much more — than the rows further down.

Of course, what matters the most for you are your use cases and criteria!

Boost nholthaus bernedom/SI mp-units Au
Conversion Safety

Guarding against unit conversions that are likely to produce large errors.

(For example: we can convert an integer number of feet to inches, but not vice versa.)

Integer Reps unsafe Integer Reps unsafe Policy consistent with std::chrono library Meets `std::chrono` baseline, plus:
  • Automatically adapts to level of overflow risk
  • Runtime conversion checkers
  • Constants have perfect conversion policy
Unit Safety

The ability to judge the unit-correctness of every individual line of code by inspection, in isolation.

  • Fair: can achieve indirectly, by casting to known type before retrieving value.
  • Good: provide unit-safe interfaces.
Only contains unit-safe interfaces Only contains unit-safe interfaces
Low Friction

How easy it is to develop with the library. Criteria include:

  • Headers: few, or easily guessable
  • Simple namespace structure
  • Reasonable, safe implicit conversions
  • Generally high learning curve
  • No (non-trivial) implicit conversions
  • Many headers; hard to guess
  • Single file is very easy
  • User-friendly API typenames (meter_t, ...)
  • Namespaces add verbosity, and friction (for example, math:: namespace prevents ADL)
  • Single, short namespace
  • Implicit conversions
  • Multiple headers, but easy to guess (one per dimension)
  • Implicit conversions with good basic safety
  • Multiple headers, one per system
  • Longer and more nested namespaces
  • Namespaces: just one, and it's short
  • Includes: either single-header, or easily-guessable header per unit
Composability

The ability to fluently combine the abstractions for units and prefixes to form new units on the fly.

  • Can compose units, prefixes, dimensions, and quantity (point) makers
  • Type names clunky to compose: must write decltype
No No
  • Can compose units, prefixes, dimensions, and quantity types
  • C++20's Non-type template parameters (NTTPs) enable composable type names
  • Can compose units, prefixes, dimensions, and quantity (point) makers
  • Type names clunky to compose: must write decltype or use traits
Unit-aware I/O

The ability to print quantities along with information about their units. Examples:

  • <iostream>, preferrably toggleable
  • Unit labels available even without <iostream>
  • fmtlb (std::format after C++20)
  • Toggleable <iostream> support
  • Impressively configurable output (format_mode, autoprefix_mode)
  • No fmtlib support
  • Toggleable <iostream> support
  • No fmtlib support
  • Toggleable <iostream> support
  • Unit labels available even without <iostream>
  • No fmtlib support
  • Supports <iostream>
  • Unit labels available even without <iostream>
  • Supports std::format
  • Toggleable <iostream> support
  • Unit labels available even without <iostream>
  • Plan to add fmtlib support; see #149
Mixed-Rep Support

The ease of freely mixing different storage types ("Reps") in the same program.

Possible, but user-facing types use a global "preferred" Rep.
Unit-aware math

Unit-aware versions of common mathematical functions (`max`, `abs`, `sin`, `round`, and so on).

  • Wide variety of functions
  • round, ceil, and so on are not unit-safe
  • Wide variety of functions
  • round, ceil, and so on are not unit-safe
No
  • Wide variety of functions
  • Unit-safe APIs for round, ceil, and so on
  • Smart, unit-aware inverse functions
  • Wide variety of functions
  • Unit-safe APIs for round, ceil, and so on
  • Smart, unit-aware inverse functions
Generic Dimensions

The ability to write (template) functions that operate on any dimensionally consistent inputs.

(For example, a function that takes any length and time quantities, and returns the appropriate speed quantity.)

Generic templates, constrained with traits Generic templates, constrained with traits Generic templates, constrained with traits Concepts excel here Currently clunky. Could be better by adding concepts in extra C++20-only file, without compromising C++14 support.
Extensibility

How easy it is to add new units, dimensions, or systems.

Can add new units and dimensions Can add new units and dimensions Can even handle, e.g., systems of "natural" units Can add new units and dimensions
Ease of Migration

Support for two migration use cases:

  • From "no units" to this library
  • Between this library and another units library (either direction)
No interop with other units libraries No interop with other units libraries No interop with other units libraries
Point Types

Support for "point-like" quantities, also known as "affine space types".

absolute wrapper for unit Optional "offset" for units, but can't distinguish quantity from point. None; would be hard to add, since units conflated with quantity type Custom origins really easy to use and compose
Magnitudes

The features of the representation for different units' sizes. Key features include:

  • Irrational numbers (such as \(\pi\))
  • Powers (robust against overflow)
  • Roots (exact representations)
Close: lacks only irrationals, basis, and instance arithmetic. Ahead of its time! Uses ratio plus "pi powers": good angle handling, but vulnerable to overflow `std::ratio` only, with no solution for pi Full support for Magnitudes Formerly, Au alone was best, but we shared Magnitudes with mp-units
Embedded Friendliness

Support common embedded use cases. Key examples include:

  • Flexibility in the Rep (usually a variety of integral types, and perhaps float, but rarely double).
  • The easy ability to exclude <iostream>.
Assumed to be good, based on mixed-Rep support Can trim by excluding <iostream>, but integer-Rep support is poor.
  • <iostream> not automatically included
  • Supports integral rep
  • Integral rep conversions unsafe
Assumed to be good, based on mixed-Rep support Best choice of all:
  • No "preferred" Rep.
  • sizeof()-friendly unit label representation
  • Safe integer operations.
Abbreviated construction

The ability to construct a Quantity using the symbol for its unit.

This is most commonly done with user-defined literals (UDLs), such as 3_m for "3 meters", but there are other alternatives.

User-defined literals (UDLs) User-defined literals (UDLs) Unit symbols Unit symbols
Linear algebra

Good interoperability with matrix and vector libraries, such as Eigen

Most libraries can work with Eigen, but only if Eigen is patched: Quantity types break several of Eigen's deeply embedded assumptions.

Experimental support for Quantity Character; can use matrix types as Rep Planned to add: #70
Rep Variety

The range of different storage types ("Reps") permitted.

  • Poor: only 1 or 2 types
  • Fair: all built-in numeric types
  • Good: also support custom numeric types
Supports custom numeric types Effectively floating-point only (integer types unsafe)
  • No "default" rep
  • Integer reps unsafe
Well defined Representation concept
  • Mature support for is_arithmetic Rep
  • Experimental support for custom Rep
  • No constraints yet (#52)
Zero

Quantity support for constructing from, and comparing with, 0: the only number which is meaningful for every unit. (Includes facilities for working with quantity signs.)

Guidance: use default constructor to construct, but no special facility for comparison Supports copysign(), but no special construction or comparison No special construction or comparison
  • Special comparison functions
  • zero() member
  • Can use ZERO to construct or compare any quantity
    Angles

    First-class support for angular quantities, including degrees and radians.

    Curiously imprecise pi value
    • Supports degrees and radians
    • pi represented as std::ratio
    Simultaneous support for both strongly-typed and "pure SI" angles
    Physical constants
    • How good is the core library support?
    • Does the library include built-in constants?
    Includes built-in constants as quantities Includes built-in constants as quantities "Faster than lightspeed" constants
    • Constants as types
    • Perfect conversion policy
    • Implicit Quantity conversion
    • No built-in values yet (see #90)
    Non-linear scales (such as dB)

    Support for logarithmic "units", such as decibels or nepers

    Plan to support someday; see #41.
    "Kind" Types

    Any feature which supports robustly distinguishing between units that have the same dimension and magnitude.

    For example, "hertz" and "becquerel" both have the same dimension and magnitude as "inverse seconds", but some libraries may prevent users from mixing them.

    No plans at present to support.
    Explicit Systems of Measurement

    Support for different systems, each with their own (possibly incompatible) collection of dimensions.

    Single, implicit global system Single, implicit global system. (Intentional design tradeoff: reduces learning curve, and makes compiler errors shorter.)
    Abstract Units/Dimensions

  • Types that represent abstract units (clearly distinct from quantities of that unit).
  • Types that represent abstract dimensions.
  • The ability to do arithmetic with instances of these types.
  • Types exist, but conflated with quantity names No separate types for units
    • Types for units
    • Types for dimensions
    • Can do arithmetic (compound units on the fly; abstract dimensional analysis)
    • Types for units
    • Types for dimensions
    • Can do arithmetic (compound units on the fly; abstract dimensional analysis)
    Macro Usage

    Avoidance of macros, especially in user-facing code.

    Common in user-facing APIs Common in user-facing APIs Very few, and confined to implementation helpers
    • Very few, mostly implementation helpers
    • Only one user-facing macro for C++20 backwards compatibility
    No macros

    1. Users may have expected a “traffic light” style, green/yellow/red color scheme. However, these traditional color schemes have poor accessibility for colorblind readers. The present color scheme was designed to be colorblind-friendly.