Document #: | P3045R0 |
Date: | 2024-02-15 |
Project: | Programming Language C++ |
Audience: |
SG6 Numerics SG16 Unicode SG18 Library Evolution Working Group Incubator (LEWGI) |
Reply-to: |
Mateusz Pusz (Epam
Systems) <mateusz.pusz@gmail.com> Dominik Berner <dominik.berner@gmail.com> Johel Ernesto Guerrero Peña <johelegp@gmail.com> Chip Hogg (Aurora Innovation) <charles.r.hogg@gmail.com> Nicolas Holthaus <nholthaus@gmail.com> Roth Michaels (Native Instruments) <isocxx@rothmichaels.us> Vincent Reverdy <vince.rev@gmail.com> |
explicit
is not explicit
enoughspace_before_unit_symbol
customization pointSeveral groups in the ISO C++ Committee reviewed the “P1935: A C++ Approach to Physical Units” [P1935R2] proposal in Belfast 2019 and Prague 2020. All those groups expressed interest in the potential standardization of such a library and encouraged further work. The authors also got valuable initial feedback that highly influenced the design of the V2 version of the [mp-units] library.
In the following years, the library’s authors focused on getting more feedback from the production about the design and developed version 2 of the [mp-units] library that resolves the issues raised by the users and Committee members. The features and interfaces of this version are close to being the best we can get with the current version of the C++ language standard.
This paper is authored by the [mp-units] library developers, the authors of other actively maintained similar libraries on the market, and other active members of the C++ physical quantities and units community who have worked on this subject for many years. We join our forces to say with one voice that we deeply care about standardizing such features as a part of the C++ Standard Library. Based on our long and broad experience in the subject, we agree that the interfaces we will provide in the upcoming proposals are the best we can get today in the C++ language.
During the Kona 2023 ISO C++ Committee meeting, we got repeating feedback that there should be one big, unified paper with all the contents inside. Addressing this requirement, this paper adds a detailed design description and also includes the most important parts of [P2980R1], [P2981R1], and [P2982R1]. With this, we assume that [P2981R1] and [P2982R1] are superseded by this paper. The plan and scope described in [P2980R1] might still be updated based on the current progress and feedback from the upcoming discussions.
Note: This paper is incomplete and many chapters are still missing. It is published to gather early feedback and possibly get acceptance for the major design decisions of the library. More details will arrive in the next revisions of this paper.
This document consistently uses the official metrology vocabulary defined in the [ISO/IEC Guide 99] and [JCGM 200:2012].
This change is purely additive. It does not change, fix, or break any of the existing tools in the C++ standard library.
std::chrono
types and
std::ratio
The only interaction of this proposal with the C++ standard
facilities is the compatibility mode with
std::chrono
types
(duration
and
time_point
) described in
[Compatibility with
std::chrono::duration
and
std::chrono::time_point
].
We should also mention the potential confusion of users with having two different ways to deal with time abstractions in the C++ standard library. If this proposal gets accepted:
std::chrono
abstractions
together with std::ratio
should
be used primarily to deal with calendars and threading facilities,The features in this chapter are heavily used in the library but are not domain-specific. Having them standardized (instead of left as exposition-only) could not only improve this library’s specification, but also serve as an essential building block for tools in other domains that we can get in the future from other authors.
Feature
|
Priority
|
Papers
|
Description
|
---|---|---|---|
fixed_string |
1 | [P3094] | String-like structural type with inline storage (can be used as an NTTP) |
Compile-time prime numbers | 1 | [P3133] | Compile-time facilities to break any integral value to a product of prime numbers and their powers |
Value-preserving conversions | 1 | [P0870R5], [P2509R0] | Type trait stating if the conversion from one type to another is value preserving or not |
Number concepts | 2 | [P3003R0] | Concepts for vector- and point-space numbers |
Bounded numeric types | 3 | [P2993] | Numerical type wrappers with values bounded to a provided interval (optionally with wraparound semantics) |
Dominik is a strong believer that the C++ language can provide very high safety guarantees when programming through strong typing; a type error caught during compilation saves hours of debugging. For the last 15 years, he has mainly coded in C++ and actively follows its evolution through the new standards.
When working on regulated projects at Med-Tech, there usually were very tight requirements on which data types were to be used for what, which turned out to be lists of primitives to be memorized by each developer. However, throughout his career, Dominik spent way too many hours debugging and fixing issues caused by these types being incorrect. In an attempt to bring a closer semantic meaning to these lists, he eventually wrote [SI library] as a side project.
While [SI library] provides many useful features, such as type-safe conversion between physical quantities as well as zero-overhead computation for values of the same units, there are some shortcomings which would require major rework. Instead of creating yet another library, Dominik decided to join forces with the other authors of this paper to push for standardizing support for more type-safety for physical quantities. He hopes that this will eventually lead to a safer and more robust C++ and open many more opportunities for the language.
Johel got interested in the units domain while writing his first
hundred lines of game development. He got up to opening the game window,
so this milestone was not reached until years later. Instead, he looked
for the missing piece of abstraction, called “pixel” in the GUI
framework, but modeled as an
int
. He found out about [nholthaus/units], and got fascinated
with the idea of a library that succinctly allows expressing his
domain’s units (https://github.com/nholthaus/units/issues/124#issuecomment-390773279).
Johel became a contributor to [nholthaus/units] v3 from 2018 to 2020.
He improved the interfaces and implementations by remodeling them after
std::chrono::duration
. This
included parameterizing the representation type with a template
parameter instead of a macro. He also improved the error messages by
mapping a list of types to an user-defined name.
By 2020, Johel had been aware of [mp-units] v0 quantity<dim_length, length, int>
,
put off by its verbosity. But then, he watched a talk by Mateusz Pusz on
[mp-units]. It described how good error
messages was a stake in the ground for the library. Thanks to his
experience in the domain, Johel was convinced that [mp-units] was the future.
Since 2020, Johel has been contributing to [mp-units]. He added
quantity_point
, the
generalization of
std::chrono::time_point
, closing
#1. He also added quantity_kind
,
which explored the need of representing distinct quantities of the same
dimension. To help guide its evolution, he’s been constantly pointing in
the direction of [JCGM 200:2012] as a
source of truth. And more recently, to [ISO/IEC 80000], also helping interpret
it.
Computing systems engineering graduate. (C++) programmer since 2014. Lives at HEAD with C++Next and good practices. Performs in-depth code reviews of familiarized code bases. Has an eye for identifying automation opportunities, and acts on them. Mostly at https://github.com/JohelEGP/.
Chip Hogg is a Staff Software Engineer on the Motion Planning Team at Aurora Innovation, the self-driving vehicle company that is developing the Aurora Driver. After obtaining his PhD in Physics from Carnegie Mellon in 2010, he was a postdoctoral researcher and then staff scientist at the National Institute of Standards and Technology (NIST), doing Bayesian data analysis. He joined Google in 2012 as a software engineer, leaving in 2016 to work on autonomous vehicles at Uber’s Advanced Technologies Group (ATG), where he stayed until their acquisition by Aurora in 2021.
Chip built his first C++ units library at Uber ATG in 2018, where he first developed the concept of unit-safe interfaces. At Aurora in 2021, he ported over only the test cases, writing a new and more powerful units library from scratch. This included novel features such as vector space magnitudes, and an adaptive conversion policy which guards against overflow in integers.
He soon realized that there was a much broader need for Aurora’s units library. No publicly available units library for C++14 or C++17 could match its ergonomics, developer experience, and performance. This motivated him to create [Au] in 2022: a new, zero-dependency units library, which was a drop-in replacement for Aurora’s original units library, but offered far more composable interfaces, and was built on simpler, stronger foundations. Once Au proved its value internally, Chip migrated it to a separate repository and led the open-sourcing process, culminating in its public release in 2023.
While Au provides excellent ergonomics and robustness for pre-C++20 users, Chip also believes the C++ community would benefit from a standard units library. For that reason, he has joined forces with the [mp-units] project, contributing code and design ideas.
Nicolas graduated Summa Cum Laude from Northwestern University with a B.S. in Computer Engineering. He worked for several years at the United States Naval Air Warfare Center - Manned Flight Simulator - designing real-time C++ software for aircraft survivability simulation. He has subsequently continued in the field at various start-ups, MIT Lincoln Laboratory, and most recently, STR (Science and Technology Research).
Nicolas became obsessed with dimensional analysis as a high school
JETS team member after learning that the $125M Mars Climate Orbiter was
destroyed due to a simple feet-to-meters miscalculation. He developed
the widely adopted C++ [nholthaus/units] library based on the
findings of the 2002 white paper “Dimensional Analysis in C++” by Scott
Meyers. Astounded that no one smarter had already written such a
library, he continued with units
2.0 and 3.0 based on modern C++. Those libraries have been extensively
adopted in many fields, including modeling & simulation,
agriculture, and geodesy.
In 2023, recognizing the limits of
units
, he joined forces with
Mateusz Pusz in his effort to standardize his evolutionary dimensional
analysis library, with the goal of providing the highest-quality
dimensional analysis to all C++ users via the C++ standard library.
Roth Michaels is a Principal Software Engineer at Native Instruments, a leading manufacturer of audio, and music, software and hardware. Working in this domain, he has been involved with the creation of ad hoc typed quantities/units for digital signal processing and GUI library use-cases. Seeing both the complexity of development and practical uses where developers need to leave the safety of these simple wrappers encouraged Roth to explore various quantity/units libraries to see if they would apply to this domain. He has been doing research into defining and using digital audio and music domain-specific quantities and units using first [mp-units] as proposed in [P1935R2] and the new V2 library described in this paper.
Before working for Native Instruments, Roth worked as a consultant in multiple industries using a variety of programming languages. He was involved with the Swift Evolution community in its early days before focusing primarily on C++ after joining iZotope and now Native Instruments.
Holding a degree in music composition, Roth has over a decade of experience working with quantities and units of measure related to music, digital signal processing, analog audio, and acoustics. He has joined the [mp-units] project as a domain expert in these areas and to provide perspective on logarithmic and non-linear quantity/unit relationships.
Mateusz got interested in the physical units subject while contributing to the [LK8000] Tactical Flight Computer Open Source project over 10 years ago. The project’s code was far from being “safe” in the C++ sense, and this is when Mateusz started to explore alternatives.
Through the following years, he tried to use several existing solutions, which were always far from being user-friendly, so he also tried to write a better framework a few times from scratch by himself.
Finally, with the availability of brand new Concepts TS in the gcc-7, the [mp-units] project was created. It was designed with safety and user experience in mind. After many years of working on the project, the [mp-units] library is probably the most modern and complete solution in the C++ market.
Through the last few years, Mateusz has put much effort into building a community around physical units. He provided many talks and workshops on this subject at various C++ conferences. He also approached the authors of other actively maintained libraries to get their feedback and invited them to work together to find and agree on the best solution for the C++ language. This paper is the result of those actions.
Vincent is an astrophysicist, computer scientist, and a member of the French delegation to the ISO C++ Committee, currently working as a full researcher at the French National Centre for Scientific Research (CNRS). He has been interested for years in units and quantities for programming languages to ensure higher levels of both expressivity and safety in computational physics codes. Back in 2019, he authored [P1930R0] to provide some context of what could be a quantity and unit library for C++.
After designing and implementing several Domain-Specific Language (DSL) demonstrators dedicated to units of measurements in C++, he became more interested in the theoretical side of the problem. Today, one of his research activities is dedicated to the mathematical formalization of systems of quantities and systems of units as an interdisciplinary problem between physics, mathematics, and computer science.
This chapter describes why we believe that physical quantities and units should be part of a C++ Standard Library.
It is no longer only the space industry or experienced pilots that benefit from the autonomous operations of some machines. We live in a world where more and more ordinary people trust machines with their lives daily. In the near future, we will be allowed to sleep while our car autonomously drives us home from a late party. As a result, many more C++ engineers are expected to write life-critical software today than it was a few years ago. However, writing safety-critical code requires extensive training and experience, both of which are in short demand. While there exists some standards and guidelines such as MISRA C++ [MISRA C++] with the aim of enforcing the creation of safe code in C++, they are cumbersome to use and tend to shift the burden on the discipline of the programmers to enforce these. At the time of writing, the C++ language does not change fast enough to enforce safe-by-construction code.
One of the ways C++ can significantly improve the safety of applications being written by thousands of developers is by introducing a type-safe, well-tested, standardized way to handle physical quantities and their units. The rationale is that people tend to have problems communicating or using proper units in code and daily life. Numerous expensive failures and accidents happened due to using an invalid unit or a quantity type.
The most famous and probably the most expensive example in the software engineering domain is the Mars Climate Orbiter that in 1999 failed to enter Mars’ orbit and crashed while entering its atmosphere [Mars Orbiter]. This is one of many examples here. People tend to confuse units quite often. We see similar errors occurring in various domains over the years:
20 °C
above the average
temperature was converted to
68 °F
. The actual temperature
increase was 32 °F
, not
68 °F
[The Guardian].The safety subject is so vast and essential by itself that we dedicated an entire Safety features chapter of this paper that discusses all the nuances in detail.
We standardized many library features mostly used in the implementation details (fmt, ranges, random-number generators, etc.). However, we believe that the most important role of the C++ Standard is to provide a standardized way of communication between different vendors.
Let’s imagine a world without
std::string
or
std::vector
. Every vendor has
their version of it, and of course, they are highly incompatible with
each other. As a result, when someone needs to integrate software from
different vendors, it turns out to be an unnecessarily arduous task.
Introducing
std::chrono::duration
and
std::chrono::time_point
improved
the interfaces a lot, but time is only one of many quantities that we
deal with in our software on a daily basis. We desperately need to be
able to express more quantities and units in a standardized way so
different libraries get means to communicate with each other.
If Lockheed Martin and NASA could have used standardized vocabulary types in their interfaces, maybe they would not interpret pound-force seconds as newton seconds, and the [Mars Orbiter] would not have crashed during the Mars orbital insertion maneuver.
Mission and life-critical projects, or those for embedded devices, often have to obey the safety norms that care about software for safety-critical systems (e.g., ISO 61508 is a basic functional safety standard applicable to all industries, and ISO 26262 for automotive). As a result, their company policy often forbid third-party tooling that lacks official certification. Such certification requires a specification to be certified against, and those tools often do not have one. The risk and cost of self-certifying an Open Source project is too high for many as well.
Companies often have a policy that the software they use must obey all the rules MISRA provides. This is a common misconception, as many of those rules are intended to be deviated from. However, those deviations require rationale and documentation, which is also considered to be risky and expensive by many.
All of those reasons often prevent the usage of an Open Source product in a company, which is a huge issue, as those companies typically are natural users of physical quantities and units libraries.
Having the physical quantities and units library standardized would solve those issues for many customers, and would allow them to produce safer code for projects on which human life depends every single day.
Suppose vendors can’t use an Open Source library in a production
project for the above reasons. They are forced to write their own
abstractions by themselves. Besides being costly and time-consuming, it
also happens that writing a physical quantities and units library by
yourself is far from easy. Doing this is complex and complicated,
especially for engineers who are not experts in the domain. There are
many exceptional corner cases to cover that most developers do not even
realize before falling into a trap in production. On the other hand,
domain experts might find it difficult to put their knowledge into code
and create a correct implementation in C++. As a result, companies
either use really simple and unsafe numeric wrappers, or abandon the
effort entirely and just use built-in types, such as
float
or
int
, to express quantity values,
thus losing all semantic categorization. This often leads to safety
issues caused by accidentally using values representing the wrong
quantity or having an incorrect unit.
Many applications of a quantity and units library may need to operate on a combination of standard (e.g., SI) and domain-specific quantities and units. The complexity of developing domain-specific solutions highlights the value in being able to define new quantities and units that have all the expressivity and safety as those provided by the library.
Experience with writing ad hoc typed quantities without library
support that can be combined with or converted to
std::chrono::duration
has shown
the downside of bespoke solutions: If not all operations or conversions
are handled, users will need to leave the safety of typed quantities to
operate on primitive types.
The interfaces of the this library were designed with ease of extensibility in mind. Each definition of a dimension, quantity type, or unit typically takes only a single line of code. This is possible thanks to the extensive usage of C++20 class types as Non-Type Template Parameters (NTTP). For example, the following code presents how second (a unit of time in the [SI]) and hertz (a unit of frequency in the [SI]) can be defined:
inline constexpr struct second : named_unit<"s", kind_of<isq::time>> {} second;
inline constexpr struct hertz : named_unit<"Hz", 1 / second, kind_of<isq::frequency>> {} hertz;
When people think about industries that could use physical quantities and unit libraries, they think of a few companies related to aerospace, autonomous cars, or embedded industries. That is all true, but there are many other potential users for such a library.
Here is a list of some less obvious candidates:
As we can see, the range of domains for such a library is vast and not limited to applications involving specifically physical units. Any software that involves measurements, or operations on counts of some standard or domain-specific quantities, could benefit from a zero-cost abstraction for operating on quantity values and their units. The library also provides affine space abstractions, which may prove useful in many applications.
Plenty of physical units libraries have been available to the public for many years. In 1998 Walter Brown provided an “Introduction to the SI Library of Unit-Based Computation” paper for the International Conference on Computing in High Energy Physics [CHEP’98]. It emphasizes the importance of strong types and static type-checking. After that, it describes a library modeling the [SI] to provide “strict compile-time type-checking without run-time overhead”.
It also states that at this time, “in numeric programming,
programmers make heavy, near-exclusive, use of a language’s native
numeric types (e.g., double
)”.
Today, twenty-five years later, plenty of “Modern C++” production code
bases still use double
to
represent various quantities and units. It is high time to change
this.
Throughout the years, we have learned the best practices for handling specific cases in the domain. Various products may have different scopes and support different C++ versions. Still, taking that aside, they use really similar concepts, types, and operations under the hood. We know how to do those things already.
The authors of this paper developed and delivered multiple successful C++ libraries for this domain. Libraries developed by them have more than 90% of all the stars on GitHub in the field of physical units libraries for C++. The [mp-units] library, which is the base of this proposal, has the most number of stars in this list, making it the most popular project in the C++ industry.
The authors joined forces and are working together to propose the best quantities and units library we can get with the latest version of the C++ language. They spend their private time and efforts hoping that the ISO C++ Committee will be willing to include such a feature in the C++ standard library.
In this chapter, we are going to review typical safety issues related to physical quantities and units in the C++ code when a proper library is not used. Even though all the examples come from the Open Source projects, expensive revenue-generating production source code often is similar.
double
It turns out that in the C++ software, most of our calculations in
the physical quantities and units domain are handled with fundamental
types like double
. Code like
below is a typical example here:
double GlidePolar::MacCreadyAltitude(double MCREADY,
double Distance,
const double Bearing,
const double WindSpeed,
const double WindBearing,
double *BestCruiseTrack,
double *VMacCready,
const bool isFinalGlide,
double *TimeToGo,
const double AltitudeAboveTarget=1.0e6,
const double cruise_efficiency=1.0,
const double TaskAltDiff=-1.0e6);
There are several problems with such an approach: The abundance of
double
parameters makes it easy
to accidentally switch values and there is no way of noticing such a
mistake at compile-time. The code is not self-documenting in what units
the parameters are expected. Is
Distance
in meters or
kilometers? Is WindSpeed
in
meters per second or knots? Different code bases choose different ways
to encode this information, which may be internally inconsistent. A
strong type system would help answer these questions at the time the
interface is written, and the compiler would verify it at
compile-time.
There are a lot of constants and conversion factors involved in the quantity equations. Source code responsible for such computations is often trashed with magic numbers:
double AirDensity(double hr, double temp, double abs_press)
{
return (1/(287.06*(temp+273.15)))*(abs_press - 230.617 * hr * exp((17.5043*temp)/(241.2+temp)));
}
Apart from the obvious readability issues, such code is hard to
maintain, and it needs a lot of domain knowledge on the developer’s
side. While it would be easy to replace these numbers with named
constants, the question of which unit the constant is in remains. Is
287.06
in pounds per square inch
(psi) or millibars (mbar)?
The lack of automated unit conversions often results in handwritten conversion functions or macros that are spread everywhere among the code base:
#ifndef PI
static const double PI = (4*atan(1));
#endif
#define EARTH_DIAMETER 12733426.0 // Diameter of earth in meters
#define SQUARED_EARTH_DIAMETER 162140137697476.0 // Diameter of earth in meters (EARTH_DIAMETER*EARTH_DIAMETER)
#ifndef DEG_TO_RAD
#define DEG_TO_RAD (PI / 180)
#define RAD_TO_DEG (180 / PI)
#endif
#define NAUTICALMILESTOMETRES (double)1851.96
#define KNOTSTOMETRESSECONDS (double)0.5144
#define TOKNOTS (double)1.944
#define TOFEETPERMINUTE (double)196.9
#define TOMPH (double)2.237
#define TOKPH (double)3.6
// meters to.. conversion
#define TONAUTICALMILES (1.0 / 1852.0)
#define TOMILES (1.0 / 1609.344)
#define TOKILOMETER (0.001)
#define TOFEET (1.0 / 0.3048)
#define TOMETER (1.0)
Again, the question of which unit the constant is in remains. Without
looking at the code, it is impossible to tell from which unit
TOMETER
converts. Also, macros
have the problem that they are not scoped to a namespace and thus can
easily clash with other macros or functions, especially if they have
such common names like PI
or
RAD_TO_DEG
. A quick search
through open source C++ code bases reveals that, for example, the
RAD_TO_DEG
macro is defined in a
multitude of different ways – sometimes even within the same
repository:
#define RAD_TO_DEG (180 / PI)
#define RAD_TO_DEG 57.2957795131
#define RAD_TO_DEG ( radians ) ((radians ) * 180.0 / M_PI)
#define RAD_TO_DEG 57.2957805f
...
Example search across multiple repositories
Multiple redefinitions in the same repository
Another safety issue occurring here is the fact that macro values can be deliberately tainted by compiler settings at built time and can acquire values that are not present in the source code. Human reviews won’t catch such issues.
Also, most of the macros do not follow best practices. Often,
necessary parentheses are missing, processing in a preprocessor ends up
with redundant casts, or some compile-time constants use too many digits
for a value to be exact for a specific type (e.g.,
float
).
If we not only lack strong types to isolate the abstractions from each other, but also lack discipline to keep our code consistent, we end up in an awful place:
void DistanceBearing(double lat1, double lon1,
double lat2, double lon2,
double *Distance, double *Bearing);
double DoubleDistance(double lat1, double lon1,
double lat2, double lon2,
double lat3, double lon3);
void FindLatitudeLongitude(double Lat, double Lon,
double Bearing, double Distance,
double *lat_out, double *lon_out);
double CrossTrackError(double lon1, double lat1,
double lon2, double lat2,
double lon3, double lat3,
double *lon4, double *lat4);
double ProjectedDistance(double lon1, double lat1,
double lon2, double lat2,
double lon3, double lat3,
double *xtd, double *crs);
Users can easily make errors if the interface designers are not
consistent in ordering parameters. It is really hard to remember which
function takes latitude or
Bearing
first and when a
latitude or Distance
is in the
front.
The previous points mean that the fundamental types can’t be leveraged to model the different concepts of quantities and units frameworks. There is no shared vocabulary between different libraries. User-facing APIs use ad-hoc conventions. Even internal interfaces are inconsistent between themselves.
Arithmetic types such as int
and double
are used to model
different concepts. They are used to represent any abstraction (be it a
magnitude, difference, point, or kind) of any quantity type of any unit.
These are weak types that make up weakly-typed interfaces. The resulting
interfaces and implementations built with these types easily allow
mixing up parameters and using operations that are not part of the
represented quantity.
The library facilities that we plan to propose in the upcoming papers is designed with the following goals in mind.
The most important property of any such a library is the safety it brings to C++ projects. The correct handling of physical quantities, units, and numerical values should be verifiable both by the compiler and by humans with manual inspection of each individual line.
In some cases, we are even eager to prioritize safe interfaces over the general usability experience (e.g., getters of the underlying raw numerical value will always require a unit in which the value should be returned in, which results in more typing and is sometimes redundant).
More information on this subject can be found in Safety features.
The library should be as fast or even faster than working with fundamental types. The should be no runtime overhead, and no space size overhead should be needed to implement higher-level abstractions.
The primary purpose of the library is to generate compile-time errors. If users did not introduce any bugs in the manual handling of quantities and units, the library would be of little use. This is why the library is optimized for readable compilation errors and great debugging experience.
The library is easy to use and flexible. The interfaces are straight-forward and safe by default. Users should be able to easily express any quantity and unit, which requires them to compose.
The above constraints imply the usage of special implementation techniques. The library will not only provide types, but also compile-time known values that will enable users to write easy to understand and efficient equations on quantities and units.
There are plenty of expectations from different parties regarding such a library. It should support at least:
Additionally, it would be good to also support the following features:
The library’s core framework does not assume the usage of any systems of quantities or units. It is fully generic and allow defining any system abstraction on top of it.
Most entities in the library can be defined with a single line of code without preprocessor macros. Users can easily extend provided systems with custom dimensions, quantities, and units.
The set of entities required for standardization should be limited to the bare minimum.
Most of the entities in systems definitions should be possible to implement with a single line of code.
Derived units do not need separate library types. Instead, they can
be obtained through the composition of predefined named units. Units
should not be associated with User-Defined Literals (UDLs), as it is the
case with std::chrono::duration
.
UDLs do not compose, have very limited scope and functionality, and are
expensive to standardize.
The user interface should have no preprocessor macros.
It should be possible for most proposed features (besides the text output) to be freestanding.
This chapter provides a very brief introduction to the quantities and units domain. Please refer to [ISO/IEC 80000] and [SI] for more details.
Note: A more detailed graph of framework’s entities can be found in the Framework entities chapter.
Dimension specifies the dependence of a quantity on the base quantities of a particular system of quantities. It is represented as a product of powers of factors corresponding to the base quantities, omitting any numerical factor.
Even though ISO does not officially define those, we find the below terms useful when discussing the domain and its C++ implementation:
As stated above, ISO does not mention a “base dimension” term. Nevertheless, it treats dimensions of base quantities in a special way by:
For example:
Dimension is not enough to describe a quantity. This is why [ISO/IEC 80000] provides hundreds of named quantity types. It turns out that there are many more quantity types in the ISQ than the named units in the [SI].
[ISO/IEC 80000] also defines the term kind of quantity as an aspect common to mutually comparable quantities. It explicitly says that two or more quantities cannot be added or subtracted unless they belong to the same category of mutually comparable quantities.
Quantities might be:
Additionally, ISO explicitly specifies a quantity of dimension one, which is commonly known as a dimensionless quantity. It is a quantity for which all the exponents of the factors corresponding to the base quantities in its quantity dimension are zero. Typically, they represent ratios of two quantities of the same dimension or counts of things.
[ISO/IEC 80000] defines a quantity as:
property of a phenomenon, body, or substance, where the property has a magnitude that can be expressed as a number and a reference.
NOTE 2 A reference can be a measurement unit, a measurement procedure, a reference material, or a combination of such.
The term “reference” is repeated several times in that ISO specification. For example:
quantity value is defined as:
Number and reference together expressing magnitude of a quantity.
numerical quantity value is defined as:
Number in the expression of a quantity value, other than any number serving as the reference
We realize that the term “reference” might be overloaded in the C++ domain. However, preserving the official metrology terminology here is still worth trying.
Measurement units are designated by conventionally assigned names and symbols.
Measurement units of quantities of the same quantity dimension may be designated by the same name and symbol even when the quantities are not of the same kind. For example, joule per kelvin and J/K are, respectively, the name and symbol of both a measurement unit of heat capacity and a measurement unit of entropy, which are generally considered to not be quantities of the same kind.
However, in some cases, special measurement unit names are restricted to be used with quantities of specific kind only. For example, the measurement unit ‘second to the power minus one’ (1/s) is called hertz (Hz) when used for frequencies and becquerel (Bq) when used for activities of radionuclides.
Measurement units of quantities of dimension one are numbers. In some cases, these measurement units are given special names, e.g., radian, steradian, and decibel, or are expressed by quotients such as millimole per mole equal to \(10^{−3}\) and microgram per kilogram equal to \(10^{−9}\).
As stated above, [ISO/IEC 80000] defines a quantity as:
property of a phenomenon, body, or substance, where the property has a magnitude that can be expressed as a number and a reference.
The above means that a quantity abstraction should store a runtime value representing the quantity numerical value and a reference that might be represented as a unit. It is a common practice to embed a reference into the C++ type expressing the quantity so it does not occupy a space/storage at runtime.
It is also worth mentioning here that the distinction between a quantity and a quantity type is not clearly defined in [ISO/IEC 80000]. [ISO/IEC 80000] even explicitly states:
It is customary to use the same term, “quantity”, to refer to both general quantities, such as length, mass, etc., and their instances, such as given lengths, given masses, etc. Accordingly, we are used to saying both that length is a quantity and that a given length is a quantity, by maintaining the specification – “general quantity, \(Q\)” or “individual quantity, \(Q_a\)” – implicit and exploiting the linguistic context to remove the ambiguity.
To prevent such ambiguities in this document, we will consistently use the term:
It is also worth mentioning here that [ISO/IEC 80000] does not distinguish between point and vector/interval quantities of The affine space.
This chapter is intended to be a short overview and present the proposed library’s final look and feel. We start with the most straightforward use cases and gradually introduce more complex abstractions. Thanks to that, the readers can assess the Teachability effort of this library by themselves.
More details about the design, rationale for it, and alternative syntaxes discussions can be found in the Design details and rationale chapter.
Consistently with a Quantity definition, a
quantity
class template takes a
reference and a representation type as parameters:
template<Reference auto R,
<get_quantity_spec(R).character> Rep = double>
RepresentationOfclass quantity;
If we want to set a value for a quantity, we always have to provide a number and a unit:
<si::metre, int> q{42, si::metre}; quantity
In case a quantity class template should use exactly the same unit and a representation type as provided in the initializer, it is recommended to use CTAD:
{42, si::metre}; quantity q
Please, note that double
is
used as a default representation type, so the following does not result
with a quantity of integral representation type:
<si::metre> q2{42, si::metre}; quantity
This is why CTAD usage is recommended when the user wants to prevent
potential conversion and just deduce the
quantity
class template
parameters from the initializer. This often prevents unneeded
conversions that can affect runtime performance or memory footprint.
CTAD-based spelling is shorter but is still quite verbose. Consider having to write:
= quantity{1, si::kilo<si::metre>} + quantity{200, si::metre}; quantity q
This is why the library offers an alternative way to construct a quantity.
The [SI] says:
The value of the quantity is the product of the number and the unit. The space between the number and the unit is regarded as a multiplication sign (just as a space between units implies multiplication).
Following the above, the value of a quantity can also be created by multiplying a number with a predefined unit:
= 42 * si::metre; quantity q
The above creates an instance of
quantity<si::metre(), int>
.
It is worth noting here that the syntax with the reversed order of
arguments is invalid and will not compile (e.g., we can’t write
si::metre * 42
).
The same can be obtained using an optional unit symbol:
using namespace si::unit_symbols;
= 42 * m; quantity q
Unit symbols introduce a lot of short identifiers into the current
scope, which is why they are opt-in. A user has to explicitly “import”
them from a dedicated
unit_symbols
namespace.
[SI] specifies 7 base and 22 coherent derived units with special names. Additionally, it specifies 24 prefixes. There are also non-SI units accepted for use with SI. Some of them are really popular, for example, minute, hour, day, degree, litre, hectare, tonne. All of those entities compose to allow the creation of a vast number of various derived units.
For example, we can create a quantity of speed with either:
= 60 * si::kilo<si::metre> / non_si::hour;
quantity speed1 = 60 * km / h; quantity speed2
In case a complex derived unit is used a lot in the project, for convenience, a user can quickly provide a nicely named wrapper for it with:
constexpr auto kmph = si::kilo<si::metre> / non_si::hour;
= 60 * kmph; quantity speed3
The library is optimized to generate short and easy-to-understand
types that highly improve the analysis of compile-time errors and
debugging experience. All of the above definitions will create an
instance of the type quantity<derived_unit<si::kilo_<si::metre>, per<non_si::hour>>{}, int>>
.
As we can see, the type generation is optimized to be easily understood
even by non-experts in the domain. The library tries to keep the type’s
readability as close to English as possible.
Various quantities can be multiplied or divided to obtain other derived quantities. Quantities of the same kind can be added, subtracted, and compared to each other. Quantities can also be easily printed with output streams or formatting facilities.
= 80 * km;
quantity dist1 = 105 * km;
quantity dist2 = 2 * h;
quantity duration = 100 * km / h;
quantity speed_limit
if ((dist1 + dist2) / duration < speed_limit)
::cout << "Thanks for driving within the speed limit of " << speed_limit << " :-)\n";
stdelse
::println("Slow down! The speed limit here is {}!", speed_limit); std
The above prints:
Thanks for driving within the speed limit of 100 km/h :-)
If we want to change the unit of a current quantity, we can use
.in(Unit)
member function:
::cout << "The total distance in meters is " << (dist1 + dist2).in(m) << "\n"; std
Trying to do the same for
speed_limit
is invalid and will
result in a compile time error stating that the member function
.in()
was not found. This is
caused by the fact that the scaling of an integral type by a rational or
irrational factor is considered not value-preserving. To force such a
conversion, we can use either a
.force_in(Unit)
member function
or an explicit
value_cast<Unit>(Quantity)
.
::cout << "The speed limit in m/s is " << speed_limit.force_in(m / s) << "\n";
std::cout << "The speed limit in m/s is " << value_cast<m / s>(speed_limit) << "\n"; std
We will get a truncated value of
27 m/s
in both cases.
To prevent truncation, we must explicitly change the quantity
representation type to a value-preserving one with value_cast<Representation>(Quantity)
overload. For example:
::cout << "The speed limit in m/s is " << value_cast<double>(speed_limit).in(m / s) << "\n"; std
This time, we will see the following in the text output:
The speed limit in m/s is 27.7778 m/s
Last but not least, if we need to obtain the numerical value of a
quantity and pass it to some the legacy unsafe interface, we can use
either .numerical_value_in(Unit)
or
.force_numerical_value_in(Unit)
member functions:
void legacy_check_speed_limit(int speed_in_km_per_h);
(((dist1 + dist2) / duration).numerical_value_in(km / h)); legacy_check_speed_limit
Such a getter will explicitly enforce the usage of a correct unit required by the underlying interface, which reduces a significant number of safety-related issues.
numerical_value_in(Unit)
always returns by value as a quantity value conversion may be required
to adjust to the target unit. In case a user needs a reference to the
underlying storage
.numerical_value_ref_in(Unit)
should be used:
void legacy_set_speed_limit(int* speed_in_km_per_h) { *speed_in_km_per_h = 100; }
<km / h, int> speed_limit;
quantity(&speed_limit.numerical_value_ref_in(km / h)); legacy_set_speed_limit
This member function again requires a target unit to enforce safety. This overload does not participate in overload resolution if the provided unit has a different scaling factor than the current one.
Simple mode is all about and just about units. In case we care about a specific quantity type, typed quantities should be preferred. Those store information not only about a unit but also about a specific quantity type we want to model.
There a few ways to obtain such a quantity:
<isq::height[m], int> q1 = 42 * m;
quantity{42, isq::height[m]};
quantity q2= 42 * isq::height[m];
quantity q3 = isq::height(42 * m); quantity q4
All of the above cases use a slightly different approach to get the
quantity, but all of them result in exactly the same
quantity
class template
instantiation.
In the above examples, an expression of
isq::height[m]
is called a
quantity reference and results in reference<isq::height, si::metre>
class template instantiation.
Note: The identifier
reference
is being used in the
[mp-units] library but definitely will
need bikeshedding during the standardization process.
More about typed quantities can be found in the following chapters:
The affine space has two types of entities:
The vector described here is specific to the affine space theory and is not the same thing as the quantity of a vector character that we discuss later (although, in some cases, those terms may overlap).
Here are the primary operations one can do in the affine space:
It is not possible to:
Point abstractions should be used more often in the C++ software. They are not only about temperature or time. Points are everywhere around us and should become more popular in the products we implement. They can be used to implement:
Improving the affine space’s Points intuition will allow us to write better and safer software.
quantity
Up until now, each time when we used a
quantity
in our code, we were
modeling some kind of a difference between two things:
0
)As we already know, a
quantity
type provides all
operations required for the vector type in an affine space.
quantity_point
and
PointOrigin
In the library, the point abstraction is modeled by:
PointOrigin
concept that specifies a measurement’s origin, andquantity_point
class
template that specifies a point relative to a predefined
origin.quantity_point
The quantity_point
class
template specifies an absolute quantity measured from a predefined
origin:
template<Reference auto R,
<get_quantity_spec(R)> auto PO = default_point_origin(R),
PointOriginFor<get_quantity_spec(R).character> Rep = double>
RepresentationOfclass quantity_point;
As we can see above, the
quantity_point
class template
exposes one additional parameter compared to
quantity
. The
PO
parameter satisfies a PointOriginFor
concept and specifies the origin of our measurement scale. By default,
it is initialized with a quantity’s zeroth point using the following
rules:
zeroth_point_origin<QuantitySpec>
is being used which provides a zeroth point for a specific quantity
type.Let’s assume that Alice goes for a trip driving a car. She likes taking notes about interesting places that she visits on the road. For every such item, she writes down:
We can implement this in the following way:
using std::chrono::system_clock;
struct trip_log_item {
::string name;
std<isq::distance[km]> odometer;
quantity_point<si::second> timestamp;
quantity_point};
using trip_log = std::vector<trip_log_item>;
trip_log log;
{quantity{system_clock::now().time_since_epoch()}};
quantity_point timestamp_1.emplace_back("home", quantity_point{1356 * km}, timestamp_1);
log
// some time passes
{quantity{system_clock::now().time_since_epoch()}};
quantity_point timestamp_2.emplace_back("castle", quantity_point{1401 * km}, timestamp_2); log
This is an excellent example of where points are helpful. There is no doubt about the correctness of their usage in this scenario:
Having such a database, we can print the trip log in the following way:
for (const auto& item : log) {
::cout << "POI: " << item.name << "\n";
std::cout << "- Distance from home: " << item.odometer - log.front().odometer << "\n";
std::cout << "- Trip duration from start: " << (item.timestamp - log.front().timestamp).in(non_si::minute) << "\n";
std}
Moreover, if Alice had reset the car’s trip odometer before leaving home, we could have rewritten one of the previous lines like that:
::cout << "Distance from home: " << item.odometer.quantity_from_zero() << "\n"; std
The above always returns a quantity measured from the “ultimate” zeroth point of a scale used for this specific quantity type.
Storing points is the most efficient representation we can choose in this scenario:
If we stored vectors in our database instead, we would have to pay at runtime for additional operations:
Now, let’s assume that Bob, a friend of Alice, also keeps a log of his trips but he, of course, measures distances from his own home with the odometer in his car. Everything is fine as long as we deal with one trip at a time, but if we start to work with both at once, we may accidentally subtract points from different trips. The library will not prevent us from doing so.
The points from Alice’s and Bob’s trips should be considered separate, and to enforce it at compilation time, we need to introduce explicit origins.
The absolute point origin specifies the “zero” of
our measurement’s scale. User can specify such an origin by deriving
from the absolute_point_origin
class template:
enum class actor { alice, bob };
template<actor A>
struct zeroth_odometer_t : absolute_point_origin<zeroth_odometer_t<A>, isq::distance> {};
template<actor A>
inline constexpr zeroth_odometer_t<A> zeroth_odometer;
Odometer is not the only one that can get an explicit point origin in
our case. As timestamps are provided by the
std::chrono::system_clock
, their
values are always relative to the epoch of this clock.
Now, we can refactor our database to benefit from the explicit points:
template<actor A>
struct trip_log_item {
::string point_name;
std<si::kilo<si::metre>, zeroth_odometer<A>> odometer;
quantity_point<si::second, chrono_point_origin<system_clock>> timestamp;
quantity_point};
template<actor A>
using trip_log = std::vector<trip_log_item<A>>;
We also need to update the initialization part in our code. In the
case of implicit zeroth origins, we could construct
quantity_point
directly from the
value of a quantity
. This is no
longer the case. As a point can be represented with a
vector from the origin, to improve the safety of the code we
write, a quantity_point
class
template must be created with one of the following operations:
= zeroth_odometer<actor::alice> + 1356 * km;
quantity_point qp1 = 1356 * km + zeroth_odometer<actor::alice>;
quantity_point qp2 = zeroth_odometer<actor::alice> - 1356 * km; quantity_point qp3
Although, the qp3
above does
not have a physical sense in this specific scenario.
Note: It is not allowed to subtract a point from a vector thus
1356 * km - zeroth_odometer<actor::alice>
is an invalid operation.
Similarly to creation of a quantity, if someone does not like the
operator-based syntax to create a
quantity_point
, the same results
can be achieved with a two-parameter constructor:
{1356 * km, zeroth_odometer<actor::alice>}; quantity_point qp4
Also, as now our timestamps have a proper point origin provided in a
type, we can simplify the previous code by directly converting
std::chrono::time_point
to our
quantity_point
type.
With all the above, we can refactor our initialization part to the following:
<actor::alice> alice_log;
trip_log
.emplace_back("home", zeroth_odometer<actor::alice> + 1356 * km, system_clock::now());
alice_log
// some time passes
.emplace_back("castle", zeroth_odometer<actor::alice> + 1401 * km, system_clock::now()); alice_log
As another example, let’s assume we will attend the CppCon conference hosted in Aurora, CO, and we want to estimate the distance we will travel. We have to take a taxi to a local airport, fly to DEN airport with a stopover in FRA, and, in the end, get a cab to the Gaylord Rockies Resort & Convention Center:
constexpr struct home : absolute_point_origin<home, isq::distance> {} home;
<isq::distance[km], home> home_airport = home + 15 * km;
quantity_point<isq::distance[km], home> fra_airport = home_airport + 829 * km;
quantity_point<isq::distance[km], home> den_airport = fra_airport + 8115 * km;
quantity_point<isq::distance[km], home> cppcon_venue = den_airport + 10.1 * mi; quantity_point
As we can see above, we can easily get a new point by adding a quantity to an origin or another quantity point.
If we want to find out the distance traveled between two points, we simply subtract them:
<isq::distance[km]> total = cppcon_venue - home;
quantity<isq::distance[km]> flight = den_airport - home_airport; quantity
If we would like to find out the total distance traveled by taxi as well, we have to do a bit more calculations:
<isq::distance[km]> taxi1 = home_airport - home;
quantity<isq::distance[km]> taxi2 = cppcon_venue - den_airport;
quantity<isq::distance[km]> taxi = taxi1 + taxi2; quantity
Now, if we print the results:
::cout << "Total distance: " << total << "\n";
std::cout << "Flight distance: " << flight << "\n";
std::cout << "Taxi distance: " << taxi << "\n"; std
we will see the following output:
Total distance: 8975.25 km
Flight distance: 8944 km
Taxi distance: 31.2544 km
Note: It is not allowed to subtract two point origins defined in
terms of absolute_point_origin
(e.g., home - home
) as those do
not contain information about the unit, so we are not able to determine
a resulting quantity
type.
We often do not have only one ultimate “zero” point when we measure things.
For example, let’s assume that we have the following absolute point origin:
constexpr struct mean_sea_level : absolute_point_origin<mean_sea_level, isq::altitude> {} mean_sea_level;
If we want to model a trip to Mount Everest, measuring all daily
hikes from the mean_sea_level
might not be efficient. We may know that we are not good climbers, so
all our climbs can be represented with an 8-bit integer type, allowing
us to save memory in our database of climbs.
For this purpose, we can define a
relative_point_origin
in the
following way:
constexpr struct everest_base_camp : relative_point_origin<mean_sea_level + 5364 * m> {} everest_base_camp;
The above can be used as an origin for subsequent Points:
constexpr quantity_point first_climb_alt = everest_base_camp + isq::altitude(std::uint8_t{42} * m);
static_assert(first_climb_alt.quantity_from(everest_base_camp) == 42 * m);
static_assert(first_climb_alt.quantity_from(mean_sea_level) == 5406 * m);
static_assert(first_climb_alt.quantity_from_zero() == 5406 * m);
As we can see above, the
quantity_from()
member function
returns a relative distance from the provided point origin while the
quantity_from_zero()
returns the
distance from the absolute point origin.
As we might represent the same point with vectors
from various origins, the library provides facilities to convert the
point to the
quantity_point
class templates
expressed in terms of different origins.
For this purpose, we can either use:
A converting constructor:
constexpr quantity_point<isq::altitude[m], mean_sea_level, int> qp = first_climb_alt;
static_assert(qp.quantity_ref_from(qp.point_origin) == 5406 * m);
A dedicated conversion interface:
constexpr quantity_point qp = first_climb_alt.point_for(mean_sea_level);
static_assert(qp.quantity_ref_from(qp.point_origin) == 5406 * m);
It is only allowed to convert between various origins defined in
terms of the same
absolute_point_origin
. Even if
it is possible to express the same point as a vector
from another
absolute_point_origin
, the
library will not provide such a conversion. A custom user-defined
conversion function will be needed to add this functionality.
Said another way, in the library, there is no way to spell how two
distinct absolute_point_origin
types relate to each other.
Another important example of relative point origins is support of temperature quantity points.
The [SI] definition in the library provides a few predefined point origins for this purpose:
namespace si {
inline constexpr struct absolute_zero : absolute_point_origin<absolute_zero, isq::thermodynamic_temperature> {} absolute_zero;
inline constexpr struct zeroth_kelvin : decltype(absolute_zero) {} zeroth_kelvin;
inline constexpr struct ice_point : relative_point_origin<quantity_point{273'150 * milli<kelvin>}> {} ice_point;
inline constexpr struct zeroth_degree_Celsius : decltype(ice_point) {} zeroth_degree_Celsius;
}
namespace usc {
inline constexpr struct zeroth_degree_Fahrenheit :
<si::zeroth_degree_Celsius - 32 * (mag<ratio{5, 9}> * si::degree_Celsius)> {} zeroth_degree_Fahrenheit;
relative_point_origin
}
The above is a great example of how point origins can be stacked on top of each other:
usc::zeroth_degree_Fahrenheit
is defined relative to
si::zeroth_degree_Celsius
si::zeroth_degree_Celsius
is
defined relative to
si::zeroth_kelvin
.Note: Notice that while stacking point origins, we can use not
only different representation types but also different units for origins
and a point. In the above example, the relative point origin
for degree Celsius is defined in terms of
si::kelvin
, while the quantity
point for it will use
si::degree_Celsius
as a
unit.
The temperature point origins defined above are provided explicitly in the respective units’ definitions:
namespace si {
inline constexpr struct kelvin :
<"K", kind_of<isq::thermodynamic_temperature>, zeroth_kelvin> {} kelvin;
named_unitinline constexpr struct degree_Celsius :
<basic_symbol_text{"°C", "`C"}, kelvin, zeroth_degree_Celsius> {} degree_Celsius;
named_unit
}
namespace usc {
inline constexpr struct degree_Fahrenheit :
<basic_symbol_text{"°F", "`F"}, mag<ratio{5, 9}> * si::degree_Celsius,
named_unit> {} degree_Fahrenheit;
zeroth_degree_Fahrenheit
}
Now let’s see how we can benefit from the above definitions. We have quite a few alternatives to choose from here. Depending on our needs or taste we can:
be explicit about the unit and origin:
<si::degree_Celsius, si::zeroth_degree_Celsius> q1 = si::zeroth_degree_Celsius + 20.5 * deg_C;
quantity_point<si::degree_Celsius, si::zeroth_degree_Celsius> q2 = {20.5 * deg_C, si::zeroth_degree_Celsius};
quantity_point<si::degree_Celsius, si::zeroth_degree_Celsius> q3{20.5 * deg_C}; quantity_point
specify a unit and use its zeroth point origin implicitly:
<si::degree_Celsius> q4 = si::zeroth_degree_Celsius + 20.5 * deg_C;
quantity_point<si::degree_Celsius> q5 = {20.5 * deg_C, si::zeroth_degree_Celsius};
quantity_point<si::degree_Celsius> q6{20.5 * deg_C}; quantity_point
benefit from CTAD:
= si::zeroth_degree_Celsius + 20.5 * deg_C;
quantity_point q7 = {20.5 * deg_C, si::zeroth_degree_Celsius};
quantity_point q8 {20.5 * deg_C}; quantity_point q9
In all of the above cases, we end up with the
quantity_point
of the same type
and value.
To play a bit more with temperatures, we can implement a simple room AC temperature controller in the following way:
constexpr struct room_reference_temp : relative_point_origin<quantity_point{21 * deg_C}> {} room_reference_temp;
using room_temp = quantity_point<isq::Celsius_temperature[deg_C], room_reference_temp>;
constexpr auto step_delta = isq::Celsius_temperature(0.5 * deg_C);
constexpr int number_of_steps = 6;
{};
room_temp room_ref= room_ref - number_of_steps * step_delta;
room_temp room_low = room_ref + number_of_steps * step_delta;
room_temp room_high
::println("Room reference temperature: {} ({}, {})\n",
std.quantity_from_zero(),
room_ref.in(usc::degree_Fahrenheit).quantity_from_zero(),
room_ref.in(si::kelvin).quantity_from_zero());
room_ref
::println("| {:<14} | {:^18} | {:^18} | {:^18} |",
std"Temperature", "Room reference", "Ice point", "Absolute zero");
::println("|{0:=^16}|{0:=^20}|{0:=^20}|{0:=^20}|", "");
std
auto print = [&](std::string_view label, auto v) {
::println("| {:<14} | {:^18} | {:^18} | {:^18:N[.2f]} |", label,
std- room_reference_temp, (v - si::ice_point).in(deg_C), (v - si::absolute_zero).in(deg_C));
v };
("Lowest", room_low);
print("Default", room_ref);
print("Highest", room_high); print
The above prints:
Room reference temperature: 21 °C (69.8 °F, 294.15 K)
| Temperature | Room reference | Ice point | Absolute zero |
|================|====================|====================|====================|
| Lowest | -3 °C | 18 °C | 291.15 °C |
| Default | 0 °C | 21 °C | 294.15 °C |
| Highest | 3 °C | 24 °C | 297.15 °C |
More about temperatures can be found in the Potential surprises while working with temperatures chapter.
The library of physical quantities and units library should work with any custom representation type. Those can be used to:
As of right now, we have two other concurrent proposals to SG6 in this subject on the fly ([P2993] and [P3003R0]), so we do not provide any concrete requirements or recommendations here so far.
Based on the results of discussions on the mentioned proposals, we will provide correct guidelines in the next revisions of this paper.
By default all floating-point and integral (besides
bool
) types are treated as
scalars.
TBD
TBD
Using a concrete unit in the interface often has a lot of sense. It is especially useful if we store the data internally in the object. In such a case, we have to select a specific unit anyway.
For example, let’s consider a simple storage tank:
class StorageTank {
<horizontal_area[m2]> base_;
quantity<isq::height[m]> height_;
quantity<isq::mass_density[kg / m3]> density_ = air_density;
quantitypublic:
constexpr StorageTank(const quantity<horizontal_area[m2]>& base, const quantity<isq::height[m]>& height) :
(base), height_(height)
base_{
}
// ...
};
As the quantities provided in the function’s interface are then stored in the class, there is probably no sense in using generic interfaces here.
However, in many cases, using a specific unit in the interface is counterproductive. Let’s consider the following function:
<km / h> avg_speed(quantity<km> distance, quantity<h> duration)
quantity{
return distance / duration;
}
Everything seems fine for now. It also works great if we call it with:
<km / h> s1 = avg_speed(220 * km, 2 * h); quantity
However, if the user starts doing the following:
<mi / h> s2 = avg_speed(140 * mi, 2 * h);
quantity<m / s> s3 = avg_speed(20 * m, 2 * s); quantity
some issues start to be clearly visible:
The arguments must be converted to units mandated by the function’s parameters at each call. This involves potentially expensive multiplication/division operations at runtime.
After the function returns the speed in a unit of
km/h
, another potentially
expensive multiplication/division operations have to be performed to
convert the resulting quantity into a unit being the derived unit of the
initial function’s arguments.
Besides the obvious runtime cost, some unit conversions may result in a data truncation, which means that the result will not be exactly equal to a direct division of the function’s arguments.
We have to use a floating-point representation type (the
quantity
class template by
default uses double
as a
representation type) which is considered value preserving. Trying to use
an integral type in this scenario will work only for
s1
, while
s2
and
s3
will fail to compile. Failing
to compile is a good thing here as the library tries to prevent the user
from doing a clearly wrong thing. To make the code compile, the user
needs to use dedicated
value_cast
or
force_in
like this:
<mi / h> s2 = avg_speed(value_cast<km>(140 * mi), 2 * h);
quantity<m / s> s3 = avg_speed((20 * m).force_in(km), (2 * s).force_in(h)); quantity
But the above will obviously provide an incorrect behavior (e.g.,
division by 0
in the evaluation
of s3
).
Much better generic code can be implemented using basic concepts provided with the library:
auto avg_speed(QuantityOf<isq::length> auto distance,
<isq::time> auto duration)
QuantityOf{
return isq::speed(distance / duration);
}
This explicitly states that the arguments passed by the user must not
only satisfy a Quantity
concept, but also that their quantity specification must be implicitly
convertible to isq::length
and
isq::time
, respectively. This no
longer leaves room for error while still allowing the compiler to
generate the most efficient code.
Please, note that now it is safe just to use integral types all the way, which again improves the runtime performance as the multiplication/division operations are often faster on integral rather than floating-point types.
The above function template resolves all of the issues described before. However, we can do even better here by additionally constraining the return type:
<isq::speed> auto avg_speed(QuantityOf<isq::length> auto distance,
QuantityOf<isq::time> auto duration)
QuantityOf{
return isq::speed(distance / duration);
}
Doing so has two important benefits:
auto
, which does not provide any
hint about the thing being returned there.If we know exactly what the function does in its internals and if we know the exact argument types passed to such a function, we often know the exact type that will be returned from its invocation.
However, if we care about performance, we should often use the generic interfaces described in this chapter. A side effect is that we sometimes are unsure about the return type. Even if we know it today, it might change a week from now due to some code refactoring.
In such cases, we can again use
auto
to denote the type:
auto s1 = avg_speed(220 * km, 2 * h);
auto s2 = avg_speed(140 * mi, 2 * h);
auto s3 = avg_speed(20 * m, 2 * s);
In this case, it is probably OK to do so as the
avg_speed
function name
explicitly provides the information on what to expect as a result.
In other scenarios where the returned quantity type is not so obvious, it is again helpful to constrain the type with a concept like so:
<isq::speed> auto s1 = avg_speed(220 * km, 2 * h);
QuantityOf<isq::speed> auto s2 = avg_speed(140 * mi, 2 * h);
QuantityOf<isq::speed> auto s3 = avg_speed(20 * m, 2 * s); QuantityOf
Again, this explicitly provides additional information about the quantity we are dealing with in the code, and it serves as a unit test checking if the “thing” returned from a function is actually what we expected here.
Let’s start with a really simple example presenting basic operations that every physical quantities and units library should provide:
import mp_units;
using namespace mp_units;
using namespace mp_units::si::unit_symbols;
// simple numeric operations
static_assert(10 * km / 2 == 5 * km);
// conversions to common units
static_assert(1 * h == 3600 * s);
static_assert(1 * km + 1 * m == 1001 * m);
// derived quantities
static_assert(1 * km / (1 * s) == 1000 * m / s);
static_assert(2 * km / h * (2 * h) == 4 * km);
static_assert(2 * km / (2 * km / h) == 1 * h);
static_assert(2 * m * (3 * m) == 6 * m2);
static_assert(10 * km / (5 * km) == 2 * one);
static_assert(1000 / (1 * s) == 1 * kHz);
Try it in the Compiler Explorer.
The next example serves as a showcase of various features available in the [mp-units] library.
import mp_units;
import std;
using namespace mp_units;
constexpr QuantityOf<isq::speed> auto avg_speed(QuantityOf<isq::length> auto d,
<isq::time> auto t)
QuantityOf{
return d / t;
}
int main()
{
using namespace mp_units::si::unit_symbols;
using namespace mp_units::international::unit_symbols;
constexpr quantity v1 = 110 * km / h;
constexpr quantity v2 = 70 * mph;
constexpr quantity v3 = avg_speed(220. * isq::distance[km], 2 * h);
constexpr quantity v4 = avg_speed(isq::distance(140. * mi), 2 * h);
constexpr quantity v5 = v3.in(m / s);
constexpr quantity v6 = value_cast<m / s>(v4);
constexpr quantity v7 = value_cast<int>(v6);
::cout << v1 << '\n'; // 110 km/h
std::cout << std::setw(10) << std::setfill('*') << v2 << '\n'; // ***70 mi/h
std::cout << std::format("{:*^10}\n", v3); // *110 km/h*
std::println("{:%N in %U}", v4); // 70 in mi/h
std::println("{:{%N:.2f}%?%U}", v5); // 30.56 m/s
std::println("{:{%N:.2f}%?{%U:n}}", v6); // 31.29 m s⁻¹
std::println("{:%N}", v7); // 31
std}
Try it in the Compiler Explorer.
This example estimates the process of filling a storage tank with some contents. It presents:
std::chrono::duration
.import mp_units;
import std;
// allows standard gravity (acceleration) and weight (force) to be expressed with scalar representation
// types instead of requiring the usage of Linear Algebra library for this simple example
template<class T>
requires mp_units::is_scalar<T>
inline constexpr bool mp_units::is_vector<T> = true;
namespace {
using namespace mp_units;
using namespace mp_units::si::unit_symbols;
// add a custom quantity type of kind isq::length
inline constexpr struct horizontal_length : quantity_spec<isq::length> {} horizontal_length;
// add a custom derived quantity type of kind isq::area
// with a constrained quantity equation
inline constexpr struct horizontal_area : quantity_spec<horizontal_length * isq::width> {} horizontal_area;
inline constexpr auto g = 1 * si::standard_gravity;
inline constexpr auto air_density = isq::mass_density(1.225 * kg / m3);
class StorageTank {
<horizontal_area[m2]> base_;
quantity<isq::height[m]> height_;
quantity<isq::mass_density[kg / m3]> density_ = air_density;
quantitypublic:
constexpr StorageTank(const quantity<horizontal_area[m2]>& base, const quantity<isq::height[m]>& height) :
(base), height_(height)
base_{
}
constexpr void set_contents_density(const quantity<isq::mass_density[kg / m3]>& density)
{
assert(density > air_density);
= density;
density_ }
[[nodiscard]] constexpr QuantityOf<isq::weight> auto filled_weight() const
{
const auto volume = isq::volume(base_ * height_);
const QuantityOf<isq::mass> auto mass = density_ * volume;
return isq::weight(mass * g);
}
[[nodiscard]] constexpr quantity<isq::height[m]> fill_level(const quantity<isq::mass[kg]>& measured_mass) const
{
return height_ * measured_mass * g / filled_weight();
}
[[nodiscard]] constexpr quantity<isq::volume[m3]> spare_capacity(const quantity<isq::mass[kg]>& measured_mass) const
{
return (height_ - fill_level(measured_mass)) * base_;
}
};
class CylindricalStorageTank : public StorageTank {
public:
constexpr CylindricalStorageTank(const quantity<isq::radius[m]>& radius, const quantity<isq::height[m]>& height) :
(quantity_cast<horizontal_area>(std::numbers::pi * pow<2>(radius)), height)
StorageTank{
}
};
class RectangularStorageTank : public StorageTank {
public:
constexpr RectangularStorageTank(const quantity<horizontal_length[m]>& length, const quantity<isq::width[m]>& width,
const quantity<isq::height[m]>& height) :
(length * width, height)
StorageTank{
}
};
} // namespace
int main()
{
const quantity height = isq::height(200 * mm);
auto tank = RectangularStorageTank(horizontal_length(1'000 * mm), isq::width(500 * mm), height);
.set_contents_density(1'000 * kg / m3);
tank
const auto duration = std::chrono::seconds{200};
const quantity fill_time = value_cast<int>(quantity{duration}); // time since starting fill
const quantity measured_mass = 20. * kg; // measured mass at fill_time
const quantity fill_level = tank.fill_level(measured_mass);
const quantity spare_capacity = tank.spare_capacity(measured_mass);
const quantity filled_weight = tank.filled_weight();
const QuantityOf<isq::mass_change_rate> auto input_flow_rate = measured_mass / fill_time;
const QuantityOf<isq::speed> auto float_rise_rate = fill_level / fill_time;
const QuantityOf<isq::time> auto fill_time_left = (height / fill_level - 1 * one) * fill_time;
const quantity fill_ratio = fill_level / height;
::println("fill height at {} = {} ({} full)", fill_time, fill_level, fill_ratio.in(percent));
std::println("fill weight at {} = {} ({})", fill_time, filled_weight, filled_weight.in(N));
std::println("spare capacity at {} = {}", fill_time, spare_capacity);
std::println("input flow rate = {}", input_flow_rate);
std::println("float rise rate = {}", float_rise_rate);
std::println("tank full E.T.A. at current flow rate = {}", fill_time_left.in(s));
std}
The above code outputs:
fill height at 200 s = 0.04 m (20% full)
fill weight at 200 s = 100 g₀ kg (980.665 N)
spare capacity at 200 s = 0.08 m³
input flow rate = 0.1 kg/s
float rise rate = 2e-04 m/s
tank full E.T.A. at current flow rate = 800 s
Try it in the Compiler Explorer.
The following example codifies the history of a famous issue during the construction of a bridge across the Rhine River between the German and Swiss parts of the town Laufenburg [Hochrheinbrücke]. It also nicely presents how the Affine Space is being modeled in the library.
import mp_units;
import std;
using namespace mp_units;
using namespace mp_units::si::unit_symbols;
constexpr struct amsterdam_sea_level : absolute_point_origin<amsterdam_sea_level, isq::altitude> {
} amsterdam_sea_level;
constexpr struct mediterranean_sea_level : relative_point_origin<amsterdam_sea_level - 27 * cm> {
} mediterranean_sea_level;
using altitude_DE = quantity_point<isq::altitude[m], amsterdam_sea_level>;
using altitude_CH = quantity_point<isq::altitude[m], mediterranean_sea_level>;
template<auto R, typename Rep>
::ostream& operator<<(std::ostream& os, quantity_point<R, altitude_DE::point_origin, Rep> alt)
std{
return os << alt.quantity_ref_from(altitude_DE::point_origin) << " AMSL(DE)";
}
template<auto R, typename Rep>
::ostream& operator<<(std::ostream& os, quantity_point<R, altitude_CH::point_origin, Rep> alt)
std{
return os << alt.quantity_ref_from(altitude_CH::point_origin) << " AMSL(CH)";
}
template<auto R, typename Rep>
struct std::formatter<quantity_point<R, altitude_DE::point_origin, Rep>> : formatter<quantity<R, Rep>> {
template<typename FormatContext>
auto format(const quantity_point<R, altitude_DE::point_origin, Rep>& alt, FormatContext& ctx) const
{
<quantity<R, Rep>>::format(alt.quantity_ref_from(altitude_DE::point_origin), ctx);
formatterreturn std::format_to(ctx.out(), " AMSL(DE)");
}
};
template<auto R, typename Rep>
struct std::formatter<quantity_point<R, altitude_CH::point_origin, Rep>> : formatter<quantity<R, Rep>> {
template<typename FormatContext>
auto format(const quantity_point<R, altitude_CH::point_origin, Rep>& alt, FormatContext& ctx) const
{
<quantity<R, Rep>>::format(alt.quantity_ref_from(altitude_CH::point_origin), ctx);
formatterreturn std::format_to(ctx.out(), " AMSL(CH)");
}
};
int main()
{
// expected bridge altitude in a specific reference system
= amsterdam_sea_level + 330 * m;
quantity_point expected_bridge_alt
// some nearest landmark altitudes on both sides of the river
// equal but not equal ;-)
= altitude_DE::point_origin + 300 * m;
altitude_DE landmark_alt_DE = altitude_CH::point_origin + 300 * m;
altitude_CH landmark_alt_CH
// artifical deltas from landmarks of the bridge base on both sides of the river
= isq::height(3 * m);
quantity delta_DE = isq::height(-2 * m);
quantity delta_CH
// artificial altitude of the bridge base on both sides of the river
= landmark_alt_DE + delta_DE;
quantity_point bridge_base_alt_DE = landmark_alt_CH + delta_CH;
quantity_point bridge_base_alt_CH
// artificial height of the required bridge pilar height on both sides of the river
= expected_bridge_alt - bridge_base_alt_DE;
quantity bridge_pilar_height_DE = expected_bridge_alt - bridge_base_alt_CH;
quantity bridge_pilar_height_CH
::println("Bridge pillars height:");
std::println("- Germany: {}", bridge_pilar_height_DE);
std::println("- Switzerland: {}", bridge_pilar_height_CH);
std
// artificial bridge altitude on both sides of the river in both systems
= bridge_base_alt_DE + bridge_pilar_height_DE;
quantity_point bridge_road_alt_DE = bridge_base_alt_CH + bridge_pilar_height_CH;
quantity_point bridge_road_alt_CH
::println("Bridge road altitude:");
std::println("- Germany: {}", bridge_road_alt_DE);
std::println("- Switzerland: {}", bridge_road_alt_CH);
std
::println("Bridge road altitude relative to the Amsterdam Sea Level:");
std::println("- Germany: {}", bridge_road_alt_DE.quantity_from(amsterdam_sea_level));
std::println("- Switzerland: {}", bridge_road_alt_CH.quantity_from(amsterdam_sea_level));
std}
The above provides the following text output:
Bridge pillars height:
- Germany: 27 m
- Switzerland: 3227 cm
Bridge road altitude:
- Germany: 330 m AMSL(DE)
- Switzerland: 33027 cm AMSL(CH)
Bridge road altitude relative to the Amsterdam Sea Level:
- Germany: 330 m
- Switzerland: 33000 cm
Try it in the Compiler Explorer.
Users can easily define new quantities and units for domain-specific use-cases. This example from digital signal processing domain will show how to define custom strongly typed dimensionless quantities, units for them, and how they can be converted to time measured in milliseconds:
import mp_units;
import std;
using namespace mp_units;
namespace ni {
// quantities
inline constexpr struct SampleCount : quantity_spec<dimensionless, is_kind> {} SampleCount;
inline constexpr struct SampleDuration : quantity_spec<isq::time> {} SampleDuration;
inline constexpr struct SamplingRate : quantity_spec<isq::frequency, SampleCount / isq::time> {} SamplingRate;
inline constexpr struct UnitSampleAmount : quantity_spec<dimensionless, is_kind> {} UnitSampleAmount;
inline constexpr auto Amplitude = UnitSampleAmount;
inline constexpr auto Level = UnitSampleAmount;
inline constexpr struct Power : quantity_spec<Level * Level> {} Power;
inline constexpr struct MIDIClock : quantity_spec<dimensionless, is_kind> {} MIDIClock;
inline constexpr struct BeatCount : quantity_spec<dimensionless, is_kind> {} BeatCount;
inline constexpr struct BeatDuration : quantity_spec<isq::time> {} BeatDuration;
inline constexpr struct Tempo : quantity_spec<isq::frequency, BeatCount / isq::time> {} Tempo;
// units
inline constexpr struct Sample : named_unit<"Smpl", one, kind_of<SampleCount>> {} Sample;
inline constexpr struct SampleValue : named_unit<"PCM", one, kind_of<UnitSampleAmount>> {} SampleValue;
inline constexpr struct MIDIPulse : named_unit<"p", one, kind_of<MIDIClock>> {} MIDIPulse;
inline constexpr struct QuarterNote : named_unit<"q", one, kind_of<BeatCount>> {} QuarterNote;
inline constexpr struct HalfNote : named_unit<"h", mag<2> * QuarterNote> {} HalfNote;
inline constexpr struct DottedHalfNote : named_unit<"h.", mag<3> * QuarterNote> {} DottedHalfNote;
inline constexpr struct WholeNote : named_unit<"w", mag<4> * QuarterNote> {} WholeNote;
inline constexpr struct EightNote : named_unit<"8th", mag<ratio{1, 2}> * QuarterNote> {} EightNote;
inline constexpr struct DottedQuarterNote : named_unit<"q.", mag<3> * EightNote> {} DottedQuarterNote;
inline constexpr struct QuarterNoteTriplet : named_unit<"qt", mag<ratio{1, 3}> * HalfNote> {} QuarterNoteTriplet;
inline constexpr struct SixteenthNote : named_unit<"16th", mag<ratio{1, 2}> * EightNote> {} SixteenthNote;
inline constexpr struct DottedEightNote : named_unit<"q.", mag<3> * SixteenthNote> {} DottedEightNote;
inline constexpr auto Beat = QuarterNote;
inline constexpr struct BeatsPerMinute : named_unit<"bpm", Beat / si::minute> {} BeatsPerMinute;
inline constexpr struct MIDIPulsePerQuarter : named_unit<"ppqn", MIDIPulse / QuarterNote> {} MIDIPulsePerQuarter;
namespace unit_symbols {
inline constexpr auto Smpl = Sample;
inline constexpr auto pcm = SampleValue;
inline constexpr auto p = MIDIPulse;
inline constexpr auto n_wd = 3 * HalfNote;
inline constexpr auto n_w = WholeNote;
inline constexpr auto n_hd = DottedHalfNote;
inline constexpr auto n_h = HalfNote;
inline constexpr auto n_qd = DottedQuarterNote;
inline constexpr auto n_q = QuarterNote;
inline constexpr auto n_qt = QuarterNoteTriplet;
inline constexpr auto n_8thd = DottedEightNote;
inline constexpr auto n_8th = EightNote;
inline constexpr auto n_16th = SixteenthNote;
}
<BeatsPerMinute, float> GetTempo()
quantity{
return 110 * BeatsPerMinute;
}
<MIDIPulsePerQuarter, unsigned> GetPPQN()
quantity{
return 960 * MIDIPulse / QuarterNote;
}
<MIDIPulse, unsigned> GetTransportPos()
quantity{
return 15836 * MIDIPulse;
}
<SamplingRate[si::hertz], float> GetSampleRate()
quantity{
return 44100.f * si::hertz;
}
}
int main()
{
using namespace ni::unit_symbols;
using namespace mp_units::si::unit_symbols;
const auto sr1 = ni::GetSampleRate();
const auto sr2 = 48000.f * Smpl / s;
const auto samples = 512 * Smpl;
const auto sampleTime1 = (samples / sr1).in(s);
const auto sampleTime2 = (samples / sr2).in(ms);
const auto sampleDuration1 = (1 / sr1).in(ms);
const auto sampleDuration2 = (1 / sr2).in(ms);
const auto rampTime = 35.f * ms;
const auto rampSamples1 = value_cast<int>((rampTime * sr1).in(Smpl));
const auto rampSamples2 = value_cast<int>((rampTime * sr2).in(Smpl));
::println("Sample rate 1 is: {}", sr1);
std::println("Sample rate 2 is: {}", sr2);
std
::println("{} @ {} is {:{%N:.5f} %U}", samples, sr1, sampleTime1);
std::println("{} @ {} is {:{%N:.5f} %U}", samples, sr2, sampleTime2);
std
::println("One sample @ {} is {:{%N:.5f} %U}", sr1, sampleDuration1);
std::println("One sample @ {} is {:{%N:.5f} %U}", sr2, sampleDuration2);
std
::println("{} is {} @ {}", rampTime, rampSamples1, sr1);
std::println("{} is {} @ {}", rampTime, rampSamples2, sr2);
std
auto sampleValue = -0.4f * pcm;
auto power1 = sampleValue * sampleValue;
auto power2 = -0.2 * pow<2>(pcm);
auto tempo = ni::GetTempo();
auto reverbBeats = 1 * n_qd;
auto reverbTime = reverbBeats / tempo;
auto pulsePerQuarter = value_cast<float>(ni::GetPPQN());
auto transportPosition = ni::GetTransportPos();
auto transportBeats = (transportPosition / pulsePerQuarter).in(n_q);
auto transportTime = (transportBeats / tempo).in(s);
::println("SampleValue is: {}", sampleValue);
std::println("Power 1 is: {}", power1);
std::println("Power 2 is: {}", power2);
std
::println("Tempo is: {}", tempo);
std::println("Reverb Beats is: {}", reverbBeats);
std::println("Reverb Time is: {}", reverbTime.in(s));
std::println("Pulse Per Quarter is: {}", pulsePerQuarter);
std::println("Transport Position is: {}", transportPosition);
std::println("Transport Beats is: {}", transportBeats);
std::println("Transport Time is: {}", transportTime);
std
// auto error = 1 * Smpl + 1 * pcm + 1 * p + 1 * Beat; // Compile-time error
}
The above code outputs:
Sample rate 1 is: 44100 Hz
Sample rate 2 is: 48000 Smpl/s
512 Smpl @ 44100 Hz is 0.01161 s
512 Smpl @ 48000 Smpl/s is 10.66667 ms
One sample @ 44100 Hz is 0.02268 ms
One sample @ 48000 Smpl/s is 0.02083 ms
35 ms is 1543 Smpl @ 44100 Hz
35 ms is 1680 Smpl @ 48000 Smpl/s
SampleValue is: -0.4 PCM
Power 1 is: 0.16000001 PCM²
Power 2 is: -0.2 PCM²
Tempo is: 110 bpm
Reverb Beats is: 1 q.
Reverb Time is: 0.8181818 s
Pulse Per Quarter is: 960 ppqn
Transport Position is: 15836 p
Transport Beats is: 16.495832 q
Transport Time is: 8.997726 s
Try it in the Compiler Explorer.
Note: More about this example can be found in “Exploration of Strongly-typed Units in C++: A Case Study from Digital Audio” CppCon 2023 talk by Roth Michaels.
Units-only is not a good design for a quantities and units library. It works to some extent, but plenty of use cases can’t be addressed, and for those that somehow work, we miss important safety improvements provided by additional abstractions in this chapter. But before we talk about those extensions, let’s first discuss some limitations of the units-only solution.
Note: The issues described below do not apply to the proposed library, because with the proposed interfaces, even if we decide to only use the simple mode, units are still backed up by quantity kinds under the framework’s hood.
A common requirement in the domain is to write unit-agnostic generic
interfaces. For example, let’s try to implement a generic
avg_speed
function template that
takes a quantity of any unit and produces the result. So if we call it
with distance in km
and
time in h
, we will get
km / h
as a result, but if we
call it with mi
and
h
, we expect
mi / h
to be returned.
template<Unit auto U1, typename Rep1, Unit auto U2, typename Rep2>
auto avg_speed(quantity<U1, Rep1> distance, quantity<U2, Rep2> time)
{
return distance / time;
}
= avg_speed(120 * km, 2 * h); quantity speed
This function works but does not provide any type safety to the users. The function arguments can be easily reordered on the call site. Also, we do not get any information about the return type of the function and any safety to ensure that the function logic actually returns a quantity of speed.
With a units-only library, we have to write the function in the following way:
<si::metre / si::second> avg_speed(quantity<si::metre> distance, quantity<si::second> time)
quantity{
return distance / time;
}
(120 * km, 2 * h).in(km / h); avg_speed
The above code decreased the performance because we always pay for
the conversion at the function’s input and output. Moreover, we had to
force double
as a representation
type to prevent narrowing, which can affect not only the performance,
but also precision and memory footprint.
We could try to provide concepts like
ScaledUnitOf<si::metre>
that will try to constrain somehow the arguments, but it leads to even
more problems with the unit definitions. For example, are Hz and Bq
scaled versions of 1 / s? What about radian and steradian or a litre and
a cubic meter?
Sometimes, we need to define several units describing the same quantity but which do not convert to each other. A typical example can be a currency use case. A user may want to define EURO and USD as units of currency, but do not provide any predefined conversion factor and handle such a conversion at runtime with custom logic. In such a case, how we can specify that EURO and USD are quantities of the same type/dimension?
To prevent the above issues, most of the libraries on the market introduce dimension abstraction. Thanks to that, we could solve the first issue of the previous chapter with:
<dim_speed> auto avg_speed(QuantityOf<dim_length> auto distance,
QuantityOf<dim_time> auto time)
QuantityOf{
return distance / time;
}
and the second one by specifying that both EURO and USD are units of
dim_currency
. This is a
significant improvement but still has some issues.
Let’s first look again at the above solution. A domain expert seeing this code will immediately say there is no such thing as a speed dimension. The ISQ specifies only 7 dimensions with unique symbols assigned, and the dimensions of all the ISQ quantities are created as a vector product of those. For example, a quantity of speed has a dimension of \(L^1T^{-1}\). So, to be physically correct, the above code should be rewritten as:
<dim_length / dim_time> auto avg_speed(QuantityOf<dim_length> auto distance,
QuantityOf<dim_time> auto time)
QuantityOf{
return distance / time;
}
Most of the libraries on the market ignore this fact and try to model distinct quantities through their dimensions, giving a false sense of safety. A dimension is not enough to describe a quantity. This has been known for a long time now. The [Measurement Data] report from 1996 says explicitly, “Dimensional analysis does not adequately model the semantics of measurement data”.
In the following chapters, we will see a few use cases that can’t be solved with an approach that only relies on units or dimensions.
The [SI] provides several units for distinct quantities of the same dimension but different kinds. For example:
There are many more similar examples in [ISO/IEC 80000]. For example, storage capacity quantity can be measured in units of one, bit, octet, and byte.
The above conflicts can’t be solved with dimensions, and they yield many safety issues. For example, we can ask ourselves what should be the result of the following:
quantity q = 1 * Hz + 1 * Bq;
quantity<Gy> q = 42 * Sv;
bool b = (1 * rad + 1 * bit) == 2 * sr;
None of the above code should compile, but most of the libraries on
the market happily accept it and provide meaningless results. Some of
them decide not to define one or more of the above units at all to avoid
potential safety issues. For example, the Au library
does not define Sv
to avoid
mixing it up with Gy.
Even if some quantities do not have a specially assigned unit, they may still have a totally different physical meaning even if they share the same dimension:
Again, we don’t want to accidentally mix those.
Even if we somehow address all the above, there are still plenty of use cases that still can’t be safely implemented with such abstractions.
Let’s consider that we want to implement a freight transport application to position cargo in the container. In such a scenario, we need to be able to discriminate between length, width, and height of the package. Also, often, we can find a “This side up” arrow on the box.
A similar but also really important use case is in aviation. The current altitude is a totally different quantity than the distance to the destination. The same is true for forward speed and sink rate. We do not want to accidentally mix those.
When we deal with energy, we should be able to implicitly construct it from a proper product of any mass, length, and time. However, when we want to calculate gravitational potential energy, we may not want it to be implicitly initialized from any expression of matching dimensions. Such an implicit construction should be allowed only if we multiply a mass with acceleration of free fall and height. All other conversions should happen explicitly.
Yet another example comes from the audio industry. In the audio software, we want to treat specific counts (e.g., beats, samples) as separate quantities, but if we divide them, we should obtain a quantity convertible to frequency. The latter has the dimension of \(T^{-1}\), which prevents us from assigning dedicated dimensions to such counts.
The last example that we want to mention here comes from finance. This time, we need to model volume as a special quantity of currency. volume can be obtained by multiplying currency by the dimensionless market quantity. Of course, both currency and volume should be expressed in the same units (e.g., USD).
None of the above scenarios can be addressed with just units and dimensions. We need a better abstraction to safely implement them.
A system of quantities is a set of quantities together with a set of noncontradictory equations relating those quantities.
The International System of Quantities (ISQ) is a system of quantities based on the seven base quantities: length, mass, time, electric current, thermodynamic temperature, amount of substance, and luminous intensity. This system of quantities is published in [ISO/IEC 80000], “Quantities and units”.
A system of units is a set of base units and derived units, together with their multiples and submultiples, defined in accordance with given rules, for a given system of quantities.
The International System of Units (SI) is a system of units, based on the International System of Quantities, their names and symbols, including a series of prefixes and their names and symbols, together with rules for their use, adopted by the General Conference on Weights and Measures (CGPM).
The physical units libraries on the market typically only focus on modeling one or more systems of units. However, this is not the only system kind to model. Another, and maybe even more important, is a system of quantities. The most important example here is the International System of Quantities (ISQ) defined by [ISO/IEC 80000].
As it was described in Limitations of dimensions, dimension is not enough to describe a quantity. We need a better abstraction to provide safety to our calculations.
The [ISO/IEC Guide 99] says:
[ISO/IEC 80000] also explicitly notes:
Measurement units of quantities of the same quantity dimension may be designated by the same name and symbol even when the quantities are not of the same kind. For example, joule per kelvin and J/K are respectively the name and symbol of both a measurement unit of heat capacity and a measurement unit of entropy, which are generally not considered to be quantities of the same kind. However, in some cases special measurement unit names are restricted to be used with quantities of specific kind only. For example, the measurement unit ‘second to the power minus one’ (1/s) is called hertz (Hz) when used for frequencies and becquerel (Bq) when used for activities of radionuclides. As another example, the joule (J) is used as a unit of energy, but never as a unit of moment of force, i.e. the newton metre (N · m).
Those provide answers to all the issues mentioned above. More than one quantity may be defined for the same dimension:
Two quantities can’t be added, subtracted, or compared unless they belong to the same quantity kind.
[ISO/IEC 80000] specifies hundreds of different quantities. Plenty of various kinds are provided, and often, each kind contains more than one quantity. It turns out that such quantities form a hierarchy of quantities of the same kind.
For example, here are all quantities of the kind length provided in [ISO/IEC 80000] (part 1):
Each of the above quantities expresses some kind of length, and each can be measured with meters, which is the unit defined by the [SI] for quantities of length. However, each has different properties, usage, and sometimes even a different character (position vector and displacement are vector quantities).
The below presents how such a hierarchy tree can be defined in the library:
inline constexpr struct dim_length : base_dimension<"L"> {} dim_length;
inline constexpr struct length : quantity_spec<dim_length> {} length;
inline constexpr struct width : quantity_spec<length> {} width;
inline constexpr auto breadth = width;
inline constexpr struct height : quantity_spec<length> {} height;
inline constexpr auto depth = height;
inline constexpr auto altitude = height;
inline constexpr struct thickness : quantity_spec<width> {} thickness;
inline constexpr struct diameter : quantity_spec<width> {} diameter;
inline constexpr struct radius : quantity_spec<width> {} radius;
inline constexpr struct radius_of_curvature : quantity_spec<radius> {} radius_of_curvature;
inline constexpr struct path_length : quantity_spec<length> {} path_length;
inline constexpr auto arc_length = path_length;
inline constexpr struct distance : quantity_spec<path_length> {} distance;
inline constexpr struct radial_distance : quantity_spec<distance> {} radial_distance;
inline constexpr struct wavelength : quantity_spec<length> {} wavelength;
inline constexpr struct position_vector : quantity_spec<length, quantity_character::vector> {} position_vector;
inline constexpr struct displacement : quantity_spec<length, quantity_character::vector> {} displacement;
In the above code:
length
takes the base
dimension to indicate that we are creating a base quantity that will
serve as a root for a tree of quantities of the same kind,width
and following
quantities are branches and leaves of this tree with the parent always
provided as the argument to
quantity_spec
class
template,breadth
is an alias name for
the same quantity as width
.Please note that some quantities may be specified by [ISO/IEC 80000] as vector or tensor
quantities (e.g.,
displacement
).
Quantity conversion rules can be defined based on the same hierarchy of quantities of kind length.
Implicit conversions
static_assert(implicitly_convertible(isq::width, isq::length));
static_assert(implicitly_convertible(isq::radius, isq::length));
static_assert(implicitly_convertible(isq::radius, isq::width));
Implicit conversions are allowed on copy-initialization:
void foo(quantity<isq::length<m>> q);
<isq::width<m>> q1 = 42 * m;
quantity<isq::length<m>> q2 = q1; // implicit quantity conversion
quantity(q1); // implicit quantity conversion foo
Explicit conversions
static_assert(!implicitly_convertible(isq::length, isq::width));
static_assert(!implicitly_convertible(isq::length, isq::radius));
static_assert(!implicitly_convertible(isq::width, isq::radius));
static_assert(explicitly_convertible(isq::length, isq::width));
static_assert(explicitly_convertible(isq::length, isq::radius));
static_assert(explicitly_convertible(isq::width, isq::radius));
Explicit conversions are forced by passing the quantity to a call
operator of a quantity_spec
type:
<isq::length<m>> q1 = 42 * m;
quantity<isq::height<m>> q2 = isq::height(q1); // explicit quantity conversion quantity
Explicit casts
static_assert(!implicitly_convertible(isq::height, isq::width));
static_assert(!explicitly_convertible(isq::height, isq::width));
static_assert(castable(isq::height, isq::width));
Explicit casts are forced with a dedicated
quantity_cast
function:
<isq::width<m>> q1 = 42 * m;
quantity<isq::height<m>> q2 = quantity_cast<isq::height>(q1); // explicit quantity cast quantity
No conversion
static_assert(!implicitly_convertible(isq::time, isq::length));
static_assert(!explicitly_convertible(isq::time, isq::length));
static_assert(!castable(isq::time, isq::length));
Even the explicit casts will not force such a conversion:
void foo(quantity<isq::length[m]>);
(quantity_cast<isq::length>(42 * s)); // Compile-time error foo
[ISO/IEC Guide 99] explicitly states that width and height are quantities of the same kind and as such they:
If we take the above for granted, the only reasonable result of
1 * width + 1 * height
is
2 * length
, where the result of
length
is known as a common
quantity type. A result of such an equation is always the first common
node in a hierarchy tree of the same kind. For example:
static_assert(common_quantity_spec(isq::width, isq::height) == isq::length);
static_assert(common_quantity_spec(isq::thickness, isq::radius) == isq::width);
static_assert(common_quantity_spec(isq::distance, isq::path_length) == isq::path_length);
= isq::thickness(1 * m) + isq::radius(1 * m);
quantity q static_assert(q.quantity_spec == isq::width);
One could argue that allowing to add or compare quantities of height and width might be a safety issue, but we need to be consistent with the requirements of [ISO/IEC 80000]. Moreover, from our experience, disallowing such operations and requiring an explicit cast to a common quantity in every single place makes the code so cluttered with casts that it nearly renders the library unusable.
Fortunately, the above-mentioned conversion rules make the code safe by construction anyway. Let’s analyze the following example:
inline constexpr struct horizontal_length : quantity_spec<isq::length> {} horizontal_length;
namespace christmas {
struct gift {
<horizontal_length[m]> length;
quantity<isq::width[m]> width;
quantity<isq::height[m]> height;
quantity};
::array<quantity<isq::length[m]>, 2> gift_wrapping_paper_size(const gift& g)
std{
const auto dim1 = 2 * g.width + 2 * g.height + 0.5 * g.width;
const auto dim2 = g.length + 2 * 0.75 * g.height;
return { dim1, dim2 };
}
} // namespace christmas
int main()
{
const christmas::gift lego = { horizontal_length(40 * cm), isq::width(30 * cm), isq::height(15 * cm) };
auto paper = christmas::gift_wrapping_paper_size(lego);
::cout << "Paper needed to pack a lego box:\n";
std::cout << "- " << paper[0] << " X " << paper[1] << "\n"; // - 1.05 m X 0.625 m
std::cout << "- area = " << paper[0] * paper[1] << "\n"; // - area = 0.65625 m²
std}
In the beginning, we introduce a custom quantity
horizontal_length
of a kind
length, which then, together with
isq::width
and
isq::height
, are used to define
the dimensions of a Christmas gift. Next, we provide a function that
calculates the dimensions of a gift wrapping paper with some wraparound.
The result of both those expressions is a quantity of
isq::length
, as this is the
closest common quantity for the arguments used in this quantity
equation.
Regarding safety, it is important to mention here, that thanks to the conversion rules provided above, it would be impossible to accidentally do the following:
void foo(quantity<horizontal_length[m]> q);
<isq::width[m]> q1 = dim1; // Compile-time error
quantity<isq::height[m]> q2{dim1}; // Compile-time error
quantity(dim1); // Compile-time error foo
The reason of compilation errors above is the fact that
isq::length
is not implicitly
convertible to the quantities defined based on it. To make the above
code compile, an explicit conversion of a quantity type is needed:
void foo(quantity<horizontal_length[m]> q);
<isq::width[m]> q1 = isq::width(dim1);
quantity<isq::height[m]> q2{isq::height(dim1)};
quantity(horizontal_length(dim1)); foo
To summarize, rules for addition, subtraction, and comparison of quantities improve the library usability, while the conversion rules enhance the safety of the library compared to the libraries that do not model quantity kinds.
The same rules propagate to derived quantities. For example, we can define strongly typed horizontal length and area:
inline constexpr struct horizontal_length : quantity_spec<isq::length> {} horizontal_length;
inline constexpr struct horizontal_area : quantity_spec<isq::area, horizontal_length * isq::width> {} horizontal_area;
The first definition says that a
horizontal_length
is a more
specialized quantity than
isq::length
and belongs to the
same quantity kind. The second line defines a
horizontal_area
, which is a more
specialized quantity than
isq::area
, so it has a more
constrained recipe as well. Thanks to that:
static_assert(implicitly_convertible(horizontal_length, isq::length));
static_assert(!implicitly_convertible(isq::length, horizontal_length));
static_assert(explicitly_convertible(isq::length, horizontal_length));
static_assert(implicitly_convertible(horizontal_area, isq::area));
static_assert(!implicitly_convertible(isq::area, horizontal_area));
static_assert(explicitly_convertible(isq::area, horizontal_area));
static_assert(implicitly_convertible(isq::length * isq::length, isq::area));
static_assert(!implicitly_convertible(isq::length * isq::length, horizontal_area));
static_assert(explicitly_convertible(isq::length * isq::length, horizontal_area));
static_assert(implicitly_convertible(horizontal_length * isq::width, isq::area));
static_assert(implicitly_convertible(horizontal_length * isq::width, horizontal_area));
Unfortunately, derived quantity equations often do not automatically form a hierarchy tree. This is why sometimes it is not obvious what such a tree should look like. Also, the [ISO/IEC Guide 99] explicitly states:
The division of ‘quantity’ according to ‘kind of quantity’ is, to some extent, arbitrary.
The below presents some arbitrary hierarchy of derived quantities of kind energy:
Notice, that even though all of those quantities have the same dimension and can be expressed in the same units, they have different quantity equations used to create them implicitly:
energy
is the most
generic one and thus can be created from base quantities of
mass
,
length
, and
time
. As those are also the
roots of quantities of their kinds and all other quantities are
implicitly convertible to them, it means that an
energy
can be implicitly
constructed from any quantity having proper powers of mass,
length, and time.
static_assert(implicitly_convertible(isq::mass * pow<2>(isq::length) / pow<2>(isq::time), isq::energy));
static_assert(implicitly_convertible(isq::mass * pow<2>(isq::height) / pow<2>(isq::time), isq::energy));
mechanical_energy
is a
more “specialized” quantity than
energy
(not every
energy
is a
mechanical_energy
). It is why an
explicit cast is needed to convert from either
energy
or the results of its
quantity equation.
static_assert(!implicitly_convertible(isq::energy, isq::mechanical_energy));
static_assert(explicitly_convertible(isq::energy, isq::mechanical_energy));
static_assert(!implicitly_convertible(isq::mass * pow<2>(isq::length) / pow<2>(isq::time), isq::mechanical_energy));
static_assert(explicitly_convertible(isq::mass * pow<2>(isq::length) / pow<2>(isq::time), isq::mechanical_energy));
gravitational_potential_energy
is not only even more specialized one but additionally, it is special in
a way that it provides its own “constrained” quantity equation. Maybe
not every mass * pow<2>(length) / pow<2>(time)
is a
gravitational_potential_energy
,
but every mass * acceleration_of_free_fall * height
is.
static_assert(!implicitly_convertible(isq::energy, gravitational_potential_energy));
static_assert(explicitly_convertible(isq::energy, gravitational_potential_energy));
static_assert(!implicitly_convertible(isq::mass * pow<2>(isq::length) / pow<2>(isq::time), gravitational_potential_energy));
static_assert(explicitly_convertible(isq::mass * pow<2>(isq::length) / pow<2>(isq::time), gravitational_potential_energy));
static_assert(implicitly_convertible(isq::mass * isq::acceleration_of_free_fall * isq::height, gravitational_potential_energy));
In the physical units library, we also need an abstraction describing an entire family of quantities of the same kind. Such quantities have not only the same dimension but also can be expressed in the same units.
To annotate a quantity to represent its kind (and not just a
hierarchy tree’s root quantity), we introduced a
kind_of<>
specifier. For
example, to express any quantity of length, we need to specify
kind_of<isq::length>
. That
entity behaves as any quantity of its kind. This means that it is
implicitly convertible to any quantity in a tree:
static_assert(!implicitly_convertible(isq::length, isq::height));
static_assert(implicitly_convertible(kind_of<isq::length>, isq::height));
Additionally, the result of operations on quantity kinds is also a quantity kind:
static_assert(same_type<kind_of<isq::length> / kind_of<isq::time>, kind_of<isq::length / isq::time>>);
However, if at least one equation’s operand is not a quantity kind, the result becomes a “strong” quantity where all the kinds are converted to the hierarchy tree’s root quantities:
static_assert(!same_type<kind_of<isq::length> / isq::time, kind_of<isq::length / isq::time>>);
static_assert(same_type<kind_of<isq::length> / isq::time, isq::length / isq::time>);
Please note that only a root quantity from the hierarchy tree or the
one marked with is_kind
specifier in the quantity_spec
definition can be put as a template parameter to the
kind_of
specifier. For example,
kind_of<isq::width>
will
fail to compile. However, we can call
get_kind(q)
to obtain a kind of
any quantity:
static_assert(get_kind(isq::width) == kind_of<isq::length>);
Modeling a system of units is the most important feature and a selling point of every physical units library. Thanks to that, the library can protect users from performing invalid operations on quantities and provide automated conversion factors between various compatible units.
Probably all the libraries in the wild model the [SI] or at least most of it (refer to SI units of quantities of the same dimension but different kinds for more details) and many of them provide support for additional units belonging to various other systems (e.g., imperial).
Systems of quantities specify a set of quantities and equations relating to those quantities. Those equations do not take any unit or a numerical representation into account at all. In order to create a quantity, we need to add those missing pieces of information. This is where a system of units kicks in.
The [SI] is explicitly stated to be based on the ISQ. Among others, it defines seven base units, one for each base quantity. In the library, this is expressed by associating a quantity kind to a unit being defined:
inline constexpr struct metre : named_unit<"m", kind_of<isq::length>> {} metre;
The
kind_of<isq::length>
above
states explicitly that this unit has an associated quantity kind. In
other words, si::metre
(and
scaled units based on it) can be used to express the amount of any
quantity of kind length.
Associated units are so useful and common in the library that they
got their own AssociatedUnit<T>
concept to improve the interfaces.
Please note that for some systems of units (e.g., natural units), a
unit may not have an associated quantity type. For example, if we define
the speed of light constant as
c = 1
, we can define a system
where both length and time will be measured in
seconds, and speed will be a quantity measured with the unit
one
. In such case, the
definition will look as follows:
inline constexpr struct second : named_unit<"s"> {} second;
One of the strongest points of the [SI] system is that its units compose. This allows providing thousands of different units for hundreds of various quantities with a really small set of predefined units and prefixes. For example, one can write:
<si::metre / si::second> q; quantity
to express a quantity of speed. The resulting quantity type is implicitly inferred from the unit equation by repeating exactly the same operations on the associated quantity kinds.
Also, as units are regular values, we can easily provide a helper ad-hoc unit with:
constexpr auto mps = si::metre / si::second;
<mps> q; quantity
The [SI] provides the names for 22 common coherent units of 22 derived quantities.
Each such named derived unit is a result of a specific predefined unit equation. For example, a unit of power quantity is defined as:
inline constexpr struct watt : named_unit<"W", joule / second> {} watt;
However, a power quantity can be expressed in other units as well. For example, the following:
auto q1 = 42 * W;
::cout << q1 << "\n";
std::cout << q1.in(J / s) << "\n";
std::cout << q1.in(N * m / s) << "\n";
std::cout << q1.in(kg * m2 / s3) << "\n"; std
prints:
42 W
42 J/s
42 N m/s
42 kg m²/s³
All of the above quantities are equivalent and mean exactly the same.
Some derived units are valid only for specific derived quantities. For example, [SI] specifies both hertz and becquerel derived units with the same unit equation \(s^{-1}\). However, it also explicitly states:
The hertz shall only be used for periodic phenomena and the becquerel shall only be used for stochastic processes in activity referred to a radionuclide.
This is why it is important for the library to allow constraining such units to be used only with a specific quantity kind:
inline constexpr struct hertz : named_unit<"Hz", one / second, kind_of<isq::frequency>> {} hertz;
inline constexpr struct becquerel : named_unit<"Bq", one / second, kind_of<isq::activity>> {} becquerel;
With the above, hertz
can
only be used for frequencies, while
becquerel
should only be used
for quantities of activity. This means that the following
equation will not compile, improving the type-safety of the library:
auto q = 1 * Hz + 1 * Bq; // Fails to compile
Besides named units, the SI specifies also 24 prefixes
(all being a power of 10
) that
can be prepended to all named units to obtain various scaled versions of
them.
Implementation of std::ratio
provided by all major compilers is able to express only 16 of them. This
is why, we had to find an alternative way to represent a unit’s
magnitude in a more flexible way.
Each prefix is implemented as:
template<PrefixableUnit U> struct quecto_ : prefixed_unit<"q", mag_power<10, -30>, U{}> {};
template<PrefixableUnit auto U> inline constexpr quecto_<std::remove_const_t<decltype(U)>> quecto;
and then a unit can be prefixed in the following way:
inline constexpr auto qm = quecto<metre>;
The usage of mag_power
not
only enables providing support for SI prefixes, but it can also
efficiently represent any rational magnitude. For example, [ISO/IEC 80000] (part 13) prefixes used
in the IT industry can be implemented as:
template<PrefixableUnit U> struct yobi_ : prefixed_unit<"Yi", mag_power<2, 80>, U{}> {};
template<PrefixableUnit auto U> inline constexpr yobi_<std::remove_const_t<decltype(U)>> yobi;
Please note that to improve the readability of generated types that are exposed in compiler errors and debugger, the variable template takes an NTTP and converts it to its type before passing the argument to the associated class template.
In the [SI], all units are either base or derived units or prefixed versions of those. However, those are not the only options possible.
For example, there is a list of off-system units accepted for use with [SI]. All of those are scaled versions of the [SI] units with ratios that can’t be explicitly expressed with predefined SI prefixes. Those include units like minute, hour, or electronvolt:
inline constexpr struct minute : named_unit<"min", mag<60> * si::second> {} minute;
inline constexpr struct hour : named_unit<"h", mag<60> * minute> {} hour;
inline constexpr struct electronvolt : named_unit<"eV",
<ratio{1'602'176'634, 1'000'000'000}> * mag_power<10, -19> * si::joule> {} electronvolt; mag
Also, units of other systems of units are often defined in terms of scaled versions of other (often SI) units. For example, the international yard is defined as:
inline constexpr struct yard : named_unit<"yd", mag<ratio{9'144, 10'000}> * si::metre> {} yard;
and then a foot
can be
defined as:
inline constexpr struct foot : named_unit<"ft", mag<ratio{1, 3}> * yard> {} foot;
For some units, a magnitude might also be irrational. The best
example here is a degree
which
is defined using a floating-point magnitude having a factor of the
number π (Pi):
inline constexpr struct mag_pi : magnitude<std::numbers::pi_v<long double>> {} mag_pi;
inline constexpr struct degree : named_unit<{"°", "deg"}, mag_pi / mag<180> * si::radian> {} degree;
Units are available via their full names or through their short symbols. To use a long version it is enough to type:
= 42 * si::metre; quantity q
The same can be obtained using an optional unit symbol:
using namespace si::unit_symbols;
= 42 * m; quantity q
Unit symbols introduce a lot of short identifiers into the current
namespace, and that is why they are opt-in. A user has to explicitly
“import” them from a dedicated
unit_symbols
namespace.
This chapter describes the features that enforce safety in our code bases. It starts with obvious things, but then it moves to probably less known benefits of using physical quantities and units libraries. This chapter also serves as a proof that it is not easy to implement such a library correctly, and that there are many cases where the lack of experience or time for the development of such a utility may easily lead to safety issues as well.
Before we go through all the features, it is essential to note that they do not introduce any runtime overhead over the raw unsafe code doing the same thing. This is a massive benefit of C++ compared to other programming languages (e.g., Python, Java, etc.).
The first thing that comes to our mind when discussing the safety of
such libraries is automated unit conversions between values of the same
physical quantity. This is probably the most important subject here. We
learned about its huge benefits long ago thanks to the
std::chrono::duration
that made
conversions of time durations error-proof.
Unit conversions are typically performed either via a converting constructor or a dedicated conversion function:
auto q1 = 5 * km;
::cout << q1.in(m) << '\n';
std<si::metre, int> q2 = q1; quantity
Such a feature benefits from the fact that the library knows about the magnitudes of the source and destination units at compile-time, and may use that information to calculate and apply a conversion factor automatically for the user.
In std::chrono::duration
, the
magnitude of a unit is always expressed with
std::ratio
. This is not enough
for a general-purpose physical units library. Some of the derived units
have huge or tiny ratios. The difference from the base units is so huge
that it cannot be expressed with
std::ratio
, which is implemented
in terms of std::intmax_t
. This
makes it impossible to define units like electronvolt (eV), where 1 eV =
1.602176634×10−19 J, or Dalton (Da), where 1 Da =
1.660539040(20)×10−27 kg. Moreover, some conversions, such as
radian to a degree, require a conversion factor based on an irrational
number like pi.
The second safety feature of such libraries is preventing accidental truncation of a quantity value. If we try the operations above with swapped units, both conversions should fail to compile:
auto q1 = 5 * m;
::cout << q1.in(km) << '\n'; // Compile-time error
std<si::kilo<si::metre>, int> q2 = q1; // Compile-time error quantity
We can’t preserve the value of a source quantity when we convert it
to one with a unit of a lower resolution while dealing with an integral
representation type for a quantity. In the example above, converting
5
meters would result in
0
kilometers if internal
conversion is performed using regular integer arithmetic.
While this could be a valid behavior, the problem arises when the
user expects to be able to convert the quantity back to the original
unit without loss of information. So the library should prevent such
conversions from happening implicitly. This is why it offers the named
cast value_cast
for these
conversions marked as unsafe.
To make the above conversions compile, we could use a floating-point representation type:
auto q1 = 5. * m; // source quantity uses `double` as a representation type
::cout << q1.in(km) << '\n';
std<si::kilo<si::metre>> q2 = q1; quantity
or:
auto q1 = 5 * m; // source quantity uses `int` as a representation type
::cout << value_cast<double>(q1).in(km) << '\n';
std<si::kilo<si::metre>> q2 = q1; // `double` by default quantity
Another possibility would be to force such a truncating conversion explicitly from the code:
auto q1 = 5 * m; // source quantity uses `int` as a representation type
::cout << q1.force_in(km) << '\n';
std<si::kilo<si::metre>, int> q2 = value_cast<km>(q1); quantity
The code above makes it clear that “something bad” may happen here if we are not extra careful.
Another case for truncation happens when we assign a quantity with a floating-point representation type to the one using an integral representation type for its value:
auto q1 = 2.5 * m;
<si::metre, int> q2 = q1; // Compile-time error quantity
Such an operation should fail to compile as well. Again, to force such a truncation, we have to be explicit in the code:
auto q1 = 2.5 * m;
<si::metre, int> q2 = value_cast<int>(q1); quantity
As we can see, it is essential not to allow such truncating conversions to happen implicitly, and a good physical quantities and units library should fail at compile-time in case an user makes such a mistake.
The affine space has two types of entities:
One can do a limited set of operations in affine space on points and vectors. This greatly helps to prevent quantity equations that do not have physical sense.
People often think that affine space is needed only to model
temperatures and maybe time points (following the std::chrono::time_point
example). Still, the applicability of this concept is much wider.
For example, if we would like to model a Mount Everest climbing expedition, we would deal with two kinds of altitude-related entities. The first would be absolute altitudes above the mean sea level (points) like base camp altitude, mount peak altitude, etc. The second one would be the heights of daily climbs (vectors). Although it makes physical sense to add heights of daily climbs, there is no sense in adding altitudes. What does adding the altitude of a base camp and the mountain peak mean after all?
Modeling such affine space entities with the
quantity
(vector) and
quantity_point
(point) class
templates improves the overall project’s safety by only providing the
operators defined by the concepts.
The following operations are not allowed in the affine space:
quantity_point
objects
quantity_point
from a
quantity
quantity_point
with a scalar
2 *
DEN airport location?quantity_point
with a quantity
quantity_point
objects
quantity_points
of different
quantity kinds
quantity_points
of inconvertible
quantities
quantity_points
of convertible
quantities but with unrelated origins
The usage of quantity_point
,
and affine space types in general, improves expressiveness and
type-safety of the code we write.
explicit
is not explicit
enoughConsider the following structure and a code using it:
struct X {
::vector<std::chrono::milliseconds> vec;
std// ...
};
X x;.vec.emplace_back(42); x
Everything works fine for years until, at some point, someone changes the structure to:
struct X {
::vector<std::chrono::microseconds> vec;
std// ...
};
The code continues to compile fine, but all the calculations are now off by orders of magnitude. This is why a good quantities and units library should not provide an explicit quantity constructor taking a raw value.
To solve this issue, a quantity always requires information about both a number and a unit during construction:
struct X {
::vector<quantity<si::milli<si::second>>> vec;
std// ...
};
X x;.vec.emplace_back(42); // Compile-time error
x.vec.emplace_back(42 * ms); // OK x
For consistency and to prevent similar safety issues, the
quantity_point
using explicit
point origins can’t be created from a standalone value of a
quantity
(contrary to the
std::chrono::time_point
design).
Such a point has to always be associated with an explicit origin:
= mean_sea_level + 42 * m;
quantity_point qp1 = default_ac_temperature + 2 * deg_C; quantity_point qp2
Continuing our previous example, let’s assume that we have an underlying “legacy” API that requires us to pass a raw numerical value of a quantity and that we do the following to use it:
void legacy_func(std::int64_t seconds);
X x;.vec.emplace_back(42s);
x(x.vec[0].count()); legacy_func
The preceding code is incorrect. Even though the duration stores a
quantity equal to 42 s, it is not stored in seconds (it’s either
microseconds or milliseconds, depending on which of the interfaces from
the previous chapter is the current one). Such issues can be prevented
with the usage of
std::chrono::duration_cast
:
(duration_cast<seconds>(x.vec[0]).count()); legacy_func
However, users often forget about this step, especially when, at the moment of writing such code, the duration stores the underlying raw value in the expected unit. But as we know, the interface can be refactored at any point to use a different unit, and the code using an underlying numerical value without the usage of an explicit cast will become incorrect.
To prevent such safety issues, the library exposes only the interface that returns a quantity numerical value in the required unit to ensure that no data truncation happens:
X x;.vec.emplace_back(42 * s);
x(x.vec[0].numerical_value_in(si::second)); legacy_func
or in case we are fine with data truncation:
X x;.vec.emplace_back(42 * s);
x(x.vec[0].force_numerical_value_in(si::second)); legacy_func
As the above member functions may need to do a conversion to provide a value in the expected unit, their results are prvalues.
Besides returning prvalues, sometimes users need to get an actual
reference to the underlying numerical value stored in a
quantity
. For those cases, the
library exposes quantity::numerical_value_ref_in(Unit)
that participates in overload resolution only:
Unit
has
the same magnitude as the one currently used by the quantity.The first condition above aims to limit the possibility of dangling
references. We want to increase the chances that the reference/pointer
provided to an underlying API remains valid for the time of its usage.
(We’re much less concerned about performance aspects for a
quantity
here, as we expect the
majority (if not all) of representation types to be cheap to copy.)
That said, we acknowledge that this approach to preventing dangling references conflates value category with lifetime. While it may prevent the majority of dangling references, it also admits both false positives and false negatives, as explained in [Value Category Is Not Lifetime]. We want to highlight this dilemma for the committee’s consideration.
In case we do decide to keep this policy of deleting rvalue overloads, here’s an example of code that it would prevent from compiling.
void legacy_func(const int& seconds);
((4 * s + 2 * s).numerical_value_ref_in(si::second)); // Compile-time error legacy_func
The library also goes one step further, by implementing all compound assignments, pre-increment, and pre-decrement operators as non-member functions that preserve the initial value category. Thanks to that, the following will also not compile:
<si::second, int> get_duration(); quantity
((4 * s += 2 * s).numerical_value_ref_in(si::second)); // Compile-time error
legacy_func((++get_duration()).numerical_value_ref_in(si::second)); // Compile-time error legacy_func
The second condition above enables the usage of various equivalent
units. For example, J
is
equivalent to N * m
, and
kg * m2 / s2
. As those have the
same magnitude, it does not matter exactly which one is being used here,
as the same numerical value should be returned for all of them.
void legacy_func(const int& joules);
= 42 * J;
quantity q1 = 42 * N * (2 * m);
quantity q2 = 42 * kJ;
quantity q3 (q1.numerical_value_ref_in(si::joule)); // OK
legacy_func(q2.numerical_value_ref_in(si::joule)); // OK
legacy_func(q3.numerical_value_ref_in(si::joule)); // Compile-time error legacy_func
What should be the result of the following quantity equation?
auto res = 1 * Hz + 1 * Bq + 1 * Bd;
We have checked a few leading libraries on the market, and here are the results:
Now let’s check what [ISO/IEC Guide 99] says about quantity kinds:
[ISO/IEC 80000] also explicitly notes:
Measurement units of quantities of the same quantity dimension may be designated by the same name and symbol even when the quantities are not of the same kind. For example, joule per kelvin and J/K are respectively the name and symbol of both a measurement unit of heat capacity and a measurement unit of entropy, which are generally not considered to be quantities of the same kind. However, in some cases special measurement unit names are restricted to be used with quantities of specific kind only. For example, the measurement unit ‘second to the power minus one’ (1/s) is called hertz (Hz) when used for frequencies and becquerel (Bq) when used for activities of radionuclides. As another example, the joule (J) is used as a unit of energy, but never as a unit of moment of force, i.e. the newton metre (N · m).
To summarize the above, [ISO/IEC 80000] explicitly states that frequency is measured in Hz and activity is measured in Bq, which are quantities of different kinds. As such, they should not be able to be compared, added, or subtracted. So, the only library from the above that was correct was [JSR 385]. The rest of them are wrong to allow such operations. Doing so may lead to vulnerable safety issues when two unrelated quantities of the same dimension are accidentally added or assigned to each other.
The reason for most of the libraries on the market to be wrong in this field is the fact that their quantities are implemented only in terms of the concept of dimension. However, we’ve learned that a dimension is not enough to describe a quantity.
The library goes beyond that and properly models quantity kinds. We believe that it is a significant feature that improves the safety of the library.
Proper modeling of distinct kinds for quantities of the same dimension is often not enough from the safety point of view. Most of the libraries allow us to write the following code in the type-safe way:
<isq::speed[m/s]> avg_speed(quantity<isq::length[m]> l, quantity<isq::time[s]> t)
quantity{
return l / t;
}
However, they fail when we need to model an abstraction using more than one quantity of the same kind:
class Box {
<isq::area[m2]> base_;
quantity<isq::length[m]> height_;
quantitypublic:
(quantity<isq::length[m]> l, quantity<isq::length[m]> w, quantity<isq::length[m]> h)
Box: base_(l * w), height_(h)
{}
// ...
};
This does not provide strongly typed interfaces anymore.
Again, it turns out that [ISO/IEC 80000] has an answer. This specification standardizes hundreds of quantities, many of which are of the same kind. Various quantities of the same kind are not a flat set. They form a hierarchy tree which influences:
More information on this subject can be found in the Systems of quantities chapter.
Some quantity types are defined by [ISO/IEC 80000] as explicitly
non-negative. Those include quantities like width, thickness, diameter,
and radius. However, it turns out that it is possible to have negative
values of quantities defined as non-negative. For example,
-1 * isq::diameter[mm]
could
represent a change in the diameter of some object. Also, a subtraction
4 * width[mm] - 6 * width[mm]
results in a negative value as the width of the second argument is
larger than the first one.
Non-negative quantities are not limited to those explicitly stated as
being non-negative in [ISO/IEC 80000].
Some quantities are implicitly non-negative from their definition. The
most obvious example here might be scalar quantities specified as
magnitudes of a vector quantity. For example, speed is defined as the
magnitude of velocity. Again,
-1 * speed[m/s]
could represent
a change in average speed between two measurements.
This means that enforcing such constraints for quantity types might be impossible as those typically are used to represent a difference between two states or measurements. However, we could apply such constraints to quantity points, which, by definition, describe the absolute quantity values. For example, when height is the measure of an object, a negative value is physically meaningless.
Such logic errors could be detected at runtime with contracts or some other preconditions or invariants checks.
While talking about quantities and units libraries, everyone expects that the library will protect (preferably at compile-time) from accidentally replacing multiplication with division operations or vice versa. Everyone knows and expects that the multiplication of length and time should not result in speed. It does not mean that such a quantity equation is invalid. It just results in a quantity of a different type.
If we expect the above protection for scalar quantities, we should also strive to provide similar guarantees for vector and tensor quantities. First, the multiplication or division of two vectors or tensors is not even mathematically defined. Such operations should be impossible on quantities using vector or tensor representation types.
What multiplication and division are for scalars, the dot and cross products are for vector quantities. The result of the first one is a scalar. The second one results in a vector perpendicular to both vectors passed as arguments. A good quantities and units library should protect the user from making such an error of accidentally replacing those operations.
Vector and tensor quantities can be implemented in two ways:
Encapsulating multiple quantities into a homogeneous vector or tensor representation type
This solution is the most common in the C++ market. It requires the quantities library to provide only basic arithmetic operations (addition, subtraction, multiplication, and division) which are being used to calculate the result of linear algebra math. However, this solution can’t provide any compile-time safety described above, and will also crash when someone passes a proper vector and tensor representation type to a quantity, expecting it to work.
Encapsulating a vector or tensor as a representation type of a quantity
This provides all the required type safety, but requires the library to implement more operations on quantities and properly constrain them so they are selectively enabled when needed. Besides [mp-units], the only library that supports such an approach is [Pint]. Such a solution requires the following operations to be exposed for quantity types (note that character refers to the algebraic structure of either scalar, vector and tensor):
a + b
- addition where both
arguments should be of the same quantity kind and charactera - b
- subtraction where
both arguments should be of the same quantity kind and charactera % b
- modulo where both
arguments should be of the same quantity kind and charactera * b
- multiplication where
one of the arguments has to be a scalara / b
- division where the
divisor has to be scalara ⋅ b
- dot product of two
vectorsa × b
- cross product of two
vectors|a|
- magnitude of a
vectora ⊗ b
- tensor product of
two vectors or tensorsa ⋅ b
- inner product of two
tensorsa ⋅ b
- inner product of
tensor and vectora : b
- scalar product of
two tensorsAdditionally, the library knows the expected quantity character, which is provided (implicitly or explicitly) in the definition of each quantity type. Thanks to that, it prevents the user, for example, from providing a scalar representation type for force or a vector representation for power quantities.
<isq::velocity> q1 = 60 * km / h; // Compile-time error
QuantityOf<isq::velocity> q2 = la_vector{0, 0, -60} * km / h; // OK
QuantityOf<isq::force> q3 = 80 * kg * (10 * m / s2); // Compile-time error
QuantityOf<isq::force> q4 = 80 * kg * (la_vector{0, 0, -10} * m / s2); // OK
QuantityOf<isq::power> q5 = q2 * q4; // Compile-time error
QuantityOf<isq::power> q5 = dot(q2, q4); // OK QuantityOf
Note: q1
and
q3
can be permitted to compile
by explicitly specializing the
is_vector<T>
trait for the
representation type.
As we can see above, such features additionally improves the compile-time safety of the library by ensuring that quantities are created with proper quantity equations and are using correct representation types.
The physical units library can’t do any runtime branching logic for the division operator. All logic has to be done at compile-time when the actual values are not known, and the quantity types can’t change at runtime.
If we expect
120 * km / (2 * h)
to return
60 km / h
, we have to agree with
the fact that 5 * km / (24 * h)
returns 0 km/h
. We can’t do a
range check at runtime to dynamically adjust scales and types based on
the values of provided function arguments.
The same applies to:
static_assert(5 * h / (120 * min) == 0 * one);
This is why floating-point representation types are recommended as a default to store the numerical value of a quantity. Some popular physical units libraries even forbid integer division at all.
The problem is similar to the one described in the section about accidental truncation of values through conversion. While the consequent use of floating-point representation types may be a good idea, it is not always possible. Especially in close-to-the-metal applications and small embedded systems, the use of floating-point types is sometimes not an option, either for performance reasons or lack of hardware support. Having different operators for safe floating-point operations and unsafe integer operations would hurt generic programming. As such, users should instead use safer representation types.
Integers can overflow on arithmetics. This has already caused some expensive failures in engineering [Ariane flight V88].
Integers can also be truncated during assignment to a narrower type.
Floating-point types may lose precision during assignment to a
narrower type. Conversion from
std::int64_t
to
double
may also lose
precision.
If we had safe numeric types in the C++ standard library, they could
easily be used as a quantity
representation type in the physical quantities and units library, which
would address these safety concerns.
Also, having a type trait informing if a conversion from one type to another is value-preserving would help to address some of the issues mentioned above.
One of the most essential requirements for a good physical quantities and units library is to implement units in such a way that they compose. With that, one can easily create any derived unit using a simple unit equation on other base or derived units. For example:
constexpr Unit auto kmph = km / h;
We can also easily obtain a quantity with:
= 60 * km / h; quantity q
Such a solution is an industry standard and is implemented not only in this library, but also is available for many years now in both [Boost.Units] and [Pint].
We believe that is the correct thing to do. However, we want to make it straight in this paper that some potential issues are associated with such a syntax. Inexperienced users are often surprised by the results of the following expression:
= 60 * km / 2 * h; quantity q
This looks like like 30 km/h
,
right? But it is not. Thanks to the order of operations, it results in
30 km⋅h
. In case we want to
divide 60 km
by
2 h
, parentheses are needed:
= 60 * km / (2 * h); quantity q
Another surprising issue may result from the following code:
template<typename T>
auto make_length(T v) { return v * si::metre; }
auto v = 42;
= make_length(v); quantity q
This might look like a good idea, but let’s consider what would happen if the user provided a quantity as input:
auto v = 42 * m;
= make_length(v); quantity q
The above function call will result in a quantity of area instead of the expected quantity of length.
The issues mentioned above could be turned into compilation errors by disallowing multiplying or dividing a quantity by a unit. The [mp-units] library initially provided such an approach, but with time, we decided this to not be user-friendly. Forcing the user to put the parenthesis around all derived units in quantity equations like the one below, was too verbose and confusing:
= 60 * (km / h); quantity q
It is important to notice that the problems mentioned above will always surface with a compile-time error at some point in the user’s code when they assign the resulting quantity to one with an explicitly provided quantity type.
Below, we provide a few examples that correctly detect such issues at compile-time:
<si::kilo<si::metre> / non_si::hour, int> q1 = 60 * km / 2 * h; // Compile-time error
quantity<isq::speed[si::kilo<si::metre> / non_si::hour], int> q2 = 60 * km / 2 * h; // Compile-time error
quantity<isq::speed> auto q3 = 60 * km / 2 * h; // Compile-time error QuantityOf
template<typename T>
auto make_length(T v) { return v * si::metre; }
auto v = 42 * m;
<si::metre, int> q1 = make_length(v); // Compile-time error
quantity<isq::length[si::metre]> q2 = make_length(v); // Compile-time error
quantity<isq::length> q3 = make_length(v); // Compile-time error QuantityOf
template<typename T>
<isq::length> auto make_length(T v) { return v * si::metre; }
QuantityOf
auto v = 42 * m;
= make_length(v); // Compile-time error quantity q
template<Representation T>
auto make_length(T v) { return v * si::metre; }
auto v = 42 * m;
= make_length(v); // Compile-time error quantity q
As stated before, modeling systems of quantities and various quantities of the same kind significantly improves the safety of the project. However, it is essential to mention here that such modeling is not ideal and there might be some pitfalls and surprises associated with some corner cases.
Everyone probably agrees that multiplying two lengths is an area, and that area should be implicitly convertible to the result of such a multiplication:
static_assert(implicitly_convertible(isq::length * isq::length, isq::area));
static_assert(implicitly_convertible(isq::area, isq::length * isq::length));
Also, probably no one would be surprised by the fact that the multiplication of width and height is also convertible to area. Still, the reverse operation is not valid in this case. Not every area is an area over width and height, so we need an explicit cast to force such a conversion:
static_assert(implicitly_convertible(isq::width * isq::height, isq::area));
static_assert(!implicitly_convertible(isq::area, isq::width * isq::height));
static_assert(explicitly_convertible(isq::area, isq::width * isq::height));
However, it might be surprising to some that the similar behavior will also be observed for the product of two heights:
static_assert(implicitly_convertible(isq::height * isq::height, isq::area));
static_assert(!implicitly_convertible(isq::area, isq::height * isq::height));
static_assert(explicitly_convertible(isq::area, isq::height * isq::height));
For humans, it is hard to imagine how two heights form an area, but the library’s logic has no way to prevent such operations.
Some pitfalls might also arise when dealing with quantities of dimension one (also known as dimensionless quantities).
If we divide two quantities of the same kind, we end up with a quantity of dimension one. For example, we can divide two lengths to get a slope of the ramp or two durations to get the clock accuracy. Those ratios mean something fundamentally different, but from the dimensional analysis standpoint, they are mutually comparable.
The above means that the following code is valid:
= 1 * m / (10 * m) + 1 * us / (1 * h);
quantity q1 = isq::length(1 * m) / isq::length(10 * m) + isq::time(1 * us) / isq::time(1 * h);
quantity q2 = isq::height(1 * m) / isq::length(10 * m) + isq::time(1 * us) / isq::time(1 * h); quantity q3
The fact that the above code compiles fine might again be surprising
to some users of such a library. The result of all such quantity
equations is a dimensionless
quantity as it is the root of this hierarchy tree.
Now, let’s try to convert such results to some quantities of
dimension one. The q1
was
obtained from the expression that only used units in the equation, which
means that the actual result of it is a quantity of
kind_of<dimensionless>
,
which behaves like any quantity from the tree. Because of it, all of the
below will compile for q1
:
<si::metre / si::metre> ok1 = q1;
quantity<(isq::length / isq::length)[m / m]> ok2 = q1;
quantity<(isq::height / isq::length)[m / m]> ok3 = q1; quantity
For q2
and
q3
, the two first conversions
also succeed. The first one passes because all quantities of a kind are
convertible to such kind. The type of the second quantity is quantity<dimensionless[one]>
in
disguise. Such a quantity is a root of the kind tree, so again, all the
quantities from such a tree are convertible to it.
The third conversion fails in both cases, though. Not every dimensionless quantity is a result of dividing height and length, so an explicit conversion would be needed to force it to work.
<si::metre / si::metre> ok4 = q2;
quantity<(isq::length / isq::length)[m / m]> ok5 = q2;
quantity<(isq::height / isq::length)[m / m]> bad1 = q2; // Compile-time error
quantity
<si::metre / si::metre> ok6 = q3;
quantity<(isq::length / isq::length)[m / m]> ok7 = q3;
quantity<(isq::height / isq::length)[m / m]> bad2 = q3; // Compile-time error quantity
Temperature support is one the most challenging parts of any physical quantities and units library design. This is why it is probably reasonable to dedicate a chapter to this subject to describe how they are intended to work and what are the potential pitfalls or surprises.
First, let’s run the following code:
= isq::thermodynamic_temperature(30. * K);
quantity q1 = isq::Celsius_temperature(30. * deg_C);
quantity q2
::println("q1: {}, {}, {}", q1, q1.in(deg_C), q1.in(deg_F));
std::println("q2: {}, {}, {}", q2.in(K), q2, q2.in(deg_F)); std
This outputs:
q1: 30 K, 30 °C, 54 °F
q2: 30 K, 30 °C, 54 °F
Also doing the following:
= isq::Celsius_temperature(q1);
quantity q3 = isq::thermodynamic_temperature(q2); quantity q4
outputs:
q3: 30 K
q4: 30 °C
Even though [ISO/IEC 80000] provides dedicated quantity types for thermodynamic temperature and Celsius temperature, it explicitly states in the description of the first one:
Differences of thermodynamic temperatures or changes may be expressed either in kelvin, symbol K, or in degrees Celsius, symbol °C
In the description of the second quantity type, we can read:
The unit degree Celsius is a special name for the kelvin for use in stating values of Celsius temperature. The unit degree Celsius is by definition equal in magnitude to the kelvin. A difference or interval of temperature may be expressed in kelvin or in degrees Celsius.
As the quantity
is a
differential quantity type, it is okay to use any temperature
unit for those, and the results should differ only by the conversion
factor. No offset should be applied here to convert between the origins
of different unit scales.
It is important to mention here that the existence of Celsius temperature quantity type in [ISO/IEC 80000] is controversial.
[ISO/IEC 80000] (part 1) says:
The system of quantities presented in this document is named the International System of Quantities (ISQ), in all languages. This name was not used in ISO 31 series, from which the present harmonized series has evolved. However, the ISQ does appear in ISO/IEC Guide 99 and is the system of quantities underlying the International System of Units, denoted “SI”, in all languages according to the SI Brochure.
According to the [ISO/IEC Guide 99], a system of quantities is a “set of quantities together with a set of non-contradictory equations relating those quantities”. It also defines the system of units as “set of base units and derived units, together with their multiples and submultiples, defined in accordance with given rules, for a given system of quantities”.
To say it explicitly, the system of quantities should not assume or use any specific units in its definitions. It is essential as various systems of units can be defined on top of it, and none of those should be favored.
However, the Celsius temperature quantity type is defined in [ISO/IEC 80000] (part 5) as:
temperature difference from the thermodynamic temperature of the ice point is called the Celsius temperature \(t\), which is defined by the quantity equation:
\(t = T − T_0\)
where \(T\) is thermodynamic temperature (item 5-1) and \(T_0 = 273,15\:K\)
Celsius temperature is an exceptional quantity in the ISQ as it uses specific SI units in its definition. This breaks the direction of dependencies between systems of quantities and units and imposes significant implementation issues.
As [mp-units] implementation clearly distinguishes between systems of quantities and units and assumes that the latter directly depends on the former, this quantity definition does not enforce any units or offsets. It is defined as just a more specialized quantity of the kind of thermodynamic temperature. We have added the Celsius temperature quantity type for completeness and to gain more experience with it. Still, maybe a good decision would be to skip it in the standardization process not to confuse users.
After quoting the official definitions and terms and presenting how quantities work, let’s discuss quantity points. Those describe specific points and are measured relative to a provided origin:
= si::zeroth_kelvin + isq::thermodynamic_temperature(300. * K);
quantity_point qp1 = si::zeroth_degree_Celsius + isq::Celsius_temperature(30. * deg_C); quantity_point qp2
The above provides two different temperature points. The first one is
measured as a relative quantity to the absolute zero
(0 K
), and the second one stores
the value relative to the ice point being the beginning of the degree
Celsius scale.
Thanks to the
default_point_origin
used in the
quantity_point
class template
definition and benefiting from the fact that units of temperature have
point origins provided in their definitions we can obtain exactly the
same quantity points with the following:
{isq::thermodynamic_temperature(300. * K)};
quantity_point qp3{isq::Celsius_temperature(30. * deg_C)}; quantity_point qp4
It is essential to understand that the origins of quantity points will not change if we convert their units:
= qp1.in(deg_C);
quantity_point qp3 = qp2.in(K);
quantity_point qp4
static_assert(std::is_same_v<decltype(qp3.point_origin), decltype(si::absolute_zero)>);
static_assert(std::is_same_v<decltype(qp4.point_origin), decltype(si::ice_point)>);
If we want to obtain the values of quantities in specific units relative to the origins of their scales, we have to be explicit. We can do it in several ways:
Subtracting points to obtain the quantity:
::println("qp1: {}, {}, {}",
std- si::zeroth_kelvin,
qp1 (qp1 - si::zeroth_degree_Celsius).in(deg_C),
(qp1 - usc::zeroth_degree_Fahrenheit).in(deg_F));
::println("qp2: {:{%N:.2f} %U}, {}, {}",
std(qp2 - si::zeroth_kelvin).in(K),
- si::zeroth_degree_Celsius,
qp2 (qp2 - usc::zeroth_degree_Fahrenheit).in(deg_F));
Using
quantity_from(PonitOrigin)
member function:
::println("qp1: {}, {}, {}",
std.quantity_from(si::zeroth_kelvin),
qp1.quantity_from(si::zeroth_degree_Celsius).in(deg_C),
qp1.quantity_from(usc::zeroth_degree_Fahrenheit).in(deg_F));
qp1::println("qp2: {:{%N:.2f} %U}, {}, {}",
std.quantity_from(si::zeroth_kelvin).in(K),
qp2.quantity_from(si::zeroth_degree_Celsius),
qp2.quantity_from(usc::zeroth_degree_Fahrenheit).in(deg_F)); qp2
Using
quantity_from_zero()
member
function that will use the point origin defined for the current
unit:
::println("qp1: {}, {}, {}",
fmt.quantity_from_zero(),
qp1.in(deg_C).quantity_from_zero(),
qp1.in(deg_F).quantity_from_zero());
qp1::println("qp2: {:{%N:.2f} %U}, {}, {}",
fmt.in(K).quantity_from_zero(),
qp2.quantity_from_zero(),
qp2.in(deg_F).quantity_from_zero()); qp2
All of the cases above will provide the same output:
qp1: 300 K, 26.85 °C, 80.33 °F
qp2: 303.15 K, 30 °C, 86 °F
Of course, all other combinations are also possible. For example,
nothing should prevent us from checking how many degrees of Celsius are
there starting from the
zeroth_degree_Fahrenheit
for a
quantity point using kelvins with the
zeroth_kelvin
origin:
= qp1.quantity_from(usc::zeroth_degree_Fahrenheit).in(deg_C); quantity q
The quantity
and
quantity_point
class templates
are structural types to allow them to be passed as template arguments.
For example, we can write the following:
constexpr struct amsterdam_sea_level : absolute_point_origin<isq::altitude> {
} amsterdam_sea_level;
constexpr struct mediterranean_sea_level : relative_point_origin<amsterdam_sea_level + isq::altitude(-27 * cm)> {
} mediterranean_sea_level;
using altitude_DE = quantity_point<isq::altitude[m], amsterdam_sea_level>;
using altitude_CH = quantity_point<isq::altitude[m], mediterranean_sea_level>;
Unfortunately, current language rules require that all member data of a structural type are public. This could be considered a safety issue. We try really hard to provide unit-safe interfaces, but at the same time expose the public “naked” data member that can be freely read or manipulated by anyone.
Hopefully, this requirement on structural types will be relaxed before the library gets standardized.
A quantity value contains a numerical value and a unit. Both of them may have various text representations. Not only numbers but also units can be formatted in many different ways. Additionally, every dimension can be represented as a text as well.
This chapter will discuss the different options we have here.
Note: For now, there is no standardized way to handle formatted text input in the C++ standard library, so this paper does not propose any approach to convert text to quantities. If [P1729R3] will be accepted by the LEWG, then we will add a proper “Text input” chapter as well.
The definitions of dimensions, units, prefixes, and constants require unique text symbols to be assigned for each entity. Those symbols can be composed to express dimensions and units of base and derived quantities.
Note: The below code examples are based on the latest version of the [mp-units] library and might not be the final version proposed for standardization.
Dimensions:
inline constexpr struct dim_length : base_dimension<"L"> {} dim_length;
inline constexpr struct dim_mass : base_dimension<"M"> {} dim_mass;
inline constexpr struct dim_time : base_dimension<"T"> {} dim_time;
inline constexpr struct dim_electric_current : base_dimension<"I"> {} dim_electric_current;
inline constexpr struct dim_thermodynamic_temperature : base_dimension<{"Θ", "O"}> {} dim_thermodynamic_temperature;
inline constexpr struct dim_amount_of_substance : base_dimension<"N"> {} dim_amount_of_substance;
inline constexpr struct dim_luminous_intensity : base_dimension<"J"> {} dim_luminous_intensity;
Units:
inline constexpr struct second : named_unit<"s", kind_of<isq::time>> {} second;
inline constexpr struct metre : named_unit<"m", kind_of<isq::length>> {} metre;
inline constexpr struct gram : named_unit<"g", kind_of<isq::mass>> {} gram;
inline constexpr struct kilogram : decltype(kilo<gram>) {} kilogram;
inline constexpr struct newton : named_unit<"N", kilogram * metre / square(second)> {} newton;
inline constexpr struct joule : named_unit<"J", newton * metre> {} joule;
inline constexpr struct watt : named_unit<"W", joule / second> {} watt;
inline constexpr struct coulomb : named_unit<"C", ampere * second> {} coulomb;
inline constexpr struct volt : named_unit<"V", watt / ampere> {} volt;
inline constexpr struct farad : named_unit<"F", coulomb / volt> {} farad;
inline constexpr struct ohm : named_unit<{"Ω", "ohm"}, volt / ampere> {} ohm;
Prefixes:
template<PrefixableUnit auto U> struct micro_ : prefixed_unit<{"µ", "u"}, mag_power<10, -6>, U> {};
template<PrefixableUnit auto U> struct milli_ : prefixed_unit<"m", mag_power<10, -3>, U> {};
template<PrefixableUnit auto U> struct centi_ : prefixed_unit<"c", mag_power<10, -2>, U> {};
template<PrefixableUnit auto U> struct deci_ : prefixed_unit<"d", mag_power<10, -1>, U> {};
template<PrefixableUnit auto U> struct deca_ : prefixed_unit<"da", mag_power<10, 1>, U> {};
template<PrefixableUnit auto U> struct hecto_ : prefixed_unit<"h", mag_power<10, 2>, U> {};
template<PrefixableUnit auto U> struct kilo_ : prefixed_unit<"k", mag_power<10, 3>, U> {};
template<PrefixableUnit auto U> struct mega_ : prefixed_unit<"M", mag_power<10, 6>, U> {};
Constants:
inline constexpr struct hyperfine_structure_transition_frequency_of_cs :
<{"Δν_Cs", "dv_Cs"}, mag<9'192'631'770> * hertz> {} hyperfine_structure_transition_frequency_of_cs;
named_unitinline constexpr struct speed_of_light_in_vacuum :
<"c", mag<299'792'458> * metre / second> {} speed_of_light_in_vacuum;
named_unitinline constexpr struct planck_constant :
<"h", mag<ratio{662'607'015, 100'000'000}> * mag_power<10, -34> * joule * second> {} planck_constant;
named_unitinline constexpr struct elementary_charge :
<"e", mag<ratio{1'602'176'634, 1'000'000'000}> * mag_power<10, -19> * coulomb> {} elementary_charge;
named_unitinline constexpr struct boltzmann_constant :
<"k", mag<ratio{1'380'649, 1'000'000}> * mag_power<10, -23> * joule / kelvin> {} boltzmann_constant;
named_unitinline constexpr struct avogadro_constant :
<"N_A", mag<ratio{602'214'076, 100'000'000}> * mag_power<10, 23> / mole> {} avogadro_constant;
named_unitinline constexpr struct luminous_efficacy :
<"K_cd", mag<683> * lumen / watt> {} luminous_efficacy; named_unit
Unicode provides only a minimal set of characters available as subscripts, which are often used to differentiate various constants and quantities of the same kind. To workaround this issue, [mp-units] uses ’_’ character to specify that the following characters should be considered a subscript of the symbol.
Although the ISQ defined in [ISO/IEC 80000] provides symbols for each quantity type, there is little use for them in the C++ code. In the [mp-units] project, we never had a request to provide such symbol definitions. Even though having them for completeness could be nice, they seem to not be required by the domain experts for their daily jobs. Also, it is worth noting that providing those raises some additional standardization and implementation challenges.
If we decide to provide symbols, the rest of this chapter provides the domain information to assess the complexity and potential issues with standardization and implementation of those.
All ISQ quantities have an official symbol assigned in their definitions, and how those should be printed is exactly specified. [ISO/IEC 80000] explicitly states:
The quantity symbols shall be written in italic (sloping) type, irrespective of the type used in the rest of the text.
Additionally, [ISO/IEC 80000] provides additional requirements for printing quantities of vector and tensor characters:
Note: In the above examples, the second symbol with arrows above should also use letters written in italics. The author could not find a way to format it properly in this document.
There are also a few requirements for printing subscripts of quantity types. [ISO/IEC 80000] states:
The following principles for the printing of subscripts apply:
- A subscript that represents a physical quantity or a mathematical variable, such as a running number, is printed in italic (sloping) type.
- Other subscripts, such as those representing words or fixed numbers, are printed in roman (upright) type.
It is worth noting that only a limited set of Unicode characters are available as subscripts. Those are often used to differentiate various quantities of the same kind.
For example, it is impossible to encode the symbols of the following quantities:
It is important to state that the same issues are related to constant definitions. For them, in the Symbol definition examples chapter, we proposed to use the ’_’ character instead, as stated in Lack of Unicode subscript characters. We could use the same practice here.
Another challenge here might be related to the fact that [ISO/IEC 80000] often provides more than one symbol for the same quantity. For example:
Last but not least, it is worth noting that symbols of ISQ base quantities are not necessary the same as official dimension symbols of those quantities:
Quantity type
|
Quantity type symbol
|
Dimension symbol
|
---|---|---|
length | l, L | L |
mass | m | M |
time | t | T |
electric current | I, i | I |
thermodynamic temperature | T, Θ | Θ |
amount of substance | n(X) | N |
luminous intensity | Iv, (I) | J |
Founding a way to define, use, and print named quantity types is not enough. What should also be covered here is the text output of derived quantities. There are plenty of operations that one might do on scalar, vector, and tensor quantities, and all of them result in another quantity type, which should also be able to be printed in the console text output.
Taking all the challenges and issues mentioned above, we do not propose providing quantity type symbols in their definitions and any text input/output support for those.
fixed_string
As shown above, symbols are provided as class NTTPs in the library. This means that the string type used for such a purpose has to satisfy the structural type requirements of the C++ language. One of such requirements is to expose all the data members publicly. So far, none of the existing string types in the C++ standard library satisfies such requirements. This is why we need to introduce a new type.
Such type should:
Such a type does not need to expose a string-like interface. In case
its interface is immutable, we can easily wrap it with
std::string_view
to get such an
interface for free.
This type is being proposed separately in [P3094].
symbol_text
Many symbols of units, prefixes, and constants require using a Unicode character set. For example:
The library should provide such Unicode output by default to be consistent with official systems’ specifications.
On the other hand, plenty of terminals do not support Unicode characters. Also, general engineering experience shows that people often prefer to work with a basic literal character set. This is why all such entities should provide an alternative spelling in their definitions.
This is where symbol_text
comes into play. It is a simple wrapper over the two
fixed_string
objects:
template<typename UnicodeCharT, std::size_t N, std::size_t M>
struct basic_symbol_text {
<UnicodeCharT, N> unicode_; // exposition only
basic_fixed_string<char, M> ascii_; // exposition only
basic_fixed_string
constexpr explicit(false) basic_symbol_text(char txt);
constexpr explicit(false) basic_symbol_text(const char (&txt)[N + 1]);
constexpr explicit(false) basic_symbol_text(const basic_fixed_string<char, N>& txt);
constexpr basic_symbol_text(const UnicodeCharT (&u)[N + 1], const char (&a)[M + 1]);
constexpr basic_symbol_text(const basic_fixed_string<UnicodeCharT, N>& u, const basic_fixed_string<char, M>& a);
[[nodiscard]] constexpr const auto& unicode() const;
[[nodiscard]] constexpr const auto& ascii() const;
[[nodiscard]] constexpr bool empty() const;
template<std::size_t N2, std::size_t M2>
[[nodiscard]] constexpr friend basic_symbol_text<UnicodeCharT, N + N2, M + M2> operator+(
const basic_symbol_text& lhs, const basic_symbol_text<UnicodeCharT, N2, M2>& rhs);
template<typename UnicodeCharT2, std::size_t N2, std::size_t M2>
[[nodiscard]] friend constexpr auto operator<=>(const basic_symbol_text& lhs,
const basic_symbol_text<UnicodeCharT2, N2, M2>& rhs) noexcept;
template<typename UnicodeCharT2, std::size_t N2, std::size_t M2>
[[nodiscard]] friend constexpr bool operator==(const basic_symbol_text& lhs,
const basic_symbol_text<UnicodeCharT2, N2, M2>& rhs) noexcept;
};
(char) -> basic_symbol_text<char, 1, 1>;
basic_symbol_text
template<std::size_t N>
(const char (&)[N]) -> basic_symbol_text<char, N - 1, N - 1>;
basic_symbol_text
template<std::size_t N>
(const basic_fixed_string<char, N>&) -> basic_symbol_text<char, N, N>;
basic_symbol_text
template<typename UnicodeCharT, std::size_t N, std::size_t M>
(const UnicodeCharT (&)[N], const char (&)[M]) -> basic_symbol_text<UnicodeCharT, N - 1, M - 1>;
basic_symbol_text
template<typename UnicodeCharT, std::size_t N, std::size_t M>
(const basic_fixed_string<UnicodeCharT, N>&, const basic_fixed_string<char, M>&)
basic_symbol_text-> basic_symbol_text<UnicodeCharT, N, M>;
Note: There is literally no way in the current version of the C++
language to output Unicode character types
(char8_t
,
char16_t
, and
char32_t
) to the console, the
[mp-units] library currently uses
char
to encode both
strings.
TBD
Based on the provided definitions for base units, the library creates symbols for derived ones.
unit_symbol_formatting
unit_symbol_formatting
is a
data type describing the configuration of the symbol generation
algorithm. It contains three orthogonal fields, and each of them has a
default value.
enum class text_encoding : std::int8_t {
// m³; µs
unicode, // m^3; us
ascii, = unicode
default_encoding };
enum class unit_symbol_solidus : std::int8_t {
// m/s; kg m⁻¹ s⁻¹
one_denominator, // m/s; kg/(m s)
always, // m s⁻¹; kg m⁻¹ s⁻¹
never, = one_denominator
default_denominator };
enum class unit_symbol_separator : std::int8_t {
// kg m²/s²
space, // kg⋅m²/s² (valid only for Unicode encoding)
half_high_dot, = space
default_separator };
struct unit_symbol_formatting {
= text_encoding::default_encoding;
text_encoding encoding = unit_symbol_solidus::default_denominator;
unit_symbol_solidus solidus = unit_symbol_separator::default_separator;
unit_symbol_separator separator };
unit_symbol()
Returns a fixed_string
storing the symbol of the unit for the provided configuration:
template<unit_symbol_formatting fmt = unit_symbol_formatting{}, typename CharT = char, Unit U>
[[nodiscard]] consteval auto unit_symbol(U);
Note 1: This function could return a
std::string_view
pointing to the
internal static buffer.
Note 2: It could be refactored to
unit_symbol(U, fmt)
when [P1045R1] is available.
For example:
static_assert(unit_symbol<{.solidus = unit_symbol_solidus::never,
.separator = unit_symbol_separator::half_high_dot}>(kg * m / s2) == "kg⋅m⋅s⁻²");
unit_symbol_to()
Inserts the generated unit symbol to the output text iterator at runtime based on the provided configuration.
template<typename CharT = char, std::output_iterator<CharT> Out, Unit U>
constexpr Out unit_symbol_to(Out out, U u, unit_symbol_formatting fmt = unit_symbol_formatting{});
For example:
::string txt;
std(std::back_inserter(txt), kg * m / s2,
unit_symbol_to{.solidus = unit_symbol_solidus::never, .separator = unit_symbol_separator::half_high_dot});
::cout << txt << "\n"; std
The above prints:
kg⋅m⋅s⁻²
space_before_unit_symbol
customization pointThe [SI] says:
The numerical value always precedes the unit and a space is always used to separate the unit from the number. … The only exceptions to this rule are for the unit symbols for degree, minute and second for plane angle,
°
,′
and″
, respectively, for which no space is left between the numerical value and the unit symbol.
There are more units with such properties. For example, percent
(%
) and per
mille(‰
).
To support the above, the library exposes
space_before_unit_symbol
customization point. By default, its value is
true
for all the units. This
means that a number and a unit will be separated by the space in the
output text. To change this behavior, a user should provide a partial
specialization for a specific unit:
template<>
inline constexpr bool space_before_unit_symbol<non_si::degree> = false;
The above works only for the default formatting or for the format
strings that use %?
placement
type
(std::format("{}", q)
is equivalent to std::format("{:%N%?%U}", q)
).
In case a user provides custom format specification (e.g., std::format("{:%N %U}", q)
),
the library will always obey this specification for all the units (no
matter what the actual value of the
space_before_unit_symbol
customization point is) and the separating space will always be used in
this case.
The easiest way to print a dimension, unit, or quantity is to provide its object to the output stream:
const quantity v1 = avg_speed(220. * km, 2 * h);
const quantity v2 = avg_speed(140. * mi, 2 * h);
::cout << v1 << '\n'; // 110 km/h
std::cout << v2 << '\n'; // 70 mi/h std
The text output will always print the value using the default formatting for this entity.
Only basic formatting can be applied for output streams. It includes control over width, fill, and alignment.
The numerical value of the quantity will be printed according to the current stream state and standard manipulators may be used to customize that (assuming that the underlying representation type respects them).
::cout << "|" << std::setw(10) << 123 * m << "|\n"; // | 123 m|
std::cout << "|" << std::setw(10) << std::left << 123 * m << "|\n"; // |123 m |
std::cout << "|" << std::setw(10) << std::setfill('*') << 123 * m << "|\n"; // |123 m*****| std
Detailed formatting of any entity may be obtained with
std::format()
usage and then
provided to the stream output if needed.
Note: Custom stream manipulators may be provided to control a dimension and unit symbol output if requested by WG21.
The library provides custom formatters for
std::format
facility, which
allows fine-grained control over what and how it is being printed in the
text output.
Formatting grammar for all the entities provides control over width,
fill, and alignment. The C++ standard grammar tokens
fill-and-align
and
width
are being used. They treat
the entity as a contiguous text to be aligned. For example, here are a
few examples of the quantity numerical value and symbol formatting:
::println("|{:0}|", 123 * m); // |123 m|
std::println("|{:10}|", 123 * m); // | 123 m|
std::println("|{:<10}|", 123 * m); // |123 m |
std::println("|{:>10}|", 123 * m); // | 123 m|
std::println("|{:^10}|", 123 * m); // | 123 m |
std::println("|{:*<10}|", 123 * m); // |123 m*****|
std::println("|{:*>10}|", 123 * m); // |*****123 m|
std::println("|{:*^10}|", 123 * m); // |**123 m***| std
It is important to note that in the second line above, the quantity text is aligned to the right by default, which is consistent with the formatting of numeric types. Units and dimensions behave as text and, thus, are aligned to the left by default.
dimension-format-spec ::= [fill-and-align] [width] [dimension-spec]
dimension-spec ::= [text-encoding]
text-encoding ::= 'U' | 'A'
In the above grammar:
fill-and-align
and
width
tokens are defined in the
format.string.std
chapter of the C++ standard specification,text-encoding
token
specifies the symbol text encoding:
U
(default) uses the
Unicode symbols defined by [ISO/IEC 80000] (e.g.,
LT⁻²
),A
forces non-standard
ASCII-only output (e.g.,
LT^-2
).unit-format-spec ::= [fill-and-align] [width] [unit-spec]
unit-spec ::= [text-encoding] [unit-symbol-solidus] [unit-symbol-separator] [L]
[text-encoding] [unit-symbol-separator] [unit-symbol-solidus] [L]
[unit-symbol-solidus] [text-encoding] [unit-symbol-separator] [L]
[unit-symbol-solidus] [unit-symbol-separator] [text-encoding] [L]
[unit-symbol-separator] [text-encoding] [unit-symbol-solidus] [L]
[unit-symbol-separator] [unit-symbol-solidus] [text-encoding] [L]
unit-symbol-solidus ::= '1' | 'a' | 'n'
unit-symbol-separator ::= 's' | 'd'
In the above grammar:
fill-and-align
and
width
tokens are defined in the
format.string.std
chapter of the C++ standard specification,unit-symbol-solidus
token
specifies how the division of units should look like:
/
only
when there is only one unit in the denominator,
otherwise negative exponents are printed (e.g.,
m/s
,
kg m⁻¹ s⁻¹
)m/s
,
kg/(m s)
)m s⁻¹
,
kg m⁻¹ s⁻¹
)unit-symbol-separator
token
specifies how multiplied unit symbols should be separated:
kg m²/s²
)⋅
) as a separator (e.g.,
kg⋅m²/s²
) (requires the Unicode
encoding)Note: The intent of the above grammar was that the elements of
unit-spec
can appear in any
order as they have unique characters. Users shouldn’t have to remember
the order of those tokens to control the formatting of a unit
symbol.
Unit symbols of some quantities are specified to use Unicode signs by
the [SI] (e.g.,
Ω
symbol for the
resistance quantity). The library follows this by default. From
the engineering point of view, sometimes Unicode text might not be the
best solution as terminals of many (especially embedded) devices can
output only letters from the basic literal character set only. In such a
case, the unit symbol can be forced to be printed using such characters
thanks to text-encoding
token:
::println("{}", si::ohm); // Ω
std::println("{:A}", si::ohm); // ohm
std::println("{}", us); // µs
std::println("{:A}", us); // us
std::println("{}", m / s2); // m/s²
std::println("{:A}", m / s2); // m/s^2 std
Additionally, both [ISO/IEC 80000] and [SI] leave some freedom on how to print unit symbols. This is why two additional tokens were introduced.
unit-symbol-solidus
specifies
how the division of units should look like. By default,
/
will be used only when the
denominator contains only one unit. However, with the ‘a’ or ‘n’
options, we can force the facility to print the
/
character always (even when
there are more units in the denominator), or never, in which case a
parenthesis will be added to enclose all denominator units.
::println("{}", m / s); // m/s
std::println("{}", kg / m / s2); // kg m⁻¹ s⁻²
std::println("{:a}", m / s); // m/s
std::println("{:a}", kg / m / s2); // kg/(m s²)
std::println("{:n}", m / s); // m s⁻¹
std::println("{:n}", kg / m / s2); // kg m⁻¹ s⁻² std
Also, there are a few options to separate the units being multiplied. [ISO/IEC 80000] (part 1) says:
When symbols for quantities are combined in a product of two or more quantities, this combination is indicated in one of the following ways:
ab
,a b
,a · b
,a × b
NOTE 1 In some fields, e.g., vector algebra, distinction is made between
a ∙ b
anda × b
.
The library supports a b
and
a · b
only. Additionally, we
decided that the extraneous space in the latter case makes the result
too verbose, so we decided just to use the
·
symbol as a separator.
The unit-symbol-separator
token allows us to obtain the following outputs:
::println("{}", kg * m2 / s2); // kg m²/s²
std::println("{:d}", kg * m2 / s2); // kg⋅m²/s² std
Note: ‘d’ requires the Unicode encoding to be set.
quantity-format-spec ::= [fill-and-align] [width] [quantity-specs]
quantity-specs ::= conversion-spec
quantity-specs conversion-spec
quantity-specs literal-char
literal-char ::= <any character other than '{', '}', or '%'>
conversion-spec ::= placement-spec
subentity-replacement-field
placement-spec ::= '%' placement-type
placement-type ::= 'N' | 'U' | 'D' | '?' | '%'
subentity-replacement-field ::= '{' '%' subentity-id [format-specifier] '}'
subentity-id ::= literal-char
subentity-id literal-char
format-specifier ::= ':' format-spec
format-spec ::= <as specified by the formatter for the argument type; cannot start with '}'>
In the above grammar:
fill-and-align
and
width
tokens are defined in the
format.string.std
chapter of the C++ standard specification,placement-type
token
specifies which entity should be put and where:
space_before_unit_symbol
for
this unit,subentity-replacement-field
token allows the composition of formatters. The following identifiers
are recognized by the quantity formatter:
format-spec
to
the formatter
specialization for
the quantity representation type,format-spec
to
the formatter
specialization for
the unit type,format-spec
to
the formatter
specialization for
the dimension type.To format quantity
values,
the formatting facility uses
quantity-format-spec
. If left
empty, the default formatting is applied. The same default formatting is
also applied to the output streams. This is why the following code lines
produce the same output:
::cout << "Distance: " << 123 * km << "\n";
std::cout << std::format("Distance: {}\n", 123 * km);
std::cout << std::format("Distance: {:%N%?%U}\n", 123 * km);
std::cout << std::format("Distance: {:{%N}%?{%U}}\n", 123 * km); std
Please note that for some quantities the
{:%N %U}
format may provide a
different output than the default one, as some units have
space_before_unit_symbol
customization point explicitly set to
false
(e.g.,
%
and
°
).
Thanks to the grammar provided above, the user can easily decide to either:
print a whole quantity:
::println("Speed: {}", 120 * km / h); std
Speed: 120 km/h
print only specific components (numerical value, unit, or dimension):
::println("Speed:\n- number: {0:%N}\n- unit: {0:%U}\n- dimension: {0:%D}", 120 * km / h); std
Speed:
- number: 120
- unit: km/h
- dimension: LT⁻¹
provide custom quantity formatting
::println("Speed: {:%N in %U}", 120 * km / h); std
Speed: 120 in km/h
provide custom formatting for components:
::println("Speed: {:{%N:.2f} {%U:n}}", 100. * km / (3 * h)); std
Speed: 33.33 km h⁻¹
placement-spec
and
subentity-replacement-field
greatly simplify element access and formatting of the quantity. Without
them the second caese above would require the following:
const auto q = 120 * km / h;
::println("Speed:\n- number: {}\n- unit: {}\n- dimension: {}",
std.numerical_value_ref_in(q.unit), q.unit, q.dimension); q
Providing such support also simplifies the specification and implementation effort of this library. Initially, [mp-units] library was providing numerical value modifiers inplace of its format specification, but it:
Note 1: The above grammar allows repeating the same field many
times, possibly with a different format spec. For example, std::println("Speed: {:%N {%N:.4f} {%N:.2f} {%U:n}}", 100. * km / (3 * h))
.
The library does not provide a text output for quantity points, as printing just a number and a unit is not enough to adequately describe a quantity point. Often, an additional postfix is required.
For example, the text output of
42 m
may mean many things and
can also be confused with an output of a regular quantity. On the other
hand, printing 42 m AMSL
for
altitudes above mean sea level is a much better solution, but the
library does not have enough information to print it that way by
itself.
basic_symbol_text
be used in a
single-argument constructor?.ascii()
)? The same name should
consistently be used in
text_encoding
and in the
formatting grammar.unit_symbol()
return
std::string_view
or
basic_fixed_string
?std::chrono::duration
uses
‘Q’ and ‘q’ for a number and a unit. In the grammar above, we proposed
using ‘N’ and ‘U’ for them, respectively. We also introduced ‘D’ for
dimensions. Are we OK with this?Note: This chapter provides more design details and rationale for them. It tries to not repeat information already provided in the previous chapters so a reader is expected to be familar with them already.
The [mp-units] library decided to use a rather unusual pattern to define entities, but it proved really successful, and we got great feedback from users so far.
Here is how we define metre and second [SI] base units:
inline constexpr struct metre : named_unit<"m", kind_of<isq::length>> {} metre;
inline constexpr struct second : named_unit<"s", kind_of<isq::time>> {} second;
Please note that the above reuses the same identifier for a type and its value. The rationale behind this is that:
To improve compiler errors’ readability and make it easier to correlate them with a user’s written code, a new idiom in the library is to use the same identifier for a type and its instance.
Let’s look again at the above units definitions. Another essential point to notice is that all the types describing entities in the library are short, nicely named identifiers that derive from longer, more verbose class template instantiations. This is really important to improve the user experience while debugging the program or analyzing the compilation error.
Note: Such a practice is rare in the industry. Some popular C++ physical units libraries generate enormously long error messages.
Many physical units libraries (in C++ or any other programming
language) assign strong types to library entities (e.g., derived units).
While metre_per_second
as a type
may not look too scary, consider, for example, units of angular
momentum. If we followed this path, its coherent unit would look like
kilogram_metre_sq_per_second
.
Now, consider how many scaled versions of this unit you would predefine
in the library to ensure that all users are happy with your choice? How
expensive would it be from the implementation point of view? How
expensive would it be to standardize?
This is why, in this library, we put a strong requirement to make everything as composable as possible. For example, to create a quantity with a unit of speed, one may write:
<si::metre / si::second> q; quantity
In case we use such a unit often and would prefer to have a handy helper for it, we can always do something like this:
constexpr auto metre_per_second = si::metre / si::second;
<metre_per_second> q; quantity
or choose any shorter identifier of our choice.
Coming back to the angular momentum case, thanks to the composability of units, a user can create such a quantity in the following way:
using namespace mp_units::si::unit_symbols;
auto q = la_vector{1, 2, 3} * isq::angular_momentum[kg * m2 / s];
It is a much better solution. It is terse and easy to understand.
Please also notice how easy it is to obtain any scaled version of such a
unit (e.g.,
mg * square(mm) / min
) without
having to introduce hundreds of types to predefine them.
This library is based on C++20, significantly improving user experience. One such improvement is the usage of value-based equations.
As we have learned above, the entities are being used as values in
the code, and they compose. Moreover, derived entities can be defined in
the library using such value-based equations. This is a considerable
improvement compared to what we can find in other physical units
libraries or what we have to deal with when we want to write some
equations for std::ratio
.
For example, below are a few definitions of the [SI] derived units showing the power of C++20 extensions to Non-Type Template Parameters, which allow us to directly pass a result of the value-based unit equation to a class template definition:
inline constexpr struct newton : named_unit<"N", kilogram * metre / square(second)> {} newton;
inline constexpr struct pascal : named_unit<"Pa", newton / square(metre)> {} pascal;
inline constexpr struct joule : named_unit<"J", newton * metre> {} joule;
The below graph presents the most important entities of the library’s framework and how they relate to each other.
Some of the entities were already introduced in the Quick domain introduction chapter. Below we describe the remaining ones.
[ISO/IEC 80000] explicitly states that quantities (even of the same kind) may have different characters:
The quantity character in the library is implemented with the
quantity_character
enumeration:
enum class quantity_character { scalar, vector, tensor };
More information on quantity characters can be found in the [Character of a quantity] chapter.
Dimension is not enough to describe a quantity. This is why [ISO/IEC 80000] provides hundreds of named quantity types. It turns out that there are many more quantity types in the ISQ than the named units in the [SI].
This is why the library introduces a quantity specification entity that stores:
For example:
isq::length
,
isq::mass
,
isq::time
,
isq::electric_current
,
isq::thermodynamic_temperature
,
isq::amount_of_substance
, and
isq::luminous_intensity
are the
specifications of base quantities in the ISQ.isq::width
,
isq::height
,
isq::radius
, and
isq::position_vector
are only a
few of many quantities of a kind length specified in the ISQ.isq::area
,
isq::speed
,
isq::moment_of_force
are only a
few of many derived quantities provided in the ISQ.A unit is a concrete amount of a quantity that allows us to measure the values of quantities of the same kind and represent the result as a number being the ratio of the two quantities.
For example:
si::second
,
si::metre
,
si::kilogram
,
si::ampere
,
si::kelvin
,
si::mole
, and
si::candela
are the base units
of the [SI].si::kilo<si::metre>
is
a prefixed unit of length.si::radian
,
si::newton
, and
si::watt
are examples of named
derived units within the [SI].non_si::minute
is an example
of a scaled unit of time.si::si2019::speed_of_light_in_vacuum
is a physical constant standardized by the SI in 2019.Note: In this library, physical constants are also implemented as units.
Quantity representation defines the type used to store the numerical value of a quantity. Such a type should be of a specific quantity character provided in the quantity specification.
Note: By default, all floating-point and integral (besides
bool
) types are treated as
scalars.
In the affine space theory, the point origin specifies where the “zero” of our measurement’s scale is.
In this library, we have two types of point origins:
Note: More information on this subject can be found in The affine space chapter.
Quantity point implements a point in the affine space theory. Its value can be easily created by adding/subtracting the quantity with a point origin.
Note: More information on this subject can be found in The affine space chapter.
This chapter enumerates all the user-facing concepts in the library.
Note 1: We understand that at this stage of the paper, without a detailed synopsis, it might be too early to review exact definitions of concepts. We list them here so the reader can familiarize with the count and granularity of them, so to have a better idea about the scope and look and feel of the library.
Note 2: Initially, C++20 was meant to use
CamelCase
for all the concept
identifiers. Frustratingly,
CamelCase
concepts got dropped
from the C++ standard at the last moment before releasing C++20. Now, we
are facing the predictable consequences of running out of names. As long
as some concepts in the library could be easily named with a
standard_case
there are some
that are hard to distinguish from the corresponding type names, such as
Quantity
,
QuantityPoint
,
QuantitySpec
, or
Reference
. This is why we
decided to use CamelCase
consistently for all the concept identifiers to make it clear when we
are talking about a type or concept identifier. However, we are aware
that this might be a temporary solution. In case the library gets
standardized, we can expect the LEWG to bikeshed/rename all of the
concept identifiers to a
standard_case
, even if it will
result in a harder to understand code.
Dimension<T> concept
Dimension
concept matches a
dimension of either a base or derived quantity:
base_dimension
class template.
It should be instantiated with a unique symbol identifier describing
this dimension in a specific system of quantities.DimensionOf<T, V>
conceptDimensionOf
concept is
satisfied when both arguments satisfy a Dimension
concept and when they compare equal.
QuantitySpec<T> concept
QuantitySpec
concept matches
all the quantity specifications including:
quantity_spec
class template
instantiated with a base dimension argument.quantity_spec
class template
instantiated with a result of a quantity equation passed as an
argument.quantity_spec
class template
instantiated with another “parent” quantity specification passed as an
argument.QuantitySpecOf<T, V>
conceptQuantitySpecOf
concept is
satisfied when both arguments satisfy a QuantitySpec
concept and when T
is implicitly
convertible to V
.
Additionally:
T
should not be a nested
quantity specification of V
T
is quantity kind or
V
should not be a nested
quantity specification of T
Those additional conditions are required to make the following work:
static_assert(ReferenceOf<si::radian, isq::angular_measure>);
static_assert(!ReferenceOf<si::radian, dimensionless>);
static_assert(!ReferenceOf<isq::angular_measure[si::radian], dimensionless>);
static_assert(ReferenceOf<one, isq::angular_measure>);
static_assert(!ReferenceOf<dimensionless[one], isq::angular_measure>);
Unit<T>
conceptUnit
concept matches all the
units in the library including:
named_unit
class template
instantiated with a unique symbol identifier describing this unit in a
specific system of units.named_unit
class template
instantiated with a unique symbol identifier and a product of
multiplying another unit with some magnitude.prefixed_unit
class template
instantiated with a prefix symbol, a magnitude, and a unit to be
prefixed.named_unit
class template
instantiated with a unique symbol identifier and a result of unit
equation passed as an argument.Note: Physical constants are also implemented as units.
AssociatedUnit<T>
conceptAssociatedUnit
concept
describes a unit with an associated quantity and is satisfied by:
named_unit
class template
instantiated with a unique symbol identifier and a QuantitySpec
of a quantity kind.All units in the [SI] have associated
quantities. For example,
si::second
is specified to
measure isq::time
.
Natural units typically do not have an associated quantity. For
example, if we assume c = 1
, a
natural::second
unit can be used
to measure both time
and
length
. In such case,
speed
would have a unit of
one
.
PrefixableUnit<T>
conceptPrefixableUnit
concept is
satisfied by all units derived from a
named_unit
class template for
which a customization point
unit_can_be_prefixed<T{}>
was not explicitly set to false
.
Such units can be passed as an argument to a
prefixed_unit
class
template.
All units in the [SI] can be prefixed with SI-defined prefixes.
Some off-system units like
non_si::day
can’t be prefixed.
To enforce that, the following has to be provided:
template<> inline constexpr bool unit_can_be_prefixed<non_si::day> = false;
UnitOf<T, V>
conceptUnitOf
concept is satisfied
for all units T
matching an AssociatedUnit
concept with an associated quantity type implicitly convertible to
V
.
Additionally, the kind of V
and the kind of quantity type associated with
T
must be the same, or the
quantity type associated with T
may not be derived from the kind of
V
.
This condition is required to make
dimensionless[si::radian]
invalid as si::radian
should be
only used for
isq::angular_measure
, which is a
nested quantity kind within the dimensionless quantities tree.
UnitCompatibleWith<T, V1, V2>
conceptUnitCompatibleWith
concept is
satisfied for all units T
when:
V1
is a Unit
,V2
is a QuantitySpec
,T
and
V1
are defined in terms of the
same reference unit,T
is an AssociatedUnit
it should satisfy UnitOf<V2>
.Reference<T>
conceptReference
concept is
satisfied by all quantity reference types. Such types provide all the
meta-information required to create a Quantity
.
A Reference
can either
be:
AssociatedUnit
.reference
class template with a
QuantitySpec
passed as the first template argument and a Unit
passed as the second one.ReferenceOf<T, V>
conceptReferenceOf
concept is
satisfied by references T
which
have a quantity specification that satisfies QuantitySpecOf<V>
concept. |
Representation<T>
conceptRepresentation
concept
constraints a type of a number that stores the value of a quantity.
RepresentationOf<T, Ch>
conceptRepresentationOf
concept is
satisfied by all Representation
types that are of a specified quantity character
Ch
.
A user can declare a custom representation type to be of a specific
character by providing the specialization with
true
for one or more of the
following variable templates:
is_scalar<T>
is_vector<T>
is_tensor<T>
If we want to use scalar types to also express vector quantities (e.g., ignoring the “direction” of the vector) the following definition can be provided to enable such a behavior:
template<class T>
requires is_scalar<T>
inline constexpr bool is_vector<T> = true;
Quantity<T>
conceptQuantity
concept matches
every quantity in the library and is satisfied by all types being or
deriving from an instantiation of a
quantity
class template.
QuantityOf<T, V>
conceptQuantityOf
concept is
satisfied by all the quantities for which a QuantitySpecOf<V>
is true
.
PointOrigin<T>
conceptPointOrigin
concept matches
all quantity point origins in the library. It is satisfied by
either:
absolute_point_origin
class
template.relative_point_origin
class
template.PointOriginFor<T, V>
conceptPointOriginFor
concept is
satisfied by all PointOrigin
types that have quantity type implicitly convertible from quantity
specification V
, which means
that V
must satisfy QuantitySpecOf<T::quantity_spec>
.
For example, si::ice_point
can serve as a point origin for points of
isq::Celsius_temperature
because
this quantity type implicitly converts to
isq::thermodynamic_temperature
.
However, if we define
mean_sea_level
in the following
way:
inline constexpr struct mean_sea_level : absolute_point_origin<isq::altitude> {} mean_sea_level;
then it can’t be used as a point origin for points of
isq::length
or
isq::width
as none of them is
implicitly convertible to
isq::altitude
:
QuantityPoint<T>
conceptQuantityPoint
concept is
satisfied by all types being either a specialization or derived from
quantity_point
class
template.
QuantityPointOf<T, V>
conceptQuantityPointOf
concept is
satisfied by all the quantity points
T
that match the following value
V
:
V
|
Condition
|
---|---|
QuantitySpec |
The quantity point quantity specification satisfies QuantitySpecOf<V>
concept. |
PointOrigin |
The point and V
have the same absolute point origin. |
QuantityLike<T>
conceptQuantityLike
concept provides
interoperability with other libraries and is satisfied by a type
T
for which an instantiation of
quantity_like_traits
type trait
yields a valid type that provides:
reference
that matches the Reference
concept,rep
type that matches RepresentationOf
concept with the character provided in
reference
.to_numerical_value(T)
static
member function returning a raw value of the quantity packed in either
convert_explicitly
or
convert_implicitly
wrapper that
enables implicit conversion in the latter case.from_numerical_value(rep)
static member function returning
T
packed in either
convert_explicitly
or
convert_implicitly
wrapper that
enables implicit conversion in the latter case.For example, this is how support for
std::chrono::seconds
can be
provided:
template<>
struct quantity_like_traits<std::chrono::seconds> {
static constexpr auto reference = si::second;
using rep = std::chrono::seconds::rep;
[[nodiscard]] static constexpr convert_implicitly<rep> to_numerical_value(const std::chrono::seconds& q)
{
return q.count();
}
[[nodiscard]] static constexpr convert_implicitly<std::chrono::seconds> from_numerical_value(const rep& v)
{
return std::chrono::seconds(v);
}
};
= 42s;
quantity q ::chrono::seconds dur = 42 * s; std
QuantityPointLike<T>
conceptQuantityPointLike
concept
provides interoperability with other libraries and is satisfied by a
type T
for which an
instantiation of
quantity_point_like_traits
type
trait yields a valid type that provides:
reference
that matches the Reference
concept.point_origin
that matches the PointOrigin
concept.rep
type that matches RepresentationOf
concept with the character provided in
reference
.to_quantity(T)
static member
function returning the quantity
being the offset of the point from the origin packed in either
convert_explicitly
or
convert_implicitly
wrapper that
enables implicit conversion in the latter case.from_quantity(quantity<reference, rep>)
static member function returning
T
packed in either
convert_explicitly
or
convert_implicitly
wrapper that
enables implicit conversion in the latter case.For eample, this is how support for a
std::chrono::time_point
of
std::chrono::seconds
can be
provided:
template<typename C>
struct quantity_point_like_traits<std::chrono::time_point<C, std::chrono::seconds>> {
using T = std::chrono::time_point<C, std::chrono::seconds>;
static constexpr auto reference = si::second;
static constexpr struct point_origin : absolute_point_origin<isq::time> {} point_origin{};
using rep = std::chrono::seconds::rep;
[[nodiscard]] static constexpr convert_implicitly<quantity<reference, rep>> to_quantity(const T& qp)
{
return quantity{qp.time_since_epoch()};
}
[[nodiscard]] static constexpr convert_implicitly<T> from_quantity(const quantity<reference, rep>& q)
{
return T(q);
}
};
= time_point_cast<std::chrono::seconds>(std::chrono::system_clock::now());
quantity_point qp ::chrono::sys_seconds q = qp + 42 * s; std
Modern C++ physical quantities and units library should expose compile-time constants for units, dimensions, and quantity types. Each of such constants should be of a different type. Said otherwise, every unit, dimension, and quantity type has a unique type and a compile-time instance. This allows us to do regular algebra on such identifiers and get proper types as results of such operations.
The operations exposed by such a library should include at least:
newton * metre
),metre / second
),pow<2>(metre)
or
pow<1, 2>(metre * metre)
).To improve the usability of the library, we also recommend adding:
sqrt(metre * metre)
as
equivalent to
pow<1, 2>(metre * metre)
),cbrt(metre * metre * metre)
as equivalent to pow<1, 3>(metre * metre * metre)
),inverse(second)
as
equivalent to
one / second
).Additionally, for units only, to improve the readability of the code, it makes sense to expose the following:
square(metre)
is
equivalent to
pow<2>(metre)
),cubic(metre)
is equivalent
to pow<3>(metre)
).The above two functions could also be considered for dimensions and
quantity types. However,
cubic(length)
does not seem to
make much sense, and probably
pow<3>(length)
should be
preferred instead.
Modern C++ physical quantities and units libraries use opaque types to improve the user experience while analyzing compile-time errors or inspecting types in a debugger. This is a huge usability improvement over the older libraries that use aliases to refer to long instantiations of class templates.
Having such strong types for entities is not enough. While doing arithmetics on them, we get derived entities, and they also should be easy to understand and correlate with the code written by the user. This is where expression templates come into play.
The library should use the same unified approach to represent the results of arithmetics on all kinds of entities. It is worth mentioning that a generic purpose expression templates library is not a good solution for a physical quantities and units library.
Let’s assume that we want to represent the results of the following two unit equations:
metre / second * second
metre * metre / metre
Both of them should result in a type equivalent to
metre
. A general-purpose library
will probably result with the types similar to the below:
mul<div<metre, second>, second>
div<mul<metre, metre>, metre>
Comparing such types for equivalence would not only be very expensive at compile-time but would also be really confusing to the users observing them in the compilation logs. This is why we need a dedicated solution here.
In a physical quantities and units library, we need expression templates to express the results of
If the above equation results in a derived entity, we must create a type that clearly describes what we are dealing with. We need to pack a simplified expression template into some container for that. There are various possibilities here. The table below presents the types generated from unit expressions by two leading products on the market in this subject:
Unit
|
[mp-units]
|
[Au]
|
---|---|---|
N⋅m |
derived_unit<metre, newton> |
UnitProduct<Meters, Newtons> |
1/s |
derived_unit<one, per<second>> |
Pow<Seconds, -1> |
km/h |
derived_unit<kilo_<metre>, per<hour>> |
UnitProduct<Kilo<Meters>, Pow<Hours, -1>> |
kg⋅m²/(s³⋅K) |
derived_unit<kilogram, pow<metre, 2>, per<kelvin, power<second, 3>>> |
UnitProduct<Pow<Meters, 2>, Kilo<Grams>, Pow<Seconds, -3>, Pow<Kelvins, -1>> |
m²/m |
metre |
Meters |
km/m |
derived_unit<kilo_<metre>, per<metre>> |
UnitProduct<Pow<Meters, -1>, Kilo<Meters>> |
m/m |
one |
UnitProduct<> |
It is a matter of taste which solution is better. While discussing
the pros and cons here, we should remember that our users often do not
have a scientific background. This is why we recommend to use syntax
that is as similar to the correct English language as possible. It
consistently uses the derived_
prefix for types representing derived units, dimensions, and quantity
specifications. Those are instantiated first with the contents of the
numerator followed by the entities of the denominator (if present)
enclosed in the per<...>
expression template.
The arithmetics on units, dimensions, and quantity types require a special identity value. Such value can be returned as a result of the division of the same entities, or using it should not modify the expression template on multiplication.
We chose the following names here:
one
in the domain of
units,dimension_one
in the domain
of dimensions,dimensionless
in the domain
of quantity types.The above names were selected based on the following quote from [ISO/IEC 80000]:
A quantity whose dimensional exponents are all equal to zero has the dimensional product denoted A0B0C0… = 1, where the symbol 1 denotes the corresponding dimension. There is no agreement on how to refer to such quantities. They have been called dimensionless quantities (although this term should now be avoided), quantities with dimension one, quantities with dimension number, or quantities with the unit one. Such quantities are dimensionally simply numbers. To avoid confusion, it is helpful to use explicit units with these quantities where possible, e.g., m/m, nmol/mol, rad, as specified in the SI Brochure.
The table below presents all the operations that can be done on units, dimensions, and quantity types in a quantities and units library. The right column presents corresponding expression templates being their results:
Operation
|
Resulting template expression arguments
|
---|---|
A * B |
A, B |
B * A |
A, B |
A * A |
power<A, 2> |
{identity} * A |
A |
A * {identity} |
A |
A / B |
A, per<B> |
A / A |
{identity} |
A / {identity} |
A |
{identity} / A |
{identity}, per<A> |
pow<2>(A) |
power<A, 2> |
pow<2>({identity}) |
{identity} |
sqrt(A)
or pow<1, 2>(A) |
power<A, 1, 2> |
sqrt({identity})
or
pow<1, 2>({identity}) |
{identity} |
To limit the length and improve the readability of generated types, there are many rules to simplify the resulting expression template.
Ordering
The resulting comma-separated arguments of multiplication are always sorted according to a specific predicate. This is why:
static_assert(A * B == B * A);
static_assert(std::is_same_v<decltype(A * B), decltype(B * A)>);
This is probably the most important of all the steps, as it allows comparing types and enables the rest of the simplification rules.
Units and dimensions have unique symbols, but ordering quantity types might not be that trivial. Although the ISQ defined in [ISO/IEC 80000] provides symbols for each quantity, there is little use for them in the C++ code. This is caused by the fact that such symbols use a lot of characters that are not available with the Unicode encoding. Most of the limitations correspond to Unicode providing only a minimal set of characters available as subscripts, which are often used to differentiate various quantities of the same kind. For example, it is impossible to encode the symbols of the following quantities:
This is why the library chose to use type name identifiers in such cases.
Aggregation
In case two of the same type identifiers are found next to each other on the argument list, they will be aggregated in one entry:
Before
|
After
|
---|---|
A, A |
power<A, 2> |
A, power<A, 2> |
power<A, 3> |
power<A, 1, 2>, power<A, 2> |
power<A, 5, 2> |
power<A, 1, 2>, power<A, 1, 2> |
A |
Simplification
In case two of the same type identifiers are found in the numerator and denominator argument lists, they are being simplified into one entry:
Before
|
After
|
---|---|
A, per<A> |
{identity} |
power<A, 2>, per<A> |
A |
power<A, 3>, per<A> |
power<A, 2> |
A, per<power<A, 2>> |
{identity}, per<A> |
It is important to notice here that only the elements with exactly
the same type are being simplified. This means that, for example,
m/m
results in
one
, but
km/m
will not be simplified. The
resulting derived unit will preserve both symbols and their relative
magnitude. This allows us to properly print symbols of some units or
constants that require such behavior. For example, the Hubble constant
is expressed in km⋅s⁻¹⋅Mpc⁻¹
,
where both km
and
Mpc
are units of
length.
Repacking
In case an expression uses two results of some other operations, the components of its arguments are repacked into one resulting type and simplified there.
For example, assuming:
constexpr auto X = A / B;
then:
Operation
|
Resulting template expression arguments
|
---|---|
X * B |
A |
X * A |
power<A, 2>, per<B> |
X * X |
power<A, 2>, per<power<B, 2>> |
X / X |
{identity} |
X / A |
{identity}, per<B> |
X / B |
A, per<power<B, 2>> |
Please note that for as long as for the ordering step in some cases, we use user-provided symbols, the aggregation, and the next steps do not benefit from those. They always use type identifiers to determine whether the operation should be performed.
Unit symbols are not guaranteed to be unique in the project. For
example, someone may use
"s"
as a symbol for a
count of samples, which, when used in a unit expression with seconds,
would cause fatal consequences (e.g.,
sample * second
would yield
s²
, or
sample / second
would result in
one
).
Some units would provide worse text output if the ordering step used
type identifiers rather than unit symbols. For example, si::metre * si::second * cgs::second
would result in s m s
, or
newton * metre
would result in
m N
, which is not how we
typically spell this unit. However, for the sake of consistency, we may
also consider changing the algorithm used for ordering to be based on
type identifiers.
Thanks to all of the steps described above, a user may write the code like this one:
using namespace mp_units::si::unit_symbols;
= isq::speed(60. * km / h);
quantity speed = 8 * s;
quantity duration = speed / duration;
quantity acceleration1 = isq::acceleration(acceleration1.in(m / s2));
quantity acceleration2 ::cout << "acceleration: " << acceleration1 << " (" << acceleration2 << ")\n"; std
the text output provides:
acceleration: 7.5 km h⁻¹ s⁻¹ (2.08333 m/s²)
The above program will produce the following types for acceleration quantities:
acceleration1
quantity<reference<derived_quantity_spec<isq::speed, per<isq::time>>,
derived_unit<si::kilo_<si::metre>, per<non_si::hour, si::second>>>{},
double>
acceleration2
quantity<reference<isq::acceleration,
derived_unit<si::metre, per<power<si::second, 2>>>>{},
double>>
In most libraries, physical constants are implemented as constant
(possibly constexpr
) quantity
values. Such an approach has some disadvantages, often resulting in
longer compilation times and a loss of precision.
When dealing with equations involving physical constants, they often occur more than once in an expression. Such a constant may appear both in a numerator and denominator of a quantity equation. As we know from fundamental physics, we can simplify such an expression by simply striking a constant out of the equation. Supporting such behavior allows a faster runtime performance and often a better precision of the resulting value.
The library allows and encourages implementing physical constants as regular units. With that, the constant’s value is handled at compile-time, and under favorable circumstances, it can be simplified in the same way as all other repeated units do. If it is not simplified, the value is stored in a type, and the expensive multiplication or division operations can be delayed in time until a user selects a specific unit to represent/print the data.
Such a feature often also allows the use of simpler or faster representation types in the equation. For example, instead of always multiplying a small integral value with a big floating-point constant number, we can just use the integral type all the way. Only in case a constant will not simplify in the equation, and the user will require a specific unit, such a multiplication will be lazily invoked, and the representation type will need to be expanded to facilitate that. With that, addition, subtractions, multiplications, and divisions will always be the fastest - compiled away or done on the fast arithmetic types or in out-of-order execution.
To benefit from all of the above, constants (defined by SI or otherwise) are implemented as units in the following way:
namespace si {
namespace si2019 {
inline constexpr struct speed_of_light_in_vacuum :
<"c", mag<299'792'458> * metre / second> {} speed_of_light_in_vacuum;
named_unit
} // namespace si2019
inline constexpr struct magnetic_constant :
<{"μ₀", "u_0"}, mag<4> * mag_pi * mag_power<10, -7> * henry / metre> {} magnetic_constant;
named_unit
} // namespace si
With the above definitions, we can calculate vacuum permittivity as:
constexpr auto permeability_of_vacuum = 1. * si::magnetic_constant;
constexpr auto speed_of_light_in_vacuum = 1 * si::si2019::speed_of_light_in_vacuum;
<isq::permittivity_of_vacuum> auto q = 1 / (permeability_of_vacuum * pow<2>(speed_of_light_in_vacuum));
QuantityOf
::cout << "permittivity of vacuum = " << q << " = " << q.in(F / m) << "\n"; std
The above first prints the following:
permittivity of vacuum = 1 μ₀⁻¹ c⁻² = 8.85419e-12 F/m
As we can clearly see, all the calculations above were just about
multiplying and dividing the number
1
with the rest of the
information provided as a compile-time type. Only when a user wants a
specific SI unit as a result, the unit ratios are lazily resolved.
Another similar example can be an equation for total energy:
<isq::mechanical_energy> auto total_energy(QuantityOf<isq::momentum> auto p,
QuantityOf<isq::mass> auto m,
QuantityOf<isq::speed> auto c)
QuantityOf{
return isq::mechanical_energy(sqrt(pow<2>(p * c) + pow<2>(m * pow<2>(c))));
}
constexpr Unit auto GeV = si::giga<si::electronvolt>;
constexpr quantity c = 1. * si::si2019::speed_of_light_in_vacuum;
constexpr quantity c2 = pow<2>(c);
const quantity p1 = isq::momentum(4. * GeV / c);
const QuantityOf<isq::mass> auto m1 = 3. * GeV / c2;
const quantity E = total_energy(p1, m1, c);
::cout << "in `GeV` and `c`:\n"
std<< "p = " << p1 << "\n"
<< "m = " << m1 << "\n"
<< "E = " << E << "\n";
const quantity p2 = p1.in(GeV / (m / s));
const quantity m2 = m1.in(GeV / pow<2>(m / s));
const quantity E2 = total_energy(p2, m2, c).in(GeV);
::cout << "\nin `GeV`:\n"
std<< "p = " << p2 << "\n"
<< "m = " << m2 << "\n"
<< "E = " << E2 << "\n";
const quantity p3 = p1.in(kg * m / s);
const quantity m3 = m1.in(kg);
const quantity E3 = total_energy(p3, m3, c).in(J);
::cout << "\nin SI base units:\n"
std<< "p = " << p3 << "\n"
<< "m = " << m3 << "\n"
<< "E = " << E3 << "\n";
The above prints the following:
in `GeV` and `c`:
p = 4 GeV/c
m = 3 GeV/c²
E = 5 GeV
in `GeV`:
p = 1.33426e-08 GeV s/m
m = 3.33795e-17 GeV s²/m²
E = 5 GeV
in SI base units:
p = 2.13771e-18 kg m/s
m = 5.34799e-27 kg
E = 8.01088e-10 J
Note: We know that probably the term “reference” will not survive too long in the Committee, but we couldn’t find a better name for it in the [mp-units] library (https://github.com/mpusz/mp-units/issues/486).
[ISO/IEC Guide 99] says:
quantity - property of a phenomenon, body, or substance, where the property has a magnitude that can be expressed as a number and a reference. … A reference can be a measurement unit, a measurement procedure, a reference material, or a combination of such.
In the library a quantity reference represents all the
domain-specific meta-data about the quantity besides its representation
type and its value. A Reference
concept is satisfied by either of:
si::metre
),reference<QuantitySpec, Unit>
class template explicitly specifying the quantity type and its
unit.A reference type is implicitly created as a result of the following expression:
constexpr Reference auto distance = isq::distance[m];
The above example defines a variable of type reference<isq::distance, si::metre>
.
The reference
class template
also exposes an arithmetic interface similar to the one that we have
already discussed in case of units and quantity types. It simply
forwards the operation to its quantity type and unit members.
constexpr ReferenceOf<isq::speed> auto speed = distance / si::second;
As a result we get a reference<derived_quantity_spec<distance, per<time>>, derived_unit<metre, per<second>>>
type.
Similarly to the AssociatedUnit
,
such a reference can be used to construct a quantity:
<isq::speed> auto s = 60 * speed; QuantityOf
The quantity
class template
is a workhorse of the library. It can be considered a generalization of
std::chrono::duration
, but is
not directly compatible with it.
Based on the ISO definition provided in the Quantity references chapter, the
quantity
class template has the
following signature:
template<Reference auto R, RepresentationOf<get_quantity_spec(R).character> Rep = double>
class quantity;
It stores only one data member of
Rep
type. Unfortunately, this
data member has to be publicly exposed to satisfy the C++ language
requirements for structural
types. Hopefully, the language rules for structural types will
improve with time before this library gets standardized.
Constructing a quantity
chapter describes and explains why we introduced the multiply syntax as
a construction helper for quantities. Many people ask why we chose this
approach over battle-proven User Defined Literals (UDLs) that work well
for the std::chrono
library.
It turns out that many reasons make UDLs a poor choice for a physical units library:
UDLs work only with literals (compile-time known values). Our observation is that besides the unit tests, only a few compile-time known quantity values are used in the production code. Please note that for Physical constants, we recommend using units rather than compile-time constants.
Typical implementations of UDLs tend to always use the widest
representation type available. In the case of
std::chrono::duration
, the
following is true:
using namespace std::chrono_literals;
auto d1 = 42s;
auto d2 = 42.s;
static_assert(std::is_same_v<decltype(d1)::rep, std::int64_t>);
static_assert(std::is_same_v<decltype(d2)::rep, long double>);
When such UDL is intermixed in arithmetics with any quantity type of a shorter representation type, it will always expand it to the longest one. In other words, such long type spreads until all types use it everywhere.
While increasing the coverage for the [mp-units] library, we learned that many
unit symbols conflict with built-in types or numeric extensions. A few
of those are: F
(farad),
J
(joule),
W
(watt),
K
(kelvin),
d
(day),
l
or
L
(litre),
erg
,
ergps
. Using the
_
prefix would make it work for
[mp-units], but if the library is
standardized, those naming collisions would be a big issue. This is why
we came up with the _q_
prefix
that would become q_
after
standardization (e.g., 42q_s
),
which is not that nice anymore.
UDLs with the same identifiers defined in different namespace
can’t be disambiguated in the C++ language. If both SI and CGS systems
define q_s
UDL for a second
unit, then it would not be possible to specify which one to use in case
both namespaces are “imported” with using directives.
Another bad property of UDLs is that they do not compose. A
coherent unit of angular momentum would have a UDL specified as
q_kg_m2_per_s
. Now imagine that
we want to make every possible user happy. How many variations of that
unit would we predefine for differently scaled versions of all unit
ingredients?
UDLs are also really expensive to define and specify. Typically, for each unit, we need two definitions. One for integral and another one for floating-point representation. In version 0.8.0 of the [mp-units] library, the coherent unit of angular momentum was defined as:
constexpr auto operator"" _q_kg_m2_per_s(unsigned long long l)
{
(std::in_range<std::int64_t>(l));
gsl_ExpectsAuditreturn angular_momentum<kilogram_metre_sq_per_second, std::int64_t>(static_cast<std::int64_t>(l));
}
constexpr auto operator"" _q_kg_m2_per_s(long double l)
{
return angular_momentum<kilogram_metre_sq_per_second, long double>(l);
}
The multiply syntax that we chose for this library does not have any of those issues.
quantity
is a numeric wrapperIf we think about it, the
quantity
class template is just
a “smart” numeric wrapper. It exposes properly constrained set of
arithmetic operations on one or two operands.
Every single arithmetic operator is exposed by the
quantity
class template only if
the underlying representation type provides it as well and its
implementation has proper semantics (e.g., returns a reasonable
type).
For example, in the following code,
-a
will compile only if
MyInt
exposes such an operation
as well:
= MyInt{42} * m;
quantity a = -a; quantity b
Assuming that:
q
is our quantity,qq
is a quantity implicitly
convertible to q
,q2
is any other
quantity,kind
is a quantity of the
same kind as q
,one
is a quantity of
dimension_one
with the unit
one
,number
is a value of a type
“compatible” with q
’s
representation type,here is the list of all the supported operators:
+q
-q
++q
q++
--q
q--
q += qq
q -= qq
q %= qq
q *= number
q *= one
q /= number
q /= one
q + kind
q - kind
q % kind
q * q2
q * number
number * q
q / q2
q / number
number / q
q == kind
q <=> kind
As we can see, there are plenty of operations one can do on a value
of a quantity
type. As most of
them are obvious, in the following chapters, we will discuss only the
most important or non-trivial aspects of quantity arithmetics.
Quantities can easily be added or subtracted from each other:
static_assert(1 * m + 1 * m == 2 * m);
static_assert(2 * m - 1 * m == 1 * m);
static_assert(isq::height(1 * m) + isq::height(1 * m) == isq::height(2 * m));
static_assert(isq::height(2 * m) - isq::height(1 * m) == isq::height(1 * m));
The above uses the same types for LHS, RHS, and the result, but in general, we can add, subtract, or compare the values of any quantity type as long as both quantities are of the same kind. The result of addition and subtraction will be the common type of the arguments:
static_assert(1 * km + 1.5 * m == 1001.5 * m);
static_assert(isq::height(1 * m) + isq::width(1 * m) == isq::length(2 * m));
static_assert(isq::height(2 * m) - isq::distance(0.5 * m) == 1.5 * m);
static_assert(isq::radius(1 * m) - 0.5 * m == isq::radius(0.5 * m));
Please note that for the compound assignment operators, both arguments have to either be of the same type or the RHS has to be implicitly convertible to the LHS, as the type of LHS is always the result of such an operation:
static_assert((1 * m += 1 * km) == 1001 * m);
static_assert((isq::height(1.5 * m) -= 1 * m) == isq::height(0.5 * m));
If we break those rules, the code will not compile:
static_assert((1 * m -= 0.5 * m) == 0.5 * m); // Compile-time error (1)
static_assert((1 * km += 1 * m) == 1001 * m); // Compile-time error (2)
static_assert((isq::height(1 * m) += isq::length(1 * m)) == 2 * m); // Compile-time error (3)
(1)
Floating-point to
integral representation type is considered narrowing.
(2)
Conversion of quantity
with integral representation type from a unit of a higher resolution to
the one with a lower resolution is considered narrowing.
(3)
Conversion from a more
generic quantity type to a more specific one is considered unsafe.
Multiplying or dividing a quantity by a number does not change its quantity type or unit. However, its representation type may change. For example:
static_assert(isq::height(3 * m) * 0.5 == isq::height(1.5 * m));
Unless we use a compound assignment operator, in which case truncating operations are again not allowed:
static_assert((isq::height(3 * m) *= 0.5) == isq::height(1.5 * m)); // Compile-time error (1)
(1)
Floating-point to
integral representation type is considered narrowing.
However, suppose we multiply or divide quantities of the same or different types, or we divide a raw number by a quantity. In that case, we most probably will end up in a quantity of yet another type:
static_assert(120 * km / (2 * h) == 60 * km / h);
static_assert(isq::width(2 * m) * isq::length(2 * m) == isq::area(4 * m2));
static_assert(50 / isq::time(1 * s) == isq::frequency(50 * Hz));
An exception from the above rule happens when one of the arguments is
a dimensionless quantity. If we multiply or divide by such a quantity,
the quantity type will not change. If such a quantity has a unit
one
, also the unit of a quantity
will not change:
static_assert(120 * m / (2 * one) == 60 * m);
An interesting special case happens when we divide the same quantity kinds or multiply a quantity by its inverted type. In such a case, we end up with a dimensionless quantity.
static_assert(isq::height(4 * m) / isq::width(2 * m) == 2 * one); // (1)
static_assert(5 * h / (120 * min) == 0 * one); // (2)
static_assert(5. * h / (120 * min) == 2.5 * one);
(1)
The resulting quantity
type of the LHS is
isq::height / isq::width
, which
is a quantity of the dimensionless kind.
(2)
The resulting quantity of
the LHS is
0 * dimensionless[h / min]
. To
be consistent with the division of different quantity types, we do not
convert quantity values to a common unit before the division.
The physical units library can’t do any runtime branching logic for the division operator. All logic has to be done at compile-time when the actual values are not known, and the quantity types can’t change at runtime.
If we expect
120 * km / (2 * h)
to return
60 km/h
, we have to agree with
the fact that 5 * km / (24 * h)
returns 0 km/h
. We can’t do a
range check at runtime to dynamically adjust scales and types based on
the values of provided function arguments.
This is why we often prefer floating-point representation types when dealing with units. Some popular physical units libraries even forbid integer division at all.
Now that we know how addition, subtraction, multiplication, and division work, it is time to talk about modulo. What would we expect to be returned from the following quantity equation?
auto q = 5 * h % (120 * min);
Most of us would probably expect to see
1 h
or
60 min
as a result. And this is
where the problems start.
The C++ language defines its
/
and
%
operators with the quotient-remainder
theorem:
q = a / b;
r = a % b;
q * b + r == a;
The important property of the modulo operator is that it only works for integral representation types (it is undefined what modulo for floating-point types means). However, as we saw in the previous chapter, integral types are tricky because they often truncate the value.
From the quotient-remainder theorem, the result of modulo operation
is r = a - q * b
. Let’s see what
we get from such a quantity equation on integral representation
types:
= 5 * h;
quantity a = 120 * min;
quantity b = a / b;
quantity q = a - q * b;
quantity r
::cout << "reminder: " << r << "\n"; std
The above code outputs:
reminder: 5 h
And now, a tough question needs an answer. Do we really want modulo
operator on physical units to be consistent with the quotient-remainder
theorem and return 5 h
for
5 * h % (120 * min)
?
This is exactly why we decided not to follow this hugely surprising path in this library. The selected approach was also consistent with the feedback from C++ experts. For example, this is what Richard Smith said about this issue:
I think the quotient-remainder property is a less important motivation here than other factors – the constraints on
%
and/
are quite different, so they lack the inherent connection they have for integers. In particular, I would expect thatA / B
works for all quantitiesA
andB
, whereasA % B
is only meaningful whenA
andB
have the same dimension. It seems like a nice-to-have for the property to apply in the case where both/
and%
are defined, but internal consistency of/
across all cases seems much more important to me.I would expect
61 min % 1 h
to be1 min
, and1 h % 59 min
to also be1 min
, so my intuition tells me that the result type ofA % B
, whereA
andB
have the same dimension, should have the smaller unit ofA
andB
(and if the smaller one doesn’t divide the larger one, we should either use thegcd / std::common_type
of the units ofA
andB
or perhaps just produce an error). I think any other behavior for%
is hard to defend.On the other hand, for division it seems to me that the choice of unit should probably not affect the result, and so if we want that
5 mm / 120 min = 0 mm/min
, then5 h / 120 min == 0 hc
(wherehc
is a dimensionless “hexaconta”, or60x
, unit). I don’t like the idea of taking SI base units into account; that seems arbitrary and like it would do the wrong thing as often as it does the right thing, especially when the units have a multiplier that is very large or small. We could special-case the situation of a dimensionless quantity, but that could lead to problematic overflow pretty easily: a calculation such as10 s * 5 GHz * 2 uW
would overflow anint
if it produces a dimensionless quantity for10 s * 5 GHz
, but it could equally produce50 G * 2 uW = 100 kW
without any overflow, and presumably would if the terms were merely reordered.If people want to use integer-valued quantities, I think it’s fundamental that you need to know what the units of the result of an operation will be, and take that into account in how you express computations; the simplest rule for heterogeneous operators like
*
or/
seems to be that the units of the result are determined by applying the operator to the units of the operands – and for homogeneous operators like+
or%
, it seems like the only reasonable option is that you get thestd::common_type
of the units of the operands.
To summarize, the modulo operator on physical units has more in common with addition and division operators than with the quotient-remainder theorem. To avoid surprising results, the operation uses a common unit to do the calculation and provide its result:
static_assert(5 * h / (120 * min) == 0 * one);
static_assert(5 * h % (120 * min) == 60 * min);
static_assert(61 * min % (1 * h) == 1 * min);
static_assert(1 * h % (59 * min) == 1 * min);
Zero is special. It is the only number that unambiguously defines the value of any kind of quantity, regardless of its units: zero inches and zero meters and zero miles are all identical. For this reason, it’s very common to compare the value of a quantity against zero. For example, when checking the sign of a quantity, or when making sure that it’s nonzero.
We could implement such checks in the following way:
if(q1 / q2 != 0 * m / s)
// ...
The above would work (assuming we are dealing with the quantity of
speed), but it’s not ideal. If the result of
q1 / q2
is not expressed in
m / s
, we’ll incur an extra unit
conversion. Even if it is in
m / s
, it’s cumbersome to repeat
the unit in a context where it makes no difference.
We could avoid repeating the unit, and guarantee there won’t be an extra conversion, by writing:
if(auto q = q1 / q2; q != q.zero())
// ...
But that is a bit inconvenient, and inexperienced users could be unaware of this technique and its rationale.
For the above reasons, the [mp-units] library provides dedicated interfaces to compare against zero that follow the naming convention of named comparison functions in the C++ Standard Library:
is_eq_zero
is_neq_zero
is_lt_zero
is_gt_zero
is_lteq_zero
is_gteq_zero
Thanks to them, to save typing and not pay for unneeded conversions, our check could be implemented as follows:
if (is_neq_zero(q1 / q2))
// ...
Those functions will work with any type
T
that exposes a
zero()
member function returning
something comparable to T
.
Thanks to that, we can use them not only with quantities but also with
std::chrono::duration
or any
other type that exposes such an interface.
This approach has a downside, though: it produces a set of new APIs
which users must learn. Nor are these six the only such functions that
will need to exist: for example,
max
and
min
are perfectly reasonable to
use with 0
regardless of the
units, but supporting them under this strategy would require adding a
new utility function for each — and coming up with a name for those
functions.
It also introduces small opportunities for error and diffs that are
harder to review, because we’re replacing a pattern that uses an
operator (say, a > 0
) with a
named function call (say,
is_gt_zero(a)
).
These pitfalls motivate us to consider other approaches as well.
Zero
typeThe [Au] library takes a different approach
to this problem. It provides an empty type,
Zero
, which represents a value
of exactly 0
(in any units). It
also provides an instance ZERO
of this type. Every quantity is implicitly constructible from
Zero
.
Consider this example legacy (i.e., pre-units-library) code:
if (speed_squared_m2ps2 > 0) { /* ... */ }
When users upgrade to a units library, they will replace the raw
number speed_squared_m2ps2
with
a strongly typed quantity
speed_squared
. Unfortunately,
this replacement won’t compile, because quantities can’t be constructed
from raw numeric values such as
0
. They can fix this problem by
using the instance, ZERO
, which
encodes its value in the type:
if (speed_squared > ZERO) { /* ... */ }
This has significant advantages. It preserves the form of the code,
making the transition less error prone than replacement with a function
such as is_gt_zero
. It also
reduces the number of new comparison APIs a user must learn:
Zero
handles them all.
Zero
has one downside: it
will not work when passed across generic quantity interfaces.
Zero
’s value comes in situations
where the surrounding context makes it unambiguous which quantity type
it should construct. While it converts to any specific quantity type, it
is not itself a quantity. This could confuse users.
This downside manifests in several different ways. Here are some examples:
While refactoring the [mp-units] code to try out this approach,
we found out a perfectly reasonable place where we could not replace the
numerical value 0
with
ZERO
:
= mean_sea_level + 0 * si::metre; // OK
msl_altitude alt = mean_sea_level + ZERO; // Compile-time error msl_altitude alt
This would not work because the
mean_sea_level
is an absolute
point origin that stores the information about the quantity type but not
its value or unit, which
msl_altitude
needs, but none of
which ZERO
has.
Callsites passing ZERO
can add friction when refactoring a concrete interface to be more
generic.
namespace v1 { void foo(quantity<si::metre> q); }
namespace v2 { void foo(QuantityOf<isq::length> auto q); }
::foo(ZERO); // OK
v1::foo(ZERO); // Compile-time error v2
In practice, this issue will be discovered at the point of
refactoring, so it mainly affects library authors, not their clients.
They can handle this by adding an overload for
Zero
, if appropriate. However,
this wouldn’t scale well for APIs with multiple parameters where users
would want to pass
Zero
.
For completeness, we mention that
Zero
works for addition but not
multiplication. When multiplying, we do not know what units (or even
what dimension!) is desired for the result. However, this is not a
problem in practice because users would not be motivated to write this
in the first place, as simple multiplication with
0
(including any necessary
units, if the result has a different dimension) would work.
= 1 * m / s;
quantity q1 = q1 + 0 * m / s; // OK
quantity q2 = q1 * (0 * s); // OK quantity q3
= 1 * m / s;
quantity q1 = q1 + ZERO; // OK
quantity q2 = q1 * ZERO; // Compile-time error quantity q3
The main concern with the
Zero
feature is that novices
might be tempted to replace every numeric value
0
with the instance
ZERO
, becoming confused when it
doesn’t work. We could address this with easy-to-read documentation that
clarifies its use cases and mental models.
Overall, these two approaches — special functions, and a
Zero
type — represent two local
optima in design space. Each has its strengths and weaknesses; each
makes different tradeoffs. It’s currently an open question as to which
approach would be best suited for a quantity type in the standard
library.
This chapter scoped only on the
quantity
type’s operators.
However, there are many named math functions provided in the [mp-units] library. Among others, we can
find there the following:
pow()
,
sqrt()
, and
cbrt()
,exp()
,abs()
,epsilon()
,fma()
,
fmod()
,floor()
,
ceil()
,
round()
,inverse()
,hypot()
,sin()
,
cos()
,
tan()
,asin()
,
acos()
,
atan()
,
atan2()
.In the library, we can also find the
<mp-units/random.h>
header
file with all the pseudo-random number generators.
We plan to provide a separate paper on those in the future.
The quantities we discussed so far always had some specific type and physical dimension. However, this is not always the case. While performing various computations, we sometimes end up with so-called “dimensionless” quantities, which [ISO/IEC Guide 99] correctly defines as quantities of dimension one:
- Quantity for which all the exponents of the factors corresponding to the base quantities in its quantity dimension are zero.
- The measurement units and values of quantities of dimension one are numbers, but such quantities convey more information than a number.
- Some quantities of dimension one are defined as the ratios of two quantities of the same kind.
- Numbers of entities are quantities of dimension one.
Dividing two quantities of the same kind always results in a quantity of dimension one. However, depending on what type of quantities we divide or what their units are, we may end up with slightly different types.
Dividing two quantities of the same dimension always results in a
quantity with the dimension being
dimension_one
. This is often
different for other physical units libraries, which may return a raw
representation type for such cases. A raw value is also always returned
from the division of two
std::chrono::duration
values.
In the initial design of the [mp-units] library, the resulting type of
division of two quantities was their common representation type (just
like std::chrono::duration
):
static_assert(std::is_same_v<decltype(10 * km / (5 * km)), int>);
The reasoning behind it was not providing a false impression of a
strong quantity
type for
something that looks and feels like a regular number. Also, all of the
mathematic and trigonometric functions were working fine out of the box
with such representation types, so we did not have to rewrite
sin()
,
cos()
,
exp()
, and others.
However, the feedback we got from the production usage was that such
an approach is really bad for generic programming. It is hard to handle
the result of the two quantities’ division (or multiplication) as it
might be either a quantity or a fundamental type. If we want to raise
such a result to some power, we must use
units::pow
or
std::pow
depending on the
resulting type (units::pow
takes
the power as template arguments). Those are only a few issues related to
such an approach.
Moreover, suppose we divide quantities of the same dimension, but with units of significantly different magnitudes. In such case, we may end up with a really small or a huge floating-point value, which may result in losing lots of precision. Returning a dimensionless quantity from such cases allows us to benefit from all the properties of scaled units and is consistent with the rest of the library.
First, let’s analyze what happens if we divide two quantities of the same type:
constexpr QuantityOf<dimensionless> auto q = isq::height(200 * m) / isq::height(50 * m);
In such a case, we end up with a dimensionless quantity that has the following properties:
static_assert(q.quantity_spec == dimensionless);
static_assert(q.dimension == dimension_one);
static_assert(q.unit == one);
In case we would like to print its value, we would see a raw value of
4
in the output with no unit
being printed.
We can divide quantities of the same dimension and unit but of different quantity types:
constexpr QuantityOf<dimensionless> auto q = isq::work(200 * J) / isq::heat(50 * J);
Again we end up with
dimension_one
and
one
, but this time:
static_assert(q.quantity_spec == isq::work / isq::heat);
As shown above, the result is not of a
dimensionless
type anymore.
Instead, we get a quantity type derived from the performed quantity
equation. According to the [ISO/IEC 80000], work divided by
heat is the recipe for the thermodynamic efficiency
quantity, thus:
static_assert(implicitly_convertible(q.quantity_spec, isq::efficiency_thermodynamics));
Please note that the quantity of
isq::efficiency_thermodynamics
is of a kind dimensionless
, so
it is implicitly convertible to
dimensionless
and satisfies the
QuantityOf<dimensionless>
concept.
Now, let’s see what happens when we divide two quantities of the same type but different units:
constexpr QuantityOf<dimensionless> auto q = isq::height(4 * km) / isq::height(2 * m);
This time we get a quantity of
dimensionless
type with a
dimension_one
as its dimension.
However, the resulting unit is not
one
anymore:
static_assert(q.unit == mag_power<10, 3> * one);
In case we would print the text output of this quantity, we would not
see a raw value of 2000
, but
2 km/m
.
First, it may look surprising, but this is actually consistent with
the division of quantities of different dimensions. For example, if we
divide 4 * km / (2 * s)
, we do
not expect km
to be “expanded”
to m
before the division, right?
We would expect the result of
2 * (km / s)
, which is exactly
what we get when we divide quantities of the same kind.
This is a compelling feature that allows us to express huge or tiny ratios without the need for big and expensive representation types. With this, we can easily define things like a Hubble’s constant that uses a unit that is proportional to the ratio of kilometers per megaparsecs, which are both units of length:
inline constexpr struct hubble_constant :
<{"H₀", "H_0"}, mag<ratio{701, 10}> * si::kilo<si::metre> / si::second / si::mega<parsec>> {
named_unit} hubble_constant;
Another important use case for dimensionless quantities is to provide strong types for counts of things. For example:
Thanks to assigning strong names to such quantities, they can be used
in the quantity equation of other quantities. For example,
rotational frequency is defined by
rotation / duration
.
As stated before, the division of two quantities of the same kind
results in a quantity of dimension one. Even though it does not have a
specific physical dimension it still uses units with various ratios such
as one
,
percent
,
radian
,
degree
, etc. It is essential to
be explicit about which unit we want to use for such a quantity.
However, in some cases, this might look like an overkill. In the Basic quantity equations chapter one of the lines looks as follows:
static_assert(10 * km / (5 * km) == 2 * one);
Another example could be subtracting a value
1
from the dimensionless
quantity that we can find in Storage tank
example:
const QuantityOf<isq::time> auto fill_time_left = (height / fill_level - 1 * one) * fill_time;
Some physical quantities and units libraries (e.g. [Boost.Units]) provide implicit conversions from the values of representation types to such quantities.
With such support, the above examples would look in the following way:
static_assert(10 * km / (5 * km) == 2);
const QuantityOf<isq::time> auto fill_time_left = (height / fill_level - 1) * fill_time;
Such simplification might look tempting, and the [mp-units] initially provided a special support that allowed the above to compile. However, in the V2 version of the library, it was removed. There are a few reasons for that:
Such support has sense only for quantities of dimension one with
a unit one
. In the case of all
the other units, the specific unit should still be provided.
If we provide implicit conversions from the representation type
to a quantity of dimension one with a unit
one
and we start depending on
such a feature, we might end up with compile-time errors after
refactoring the unit in a type of such a quantity. For example:
Before
|
After
|
---|---|
|
|
Please also note that we will still need to use explicit units to
create a quantity for some cases. For example, in the following code,
asin(-1)
would use the overload
from the <math>
header of
the C++ standard library rather than the one for quantities provided in
<mp-units/math.h>
header
file:
(asin(-1 * one), AlmostEquals(-90. * deg)); REQUIRE_THAT
The authors of this paper are not opposed to providing support for
conversions from the raw value to the dimensionless quantity of a unit
one
. If WG21 groups decide that
is a good direction, we will provide additional interfaces to the
library to support such a scenario. If we choose to go this path, two
questions should be answered first:
Should such a conversion be explicit or implicit?
We may be tempted to stay on the safe side and choose explicit conversions here. However, this would make the following expression illegal or at least awkward:
static_assert(10 * km / (5 * km) + 1 == 3);
It would be strange to support arithmetics against the raw value if the quantity type can’t be implicitly constructed from it.
Should we support converting from the dimensionless quantity with
unit one
to the raw value? And
if yes, should it be implicit or explicit?
It could probably be better to allow implicit conversions to work with legacy interfaces or to benefit from regular math-related functions that work on fundamental types. Otherwise, we will need to type something like this in our code:
auto res = sin(static_cast<double>(q));
which really is not a great improvement over:
auto res = sin(q.numerical_value_in(one));
As we observed above, the most common unit for dimensionless
quantities is one
. It has the
ratio of 1
and does not output
any textual symbol.
A unit one
is special in the
entire type system of units as it is considered to be an identity
operand in the unit expression templates. This means that, for
example:
static_assert(one * one == one);
static_assert(one * si::metre == si::metre);
static_assert(si::metre / si::metre == one);
The same is also true for
dimension_one
and
dimensionless
in the domains of
dimensions and quantity specifications, respectively.
Besides the unit one
, there
are a few other scaled units predefined in the library for usage with
dimensionless quantities:
inline constexpr struct percent : named_unit<"%", mag<ratio{1, 100}> * one> {} percent;
inline constexpr struct per_mille : named_unit<{"‰", "%o"}, mag<ratio(1, 1000)> * one> {} per_mille;
inline constexpr struct parts_per_million : named_unit<"ppm", mag<ratio(1, 1'000'000)> * one> {} parts_per_million;
inline constexpr auto ppm = parts_per_million;
Special, often controversial, examples of dimensionless quantities
are the angular measure and solid angular measure
quantities that are defined in [ISO/IEC 80000] (part 3) to be the result
of a division of
arc_length / radius
and
area / pow<2>(radius)
respectively. Moreover, [ISO/IEC 80000] also
explicitly states that both can be expressed in the unit
one
. This means that both
isq::angular_measure
and
isq::solid_angular_measure
should be of a kind of
dimensionless
.
On the other hand, [ISO/IEC 80000] also
specifies that the unit radian
can be used for angular measure, and the unit
steradian
can be used for
solid angular measure. Those should not be mixed or used to
express other types of dimensionless quantities. We should not be able
to measure:
This means that both
isq::angular_measure
and
isq::solid_angular_measure
should also be quantity kinds by themselves.
Note: Many people claim that angle being a dimensionless quantity
is a bad idea. There are proposals submitted to make an angle a base
quantity and rad
to become a
base unit in both [SI] and [ISO/IEC 80000].
Angular quantities are not the only ones with such a “strange”
behavior. A similar case is the storage capacity quantity
specified in [ISO/IEC 80000]
(part 13) that again allows expressing it in both
one
and
bit
units.
Those cases make dimensionless quantities an exceptional tree in the library. This is the only quantity hierarchy that contains more than one quantity kind in its tree:
To provide such support in the library, we provided an
is_kind
specifier that can be
appended to the quantity specification:
inline constexpr struct angular_measure : quantity_spec<dimensionless, arc_length / radius, is_kind> {} angular_measure;
inline constexpr struct solid_angular_measure : quantity_spec<dimensionless, area / pow<2>(radius), is_kind> {} solid_angular_measure;
inline constexpr struct storage_capacity : quantity_spec<dimensionless, is_kind> {} storage_capacity;
With the above, we can constrain
radian
,
steradian
, and
bit
to be allowed for usage with
specific quantity kinds only:
inline constexpr struct radian : named_unit<"rad", metre / metre, kind_of<isq::angular_measure>> {} radian;
inline constexpr struct steradian : named_unit<"sr", square(metre) / square(metre), kind_of<isq::solid_angular_measure>> {} steradian;
inline constexpr struct bit : named_unit<"bit", one, kind_of<storage_capacity>> {} bit;
This still allows the usage of
one
(possibly scaled) for such
quantities which is exactly what we wanted to achieve.
It is easy to cooperate with similar entities of other libraries. No
matter if we want to provide interoperability with a simple home-grown
strongly typed wrapper type (e.g.,
Meter
,
Timestamp
, …) or with a
feature-rich quantities and units library, we have to provide
specializations of:
quantity_like_traits
for
external quantity
-like
type,quantity_point_like_traits
for external quantity_point
-like
type.Before we delve into the template specialization details, let’s first decide if we want the conversions to happen implicitly or if explicit ones would be a better choice. Or maybe the conversion should be implicit in one direction only (e.g., into abstractions in this library) while the explicit conversions in the other direction should be preferred?
There is no one unified answer to the above questions. Everything depends on the use case.
Typically, in the C++ language, the implicit conversions are allowed in cases where:
In all other scenarios, we should probably enforce explicit conversions.
The kinds of inter-library conversions can be easily configured in
partial specializations of conversion traits. To require an explicit
conversion, the return type of the conversion function should be wrapped
in convert_explicitly<T>
.
Otherwise,
convert_implicitly<T>
should be used.
For example, let’s assume that some company has its own
Meter
strong-type wrapper:
struct Meter {
int value;
};
As every usage of Meter
is at
least as good and safe as the usage of
quantity<si::metre, int>
,
and as there is no significant runtime performance penalty, we would
like to allow the conversion to
mp_units::quantity
to happen
implicitly.
On the other hand, the
quantity
type is much safer than
the Meter
, and that is why we
would prefer to see the opposite conversions stated explicitly in our
code.
To enable such interoperability, we must define a partial
specialization of the
quantity_like_traits<T>
type trait. Such specialization should provide:
reference
that provides the quantity reference (e.g., unit),rep
type that specifies the
underlying storage type,to_numerical_value(T)
static
member function returning a quantity’s raw value of
rep
type packed in either
convert_explicitly
or
convert_implicitly
wrapper.from_numerical_value(rep)
static member function returning
T
packed in either
convert_explicitly
or
convert_implicitly
wrapper.For example, for our Meter
type, we could provide the following:
template<>
struct std::quantity_like_traits<Meter> {
static constexpr auto reference = si::metre;
using rep = decltype(Meter::value);
static constexpr convert_implicitly<rep> to_numerical_value(Meter m) { return m.value; }
static constexpr convert_explicitly<Meter> from_numerical_value(rep v) { return Meter{v}; }
};
After that, we can check that the QuantityLike
concept is satisfied:
static_assert(QuantityLike<Meter>);
and we can write the following:
void print(Meter m) { std::cout << m.value << " m\n"; }
int main()
{
using namespace std::si::unit_symbols;
{42};
Meter height
// implicit conversions
::quantity h1 = height;
std::quantity<isq::height[m], int> h2 = height;
std
::cout << h1 << "\n";
std::cout << h2 << "\n";
std
// explicit conversions
(Meter(h1));
print(Meter(h2));
print}
No matter if we decide to use implicit or explicit conversions, the library’s framework will not allow unsafe operations to happen.
If we extend the above example with unsafe conversions, the code will not compile, and we will have to fix the issues first before the conversion may be performed:
Unsafe
|
Fixed
|
---|---|
|
|
(1)
Truncation of value while
converting from meters to kilometers.
(2)
Conversion of
double
to
int
is not value-preserving.
(3)
Truncation of value while
converting from millimeters to meters.
To play with quantity point conversions, let’s assume that we have a
Timestamp
strong type in our
codebase, and we would like to start using this library to work with
this abstraction.
struct Timestamp {
int seconds;
};
As we described in The Affine Space chapter, timestamps should be modeled as quantity points rather than regular quantities.
To allow the conversion between our custom
Timestamp
type and the
quantity_point
class template we
need to provide the following in the partial specialization of the quantity_point_like_traits<T>
type trait:
reference
that provides the quantity point reference (e.g., unit),point_origin
that specifies the
absolute point, which is the beginning of our measurement scale for our
points,rep
type that specifies the
underlying storage type,to_quantity(T)
static member
function returning the quantity
being the offset of the point from the origin packed in either
convert_explicitly
or
convert_implicitly
wrapper,from_quantity(quantity<reference, rep>)
static member function returning
T
packed in either
convert_explicitly
or
convert_implicitly
wrapper.For example, for our
Timestamp
type, we could provide
the following:
template<>
struct std::quantity_point_like_traits<Timestamp> {
static constexpr auto reference = si::second;
static constexpr auto point_origin = default_point_origin(reference);
using rep = decltype(Timestamp::seconds);
static constexpr convert_implicitly<quantity<reference, rep>> to_quantity(Timestamp ts)
{
return ts.seconds * si::second;
}
static constexpr convert_explicitly<Timestamp> from_quantity(quantity<reference, rep> q)
{
return Timestamp(q.numerical_value_ref_in(si::second));
}
};
After that, we can check that the QuantityPointLike
concept is satisfied:
static_assert(mp_units::QuantityPointLike<Timestamp>);
and we can write the following:
void print(Timestamp ts) { std::cout << ts.seconds << " s\n"; }
int main()
{
using namespace mp_units;
using namespace mp_units::si::unit_symbols;
{42};
Timestamp ts
// implicit conversion
= ts;
quantity_point qp
::cout << qp.quantity_from_zero() << "\n";
std
// explicit conversion
(Timestamp(qp));
print}
std::chrono
abstractionsIn the C++ standard library, we have two types that handle quantities and model the affine space. Those are:
std::chrono::duration
- specifies quantities of time,std::chrono::time_point
- specifies quantity points of time.This library comes with built-in interoperability with those types thanks to:
quantity_like_traits
and
quantity_point_like_traits
that
provide support for implicit conversions between types in both
directions,chrono_point_origin<Clock>
point origin for std
clocks,to_chrono_duration
and
to_chrono_time_point
dedicated
conversion functions that result in types exactly representing this
library’s abstractions.It is important to note here that only a
quantity_point
that uses
chrono_point_origin<Clock>
as its origin can be converted to the
std::chrono
abstractions:
inline constexpr struct ts_origin : relative_point_origin<chrono_point_origin<system_clock> + 1 * h> {} ts_origin;
inline constexpr struct my_origin : absolute_point_origin<my_origin, isq::time> {} my_origin;
= sys_seconds{1s};
quantity_point qp1 auto tp1 = to_chrono_time_point(qp1); // OK
= chrono_point_origin<system_clock> + 1 * s;
quantity_point qp2 auto tp2 = to_chrono_time_point(qp2); // OK
= ts_origin + 1 * s;
quantity_point qp3 auto tp3 = to_chrono_time_point(qp3); // OK
= my_origin + 1 * s;
quantity_point qp4 auto tp4 = to_chrono_time_point(qp4); // Compile-time Error (1)
{1 * s};
quantity_point qp5auto tp5 = to_chrono_time_point(qp5); // Compile-time Error (2)
(1)
my_origin
is not defined in
terms of
chrono_point_origin<Clock>
.
(2)
zeroth_point_origin
is not
defined in terms of
chrono_point_origin<Clock>
.
Here is an example of how interoperability described in this chapter can be used in practice:
using namespace std::chrono;
= floor<seconds>(system_clock::now());
sys_seconds ts_now
= ts_now;
quantity_point start_time = 925. * km / h;
quantity speed = 8111. * km;
quantity distance = distance / speed;
quantity flight_time = start_time + flight_time;
quantity_point exp_end_time
= value_cast<int>(exp_end_time.in(s));
sys_seconds ts_end
auto curr_time = zoned_time(current_zone(), ts_now);
auto mst_time = zoned_time("America/Denver", ts_end);
::cout << "Takeoff: " << curr_time << "\n";
std::cout << "Landing: " << mst_time << "\n"; std
The above may print the following output:
: 2023-11-18 13:20:54 UTC
Takeoff: 2023-11-18 15:07:01 MST Landing
Through the last years [mp-units] library proved to be very intuitive to both novices in the domain and non-C++ experts. Thanks to the user-friendly multiply syntax, support for CTAD, excellent readability of generated types in compiler error messages, and simplicity of systems definitions, this library makes it easy to do the first steps in the dimensional analysis domain.
If someone is new to the domain, a concise introduction of Systems of units, the [SI], and the US Customary System (and how it relates to SI) might be needed.
After that, every new user, even a C++ newbie, should have no problems with understanding the topics of the Unit-based quantities (simple mode) chapter and should be able to start using the library successfully. At least as long as they keep operating in the safety zone using floating-point representation types.
Eventually, the library will stand in the way, disallowing “unsafe” conversions. This would be a perfect place to mention the importance of providing safe interfaces at compile-time and describe why narrowing conversions are unwelcome and what the side effects of those might be. After that, forced conversions in the library should be presented.
In case a target audience needs to interact with legacy interfaces that take raw numeric values, Obtaining a numerical value of a quantity chapter should be introduced. In such a case, it is important to warn students of why this operation is unsafe and what are the potential maintainability issues.
Next, we could show how easy extending the library with custom units is. A simple and funny example like the below could be a great exercise here:
import mp_units;
import std;
inline constexpr struct smoot : std::named_unit<"smoot", std::mag<67> * std::usc::inch> {} smoot;
int main()
{
constexpr std::quantity dist = 364.4 * smoot;
::println("Harvard Bridge length = {:{%N:.5} %U} ({:{%N:.5} %U}, {:{%N:.5} %U}) ± 1 εar",
std.in(usc::foot), dist.in(si::metre));
dist, dist}
After a while, we can also introduce students to The affine space abstractions and discuss the Temperature support.
With the above, we have learned enough for most users’ needs and do not need to delve into more details. The library is intuitive and will prevent all errors at compile time.
For more advanced classes, groups, or use cases, we can introduce Generic Interfaces and Systems of quantities but we don’t have to describe every detail and corner cases of quantity types design and their convertibility. It is good to start here with Why do we need typed quantities?, followed by Quantities of the same kind and System of quantities is not only about kinds.
According to our experience, the most common pitfall in using quantity types might be related to the names chosen for them by the [ISO/IEC 80000] (e.g., length). It might be good to describe what length means when we say “every height is a length” and what it means when we describe a box of length, width, and height dimensions. In the latter case, length will not restrict us to the horizontal dimension only. This is how the ISQ is defined, and we should accept this. However, we should present a way to define horizontal length as presented in the Comparing, adding, and subtracting quantities of the same kind and describe its rationale.
Special thanks and recognition goes to Epam Systems for supporting Mateusz’s membership in the ISO C++ Committee and the production of this proposal.
We would also like to thank Peter Sommerlad for providing valuable feedback that helped us shape the final version of this document.
std::basic_fixed_string
.