Skip to content

Introduction to Quantities and Units

Try it live on Compiler Explorer

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 International Yard and Pound,
  • text formatting and stream output support.
hello_units.cpp
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
#include <mp-units/compat_macros.h>
#include <mp-units/ext/format.h>
#ifdef MP_UNITS_IMPORT_STD
import std;
#else
#include <iomanip>
#include <iostream>
#endif
#ifdef MP_UNITS_MODULES
import mp_units;
#else
#include <mp-units/systems/international.h>
#include <mp-units/systems/isq.h>
#include <mp-units/systems/si.h>
#endif

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

hello_units.cpp
16
using namespace mp_units;

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:

hello_units.cpp
17
18
19
20
constexpr QuantityOf<isq::speed> auto avg_speed(QuantityOf<isq::length> auto d, QuantityOf<isq::time> auto t)
{
  return d / t;
}

The above function template takes any quantities implicitly convertible to isq::length and isq::time, 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

hello_units.cpp
21
22
23
24
int main()
{
  using namespace mp_units::si::unit_symbols;
  using namespace mp_units::international::unit_symbols;

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

hello_units.cpp
25
26
27
28
29
30
31
  constexpr quantity v1 = 110 * km / h;
  constexpr quantity v2 = 70 * mph;
  constexpr quantity v3 = avg_speed(220. * km, 2 * h);
  constexpr quantity v4 = avg_speed(isq::distance(140. * mi), 2 * isq::duration[h]);
  constexpr quantity v5 = v3.in(m / s);
  constexpr quantity v6 = value_cast<m / s>(v4);
  constexpr quantity v7 = value_cast<int>(v6);
  • Lines 25 & 26 create a quantity of kind isq::length / isq::time 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::time 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

hello_units.cpp
32
33
34
35
36
37
38
39
  std::cout << v1 << '\n';                                           // 110 km/h
  std::cout << std::setw(10) << std::setfill('*') << v2 << '\n';     // ***70 mi/h
  std::cout << MP_UNITS_STD_FMT::format("{:*^10}\n", v3);            // *110 km/h*
  std::cout << MP_UNITS_STD_FMT::format("{:%N in %U of %D}\n", v4);  // 70 in mi/h of LT⁻¹
  std::cout << MP_UNITS_STD_FMT::format("{::N[.2f]}\n", v5);         // 30.56 m/s
  std::cout << MP_UNITS_STD_FMT::format("{::N[.2f]U[dn]}\n", v6);    // 31.29 m⋅s⁻¹
  std::cout << MP_UNITS_STD_FMT::format("{:%N}\n", v7);              // 31
}

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

Tip

MP_UNITS_STD_FMT is used for compatibility reasons. If a specific compiler does not support std::format or a user prefers to use the {fmt} library, this macro will resolve to fmt namespace. Otherwise, the std namespace will be used.

More about it can be found in the Wide Compatibility chapter.