mirror of
https://github.com/mpusz/mp-units.git
synced 2026-05-05 12:24:15 +02:00
docs: "Concepts" chapter improved
This commit is contained in:
Mateusz Pusz
@@ -1,61 +1,59 @@
|
||||
# Concepts
|
||||
|
||||
This chapter enumerates all the user-facing concepts in the **mp-units** library.
|
||||
This chapter enumerates all user-facing concepts in **mp-units**.
|
||||
|
||||
|
||||
## `Dimension<T>` { #Dimension }
|
||||
|
||||
`Dimension` concept matches a [dimension](../../appendix/glossary.md#dimension) of either a base
|
||||
or derived [quantity](../../appendix/glossary.md#quantity):
|
||||
`Dimension` matches a [dimension](../../appendix/glossary.md#dimension) of either a base or
|
||||
derived [quantity](../../appendix/glossary.md#quantity):
|
||||
|
||||
- [Base dimensions](../../appendix/glossary.md#base-dimension) are explicitly defined by the 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.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).
|
||||
- [Base dimensions](../../appendix/glossary.md#base-dimension) are explicitly defined by
|
||||
inheriting from a `base_dimension` instantiation with a unique symbol identifier for a
|
||||
specific [system of quantities](../../appendix/glossary.md#system-of-quantities).
|
||||
- [Derived dimensions](../../appendix/glossary.md#derived-dimension) are implicitly created by
|
||||
the framework from a [quantity equation](../../appendix/glossary.md#quantity-equation)
|
||||
provided in a [quantity specification](../../appendix/glossary.md#quantity_spec).
|
||||
|
||||
All of the above dimensions have to be marked as `final`.
|
||||
|
||||
|
||||
### `DimensionOf<T, V>` { #DimensionOf }
|
||||
|
||||
`DimensionOf` concept is satisfied when both arguments satisfy a [`Dimension`](#Dimension) concept and
|
||||
when they compare equal.
|
||||
`DimensionOf` is satisfied when both arguments satisfy [`Dimension`](#Dimension)
|
||||
and they compare equal.
|
||||
|
||||
|
||||
## `QuantitySpec<T>` { #QuantitySpec }
|
||||
|
||||
`QuantitySpec` concept matches all the [quantity specifications](../../appendix/glossary.md#quantity_spec)
|
||||
`QuantitySpec` matches all [quantity specifications](../../appendix/glossary.md#quantity_spec),
|
||||
including:
|
||||
|
||||
- [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.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.md#quantity-equation) passed as an argument.
|
||||
- [Base quantities](../../appendix/glossary.md#base-quantity) defined by inheriting from
|
||||
`quantity_spec<base_dimension>`.
|
||||
- [Derived named quantities](../../appendix/glossary.md#derived-quantity) defined by inheriting
|
||||
from `quantity_spec` instantiated with a [quantity equation](../../appendix/glossary.md#quantity-equation).
|
||||
- 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.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.
|
||||
of the same [kind](../../appendix/glossary.md#kind) defined by passing parent `quantity_spec`
|
||||
instantiation as an argument.
|
||||
- [Quantity kinds](../../appendix/glossary.md#kind) describing a family of mutually comparable
|
||||
quantities.
|
||||
- Intermediate [derived quantity](../../appendix/glossary.md#derived-quantity) specifications
|
||||
produced by a [quantity equation](../../appendix/glossary.md#quantity-equation) on other
|
||||
specifications.
|
||||
|
||||
All of the above quantity specifications have to be marked as `final`.
|
||||
|
||||
|
||||
### `QuantitySpecOf<T, V>` { #QuantitySpecOf }
|
||||
|
||||
`QuantitySpecOf` concept is satisfied when both arguments satisfy a [`QuantitySpec`](#QuantitySpec) concept
|
||||
and when `T` is implicitly convertible to `V`.
|
||||
`QuantitySpecOf` is satisfied when both arguments satisfy [`QuantitySpec`](#QuantitySpec) and
|
||||
`T` is implicitly convertible to `V`.
|
||||
|
||||
|
||||
## `UnitMagnitude<T>` { #UnitMagnitude }
|
||||
|
||||
`UnitMagnitude` concept is satisfied by all types defining a unit magnitude.
|
||||
`UnitMagnitude` is satisfied by all types defining a unit magnitude.
|
||||
|
||||
!!! info
|
||||
|
||||
@@ -64,20 +62,19 @@ and when `T` is implicitly convertible to `V`.
|
||||
|
||||
## `Unit<T>` { #Unit }
|
||||
|
||||
`Unit` concept matches all the [units](../../appendix/glossary.md#unit) in the library including:
|
||||
`Unit` matches all [units](../../appendix/glossary.md#unit) in the library including:
|
||||
|
||||
- [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.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 prefix symbol, a magnitude, and a unit to be prefixed.
|
||||
- [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.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.
|
||||
- [Base units](../../appendix/glossary.md#base-unit) defined by inheriting from `named_unit`
|
||||
with a unique symbol identifier for a specific [system of units](../../appendix/glossary.md#system-of-units).
|
||||
- Named scaled units defined by inheriting from `named_unit` with a unique symbol
|
||||
identifier and the product of another unit and a magnitude.
|
||||
- Prefixed units defined by inheriting from `prefixed_unit` with a prefix symbol, a magnitude,
|
||||
and a base unit.
|
||||
- [Derived named units](../../appendix/glossary.md#derived-unit) defined by inheriting from
|
||||
`named_unit` with a unique symbol identifier and a
|
||||
[unit equation](../../appendix/glossary.md#unit-equation) result.
|
||||
- [Derived unnamed units](../../appendix/glossary.md#derived-unit) produced by a
|
||||
[unit equation](../../appendix/glossary.md#unit-equation) on other units.
|
||||
|
||||
All of the above units have to be marked as `final`.
|
||||
|
||||
@@ -88,12 +85,12 @@ All of the above units have to be marked as `final`.
|
||||
|
||||
### `AssociatedUnit<T>` { #AssociatedUnit }
|
||||
|
||||
`AssociatedUnit` concept describes a [unit with an associated quantity](../../appendix/glossary.md#associated-unit)
|
||||
`AssociatedUnit` 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) of a [quantity kind](../../appendix/glossary.md#kind).
|
||||
- All units being a result of [unit equations](../../appendix/glossary.md#unit-equation) on other
|
||||
- All units derived from `named_unit` instantiated with a unique symbol identifier and a
|
||||
[`QuantitySpec`](#QuantitySpec) of a [quantity kind](../../appendix/glossary.md#kind).
|
||||
- All units produced by [unit equations](../../appendix/glossary.md#unit-equation) on other
|
||||
associated units.
|
||||
|
||||
??? abstract "Examples"
|
||||
@@ -108,47 +105,45 @@ and is satisfied by:
|
||||
|
||||
### `PrefixableUnit<T>` { #PrefixableUnit }
|
||||
|
||||
`PrefixableUnit` concept is satisfied by all units derived from a `named_unit` class template.
|
||||
Such units can be passed as an argument to a `prefixed_unit` class template.
|
||||
`PrefixableUnit` is satisfied by all units derived from `named_unit`. Such units can be
|
||||
used as arguments to `prefixed_unit`.
|
||||
|
||||
|
||||
### `UnitOf<T, V>` { #UnitOf }
|
||||
|
||||
`UnitOf` concept is satisfied for all units `T` for which an associated quantity spec is implicitly
|
||||
convertible to the provided [`QuantitySpec`](#QuantitySpec) value.
|
||||
`UnitOf` is satisfied for all units `T` whose associated quantity spec is implicitly convertible
|
||||
to the provided [`QuantitySpec`](#QuantitySpec).
|
||||
|
||||
|
||||
## `Reference<T>` { #Reference }
|
||||
|
||||
`Reference` concept is satisfied by all [quantity reference](../../appendix/glossary.md#reference)
|
||||
types. Such types provide all the meta-information required to create a [`Quantity`](#Quantity).
|
||||
`Reference` is satisfied by all [quantity reference](../../appendix/glossary.md#reference)
|
||||
types. Such types provide the meta-information required to create a
|
||||
[`Quantity`](#Quantity).
|
||||
A `Reference` can either be:
|
||||
|
||||
- An [`AssociatedUnit`](#AssociatedUnit).
|
||||
- The instantiation of a `reference` class template with a [`QuantitySpec`](#QuantitySpec) passed as
|
||||
the first template argument and a [`Unit`](#Unit) passed as the second one.
|
||||
- An instantiation of `reference<QuantitySpec, Unit>`.
|
||||
|
||||
|
||||
### `ReferenceOf<T, V>` { #ReferenceOf }
|
||||
|
||||
`ReferenceOf` concept is satisfied by references `T` which have a quantity specification that satisfies
|
||||
[`QuantitySpecOf<V>`](#QuantitySpecOf) concept.
|
||||
`ReferenceOf` is satisfied by references `T` whose quantity specification satisfies
|
||||
[`QuantitySpecOf<V>`](#QuantitySpecOf).
|
||||
|
||||
|
||||
### `RepresentationOf<T, V>` { #RepresentationOf }
|
||||
|
||||
`RepresentationOf` concept constraints a type of a number that stores the
|
||||
`RepresentationOf` constrains a numeric type that stores the
|
||||
[value of a quantity](../../appendix/glossary.md#quantity-value) and is satisfied:
|
||||
|
||||
- if the type of `V` satisfies [`QuantitySpec`](#QuantitySpec):
|
||||
- if `V` satisfies [`QuantitySpec`](#QuantitySpec):
|
||||
|
||||
- by all representation types when `V` describes
|
||||
a [quantity kind](../../appendix/glossary.md#kind),
|
||||
- otherwise, by representation types that are of
|
||||
a [quantity character](../../appendix/glossary.md#character) associated with a provided
|
||||
quantity specification `V`.
|
||||
- all representation types when `V` is a [quantity kind](../../appendix/glossary.md#kind),
|
||||
- otherwise, representation types whose [quantity character](../../appendix/glossary.md#character)
|
||||
matches the specification `V`.
|
||||
|
||||
- if `V` is of `quantity_character` type:
|
||||
- if `V` is a `quantity_character`:
|
||||
|
||||
- by representation types that are of a provided
|
||||
[quantity character](../../appendix/glossary.md#character).
|
||||
@@ -156,24 +151,23 @@ A `Reference` can either be:
|
||||
|
||||
## `Quantity<T>` { #Quantity }
|
||||
|
||||
`Quantity` concept matches every [quantity](../../appendix/glossary.md#quantity) in the library and is
|
||||
satisfied by all types being or deriving from an instantiation of a `quantity` class template.
|
||||
`Quantity` matches every [quantity](../../appendix/glossary.md#quantity) and is satisfied by
|
||||
any type that is or derives from `quantity<...>`.
|
||||
|
||||
|
||||
### `QuantityOf<T, V>` { #QuantityOf }
|
||||
|
||||
`QuantityOf` concept is satisfied by all the quantities for which a [`ReferenceOf<V>`](#ReferenceOf)
|
||||
is `true`.
|
||||
`QuantityOf` is satisfied by all quantities for which [`ReferenceOf<V>`](#ReferenceOf) is `true`.
|
||||
|
||||
|
||||
### `QuantityLike<T>` { #QuantityLike }
|
||||
|
||||
`QuantityLike` concept provides interoperability with other libraries and is satisfied by a type `T`
|
||||
for which an instantiation of `quantity_like_traits` type trait yields a valid type that provides:
|
||||
`QuantityLike` enables interoperability with other libraries. A type `T` satisfies it if a
|
||||
`quantity_like_traits<T>` specialization provides:
|
||||
|
||||
- `reference` static data member that matches the [`Reference`](#Reference) concept,
|
||||
- `rep` type that matches [`RepresentationOf`](#RepresentationOf) concept with the character provided
|
||||
in `reference`,
|
||||
- `rep` type that matches [`RepresentationOf`](#RepresentationOf) concept with the character
|
||||
provided in `reference`,
|
||||
- `explicit_import` static data member convertible to `bool` that specifies that the conversion
|
||||
from `T` to a `quantity` type should happen explicitly (if `true`),
|
||||
- `explicit_export` static data member convertible to `bool` that specifies that the conversion
|
||||
@@ -211,8 +205,8 @@ for which an instantiation of `quantity_like_traits` type trait yields a valid t
|
||||
|
||||
## `PointOrigin<T>` { #PointOrigin }
|
||||
|
||||
`PointOrigin` concept matches all [quantity point origins](../../appendix/glossary.md#point-origin) in
|
||||
the library. It is satisfied by either:
|
||||
`PointOrigin` matches all [quantity point origins](../../appendix/glossary.md#point-origin).
|
||||
It is satisfied by either:
|
||||
|
||||
- All types derived from an `absolute_point_origin` class template.
|
||||
- All types derived from a `relative_point_origin` class template.
|
||||
@@ -220,9 +214,9 @@ the library. It is satisfied by either:
|
||||
|
||||
### `PointOriginFor<T, V>` { #PointOriginFor }
|
||||
|
||||
`PointOriginFor` concept is satisfied by all [`PointOrigin`](#PointOrigin) types that have quantity type
|
||||
implicitly convertible from quantity specification `V`, which means that `V` must satisfy
|
||||
[`QuantitySpecOf<T::quantity_spec>`](#QuantitySpecOf).
|
||||
`PointOriginFor` is satisfied by all [`PointOrigin`](#PointOrigin) types whose quantity type
|
||||
is implicitly convertible from quantity specification `V` (i.e. `V` satisfies
|
||||
[`QuantitySpecOf<T::quantity_spec>`](#QuantitySpecOf)).
|
||||
|
||||
??? abstract "Examples"
|
||||
|
||||
@@ -244,13 +238,13 @@ implicitly convertible from quantity specification `V`, which means that `V` mus
|
||||
|
||||
## `QuantityPoint<T>` { #QuantityPoint }
|
||||
|
||||
`QuantityPoint` concept is satisfied by all types being either a specialization or derived from `quantity_point`
|
||||
class template.
|
||||
`QuantityPoint` is satisfied by all types that are or derive from `quantity_point<...>`.
|
||||
|
||||
|
||||
### `QuantityPointOf<T, V>` { #QuantityPointOf }
|
||||
|
||||
`QuantityPointOf` concept is satisfied by all the quantity points `T` that match the following value `V`:
|
||||
`QuantityPointOf` concept is satisfied by all the quantity points `T` that match the
|
||||
following value `V`:
|
||||
|
||||
| `V` | Condition |
|
||||
|----------------|-----------------------------------------------------------------------------------------------|
|
||||
|
||||
Reference in New Issue
Block a user