diff --git a/docs/getting_started/faq.md b/docs/getting_started/faq.md index 157bc711..f70c9310 100644 --- a/docs/getting_started/faq.md +++ b/docs/getting_started/faq.md @@ -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 diff --git a/docs/getting_started/installation_and_usage.md b/docs/getting_started/installation_and_usage.md index d4259d85..2e45a96b 100644 --- a/docs/getting_started/installation_and_usage.md +++ b/docs/getting_started/installation_and_usage.md @@ -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 diff --git a/docs/getting_started/introduction.md b/docs/getting_started/introduction.md index 23060c26..b27951e6 100644 --- a/docs/getting_started/introduction.md +++ b/docs/getting_started/introduction.md @@ -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
- No external dependencies (assuming full C++20 support)
- No macros in the user interface (besides portability and standard-compliance issues)
- 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 diff --git a/docs/getting_started/quick_start.md b/docs/getting_started/quick_start.md index 5addd99c..cb834224 100644 --- a/docs/getting_started/quick_start.md +++ b/docs/getting_started/quick_start.md @@ -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`. 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). diff --git a/docs/users_guide/framework_basics/basic_concepts.md b/docs/users_guide/framework_basics/basic_concepts.md index 574b8592..172160c6 100644 --- a/docs/users_guide/framework_basics/basic_concepts.md +++ b/docs/users_guide/framework_basics/basic_concepts.md @@ -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` 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>` 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` 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>` 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` { #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` 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` { #representationof } `RepresentationOf` 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`](#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` diff --git a/docs/users_guide/framework_basics/character_of_a_quantity.md b/docs/users_guide/framework_basics/character_of_a_quantity.md index 9cbb835c..aab134aa 100644 --- a/docs/users_guide/framework_basics/character_of_a_quantity.md +++ b/docs/users_guide/framework_basics/character_of_a_quantity.md @@ -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(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 diff --git a/docs/users_guide/framework_basics/generic_interfaces.md b/docs/users_guide/framework_basics/generic_interfaces.md index 3ee4c600..1d73f29e 100644 --- a/docs/users_guide/framework_basics/generic_interfaces.md +++ b/docs/users_guide/framework_basics/generic_interfaces.md @@ -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 s2 = avg_speed(value_cast(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 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). diff --git a/docs/users_guide/framework_basics/interface_introduction.md b/docs/users_guide/framework_basics/interface_introduction.md index cc389e84..e85b1ceb 100644 --- a/docs/users_guide/framework_basics/interface_introduction.md +++ b/docs/users_guide/framework_basics/interface_introduction.md @@ -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> {} 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: diff --git a/docs/users_guide/framework_basics/systems_of_quantities.md b/docs/users_guide/framework_basics/systems_of_quantities.md index bf334e53..79b21ca9 100644 --- a/docs/users_guide/framework_basics/systems_of_quantities.md +++ b/docs/users_guide/framework_basics/systems_of_quantities.md @@ -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. diff --git a/docs/users_guide/framework_basics/systems_of_units.md b/docs/users_guide/framework_basics/systems_of_units.md index f5cf912c..073019d0 100644 --- a/docs/users_guide/framework_basics/systems_of_units.md +++ b/docs/users_guide/framework_basics/systems_of_units.md @@ -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> {} 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 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 struct quecto_ : prefixed_unit<"q", mag_power<10 template inline constexpr quecto_ 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 inline constexpr yobi_ 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 * 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> {} m ```cpp inline constexpr struct degree : named_unit * si::radian> {} degree; ``` - diff --git a/docs/users_guide/framework_basics/text_output.md b/docs/users_guide/framework_basics/text_output.md index 4e78d0b6..0c2bf168 100644 --- a/docs/users_guide/framework_basics/text_output.md +++ b/docs/users_guide/framework_basics/text_output.md @@ -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("\n", ); ``` @@ -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, diff --git a/docs/users_guide/framework_basics/the_affine_space.md b/docs/users_guide/framework_basics/the_affine_space.md index 95873286..9189769a 100644 --- a/docs/users_guide/framework_basics/the_affine_space.md +++ b/docs/users_guide/framework_basics/the_affine_space.md @@ -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. diff --git a/docs/users_guide/terms_and_definitions.md b/docs/users_guide/terms_and_definitions.md index bc4eb0d0..3a8e4b1c 100644 --- a/docs/users_guide/terms_and_definitions.md +++ b/docs/users_guide/terms_and_definitions.md @@ -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.