Your First Quantities

Welcome to mp-units! In this lesson, you'll create your first quantities and see them in action.

Goal: Create quantities with units and display them
Time: ~10 minutes

What is a Quantity?

A quantity combines a numerical value with its unit. For example:

• 120 kilometers (distance)
• 2 hours (time)
• 75 kilograms (mass)

mp-units ensures the value and unit always stay together, preventing unit errors.

Try It: Create Your First Quantity

The code below creates quantities. It compiles and runs automatically as you modify it!

// ce-embed height=500 compiler=clang2110 flags="-std=c++23 -stdlib=libc++ -O3" mp-units=trunk
#include <mp-units/systems/si.h>
#include <iostream>

int main()
{
  using namespace mp_units;
  using namespace mp_units::si::unit_symbols;

  // Create a distance
  quantity distance = 120 * km;
  std::cout << "Distance: " << distance << "\n";

  // Create a time duration
  quantity time = 2 * h;
  std::cout << "Time: " << time << "\n";

  // Create a mass
  quantity mass = 75 * kg;
  std::cout << "Mass: " << mass << "\n";
}

What happened:

• quantity distance = 120 * km; creates a quantity with value 120 and unit kilometers
• The library remembers both the number AND its unit
• Output shows the complete quantity: Distance: 120 km

Understanding the Code

Let's break it down:

#include <mp-units/systems/si.h>

This includes the International System of Units (SI).

using namespace mp_units::si::unit_symbols;

This lets us write km, h, kg directly (kilometer, hour, kilogram symbols).

quantity distance = 120 * km;

• quantity is a class template (the compiler deduces the specific type automatically)
• 120 is the numerical value
• km is the unit symbol
• The * operator combines them

Key insight: The quantity type combines a numerical value with its unit, creating type-safe measurements that prevent unit errors at compile time.

Unit Names vs Symbols

So far we've used unit symbols like km, h, kg. But you can also use full unit names with prefixes:

// ce-embed height=550 compiler=clang2110 flags="-std=c++23 -stdlib=libc++ -O3" mp-units=trunk
#include <mp-units/systems/si.h>
#include <iostream>

int main()
{
  using namespace mp_units;
  using namespace mp_units::si::unit_symbols;

  // Using symbols (imported from unit_symbols namespace)
  quantity distance1 = 5.0 * km;

  // Using full unit names with prefixes
  quantity<si::kilo<si::metre>, double> distance2 = 5.0 * si::kilo<si::metre>;

  std::cout << "With symbols: " << distance1 << "\n";
  std::cout << "With names: " << distance2 << "\n";
  std::cout << "Equal? " << (distance1 == distance2 ? "Yes" : "No") << "\n";
}

When to use each:

• Symbols (km, m, h): Implementation code - quick and readable
• Names (si::kilo<si::metre>): Header files for function declarations, where you don't want to import unit_symbols

For most code, use symbols

Symbols are more concise and readable but come at the cost of polluting the current namespace with many short identifiers brought in by the using namespace directives.

Use full names primarily in header files when declaring function interfaces. As a general C++ best practice, using namespace directives should not appear in the namespace scope of header files to avoid forcing namespace pollution on users of your headers.

Key insight: Both symbols and full names create identical quantity types - they're just different syntaxes.

Challenges

Try modifying the code above:

1. Change values: Try distance = 250 * km
2. Try different units: Replace km with m (meters)
3. Add more quantities: Create quantity power = 1500 * W; (watts)
4. Try derived units: Create quantity speed = 100.5 * m / s; (meters per second)

What You Learned?

✅ How to include mp-units headers
✅ Quantities combine values with units
✅ Use value * unit syntax to create quantities
✅ Unit symbols (km) for implementation, full names (si::kilo<si::metre>) for headers
✅ Output quantities with IO streams (std::cout)