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

docs: cross-page links fixed

Browse Source
This commit is contained in:
Mateusz Pusz
2023-08-03 21:23:34 +02:00
parent 290161ab07
commit 4c49e9c57f
14 changed files with 146 additions and 146 deletions
Download Patch File Download Diff File Expand all files Collapse all files

8
docs/getting_started/faq.md
View File

@@ -2,7 +2,7 @@
## Why do we spell `metre` instead of `meter`?
This is how the BIPM defines it in the [SI Brochure](../../appendix/references/#SIBrochure)
This is how the BIPM defines it in the [SI Brochure](../appendix/references.md#SIBrochure)
(British English spelling by default).
@@ -159,13 +159,13 @@ all the properties of scaled units and is consistent with the rest of the librar
!!! info
More information on the current design can be found in
[the Dimensionless Quantities chapter](../../users_guide/framework_basics/dimensionless_quantities).
[the Dimensionless Quantities chapter](../users_guide/framework_basics/dimensionless_quantities.md).
## Why Unicode quantity symbols are used by default instead of ASCII-only characters?
Both C++ and [ISO 80000](../../appendix/references/#ISO80000) are standardized by the ISO.
[ISO 80000](../../appendix/references/#ISO80000) and the [SI](../../appendix/references/#SIBrochure)
Both C++ and [ISO 80000](../appendix/references.md#ISO80000) are standardized by the ISO.
[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
(i.e. `Ω` symbol for the resistance quantity).
As **mp-units** library will be proposed for standardization as a part of the C++ Standard Library

3
docs/getting_started/installation_and_usage.md
View File

@@ -71,7 +71,8 @@ This repository contains three independent CMake-based projects:
- _./src/CMakeLists.txt_ contains only a pure library definition and should be used by the customers
that prefer to use CMake's `add_subdirectory()` to handle the dependencies.
To learn more about the rationale, please check our [FAQ](../faq/#why-dont-you-have-cmake-options-to-disable-building-of-tests-and-examples).
To learn more about the rationale, please check our
[FAQ](faq.md#why-dont-you-have-cmake-options-to-disable-building-of-tests-and-examples).
## Obtaining Dependencies

42
docs/getting_started/introduction.md
View File

@@ -26,8 +26,8 @@ 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/#strong-types-instead-of-aliases),
- [usage of expression templates to improve the readability of generated types](../../users_guide/framework_basics/interface_introduction/#expression-templates),
- [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),
- limiting the number of template arguments to the bare minimum.
!!! note
@@ -50,27 +50,27 @@ To achieve this goal, several techniques are applied:
| **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 |
[The affine space strong types]: ../../users_guide/framework_basics/the_affine_space
[Compile-time checked conversions of quantities and units]: ../../users_guide/framework_basics/systems_of_quantities/#converting-between-quantities
[Unique support for many quantities of the same kind]: ../../users_guide/framework_basics/systems_of_quantities/#quantities-of-the-same-kind
[Type-safe equations on scalar, vector, and tensor quantities and their units]: ../../users_guide/framework_basics/quantity_arithmetics
[Value-preserving conversions]: ../../users_guide/framework_basics/value_conversions/#value-preserving-conversions
[The affine space strong types]: ../users_guide/framework_basics/the_affine_space.md
[Compile-time checked conversions of quantities and units]: ../users_guide/framework_basics/systems_of_quantities.md#converting-between-quantities
[Unique support for many quantities of the same kind]: ../users_guide/framework_basics/systems_of_quantities.md#quantities-of-the-same-kind
[Type-safe equations on scalar, vector, and tensor quantities and their units]: ../users_guide/framework_basics/quantity_arithmetics.md
[Value-preserving conversions]: ../users_guide/framework_basics/value_conversions.md#value-preserving-conversions
[Optimized for readable compilation errors and great debugging experience]: ../../users_guide/framework_basics/simple_and_typed_quantities/#easy-to-understand-compilation-error-messages
[Efficient and composable way to specify a unit of choice]: ../../users_guide/framework_basics/systems_of_units/#units-compose
[Value-based dimension, unit, and quantity equations]: ../../users_guide/framework_basics/interface_introduction/#value-based-equations
[Optimized for readable compilation errors and great debugging experience]: ../users_guide/framework_basics/simple_and_typed_quantities.md#easy-to-understand-compilation-error-messages
[Efficient and composable way to specify a unit of choice]: ../users_guide/framework_basics/systems_of_units.md#units-compose
[Value-based dimension, unit, and quantity equations]: ../users_guide/framework_basics/interface_introduction.md#value-based-equations
[Systems of Quantities]: ../../users_guide/framework_basics/systems_of_quantities
[Systems of Units]: ../../users_guide/framework_basics/systems_of_units
[Scalar, vector, and tensor quantities]: ../../users_guide/framework_basics/character_of_a_quantity
[The affine space]: ../../users_guide/framework_basics/the_affine_space
[Natural units systems support]: ../../users_guide/defining_systems/natural_units
[Strong angular system]: ../../users_guide/defining_systems/strong_angular_system
[Supports any unit's magnitude (huge, small, floating-point)]: ../../users_guide/framework_basics/systems_of_units/#scaled-units
[Faster-than-lightspeed constants]: ../../users_guide/framework_basics/faster_than_lightspeed_constants
[Highly adjustable text-output formatting]: ../../users_guide/framework_basics/text_output
[Systems of Quantities]: ../users_guide/framework_basics/systems_of_quantities.md
[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
[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/#new-style-of-definitions
[User can easily extend the systems with custom dimensions, quantities, and units]: ../../users_guide/framework_basics/interface_introduction/#new-style-of-definitions
[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
[freestanding]: https://en.cppreference.com/w/cpp/freestanding

6
docs/getting_started/quick_start.md
View File

@@ -19,7 +19,7 @@ auto q = 42 * si::metre;
!!! note
The above spelling of `metre` is not a typo. For motivation, please check our
[FAQ](../faq/#why-do-we-spell-metre-instead-of-meter).
[FAQ](faq.md#why-do-we-spell-metre-instead-of-meter).
The above creates an instance of `quantity<si::metre(), int>`. The same can be obtained using
an optional unit symbol:
@@ -63,7 +63,7 @@ auto speed = 60 * (km / h);
!!! note
Please note that `60 * km / h` will not compile. To read more about the rationale for such
a design please check our [FAQ](../faq/#why-dont-we-use-udls-to-create-a-quantity).
a design please check our [FAQ](faq.md#why-dont-we-use-udls-to-create-a-quantity).
In case such a unit is used a lot in the project, a user can easily provide a nicely named
wrapper for it with:
@@ -85,4 +85,4 @@ auto speed = 60 * kmph;
!!! note
In case you wonder why this library does not use UDLs to create quantities, please check
our [FAQ](../faq/#why-dont-we-use-udls-to-create-quantities).
our [FAQ](faq.md#why-dont-we-use-udls-to-create-quantities).

84
docs/users_guide/framework_basics/basic_concepts.md
View File

@@ -26,23 +26,23 @@ flowchart TD
## `Dimension`
`Dimension` concept matches a [dimension](../../../appendix/glossary/#dimension) of either a base
or derived [quantity](../../../appendix/glossary/#quantity):
`Dimension` concept matches a [dimension](../../appendix/glossary.md#dimension) of either a base
or derived [quantity](../../appendix/glossary.md#quantity):
- [Base dimensions](../../../appendix/glossary/#base-dimension) are explicitly defined by a user
- [Base dimensions](../../appendix/glossary.md#base-dimension) are explicitly defined by a user
by inheriting from the instantiation of a `base_dimension` class template. It should be instantiated with
a unique symbol identifier describing this dimension in a specific
[system of quantities](../../../appendix/glossary/#system-of-quantities).
- [Derived dimensions](../../../appendix/glossary/#derived-dimension) are implicitly created
by the library's framework based on the [quantity equation](../../../appendix/glossary/#quantity-equation)
provided in the [quantity specification](../../../appendix/glossary/#quantity_spec).
[system of quantities](../../appendix/glossary.md#system-of-quantities).
- [Derived dimensions](../../appendix/glossary.md#derived-dimension) are implicitly created
by the library's framework based on the [quantity equation](../../appendix/glossary.md#quantity-equation)
provided in the [quantity specification](../../appendix/glossary.md#quantity_spec).
??? abstract "Examples"
`isq::dim_length`, `isq::dim_mass`, `isq::dim_time`, `isq::dim_electric_current`,
`isq::dim_thermodynamic_temperature`, `isq::dim_amount_of_substance`, and
`isq::dim_luminous_intensity` are the dimensions of base quantities in the
[ISQ](../../../appendix/glossary/#isq).
[ISQ](../../appendix/glossary.md#isq).
IEC 80000 provides `iec80000::dim_traffic_intensity` base dimension to extend ISQ
with information technology quantities.
@@ -59,36 +59,36 @@ or derived [quantity](../../../appendix/glossary/#quantity):
## `QuantitySpec`
`QuantitySpec` concept matches all the [quantity specifications](../../../appendix/glossary/#quantity_spec)
`QuantitySpec` concept matches all the [quantity specifications](../../appendix/glossary.md#quantity_spec)
including:
- [Base quantities](../../../appendix/glossary/#base-quantity) defined by a user by inheriting from
the `quantity_spec` class template instantiated with a [base dimension](../../../appendix/glossary/#base-dimension)
- [Base quantities](../../appendix/glossary.md#base-quantity) defined by a user by inheriting from
the `quantity_spec` class template instantiated with a [base dimension](../../appendix/glossary.md#base-dimension)
argument.
- [Derived named quantities](../../../appendix/glossary/#derived-quantity) defined by a user by
- [Derived named quantities](../../appendix/glossary.md#derived-quantity) defined by a user by
inheriting from the `quantity_spec` class template instantiated with a result of a
[quantity equation](../../../appendix/glossary/#quantity-equation) passed as an argument.
- Other named quantities forming a [hierarchy of quantities](../../../appendix/glossary/#quantity-hierarchy)
of the same [kind](../../../appendix/glossary/#kind) defined by a user by inheriting from the
[quantity equation](../../appendix/glossary.md#quantity-equation) passed as an argument.
- Other named quantities forming a [hierarchy of quantities](../../appendix/glossary.md#quantity-hierarchy)
of the same [kind](../../appendix/glossary.md#kind) defined by a user by inheriting from the
`quantity_spec` class template instantiated with another "parent" quantity specification passed as an
argument.
- [Quantity kinds](../../../appendix/glossary/#kind) describing a family of mutually comparable quantities.
- Intermediate [derived quantity](../../../appendix/glossary/#derived-quantity) specifications being
a result of a [quantity equations](../../../appendix/glossary/#quantity-equation) on other specifications.
- [Quantity kinds](../../appendix/glossary.md#kind) describing a family of mutually comparable quantities.
- Intermediate [derived quantity](../../appendix/glossary.md#derived-quantity) specifications being
a result of a [quantity equations](../../appendix/glossary.md#quantity-equation) on other specifications.
??? abstract "Examples"
`isq::length`, `isq::mass`, `isq::time`, `isq::electric_current`, `isq::thermodynamic_temperature`,
`isq::amount_of_substance`, and `isq::luminous_intensity` are the specifications of base quantities
in the [ISQ](../../../appendix/glossary/#isq).
in the [ISQ](../../appendix/glossary.md#isq).
`isq::width`, `isq::height`, `isq::radius`, and `isq::position_vector` are only a few of many
quantities of a kind length specified in the [ISQ](../../../appendix/glossary/#isq).
quantities of a kind length specified in the [ISQ](../../appendix/glossary.md#isq).
`kind_of<isq::length>` behaves as any of the quantities of a kind length.
`isq::area`, `isq::speed`, `isq::moment_of_force` are only a few of many derived quantities provided
in the [ISQ](../../../appendix/glossary/#isq).
in the [ISQ](../../appendix/glossary.md#isq).
`derived_quantity_spec<isq::length, per<isq::time>>` is a resulting quantity specification of
`isq::length / isq::time`.
@@ -122,20 +122,20 @@ including:
## `Unit`
`Unit` concept matches all the [units](../../../appendix/glossary/#unit) in the library including:
`Unit` concept matches all the [units](../../appendix/glossary.md#unit) in the library including:
- [Base units](../../../appendix/glossary/#base-unit) defined by a user by inheriting from the `named_unit`
- [Base units](../../appendix/glossary.md#base-unit) defined by a user by inheriting from the `named_unit`
class template instantiated with a unique symbol identifier describing this unit in a specific
[system of units](../../../appendix/glossary/#system-of-units).
[system of units](../../appendix/glossary.md#system-of-units).
- Named scaled units defined by a user by inheriting from the `named_unit` class template instantiated
with a unique symbol identifier and a product of multiplying another unit with some magnitude.
- Prefixed units defined by a user by inheriting from the `prefixed_unit` class template instantiated
with a magnitude and a unit to be prefixed.
- [Derived named units](../../../appendix/glossary/#derived-unit) defined by a user by inheriting from the
- [Derived named units](../../appendix/glossary.md#derived-unit) defined by a user by inheriting from the
`named_unit` class template instantiated with a unique symbol identifier and a result of
[unit equation](../../../appendix/glossary/#unit-equation) passed as an argument.
- [Derived unnamed units](../../../appendix/glossary/#derived-unit) being a result of a
[unit equations](../../../appendix/glossary/#unit-equation) on other units.
[unit equation](../../appendix/glossary.md#unit-equation) passed as an argument.
- [Derived unnamed units](../../appendix/glossary.md#derived-unit) being a result of a
[unit equations](../../appendix/glossary.md#unit-equation) on other units.
!!! note
@@ -144,12 +144,12 @@ including:
??? abstract "Examples"
`si::second`, `si::metre`, `si::kilogram`, `si::ampere`, `si::kelvin`, `si::mole`, and `si::candela`
are the base units of [SI](../../../appendix/glossary/#si).
are the base units of [SI](../../appendix/glossary.md#si).
`si::kilo<si::metre>` is a prefixed unit on length.
`si::radian`, `si::newton`, and `si::watt` are examples of named derived quantities within
[SI](../../../appendix/glossary/#si).
[SI](../../appendix/glossary.md#si).
`derived_unit<si::metre, per<si::second>>` is a resulting derived unit of `si::metre / si::second`.
@@ -170,17 +170,17 @@ including:
### `AssociatedUnit`
`AssociatedUnit` concept describes a [unit with an associated quantity](../../../appendix/glossary/#associated-unit)
`AssociatedUnit` concept describes a [unit with an associated quantity](../../appendix/glossary.md#associated-unit)
and is satisfied by:
- All units derived from a `named_unit` class template instantiated with a unique symbol identifier
and a [`QuantitySpec`](#quantityspec).
- All units being a result of a [unit equations](../../../appendix/glossary/#unit-equation) on other
- All units being a result of a [unit equations](../../appendix/glossary.md#unit-equation) on other
associated units.
??? abstract "Examples"
All units in the [SI](../../../appendix/glossary/#si) have associated quantities.
All units in the [SI](../../appendix/glossary.md#si) have associated quantities.
Natural units typically do not have an associated quantity.
@@ -193,9 +193,9 @@ units can be passed as an argument to a `prefixed_unit` class template.
??? abstract "Examples"
All units in the [SI](../../../appendix/glossary/#si) can be prefixed with SI-defined prefixes.
All units in the [SI](../../appendix/glossary.md#si) can be prefixed with SI-defined prefixes.
Some [off-system units](../../../appendix/glossary/#off-system-unit) like `non_si::day`
Some [off-system units](../../appendix/glossary.md#off-system-unit) like `non_si::day`
can't be prefixed.
### `UnitOf<QS>` { #unitof }
@@ -206,7 +206,7 @@ concept with an associated quantity type implicitly convertible to `QS`.
## `Reference`
`Reference` concept is satisfied by all [quantity reference types](../../../appendix/glossary/#reference)
`Reference` concept is satisfied by all [quantity reference types](../../appendix/glossary.md#reference)
types. Such types provide all the meta-information required to create a [`Quantity`](#quantity).
A `Reference` can be either:
@@ -216,7 +216,7 @@ A `Reference` can be either:
??? abstract "Examples"
`si::metre` is defined in the [SI](../../../appendix/glossary/#si) as a unit of `isq::length`
`si::metre` is defined in the [SI](../../appendix/glossary.md#si) as a unit of `isq::length`
and thus can be used as a reference to instantiate a quantity of length.
The expression `isq::height[m]` results with `reference<isq::height, si::metre>` which can be used to
@@ -237,13 +237,13 @@ A `Reference` can be either:
## `Representation`
`Representation` concept constraints a type of a number that stores the
[value of a quantity](../../../appendix/glossary/#quantity-value).
[value of a quantity](../../appendix/glossary.md#quantity-value).
### `RepresentationOf<Ch>` { #representationof }
`RepresentationOf<Ch>` concept is satisfied by all `Representation` types that are of a specified
[quantity character](../../../appendix/glossary/#character). A user can declare a custom representation
[quantity character](../../appendix/glossary.md#character). A user can declare a custom representation
type to be of a specific character by providing the specialization with `true` for one or more of
the following variable templates:
@@ -254,7 +254,7 @@ the following variable templates:
## `Quantity`
`Quantity` concept matches every [quantity](../../../appendix/glossary/#quantity) in the library and is
`Quantity` concept matches every [quantity](../../appendix/glossary.md#quantity) in the library and is
satisfied by all types being or deriving from and instantiation of a `quantity` class template.
??? abstract "Examples"
@@ -272,7 +272,7 @@ is `true`.
## `PointOrigin`
`PointOrigin` concept matches all [quantity point origins](../../../appendix/glossary/#point-origin) in
`PointOrigin` concept matches all [quantity point origins](../../appendix/glossary.md#point-origin) in
the library. It is satisfied by either:
- Compile-time known [`QuantityPoint`](#quantitypoint)
@@ -314,7 +314,7 @@ class template.
- a [`ReferenceOf<V>`](#referenceof) is `true`.
- the type of `V` satisfies [`PointOrigin`](#pointorigin) concept and the quantity point's
[absolute point origin](../../../appendix/glossary/#absolute-point-origin) is convertible to `V`.
[absolute point origin](../../appendix/glossary.md#absolute-point-origin) is convertible to `V`.
## `QuantityLike`

6
docs/users_guide/framework_basics/character_of_a_quantity.md
View File

@@ -117,8 +117,8 @@ enumeration can be appended to the `quantity_spec` describing such a quantity ty
With the above, all the quantities derived from `position_vector` or `displacement` will have a correct
character determined according to the kind of operations included in the
[quantity equation](../../../appendix/glossary/#quantity-equation) defining a
[derived quantity](../../../appendix/glossary/#derived-quantity).
[quantity equation](../../appendix/glossary.md#quantity-equation) defining a
[derived quantity](../../appendix/glossary.md#derived-quantity).
For example, `velocity` in the below definition will be defined as a vector quantity (no explicit
character override is needed):
@@ -152,7 +152,7 @@ template<Reference auto R,
class quantity;
```
The second template parameter is constrained with a [`RepresentationOf`](../basic_concepts/#representationof)
The second template parameter is constrained with a [`RepresentationOf`](basic_concepts.md#representationof)
concept that checks if the provided representation type satisfies the requirements for the character
associated with this quantity type.

30
docs/users_guide/framework_basics/dimensionless_quantities.md
View File

@@ -3,7 +3,7 @@
The quantities we discussed so far always had some specific type and physical dimension.
However, this is not always the case. While performing various computations, we sometimes end up with
so-called "dimensionless" quantities, which ISO correctly defines as
[quantities of dimension one](../../../appendix/glossary/#dimensionless-quantity):
[quantities of dimension one](../../appendix/glossary.md#dimensionless-quantity):
!!! quote "ISO/IEC Guide 99"
@@ -18,7 +18,7 @@ so-called "dimensionless" quantities, which ISO correctly defines as
## Dividing two quantities of the same kind
Dividing two quantities of the same kind always results in a
[quantity of dimension one](../../../appendix/glossary/#dimensionless-quantity).
[quantity of dimension one](../../appendix/glossary.md#dimensionless-quantity).
However, depending on what type of quantities we divide or what their units are, we may end up
with slightly different results.
@@ -30,7 +30,7 @@ with slightly different results.
returned from the division of two `std::chrono::duration` objects.
To read more about the reasoning for this design decision, please check our
[FAQ](../../../getting_started/faq/#why-a-dimensionless-quantity-is-not-just-a-fundamental-arithmetic-type).
[FAQ](../../getting_started/faq.md#why-a-dimensionless-quantity-is-not-just-a-fundamental-arithmetic-type).
### Dividing quantities of the same type
@@ -69,8 +69,8 @@ static_assert(q.quantity_spec == isq::work / isq::heat);
```
As shown above, the result is not of a `dimensionless` type anymore. Instead, we get a quantity type
derived from the performed [quantity equation](../../../appendix/glossary/#quantity-equation).
According to the [ISQ](../../../appendix/glossary/#isq), work divided by heat is the recipe for
derived from the performed [quantity equation](../../appendix/glossary.md#quantity-equation).
According to the [ISQ](../../appendix/glossary.md#isq), work divided by heat is the recipe for
the thermodynamic efficiency quantity, thus:
```cpp
@@ -129,7 +129,7 @@ of things. For example:
in which the corresponding digits of two words of the same length are different.
Thanks to assigning strong names to such quantities, later on they can be explicitly used as
arguments in the [quantity equations](../../../appendix/glossary/#quantity-equation) of other
arguments in the [quantity equations](../../appendix/glossary.md#quantity-equation) of other
quantities deriving from them.
@@ -141,7 +141,7 @@ ratio of `1` and does not output any textual symbol.
!!! note
A unit `one` is special in the entire type system of units as it is considered to be
[an identity operand in the unit expression templates](../interface_introduction/#identities).
[an identity operand in the unit expression templates](interface_introduction.md#identities).
This means that, for example:
```cpp
@@ -166,23 +166,23 @@ inline constexpr struct per_mille : named_unit<basic_symbol_text{"‰", "%o"}, m
## Angular quantities
Special, often controversial, examples of dimensionless quantities are an angular measure
and solid angular measure quantities that are defined in the [ISQ](../../../appendix/glossary/#isq)
and solid angular measure quantities that are defined in the [ISQ](../../appendix/glossary.md#isq)
to be the result of a division of `arc_length / radius` and `area / pow<2>(radius)` respectively.
Moreover, [ISQ](../../../appendix/glossary/#isq) also explicitly states that both can be
Moreover, [ISQ](../../appendix/glossary.md#isq) also explicitly states that both can be
expressed in the unit `one`. This means that both `isq::angular_measure` and `isq::solid_angular_measure`
should be of a [kind](../../../appendix/glossary/#kind) of `dimensionless`.
should be of a [kind](../../appendix/glossary.md#kind) of `dimensionless`.
On the other hand, [ISQ](../../../appendix/glossary/#isq) also specifies that a unit `radian` can
On the other hand, [ISQ](../../appendix/glossary.md#isq) also specifies that a unit `radian` can
be used for `isq::angular_measure`, and a unit `steradian` can be used for `isq::solid_angular_measure`.
Those should not be mixed or used to express other types of dimensionless quantities. This means
that both `isq::angular_measure` and `isq::solid_angular_measure` should also be
[quantity kinds](../../../appendix/glossary/#kind) by themselves.
[quantity kinds](../../appendix/glossary.md#kind) by themselves.
!!! note
Many people claim that angle being a dimensionless quantity is a bad idea. There are
proposals submitted to make an angle a base quantity and `rad` to become a base unit. More on this
topic can be found in the ["Strong Angular System" chapter](../../defining_systems/strong_angular_system).
topic can be found in the ["Strong Angular System" chapter](../defining_systems/strong_angular_system.md).
## Nested quantity kinds
@@ -192,8 +192,8 @@ is a `storage_capacity` quantity specified in IEC-80000-13 that again allows exp
`one` and `bit` units.
Those cases make dimensionless quantities an exceptional tree in the library. This is the only
[quantity hierarchy](../../../appendix/glossary/#quantity-hierarchy) that contains more than one
[quantity kind](../../../appendix/glossary/#kind) in its tree:
[quantity hierarchy](../../appendix/glossary.md#quantity-hierarchy) that contains more than one
[quantity kind](../../appendix/glossary.md#kind) in its tree:
```mermaid
flowchart TD

12
docs/users_guide/framework_basics/generic_interfaces.md
View File

@@ -61,11 +61,11 @@ some issues start to be clearly visible:
means that the result will not be exactly equal to a direct division of the function's arguments.
4. We have to use a floating-point representation type (the `quantity` class template by default uses
`double` as a representation type) which is considered
[value preserving](../value_conversions/#value-preserving-conversions).
[value preserving](value_conversions.md#value-preserving-conversions).
Trying to use an integral type in this scenario will work only for `s1`, while `s2` and `s3`
will fail to compile. Failing to compile is a good thing here as the library tries to prevent
the user from doing a clearly wrong thing. To make the code compile, the user needs to use
a dedicated [`value_cast`](../value_conversions/#value-truncating-conversions) like this:
a dedicated [`value_cast`](value_conversions.md#value-truncating-conversions) like this:
```cpp
quantity<isq::speed[mi / h]> s2 = avg_speed(value_cast<km>(140 * mi), 2 * h);
@@ -107,7 +107,7 @@ accepts everything:
## Constraining function template arguments with concepts
Much better generic code can be implemented using [basic concepts](../basic_concepts)
Much better generic code can be implemented using [basic concepts](basic_concepts.md)
provided with the library:
```cpp
@@ -119,7 +119,7 @@ auto avg_speed(QuantityOf<isq::length> auto distance,
```
This explicitly states that the arguments passed by the user must not only satisfy
a [`Quantity`](../basic_concepts/#quantity) concept but also their quantity specification must
a [`Quantity`](basic_concepts.md#quantity) concept but also their quantity specification must
be implicitly convertible to `isq::length` and `isq::time` accordingly. This no longer leaves
room for error while still allowing the compiler to generate the most efficient code.
@@ -150,7 +150,7 @@ Doing so has two important benefits:
the thing being returned there.
2. Such a concept constrains the type returned from the function. This means that it works as
a unit test to verify if our function actually performs what it is supposed to do. If there is
an error in [quantity equations](../../appendix/glossary/#quantity-equation), we will learn
an error in [quantity equations](../../appendix/glossary.md#quantity-equation), we will learn
about it right away.
@@ -192,4 +192,4 @@ what we expected here.
The `QuantityOf` and `QuantityPointOf` concepts are probably the most useful, but there
are a few more to play with. A list of all the concepts can be found in
[the "Basic Concepts" chapter](../basic_concepts).
[the "Basic Concepts" chapter](basic_concepts.md).

14
docs/users_guide/framework_basics/interface_introduction.md
View File

@@ -3,7 +3,7 @@
## New style of definitions
The **mp-units** library decided to use a rather unusual pattern to define entities.
Here is how we define `metre` and `second` [SI](../../../appendix/glossary/#si) base units:
Here is how we define `metre` and `second` [SI](../../appendix/glossary.md#si) base units:
```cpp
inline constexpr struct metre : named_unit<"m", kind_of<isq::length>> {} metre;
@@ -42,7 +42,7 @@ to improve the user experience while debugging the program or analyzing the comp
Many physical units libraries (in C++ or any other programming language) assign strong types
to library entities (i.e. derived units). While `metre_per_second` as a type may not look too
scary, consider, for example, units of angular momentum. If we followed this path, its
[coherent unit](../../../appendix/glossary/#coherent-derived-unit) would look like
[coherent unit](../../appendix/glossary.md#coherent-derived-unit) would look like
`kilogram_metre_sq_per_second`. Now, consider how many scaled versions of this unit would you
predefine in the library to ensure that all users are happy with your choice?
How expensive would it be from the implementation point of view?
@@ -90,7 +90,7 @@ what we have to deal with when we want to write some equations for `std::ratio`.
For example, below are a few definitions of the SI derived units showing the power of C++20
extensions to Non-Type Template Parameters, which allows us to directly pass a result of
the value-based [unit equation](../../../appendix/glossary/#unit-equation) to a class template
the value-based [unit equation](../../appendix/glossary.md#unit-equation) to a class template
definition:
```cpp
@@ -110,12 +110,12 @@ The **mp-units** library greatly improves the user experience by extensively usi
expression templates. Such expressions are used consistently throughout the entire library
to describe the results of:
- [dimension equation](../../../appendix/glossary/#dimension-equation) - the result is put into
- [dimension equation](../../appendix/glossary.md#dimension-equation) - the result is put into
the `derived_dimension<>` class template
- [quantity equation](../../../appendix/glossary/#quantity-equation) - the result is put into
- [quantity equation](../../appendix/glossary.md#quantity-equation) - the result is put into
the `derived_quantity_spec<>` class template
- [unit equation](../../../appendix/glossary/#unit-equation) - the result is put into
the `derived_unit<>` class template
- [unit equation](../../appendix/glossary.md#unit-equation) - the result is put into the
`derived_unit<>` class template
For example, if we take the above-defined base units and put the results of their division into
the quantity class template like this:

20
docs/users_guide/framework_basics/systems_of_quantities.md
View File

@@ -1,14 +1,14 @@
# Systems of Quantities
The physical units libraries on the market typically only scope on modeling one or more
[systems of units](../../../appendix/glossary/#system-of-units). However, this is not the
[systems of units](../../appendix/glossary.md#system-of-units). However, this is not the
only system kind to model. Another, and maybe even more important, system kind is a
[system of quantities](../../../appendix/glossary/#system-of-quantities).
[system of quantities](../../appendix/glossary.md#system-of-quantities).
!!! info
Please note that the **mp-units** is probably the first library on the Open Source market
(in any programming language) that models the [ISQ](../../../appendix/glossary/#isq)
(in any programming language) that models the [ISQ](../../appendix/glossary.md#isq)
with all its definitions provided in ISO 80000. Please provide feedback if something
looks odd or could be improved.
@@ -55,12 +55,12 @@ physical properties.
!!! info
More than one quantity may be defined for the same dimension:
- quantities of _different kinds_ (i.e. frequency, modulation rate, activity, ...)
- quantities of _the same kind_ (i.e. length, width, altitude, distance, radius, wavelength, position vector, ...)
It turns out that the above issues can't be solved correctly without proper modeling of
a [system of quantities](../../../appendix/glossary/#system-of-quantities).
a [system of quantities](../../appendix/glossary.md#system-of-quantities).
## Quantities of the same kind
@@ -77,7 +77,7 @@ a [system of quantities](../../../appendix/glossary/#system-of-quantities).
- Quantities of the **same dimension are not necessarily of the same kind**
The above quotes from ISO 80000 answer to all the issues above. Two quantities can't be
added, subtracted, or compared unless they belong to the same [kind](../../../appendix/glossary/#kind).
added, subtracted, or compared unless they belong to the same [kind](../../appendix/glossary.md#kind).
As frequency, activity, and modulation rate are different kinds, the expression provided above should
not compile.
@@ -190,7 +190,7 @@ For example, here is how the above quantity kind tree can be modeled in the libr
!!! note
More information on how to define a system of quantities can be found in the
["International System of Quantities (ISQ)"](../../defining_systems/isq) chapter.
["International System of Quantities (ISQ)"](../defining_systems/isq.md) chapter.
## Comparing, adding, and subtracting quantities
@@ -289,7 +289,7 @@ flowchart TD
```
Notice, that even though all of those quantities have the same dimension and can be expressed
in the same units, they have different [quantity equations](../../../appendix/glossary/#quantity-equation)
in the same units, they have different [quantity equations](../../appendix/glossary.md#quantity-equation)
used to create them implicitly:
- `energy` is the most generic one and thus can be created from base quantities of `mass`, `length`,
@@ -304,7 +304,7 @@ used to create them implicitly:
- `mechanical_energy` is a more "specialized" quantity than `energy` (not every `energy` is
a `mechanical_energy`). It is why an explicit cast is needed to convert from either `energy` or
the results of its [quantity equation](../../../appendix/glossary/#quantity-equation).
the results of its [quantity equation](../../appendix/glossary.md#quantity-equation).
```cpp
static_assert(!implicitly_convertible(isq::energy, isq::mechanical_energy));
@@ -317,7 +317,7 @@ used to create them implicitly:
- `gravitational_potential_energy` is not only even more specialized one but additionally,
it is special in a way that it provides its own "constrained"
[quantity equation](../../../appendix/glossary/#quantity-equation). Maybe not every
[quantity equation](../../appendix/glossary.md#quantity-equation). Maybe not every
`mass * pow<2>(length) / pow<2>(time)` is a `gravitational_potential_energy`, but every
`mass * acceleration_of_free_fall * height` is.

43
docs/users_guide/framework_basics/systems_of_units.md
View File

@@ -1,27 +1,27 @@
# Systems of Units
Modeling a [system of units](../../../appendix/glossary/#system-of-units) is probably
Modeling a [system of units](../../appendix/glossary.md#system-of-units) is probably
the most important feature and a selling point of every physical units library.
Thanks to that, the library can protect users from performing invalid operations on
quantities and provide automated conversion factors between various compatible units.
Probably all the libraries in the wild model the [SI](../../../appendix/glossary/#si)
Probably all the libraries in the wild model the [SI](../../appendix/glossary.md#si)
and many of them provide support for additional units belonging to various other systems
(i.e. imperial).
## Systems of Units are based on Systems of Quantities
[Systems of quantities](../../../appendix/glossary/#system-of-quantities) specify a set
[Systems of quantities](../../appendix/glossary.md#system-of-quantities) specify a set
of quantities and equations relating to those quantities. Those equations do not take any
unit or a numerical representation into account at all. In order to create a quantity,
we need to add those missing pieces of information. This is where
a [system of units](../../../appendix/glossary/#system-of-units) kicks in.
a [system of units](../../appendix/glossary.md#system-of-units) kicks in.
The [SI](../../../appendix/glossary/#si) is explicitly stated to be based on
the [ISQ](../../../appendix/glossary/#isq). Among others, it defines
`7` [base units](../../../appendix/glossary/#base-unit), one for each
[base quantity](../../../appendix/glossary/#base-quantity). In the **mp-units**
The [SI](../../appendix/glossary.md#si) is explicitly stated to be based on
the [ISQ](../../appendix/glossary.md#isq). Among others, it defines
`7` [base units](../../appendix/glossary.md#base-unit), one for each
[base quantity](../../appendix/glossary.md#base-quantity). In the **mp-units**
this is expressed by associating a quantity kind (that we discussed in detail in the
previous chapter) with a unit that is used to express it:
@@ -38,32 +38,32 @@ inline constexpr struct metre : named_unit<"m", kind_of<isq::length>> {} metre;
## Units compose
One of the strongest points of the [SI](../../../appendix/glossary/#si) system
One of the strongest points of the [SI](../../appendix/glossary.md#si) system
is that its units compose. This allows providing thousands of different units for
hundreds of various quantities with a really small set of predefined units
and prefixes.
The same is modeled in the **mp-units** library, which also allows composing
predefined units to create a nearly infinite number of different
[derived units](../../../appendix/glossary/#derived-unit). For example, one can write:
[derived units](../../appendix/glossary.md#derived-unit). For example, one can write:
```cpp
quantity<si::metre / si::second> q;
```
to express a quantity of speed. The resulting quantity type is implicitly inferred
from the [unit equation](../../../appendix/glossary/#unit-equation) by repeating
from the [unit equation](../../appendix/glossary.md#unit-equation) by repeating
exactly the same operations on the associated quantity kinds.
## Many shades of the same unit
The [SI](../../../appendix/glossary/#si) provides the names for 22 common
[coherent units](../../../appendix/glossary/#coherent-derived-unit) of 22
[derived quantities](../../../appendix/glossary/#derived-quantity).
The [SI](../../appendix/glossary.md#si) provides the names for 22 common
[coherent units](../../appendix/glossary.md#coherent-derived-unit) of 22
[derived quantities](../../appendix/glossary.md#derived-quantity).
Each such named [derived unit](../../../appendix/glossary/#derived-unit) is a result
of a specific predefined [unit equation](../../../appendix/glossary/#unit-equation).
Each such named [derived unit](../../appendix/glossary.md#derived-unit) is a result
of a specific predefined [unit equation](../../appendix/glossary.md#unit-equation).
For example, a unit of power quantity is defined in the library as:
```cpp
@@ -123,7 +123,7 @@ This is exactly what we wanted to achieve to improve the type-safety of the libr
## Prefixed units
Besides named units, the [SI](../../../appendix/glossary/#si) specifies also 24 prefixes
Besides named units, the [SI](../../appendix/glossary.md#si) specifies also 24 prefixes
(all being a power of `10`) that can be prepended to all named units to obtain various scaled
versions of them.
@@ -138,7 +138,7 @@ template<PrefixableUnit auto U> struct quecto_ : prefixed_unit<"q", mag_power<10
template<PrefixableUnit auto U> inline constexpr quecto_<U> quecto;
```
and then a [PrefixableUnit](../basic_concepts/#prefixableunit) can be prefixed in the following
and then a [PrefixableUnit](basic_concepts.md#prefixableunit) can be prefixed in the following
way:
```cpp
@@ -156,10 +156,10 @@ template<PrefixableUnit auto U> inline constexpr yobi_<U> yobi;
## Scaled units
In the [SI](../../../appendix/glossary/#si), all units are either base or derived units or prefixed
In the [SI](../../appendix/glossary.md#si), all units are either base or derived units or prefixed
versions of those. However, those are not the only options possible.
For example, there is a list of [off-system units](../../../appendix/glossary/#off-system-unit)
For example, there is a list of [off-system units](../../appendix/glossary.md#off-system-unit)
accepted for use with SI. All of those are scaled versions of the SI units with ratios that can't
be explicitly expressed with predefined SI prefixes. Those include units like minute, hour, or
electronvolt:
@@ -170,7 +170,7 @@ inline constexpr struct hour : named_unit<"h", mag<60> * minute> {} hour;
inline constexpr struct electronvolt : named_unit<"eV", mag<ratio{1'602'176'634, 1'000'000'000}> * mag_power<10, -19> * si::joule> {} electronvolt;
```
Also, units of other [systems of units](../../../appendix/glossary/#system-of-units) are often defined
Also, units of other [systems of units](../../appendix/glossary.md#system-of-units) are often defined
in terms of scaled versions of the SI units. For example, the international yard is defined as:
```cpp
@@ -187,4 +187,3 @@ inline constexpr struct mag_pi : magnitude<std::numbers::pi_v<long double>> {} m
```cpp
inline constexpr struct degree : named_unit<basic_symbol_text{"°", "deg"}, mag_pi / mag<180> * si::radian> {} degree;
```

16
docs/users_guide/framework_basics/text_output.md
View File

@@ -10,7 +10,7 @@ any quantity in the most user-friendly way.
For example, the text output of `42 m` may mean many things and can also be confused with
an output of a regular quantity. On the other hand, printing `42 m AMSL` for altitudes above
mean sea level is a much better solution, but the library does not have enough information
to print it that way.
to print it that way.
## Output Streams
@@ -33,14 +33,14 @@ std::cout << v1 << '\n'; // 110 km/h
std::cout << v2 << '\n'; // 70 mi/h
```
The text output will always print the [value of a quantity](../../../appendix/glossary/#quantity-value)
typically followed by a space and then the symbol of a [unit](../../../appendix/glossary/#unit)
The text output will always print the [value of a quantity](../../appendix/glossary.md#quantity-value)
typically followed by a space and then the symbol of a [unit](../../appendix/glossary.md#unit)
associated with this quantity.
!!! note
Remember that when we deal with a quantity of an "unknown" `auto` type, it is a good practice
to always [convert the unit to the expected one](../value_conversions/#value-conversions)
to always [convert the unit to the expected one](value_conversions.md#value-conversions)
before passing it to the text output:
```cpp
@@ -100,7 +100,7 @@ In the above grammar:
- tokens `Q` and `q` of `units-type` are described in the [time.format](https://wg21.link/time.format)
chapter of the C++ standard specification,
- `units-text-encoding` tokens specify the unit text encoding:
- `U` (default) uses the **Unicode** symbols defined by the [SI](../../../appendix/glossary/#si)
- `U` (default) uses the **Unicode** symbols defined by the [SI](../../appendix/glossary.md#si)
specification (i.e. `m³`, `µs`)
- `A` token forces non-standard **ASCII**-only output (i.e. `m^3`, `us`)
- `units-unit-symbol-solidus` tokens specify how the division of units should look like:
@@ -147,7 +147,7 @@ std::println("|{:*^10}|", 123 * m); // |**123 m***|
[`std::println` is a C++23 facility](https://en.cppreference.com/w/cpp/io/print). In case you
do not have access to C++23, you can obtain the same output with:
```cpp
std::cout << std::format("<format-string>\n", <format-args>);
```
@@ -237,7 +237,7 @@ std::println("{:%.3GQ %q}", 1.2345678e8 * m); // 1.23E+08 m
### Unit symbol formatting
Unit symbols of some quantities are specified to use Unicode signs by the
[SI](../../../appendix/glossary/#si) (i.e. `Ω` symbol for the resistance quantity). The **mp-units**
[SI](../../appendix/glossary.md#si) (i.e. `Ω` symbol for the resistance quantity). The **mp-units**
library follows this by default. From the engineering point of view, sometimes Unicode text might
not be the best solution as terminals of many (especially embedded) devices are ASCII-only.
In such a case, the unit symbol can be forced to be printed using ASCII-only characters thanks to
@@ -252,7 +252,7 @@ std::println("{}", 9.8 * (m / s2)); // 9.8 m/s²
std::println("{:%Q %Aq}", 9.8 * (m / s2)); // 9.8 m/s^2
```
Additionally, both [ISQ](../../../appendix/glossary/#isq) and [SI](../../../appendix/glossary/#si)
Additionally, both [ISQ](../../appendix/glossary.md#isq) and [SI](../../appendix/glossary.md#si)
leave some freedom on how to print unit symbols. This is why two additional tokens were introduced.
`units-unit-symbol-solidus` specifies how the division of units should look like. By default,

4
docs/users_guide/framework_basics/the_affine_space.md
View File

@@ -10,7 +10,7 @@ The affine space has two types of entities:
The _vector_ described here is specific to the affine space theory and is not the same thing
as the quantity of a vector character that we discussed in the
["Scalars, vectors, and tensors" chapter](character_of_a_quantity/#scalars-vectors-and-tensors)
["Scalars, vectors, and tensors" chapter](character_of_a_quantity.md#scalars-vectors-and-tensors)
(although, in some cases, those terms may overlap).
@@ -63,7 +63,7 @@ class quantity_point;
```
As we can see above, the `quantity_point` class template exposes one additional parameter compared
to `quantity`. The `PO` parameter satisfies a [`PointOriginFor` concept](../basic_concepts/#pointoriginfor)
to `quantity`. The `PO` parameter satisfies a [`PointOriginFor` concept](basic_concepts.md#pointoriginfor)
and specifies the origin of our scale.

4
docs/users_guide/terms_and_definitions.md
View File

@@ -2,11 +2,11 @@
The **mp-units** project consistently uses the official metrology vocabulary defined by
the ISO and BIPM. You can find essential project-related definitions in
[our documentation's "Glossary" chapter](../../appendix/glossary).
[our documentation's "Glossary" chapter](../appendix/glossary.md).
Even more, terms are provided in the official vocabulary of the [ISO](https://www.iso.org/obp/ui#iso:std:iso-iec:guide:99:ed-1:v2:en)
and [BIPM](https://jcgm.bipm.org/vim/en).
!!! tip
Please familiarize yourself with terms from ["Glossary"](../../appendix/glossary) to
Please familiarize yourself with terms from ["Glossary"](../appendix/glossary.md) to
better understand the documentation and improve domain-related communication and discussions.