mpusz/mp-units
1
0
Fork 1
mirror of https://github.com/mpusz/mp-units.git synced 2025-08-03 20:34:26 +02:00
Code Issues Packages Projects Releases Wiki Activity

docs: "Getting Started" chapters updated

Browse Source
This commit is contained in:
Mateusz Pusz
2023-10-25 14:12:25 +02:00
parent 5cc7fb1f0b
commit 0b3618d723
5 changed files with 102 additions and 101 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
docs/getting_started/code_example.md
View File

@@ -32,7 +32,7 @@ static_assert(1000 / (1 * s) == 1 * kHz);
This library requires some C++20 features ([concepts and constraints](https://en.cppreference.com/w/cpp/language/constraints),
[classes as NTTP](https://en.cppreference.com/w/cpp/language/template_parameters), ...). Thanks to them,
the user gets a powerful but still easy-to-use interface where all unit conversions and dimensional analysis can be
a user gets a powerful but still easy-to-use interface where all unit conversions and dimensional analysis can be
performed without sacrificing accuracy. Please see the below example for a quick preview of basic library features:
*[NTTP]: Non-Type Template Parameter

66
docs/getting_started/faq.md
View File

@@ -11,7 +11,9 @@ This is how the BIPM defines it in the [SI Brochure](../appendix/references.md#S
Many reasons make UDLs a poor choice for a physical units library:
1. UDLs work only with literals (compile-time known values). Our observation is that besides
the unit tests, there are few compile-time known constants used in the production code.
the unit tests, there are only a few compile-time known quantity values used in the production
code. Please note that for physical constants, we recommend using
[Faster-than-lightspeed Constants](../users_guide/framework_basics/faster_than_lightspeed_constants.md).
2. Typical implementations of UDLs tend to always use the widest representation type available.
In the case of `std::chrono::duration`, the following is true:
@@ -23,25 +25,25 @@ Many reasons make UDLs a poor choice for a physical units library:
static_assert(std::is_same_v<decltype(d2)::rep, long double>);
```
3. While increasing the coverage for the library, we learned that many unit symbols conflict with
3. While increasing the coverage for the library, we learned that many unit symbols conflict with
built-in types or numeric extensions. A few of those are: `F` (farad), `J` (joule), `W` (watt),
`K` (kelvin), `d` (day), `l` or `L` (litre), `erg`, `ergps`. For a while for those we used `_` prefix
to make the library work at all, but at some point, we had to unify the naming, and we came up with `_q_`
prefix, which resulted in creating a quantity of a provided unit. So in case the library is
standardized, all quantities would be created with UDLs having `q_` prefix (e.g. `42q_s`)
which is not that nice anymore.
`K` (kelvin), `d` (day), `l` or `L` (litre), `erg`, `ergps`. Usage of the `_` prefix would make
it work for **mp-units**, but in case the library is standardized, those naming collisions would
be a big issue. This is why we came up with the `_q_` prefix that would become `q_` after
standardization (e.g., `42q_s`), which is not that nice anymore.
4. UDLs with the same identifiers defined in different namespace can't be disambiguated in the C++
language. If both SI and CGS systems define `_q_s` UDL for a second unit, then it would not be possible
to specify which one to use in case both namespaces are "imported".
to specify which one to use in case both namespaces are "imported" with using directives.
5. Another bad property of UDLs is that they do not compose. A coherent unit of angular momentum would
have a UDL specified as `_q_kg_m2_per_s`. Now imagine that you want to make every possible user happy.
How many variations of that unit would you predefine for differently scaled versions of unit ingredients?
How many variations of that unit would you predefine for differently scaled versions of all unit
ingredients?
6. UDLs are also really expensive to define and specify. For each unit, we need two definitions. One for
integral and another one for floating-point representation. Before the V2 framework, the coherent unit of
angular momentum was defined as:
6. UDLs are also really expensive to define and specify. Typically, for each unit, we need two
definitions. One for integral and another one for floating-point representation. Before the
V2 framework, the coherent unit of angular momentum was defined as:
```cpp
constexpr auto operator"" _q_kg_m2_per_s(unsigned long long l)
@@ -49,6 +51,7 @@ Many reasons make UDLs a poor choice for a physical units library:
gsl_ExpectsAudit(std::in_range<std::int64_t>(l));
return angular_momentum<kilogram_metre_sq_per_second, std::int64_t>(static_cast<std::int64_t>(l));
}
constexpr auto operator"" _q_kg_m2_per_s(long double l)
{
return angular_momentum<kilogram_metre_sq_per_second, long double>(l);
@@ -58,9 +61,9 @@ Many reasons make UDLs a poor choice for a physical units library:
## Why can't I create a quantity by passing a number to a constructor?
A quantity class template in the **mp-units** library has no publicly available constructor taking a raw value.
Such support is provided by the `std::chrono::duration` and was pointed out to us as a red flag safety issue
by a few parties already.
A quantity class template in the **mp-units** library has no publicly available constructor taking
a raw value. Such support is provided by the `std::chrono::duration` and was pointed out to us as
a red flag safety issue by a few parties already.
Consider the following structure and a code using it:
@@ -76,7 +79,7 @@ X x;
x.vec.emplace_back(42);
```
Everything works fine for years until at some point someone changes the structure to:
Everything works fine for years until, at some point, someone changes the structure to:
```cpp
struct X {
@@ -85,11 +88,18 @@ struct X {
};
```
The code continues to compile just fine but all the calculations are off now. This is why we decided to not
follow this path.
The code continues to compile just fine, but all the calculations are off now. This is why we decided
to not follow this path.
In the **mp-units** library, both a number and a unit have to always be explicitly provided in order to
form a quantity.
In the **mp-units** library, both a number and a unit have to always be explicitly provided in order
to form a quantity.
!!! note
The same applies to the `quantity_point` construction. To prevent similar issues during
construction, it always needs to get both a `quantity` and
a [`PointOrigin`](../users_guide/framework_basics/basic_concepts.md#PointOrigin) that we use
as a reference point.
## Why a dimensionless quantity is not just a fundamental arithmetic type?
@@ -145,8 +155,9 @@ code.
!!! note
In case you have a good idea on how to rename [existing concepts](../users_guide/framework_basics/basic_concepts.md)
to the `standard_case`, please let us know in the associated [GitHub Issue]().
In case you have a good idea of how to rename
[existing concepts](../users_guide/framework_basics/basic_concepts.md) to the `standard_case`,
please let us know in the associated [GitHub Issue](https://github.com/mpusz/mp-units/issues/93).
## Why Unicode quantity symbols are used by default instead of ASCII-only characters?
@@ -155,18 +166,18 @@ Both C++ and [ISO 80000](../appendix/references.md#ISO80000) are standardized by
[ISO 80000](../appendix/references.md#ISO80000) and the [SI](../appendix/references.md#SIBrochure)
standards specify Unicode symbols as the official unit names for some quantities
(e.g. `Ω` symbol for the resistance quantity).
As **mp-units** library will be proposed for standardization as a part of the C++ Standard Library
As the **mp-units** library will be proposed for standardization as a part of the C++ Standard Library
we have to obey the rules and be consistent with ISO specifications.
!!! note
We do understand engineering reality and the constraints of some environments. This is why the library
has the option of ASCII-only Quantity Symbols.
has the option of [ASCII-only Quantity Symbols](../users_guide/framework_basics/text_output.md#unit-symbol-formatting).
## Why don't you have CMake options to disable the building of tests and examples?
Over time many people provided PRs proposing adding options to build tests and examples conditionally.
Over time, many people provided PRs proposing adding options to build tests and examples conditionally.
Here are a few examples:
- [Add CMake options for disabling docs, examples and tests](https://github.com/mpusz/mp-units/pull/124)
@@ -186,7 +197,7 @@ project is not the best idea as it might cause a lot of harm if this project sto
because of that.
Last but not least, not having those options is on purpose. Top level _CMakeLists.txt_ file should only
be used by **mp-units** developers and contributors as an entry point for project's development.
be used by **mp-units** developers and contributors as an entry point for the project's development.
We want to ensure that everyone will build **ALL** the code correctly before pushing a commit. Having
such options would allow unintended issues to leak to PRs and CI.
@@ -199,5 +210,6 @@ This is why our projects have two entry points:
!!! note
For more details on this please refer to the [CMake + Conan: 3 Years Later - Mateusz Pusz](https://youtu.be/mrSwJBJ-0z8?t=1931)
For more details on this please refer to the
[CMake + Conan: 3 Years Later - Mateusz Pusz](https://youtu.be/mrSwJBJ-0z8?t=1931)
lecture that Mateusz Pusz provided at the C++Now 2021 conference.

79
docs/getting_started/installation_and_usage.md
View File

@@ -34,9 +34,7 @@ This repository contains three independent CMake-based projects:
- [gsl-lite](https://github.com/gsl-lite/gsl-lite) to verify runtime contracts with
the `gsl_Expects` macro,
- [{fmt}](https://github.com/fmtlib/fmt) to provide text formatting of quantities
(if `std::format` is not supported yet on a specific compiler),
- [only for clang < 14 with libc++] [range-v3](https://github.com/ericniebler/range-v3)
to provide needed C++20 concepts and utilities.
(if `std::format` is not supported yet on a specific compiler).
- _._
@@ -44,21 +42,17 @@ This repository contains three independent CMake-based projects:
- it wraps _./src_ project together with usage examples and tests
- additionally to the dependencies of _./src_ project, it uses:
- `Catch2 <https://github.com/catchorg/Catch2>`_ library as a unit tests framework,
- `linear algebra <https://github.com/BobSteagall/wg21/tree/master/include>`_
library based on proposal `P1385 <https://wg21.link/P1385>`_ used in some examples
- [Catch2](https://github.com/catchorg/Catch2) library as a unit tests framework,
- [linear algebra](https://github.com/BobSteagall/wg21/tree/master/include)
library based on proposal [P1385](https://wg21.link/P1385) used in some examples
and tests.
- in case you also want to generate the project's documentation, you will need:
- [Material for MkDocs](https://squidfunk.github.io/mkdocs-material)
- *./test_package*
- library installation and Conan package verification.
- CMake library installation and Conan package verification.
!!! tip
!!! important "Important: Library users should not use the top-level CMake file"
Top level _CMakeLists.txt_ file should only be used by **mp-units** developers and contributors
as an entry point for the project's development. We want to ensure that everyone will build **ALL**
@@ -110,34 +104,37 @@ os=Linux
tools.build:compiler_executables={"c": "gcc-12", "cpp": "g++-12"}
```
!!! tip
!!! tip "Setting the language version"
Please note that the **mp-units** library requires C++20 to be set in a Conan profile or forced
via the Conan command line. If you do the former, you will not need to provide `-s compiler.cppstd=20`
every time your run a Conan command line (as provided in the command line instructions below).
Please note that the **mp-units** library requires at least C++20 to be set in a Conan profile
or forced via the Conan command line. If you do the former, you will not need to provide
`-s compiler.cppstd=20` every time you run a Conan command line (as provided in the command
line instructions below).
Additionally, it is recommended to set Ninja as a CMake generator for Conan. To do so, you should create
a _~/.conan2/global.conf_ file that will set `tools.cmake.cmaketoolchain:generator` to one of Ninja
generators. For example:
!!! tip "Using Ninja as a CMake generator for Conan"
```text title="~/.conan2/global.conf"
tools.cmake.cmaketoolchain:generator="Ninja Multi-Config"
```
It is highly recommended to set Ninja as a CMake generator for Conan. To do so, you should
create a _~/.conan2/global.conf_ file that will set `tools.cmake.cmaketoolchain:generator`
to one of the Ninja generators. For example:
!!! info
```text title="~/.conan2/global.conf"
tools.cmake.cmaketoolchain:generator="Ninja Multi-Config"
```
!!! tip "Separate build folders for different configurations"
_~/.conan2/global.conf_ file may also set `tools.cmake.cmake_layout:build_folder_vars` which
[makes working with several compilers or build configurations easier](https://docs.conan.io/2/reference/tools/cmake/cmake_layout.html#multi-setting-option-cmake-layout).
For example, the below line will force Conan to generate separate CMake presets and folders for
each compiler:
each compiler and C++ standard version:
```text title="~/.conan2/global.conf"
tools.cmake.cmake_layout:build_folder_vars=["settings.compiler", "settings.compiler.version"]
tools.cmake.cmake_layout:build_folder_vars=["settings.compiler", "settings.compiler.version", "settings.compiler.cppstd"]
```
In such a case, you will need to use a configuration-specific preset name in the Conan instructions
provided below rather then just `conan-default` and `conan-release`
(e.g. `conan-gcc-11` and `conan-gcc-11-release`)
provided below rather than just `conan-default` and `conan-release`
(e.g. `conan-gcc-13-23` and `conan-gcc-13-23-release`)
## Build Options
@@ -148,8 +145,7 @@ tools.cmake.cmaketoolchain:generator="Ninja Multi-Config"
: [:octicons-tag-24: 0.8.0][build all support] · :octicons-milestone-24: `True`/`False` (Default: `False`)
Enables compilation of all the source code including tests and examples. To support
this it requires some additional Conan build dependencies described in
Enables compilation of all the source code, including tests and examples. To support this, it requires some additional Conan build dependencies described in
[Repository Structure and Dependencies](#repository-structure-and-dependencies).
It also runs unit tests during Conan build (unless `tools.build:skip_test`
configuration property is set to `True`).
@@ -162,7 +158,7 @@ tools.cmake.cmaketoolchain:generator="Ninja Multi-Config"
: [:octicons-tag-24: 0.8.0][skip la support] · :octicons-milestone-24: `True`/`False` (Default: `False`)
If `user.build:all` is enabled, among others, Conan installs the external
[wg21-linear_algebra](https://conan.io/center/wg21-linear_algebra)
[wg21-linear_algebra](https://conan.io/center/recipes/wg21-linear_algebra)
dependency and enables the compilation of linear algebra-based tests and usage examples.
Such behavior can be disabled with this option.
@@ -203,7 +199,7 @@ tools.cmake.cmaketoolchain:generator="Ninja Multi-Config"
: [:octicons-tag-24: 2.0.0][use libfmt support] · :octicons-milestone-24: `ON`/`OFF` (Default: `ON`)
Enables usage of [{fmt}](https://github.com/fmtlib/fmt) library instead of the C++20 Standard
Forces usage of [{fmt}](https://github.com/fmtlib/fmt) library instead of the C++20 Standard
Library feature.
[use libfmt support]: https://github.com/mpusz/mp-units/releases/tag/v2.0.0
@@ -212,7 +208,7 @@ tools.cmake.cmaketoolchain:generator="Ninja Multi-Config"
## CMake with Presets Support
It is recommended to use at least CMake 3.23 to build this project as this version introduced support
for CMake Presets schema version 4 used now by Conan to generate presets files. All build instructions
for CMake Presets schema version 4, used now by Conan to generate presets files. All build instructions
below assume that you have such support. If not, your CMake invocations have to be replaced with something
like:
@@ -234,7 +230,7 @@ cmake --build . --config Release
There are many different ways of installing/reusing **mp-units** in your project. Below we mention
only a few of many options possible.
!!! important
!!! important "Important: Prefer using Conan if possible"
The easiest and most recommended way to obtain **mp-units** is with the Conan package manager.
See [Conan + CMake (release)](#conan-cmake-release) for a detailed instruction.
@@ -247,7 +243,7 @@ to your source tree.
!!! note
In such a case, you are on your own to ensure all the dependencies are installed, and their header
In such a case, you are on your own to ensure all the dependencies are installed and their header
files can be located during the build. Please also note that some compiler-specific flags are needed
to make the code compile without issues.
@@ -255,7 +251,7 @@ to your source tree.
### Copy + CMake
If you copy the whole **mp-units** repository to your project's file tree, you can reuse CMake targets
defined by the library. To do so, you should use _CMakeLists.txt_ file from the _./src_ directory:
defined by the library. To do so, **you should use _CMakeLists.txt_ file from the _./src_ directory**:
```cmake
add_subdirectory(<path_to_units_folder>/src)
@@ -278,8 +274,8 @@ target_link_libraries(<your_target> <PUBLIC|PRIVATE|INTERFACE> mp-units::mp-unit
[Consuming packages](https://docs.conan.io/2/tutorial/consuming_packages.html)
chapter of the official Conan documentation for more information.
**mp-units** releases are hosted on [Conan-Center](https://conan.io/center/mp-units).
To obtain an official library release, the following steps may be performed:
**mp-units** releases are hosted on [Conan-Center](https://conan.io/center/recipes/mp-units).
The following steps may be performed to obtain an official library release:
1. Create Conan configuration file (either _conanfile.txt_ or _conanfile.py_) in your
project's top-level directory and add **mp-units** as a dependency of your project.
@@ -320,13 +316,13 @@ To obtain an official library release, the following steps may be performed:
### Conan + CMake (Live At Head)
This chapter describes the procedure to Live At Head, which means using the latest version
This chapter describes the procedure to Live At Head, which means using the latest stable version
of **mp-units** all the time.
!!! note
Please note that even though the Conan packages that you will be using are generated **ONLY**
for builds that are considered stable (passed our CI tests) some minor regressions may happen
for builds that are considered stable (passed our CI tests), some minor regressions may happen
(our CI and C++20 build environment is not perfect yet). Also, please expect that the library
interface might, and probably will, change occasionally. Even though we do our best, such
changes might not be reflected in the project's documentation right away.
@@ -370,8 +366,7 @@ with the following differences:
### Install
In case you don't want to use Conan in your project and just want to install the **mp-units**
library on your file system and use `find_package(mp-units)` from another repository
to find it, it is enough to perform the following steps:
library on your file system and use `find_package(mp-units)` from another repository to find it; it is enough to perform the following steps:
```shell
conan install . -pr <your_conan_profile> -s compiler.cppstd=20 -b=missing
@@ -438,7 +433,7 @@ After that, you can either:
To test CMake installation and Conan packaging or create a Conan package run:
```shell
conan create . <username>/<channel> -pr <your_conan_profile> -s compiler.cppstd=20 -c user.build:all=True -b missing
conan create . --user <username> --channel <channel> -pr <your_conan_profile> -s compiler.cppstd=20 -c user.build:all=True -b missing
```
The above will create a Conan package and run tests provided in _./test_package_ directory.

43
docs/getting_started/introduction.md
View File

@@ -8,7 +8,7 @@ experience.
!!! info
A brief introduction to the library's interfaces and the rationale for changes in the version 2.0
A brief introduction to the library's interfaces and the rationale for changes in version 2.0
of **mp-units** were provided in detail by [Mateusz Pusz](https://github.com/mpusz) in the
["The Power of C++ Templates With mp-units: Lessons Learned & a New Library Design" talk at the C++ on Sea 2023 conference](https://www.youtube.com/watch?v=eUdz0WvOMm0).
@@ -26,34 +26,36 @@ and improvements) at <https://github.com/mpusz/mp-units>.
Most of the critical design decisions in the library are dictated by the requirement of
providing the best user experience possible. Other C++ physical units libraries are
"famous" for their enormous and hard-to-understand error messages (one line of the error log often
do not fit on one slide). The ultimate goal of **mp-units** is to improve this and make compile-time
does not fit on one slide). The ultimate goal of **mp-units** is to improve this and make compile-time
errors and debugging as easy and user-friendly as possible.
To achieve this goal, several techniques are applied:
- usage of C++20 concepts,
- [using strong types for framework entities (instead of type aliases)](../users_guide/framework_basics/interface_introduction.md#strong-types-instead-of-aliases),
- [usage of expression templates to improve the readability of generated types](../users_guide/framework_basics/interface_introduction.md#expression-templates),
- [usage of C++20 concepts](../users_guide/framework_basics/basic_concepts.md) that improve
compile-times and the readability of error messages when compared to the traditional template
metaprogramming with [SFINAE](https://en.cppreference.com/w/cpp/language/sfinae),
- [usage of strong types for framework entities](../users_guide/framework_basics/interface_introduction.md#strong-types-instead-of-aliases) (instead of type aliases),
- [usage of expression templates](../users_guide/framework_basics/interface_introduction.md#expression-templates) to improve the readability of generated types,
- limiting the number of template arguments to the bare minimum.
!!! important
!!! important "Important: It is all about errors"
In many generic C++ libraries compile-time errors do not happen often. It is hard to
break `std::string` or `std::vector` in a way it won't compile with a huge error
log. Physical Units libraries are different. **Generation of compile-time errors
is the main reason to use such a library.**
In many generic C++ libraries, compile-time errors do not happen often. It is hard to
break `std::string` or `std::vector` in a way that won't compile with a huge error
log. Physical quantities and units libraries are different.
**Generation of compile-time errors is the main reason to use such a library.**
## Key Features
| Feature | Description |
|------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| **Safety** | - [The affine space strong types] (`quantity` and `quantity_point`)<br>- [Compile-time checked conversions of quantities and units]<br>- [Unique support for many quantities of the same kind]<br>- [Type-safe equations on scalar, vector, and tensor quantities and their units]<br>- [Value-preserving conversions] |
| **Performance** | - All the compile-time logic implemented as immediate (`consteval`) functions<br>- As fast or even faster than working with fundamental types<br>- No space size overhead needed to implement high-level abstractions |
| **Great User Experience** | - [Optimized for readable compilation errors and great debugging experience]<br>- [Efficient and composable way to specify a unit of choice]<br>- [Value-based dimension, unit, and quantity equations] |
| **Feature Rich** | - [Systems of Quantities]<br>- [Systems of Units]<br>- [Scalar, vector, and tensor quantities]<br>- [The affine space]<br>- [Natural units systems support]<br>- [Strong angular system]<br>- [Supports any unit's magnitude (huge, small, floating-point)]<br>- [Faster-than-lightspeed constants]<br>- [Highly adjustable text-output formatting] |
| **Easy to Extend** | - [Each entity can be defined with a single line of code]<br>- [User can easily extend the systems with custom dimensions, quantities, and units] |
| **Low Standardization Cost** | - Small number of predefined entities needed thanks to composability<br>- No external dependencies (assuming full C++20 support)<br>- No macros in the user interface (besides portability and standard-compliance issues)<br>- Possibility to be standardized as a [freestanding] part of the C++ Standard Library |
| Feature | Description |
|------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| **Safety** | - [The affine space strong types] (`quantity` and `quantity_point`)<br>- [Compile-time checked conversions of quantities and units]<br>- [Unique support for many quantities of the same kind]<br>- [Type-safe equations on scalar, vector, and tensor quantities and their units]<br>- [Value-preserving conversions] |
| **Performance** | - All the compile-time logic implemented as immediate (`consteval`) functions<br>- As fast or even faster than working with fundamental types<br>- No space size overhead needed to implement high-level abstractions |
| **Great User Experience** | - [Optimized for readable compilation errors and great debugging experience]<br>- [Efficient and composable way to specify a unit of choice]<br>- [Value-based dimension, unit, and quantity equations] |
| **Feature Rich** | - [Systems of Quantities]<br>- [Systems of Units]<br>- [Scalar, vector, and tensor quantities]<br>- [The affine space]<br>- [Different models of the universe (e.g. natural units systems)]<br>- [Strong dimensionless quantities]<br>- [Strong angular system]<br>- [Supports any unit's magnitude (huge, small, floating-point)]<br>- [Faster-than-lightspeed constants]<br>- [Highly adjustable text-output formatting] |
| **Easy to Extend** | - [Each entity can be defined with a single line of code]<br>- [User can easily extend the systems with custom dimensions, quantities, and units] |
| **Low Standardization Cost** | - Small number of predefined entities thanks to their composability<br>- No external dependencies (assuming full C++20 support)<br>- No macros in the user interface (besides portability and standard-compliance issues)<br>- Possibility to be standardized as a [freestanding] part of the C++ Standard Library |
[The affine space strong types]: ../users_guide/framework_basics/the_affine_space.md
@@ -70,13 +72,14 @@ To achieve this goal, several techniques are applied:
[Systems of Units]: ../users_guide/framework_basics/systems_of_units.md
[Scalar, vector, and tensor quantities]: ../users_guide/framework_basics/character_of_a_quantity.md
[The affine space]: ../users_guide/framework_basics/the_affine_space.md
[Natural units systems support]: ../users_guide/defining_systems/natural_units.md
[Different models of the universe (e.g. natural units systems)]: ../users_guide/defining_systems/natural_units.md
[Strong dimensionless quantities]: ../users_guide/framework_basics/dimensionless_quantities.md
[Strong angular system]: ../users_guide/defining_systems/strong_angular_system.md
[Supports any unit's magnitude (huge, small, floating-point)]: ../users_guide/framework_basics/systems_of_units.md#scaled-units
[Faster-than-lightspeed constants]: ../users_guide/framework_basics/faster_than_lightspeed_constants.md
[Highly adjustable text-output formatting]: ../users_guide/framework_basics/text_output.md
[Each entity can be defined with a single line of code]: ../users_guide/framework_basics/interface_introduction.md#new-style-of-definitions
[User can easily extend the systems with custom dimensions, quantities, and units]: ../users_guide/framework_basics/interface_introduction.md#new-style-of-definitions
[User can easily extend the systems with custom dimensions, quantities, and units]: ../users_guide/use_cases/extending_the_library.md#new-style-of-definitions
[freestanding]: https://en.cppreference.com/w/cpp/freestanding

13
docs/getting_started/quick_start.md
View File

@@ -1,7 +1,7 @@
# Quick Start
A **quantity** is a concrete amount of a unit for a quantity type of a specified dimension with a
specific representation, and is represented in the library with a `quantity` class template.
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
@@ -78,15 +78,6 @@ constexpr auto kmph = km / h;
quantity speed = 60 * kmph;
```
or even:
```cpp
constexpr auto kilometre = si::kilo<si::metre>;
constexpr auto kilometre_per_hour = kilometre / si::hour;
constexpr auto kmph = kilometre_per_hour;
quantity speed = 60 * kmph;
```
!!! note
In case you wonder why this library does not use UDLs to create quantities, please check