Introduction to Quantities and Units

Try it live on Compiler Explorer{ .md-button }

Overview

This is a really simple example showcasing the basic features of the mp-units library. It demonstrates how to create quantities, perform calculations with them, convert between units, and format output in various ways.

Key Features Demonstrated

Creating quantities with units
Generic function templates with quantity concepts
Quantity kinds vs. typed quantities
Unit conversions (value-preserving and value-truncating)
Text formatting and stream output

Code Walkthrough

Including Headers and Namespaces

First, we either import the mp_units module or include the headers for:

an International System of Quantities (ISQ),
an International System of Units (SI),
units derived from the Yard and Pound (1959 international agreement),
text formatting and stream output support.

--8<-- "example/hello_units.cpp:28:43"

Also, to shorten the definitions, we "import" all the symbols from the mp_units namespace.

--8<-- "example/hello_units.cpp:44:45"

Defining a Generic Speed Function

Next, we define a simple function that calculates the average speed based on the provided arguments of length and time:

--8<-- "example/hello_units.cpp:46:49"

The above function template takes any quantities implicitly convertible to isq::length and isq::duration, respectively. Those quantities can use any compatible unit and a representation type. The function returns a result of a straightforward equation and ensures that its quantity type is implicitly convertible to isq::speed.

!!! tip

Besides verifying the type returned from the function, constraining a generic return type
is beneficial for users of such a function as it provides more information about what to
expect from a function than just using `auto`.

Using Unit Symbols

--8<-- "example/hello_units.cpp:51:54"

The above lines explicitly opt into using unit symbols from two systems of units. As this introduces a lot of short identifiers into the current scope, it is not done implicitly while including a header file.

Creating and Converting Quantities

--8<-- "example/hello_units.cpp:56:62"

Lines 25 & 26 create a quantity of kind isq::length / isq::duration with the numbers and units provided. Such quantities can be converted or assigned to any other quantity with a matching kind.
Line 27 calls our function template with quantities of kind isq::length and isq::duration and number and units provided.
Line 28 explicitly provides quantity types of the quantities passed to a function template. This time, those will not be quantity kinds anymore and will have more restrictive conversion rules.
Line 29 changes the unit of a quantity v3 to m / s in a value-preserving way (floating-point representations are considered to be value-preserving).
Line 30 does a similar operation, but this time, it would also succeed for value-truncating cases (if that was the case).
Line 31 does a value-truncating conversion of changing the underlying representation type from double to int.

Formatting Output

--8<-- "example/hello_units.cpp:64"

The above presents various ways to print a quantity. Both stream insertion operations and std::format facilities are supported.