docs: "Quick Start" chapter reworked to be simpler and include quantity points

This commit is contained in:
Mateusz Pusz
2023-12-21 12:13:38 +01:00
parent 2493152ec7
commit ed2b91500a
2 changed files with 74 additions and 27 deletions

View File

@@ -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)
```

View File

@@ -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