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 legend¹:

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	Pioneered strong typedefs for units Expression templates produce very readable errors	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	One-line macro defines new units Can't add 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	QuantityLike<T> supports bidirectional conversions Can specify implicit or explicit	CorrespondingQuantity supports bidirectional implicit conversions Supports "two-hop" conversions
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 Includes exact constants from SI 2019
Non-linear scales (such as dB) Support for logarithmic "units", such as decibels or nepers					Plan to support someday; see #41.
Quantity template parameters The ability to use quantity values as template parameters.				Supports all quantities Supports automatic conversions Supports quantity families via concepts	Supports integral rep Only library with pre-C++20 support User must provide exact unit and rep No floating point support
"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	Zero user-facing macros; only two internal 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. ↩