diff --git a/docs/getting_started/quick_start.md b/docs/getting_started/quick_start.md index dd96894e4..5da05a18c 100644 --- a/docs/getting_started/quick_start.md +++ b/docs/getting_started/quick_start.md @@ -1,10 +1,12 @@ # Quick Start -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. +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 -## Creating a quantity +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. The [SI Brochure](../appendix/references.md#SIBrochure) says: @@ -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 + + 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 spelling of `metre` is not a typo. For motivation, please check our - [FAQ](faq.md#why-do-we-spell-metre-instead-of-meter). + ```cpp + #include -The above creates an instance of `quantity`. The same can be obtained using -an optional unit symbol: + using namespace mp_units; + + quantity q{42, si::metre / si::second}; + ``` + +The above creates an instance of `quantity>{}, int>`. +The same can be obtained using optional unit symbols: ```cpp #include @@ -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 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; +static_assert(140 * km / (2 * h) == 70 * 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: +!!! 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 -constexpr auto kmph = km / h; -quantity speed = 60 * kmph; +#include +#include +#include +#include + +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"; +} ``` -!!! note +The above outputs: - 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). +```text +Temperature: 20 °C (68 °F) +``` diff --git a/docs/users_guide/framework_basics/simple_and_typed_quantities.md b/docs/users_guide/framework_basics/simple_and_typed_quantities.md index eddd5489e..73be74234 100644 --- a/docs/users_guide/framework_basics/simple_and_typed_quantities.md +++ b/docs/users_guide/framework_basics/simple_and_typed_quantities.md @@ -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