mirror of
https://github.com/mpusz/mp-units.git
synced 2025-08-03 20:34:26 +02:00
docs: "Quick Start" chapter reworked to be simpler and include quantity points
This commit is contained in:
@@ -1,11 +1,13 @@
|
||||
# Quick Start
|
||||
|
||||
This chapter provides a quick introduction to get you started with **mp-units**.
|
||||
Much more details can be found in our [User's Guide](../users_guide/terms_and_definitions.md).
|
||||
|
||||
## Quantities
|
||||
|
||||
A **quantity** is a concrete amount of a unit representing a quantity type of a specified dimension with a
|
||||
specific representation. It is represented in the library with a `quantity` class template.
|
||||
|
||||
|
||||
## Creating a quantity
|
||||
|
||||
The [SI Brochure](../appendix/references.md#SIBrochure) says:
|
||||
|
||||
!!! quote "SI Brochure"
|
||||
@@ -23,16 +25,25 @@ a number with a predefined unit:
|
||||
|
||||
using namespace mp_units;
|
||||
|
||||
quantity q = 42 * si::metre;
|
||||
quantity q = 42 * si::metre / si::second;
|
||||
```
|
||||
|
||||
!!! note
|
||||
!!! info
|
||||
|
||||
The above spelling of `metre` is not a typo. For motivation, please check our
|
||||
[FAQ](faq.md#why-do-we-spell-metre-instead-of-meter).
|
||||
In case someone doesn't like the multiply syntax or there is an ambiguity between `operator*`
|
||||
provided by this and other libraries, a quantity can also be created with a two-parameter
|
||||
constructor:
|
||||
|
||||
The above creates an instance of `quantity<si::metre(), int>`. The same can be obtained using
|
||||
an optional unit symbol:
|
||||
```cpp
|
||||
#include <mp-units/systems/si/si.h>
|
||||
|
||||
using namespace mp_units;
|
||||
|
||||
quantity q{42, si::metre / si::second};
|
||||
```
|
||||
|
||||
The above creates an instance of `quantity<derived_unit<si::metre, per<si::second>>{}, int>`.
|
||||
The same can be obtained using optional unit symbols:
|
||||
|
||||
```cpp
|
||||
#include <mp-units/systems/si/si.h>
|
||||
@@ -40,7 +51,7 @@ an optional unit symbol:
|
||||
using namespace mp_units;
|
||||
using namespace mp_units::si::unit_symbols;
|
||||
|
||||
quantity q = 42 * m;
|
||||
quantity q = 42 * m / s;
|
||||
```
|
||||
|
||||
!!! tip
|
||||
@@ -49,36 +60,55 @@ quantity q = 42 * m;
|
||||
why they are opt-in. A user has to explicitly "import" them from a dedicated `unit_symbols`
|
||||
namespace.
|
||||
|
||||
In case someone doesn't like the multiply syntax or there is an ambiguity between `operator*`
|
||||
provided by this and other libraries, a quantity can also be created with a two-parameter
|
||||
constructor:
|
||||
Quantities of the same kind can be added, subtracted, and compared to each other:
|
||||
|
||||
```cpp
|
||||
#include <mp-units/systems/si/si.h>
|
||||
|
||||
using namespace mp_units;
|
||||
using namespace mp_units::si::unit_symbols;
|
||||
|
||||
quantity q{42, si::metre};
|
||||
static_assert(1 * km + 50 * m == 1050 * m);
|
||||
```
|
||||
|
||||
|
||||
## User-provided unit wrappers
|
||||
|
||||
Sometimes it might be awkward to type some derived units:
|
||||
Various quantities can be multiplied or divided by each other:
|
||||
|
||||
```cpp
|
||||
quantity speed = 60 * km / h;
|
||||
```
|
||||
|
||||
In case such a unit is used a lot in the project, a user can easily provide a nicely named
|
||||
wrapper for it with:
|
||||
|
||||
```cpp
|
||||
constexpr auto kmph = km / h;
|
||||
quantity speed = 60 * kmph;
|
||||
static_assert(140 * km / (2 * h) == 70 * km / h);
|
||||
```
|
||||
|
||||
!!! note
|
||||
|
||||
In case you wonder why this library does not use UDLs to create quantities, please check
|
||||
our [FAQ](faq.md#why-dont-we-use-udls-to-create-quantities).
|
||||
|
||||
|
||||
## Quantity points
|
||||
|
||||
The `quantity_point` class template specifies an absolute quantity with respect to an origin.
|
||||
Together with quantities they model [The Affine Space](../users_guide/framework_basics/the_affine_space.md).
|
||||
|
||||
```cpp
|
||||
#include <mp-units/ostream.h>
|
||||
#include <mp-units/systems/si/si.h>
|
||||
#include <mp-units/systems/usc/usc.h>
|
||||
#include <iostream>
|
||||
|
||||
int main()
|
||||
{
|
||||
using namespace mp_units;
|
||||
using namespace mp_units::si::unit_symbols;
|
||||
using namespace mp_units::usc::unit_symbols;
|
||||
|
||||
quantity_point temp = si::zeroth_degree_Celsius + 20. * deg_C;
|
||||
std::cout << "Temperature: "
|
||||
<< temp.quantity_from(si::zeroth_degree_Celsius) << " ("
|
||||
<< temp.in(deg_F).quantity_from(usc::zeroth_degree_Fahrenheit) << ")\n";
|
||||
}
|
||||
```
|
||||
|
||||
The above outputs:
|
||||
|
||||
```text
|
||||
Temperature: 20 °C (68 °F)
|
||||
```
|
||||
|
@@ -89,6 +89,23 @@ A car driving 110 km in 2 h has an average speed of 15.2778 m/s (55 km/h)
|
||||
!!! example "[Try it on Compiler Explorer](https://godbolt.org/z/zWe8ecf93)"
|
||||
|
||||
|
||||
### User-provided unit wrappers
|
||||
|
||||
Sometimes it might be awkward to type some derived units:
|
||||
|
||||
```cpp
|
||||
quantity speed = 60 * km / h;
|
||||
```
|
||||
|
||||
In case such a unit is used a lot in the project, a user can easily provide a nicely named
|
||||
wrapper for it with:
|
||||
|
||||
```cpp
|
||||
constexpr auto kmph = km / h;
|
||||
quantity speed = 60 * kmph;
|
||||
```
|
||||
|
||||
|
||||
### Easy-to-understand compilation error messages
|
||||
|
||||
In case a user makes an error in a quantity equation and the result of the calculation
|
||||
|
Reference in New Issue
Block a user