mirror of
https://github.com/mpusz/mp-units.git
synced 2026-02-07 15:45:39 +01:00
143 lines
4.2 KiB
Markdown
143 lines
4.2 KiB
Markdown
# 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!
|
|
|
|
```cpp
|
|
// 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:
|
|
|
|
```cpp
|
|
#include <mp-units/systems/si.h>
|
|
```
|
|
|
|
This includes the [International System of Units (SI)](../../users_guide/systems/si.md).
|
|
|
|
```cpp
|
|
using namespace mp_units::si::unit_symbols;
|
|
```
|
|
|
|
This lets us write `km`, `h`, `kg` directly (kilometer, hour, kilogram symbols).
|
|
|
|
```cpp
|
|
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:
|
|
|
|
```cpp
|
|
// 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`
|
|
|
|
!!! tip "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`)
|