mpusz/mp-units
1
0
Fork 1
mirror of https://github.com/mpusz/mp-units.git synced 2025-07-31 02:47:16 +02:00
Code Issues Packages Projects Releases Wiki Activity

docs: Documentation updated

Browse Source
This commit is contained in:
Mateusz Pusz
2021-02-16 16:19:57 +01:00
parent a8fccf0cb5
commit c641f1873f
28 changed files with 244 additions and 102 deletions
Download Patch File Download Diff File Expand all files Collapse all files

BIN
docs/_static/img/concepts.png vendored
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 58 KiB

After

Width:  |  Height:  |  Size: 165 KiB

4
docs/conf.py
View File

@ -294,6 +294,10 @@ nitpicky = True
# or ('envvar', 'LD_LIBRARY_PATH').
nitpick_ignore = []
# True to prefix each section label with the name of the document it is in,
# followed by a colon. Useful for avoiding ambiguity when the same section
# heading appears in different documents.
autosectionlabel_prefix_document = True
# -- C++ configuration ---------------------------------------------------

2
docs/design/directories.rst
View File

@ -57,7 +57,7 @@ Library Directories Structure
.. seealso::
More information on provided :term:`systems of units <system of units>` can be
found in :ref:`Systems` chapter.
found in :ref:`reference/systems:Systems` chapter.
.. important::

16
docs/faq.rst
View File

@ -39,7 +39,8 @@ of units of the same physical dimension between different systems.
.. seealso::
More details on this subject can be found in the :ref:`Custom Systems` chapter.
More details on this subject can be found in the
:ref:`use_cases/extensions:Custom Systems` chapter.
Why a dimensionless quantity is not just an fundamental arithmetic type?
@ -66,8 +67,8 @@ This is why it was decided to go with the current approach.
.. seealso::
More information on the current design can be found in :ref:`Dimensionless quantities`
chapter.
More information on the current design can be found in
the :ref:`framework/quantities:Dimensionless Quantities` chapter.
Why do we spell ``metre`` instead of ``meter``?
@ -114,7 +115,7 @@ to obey the rules and be consistent with ISO specifications.
.. seealso::
We do understand engineering reality and constraints and that is why the library
has the option of :ref:`ASCII-only quantity symbols`.
has the option of :ref:`framework/text_output:ASCII-only quantity symbols`.
Compilation Errors
@ -124,6 +125,7 @@ error: reference to ‘time’ is ambiguous
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Unfortunately, if `using-directives <https://en.cppreference.com/w/cpp/language/namespace#Using-directives>`_
(i.e. ``using namespace units::physical::si``) are being used, `units::physical::si::time` will
collide with C `time <https://en.cppreference.com/w/c/chrono/time>`_ function. In such a case the library's
``time`` function needs to be prefixed with at least one (or all) namespace names.
(i.e. ``using namespace units::physical::si``) are being used, `units::physical::si::time`
will collide with C `time <https://en.cppreference.com/w/c/chrono/time>`_ function. In
such a case the library's ``time`` function needs to be prefixed with at least one (or all)
namespace names.

2
docs/framework/basic_concepts.rst
View File

@ -45,7 +45,7 @@ The most important concepts in the library are `Unit`, `Dimension`,
[<abstract>PointKind]<-[QuantityPointKind]
[Kind]<-[PointKind]
[QuantityKind]-<[QuantityPointKind]
[QuantityKind]<-[QuantityPointKind]
`Unit` is a basic building block of the library. Every dimension works with
a concrete hierarchy of units. Such hierarchy defines a reference unit and

22
docs/framework/conversions_and_casting.rst
View File

@ -55,8 +55,7 @@ Implicit conversions are allowed only across quantities of the same dimension:
Explicit
--------
Explicit conversions are available with
the `quantity_cast`, `quantity_point_cast`,
Explicit conversions are available with the `quantity_cast`, `quantity_point_cast`,
`quantity_kind_cast`, and `quantity_point_kind_cast` function templates.
They are especially useful to force a truncating conversion across quantities of the same
dimension for integral representation types and ratios that may cause precision loss::
@ -66,9 +65,9 @@ dimension for integral representation types and ratios that may cause precision
.. seealso::
Explicit casts are also really useful when working with legacy interfaces. More
information on this subject can be found in :ref:`Working with Legacy Interfaces`
chapter.
Explicit casts are also really useful when working with legacy interfaces.
More information on this subject can be found in the
:ref:`use_cases/legacy_interfaces:Working with Legacy Interfaces` chapter.
Quantity Cast Overloads
^^^^^^^^^^^^^^^^^^^^^^^
@ -109,17 +108,18 @@ accept a `PointKind` and `Kind` instead of a `Dimension`, respectively.
.. seealso::
For more information on conversion and casting and on how to extend the above "integral"
vs "floating-point" logic please refer to the :ref:`Using Custom Representation Types`
chapter.
For more information on conversion and casting and on how to extend the above
"integral" vs "floating-point" logic please refer to the
:ref:`use_cases/custom_representation_types:Using Custom Representation Types` chapter.
Implicit conversions of dimensionless quantities
------------------------------------------------
As noted in the :ref:`Dimensionless Quantities` chapter, :term:`quantity of dimension one`
is somehow special but still obey most of the rules defined for quantities. However, as they
represent numbers it would be highly uncomfortable to every time type::
As noted in the :ref:`framework/quantities:Dimensionless Quantities` chapter,
:term:`quantity of dimension one` is somehow special but still obey most of the rules defined
for quantities. However, as they represent numbers it would be highly uncomfortable to every
time type::
const auto d1 = 10_q_km;
const auto d2 = 3_q_km;

70
docs/framework/dimensions.rst
View File

@ -8,8 +8,11 @@ In the previous chapter we briefly introduced the notion of a physical
Length, time, speed, area, energy are only a few examples of physical
dimensions.
Operations
----------
Arithmetics
-----------
Quantities
++++++++++
Quantities of the same dimension can be easily added or subtracted with
each other and the result will always be a quantity of the same dimension:
@ -61,24 +64,32 @@ dimension, than we will end up with just a dimensionless quantity:
Dimensionless auto v1 = dur1 / dur2; // quantity(5)
Dimensionless auto v2 = dur1 * fr1; // quantity(50)
Quantity kinds behave the same as quantities for addition, substraction, and
multiplication with, and division by a :term:`scalable number`.
Quantity Kinds
++++++++++++++
Multiplication and divison with a quantity
(but not a quantity kind) is allowed.
The result is a quantity kind with the appropiate dimension
and related to the original quantity kind.
Quantity kinds behave the same as quantities for addition and subtraction.
The same behavior is also provided for multiplication with, and division by
a :term:`scalable number`.
Multiplication and division with a quantity (but not a quantity kind) is allowed.
The result is a quantity kind with the appropriate dimension
and related to the original quantity kind:
.. code-block::
:emphasize-lines: 5-6
struct height : kind<height, dim_length> {};
struct rate_of_climb : derived_kind<rate_of_climb, height, dim_speed> {};
quantity_kind h(height{}, 100 * m);
quantity_point_kind rate = h / (25 * s);
// `quantity_point_kind<rate_of_climb, si::metre_per_second, int>(4 * m / s)`
// quantity_point_kind<rate_of_climb, si::metre_per_second, int>(4 * m / s)
Quantity Points
+++++++++++++++
Quantity points have a more restricted set of operations.
Quantity points can't be added together,
but can be added to or subtracted from quantities.
Quantity can be added to or subtracted from a quantity point.
The result will always be a quantity point of the same dimension:
.. code-block::
@ -90,17 +101,6 @@ The result will always be a quantity point of the same dimension:
QuantityPoint auto res2 = dist1 + quantity_point{dist2};
QuantityPoint auto res3 = quantity_point{dist1} - dist2;
.. note::
You can't subtract a quantity from a quantity point:
.. code-block::
:emphasize-lines: 3
Length auto dist1 = 2_q_m;
Length auto dist2 = 1_q_m;
auto res1 = dist1 - quantity_point{dist2}; // ERROR
We can also subtract two quantity points.
The result is a relative quantity of the same dimension:
@ -111,7 +111,25 @@ The result is a relative quantity of the same dimension:
Length auto dist2 = 1_q_m;
Length auto res1 = quantity_point{dist1} - quantity_point{dist2};
That's it! You can't multiply nor divide quantity points with anything else.
.. note::
It is not allowed to:
- add quantity points
- subtract a quantity point from a quantity:
- multiply nor divide quantity points with anything else.
.. code-block::
:emphasize-lines: 3-5
Length auto dist1 = 2_q_m;
Length auto dist2 = 1_q_m;
auto res1 = quantity_point{dist1} + quantity_point{dist2}; // ERROR
auto res2 = dist1 - quantity_point{dist2}; // ERROR
auto res3 = quantity_point{dist1} / 2_q_s; // ERROR
Quantity Point Kinds
++++++++++++++++++++
The same restrictions of a quantity point with respect to its quantity
apply to a quantity point kind with respect to its quantity kind.
@ -185,7 +203,8 @@ an dimension's unnamed unit symbol is being printed in the text output.
.. seealso::
More information on how the :term:`recipe` affect the printed symbol
of unnamed unit can be found in the :ref:`Derived Unnamed Units` chapter.
of unnamed unit can be found in the :ref:`framework/units:Derived Unnamed Units`
chapter.
It is important to mention here that beside text output the order and
the number of elements in the `derived_dimension` definition does not
@ -213,7 +232,8 @@ analysis in the library to work as expected.
child class inherited from the instantiation of this `derived_dimension`
class template. This is called a
:abbr:`CRTP (Curiously Recurring Template Parameter)` Idiom and is used
in many places in this library to provide :ref:`The Downcasting Facility`.
in many places in this library to provide
:ref:`design/downcasting:The Downcasting Facility`.
Hopefully if [P0847]_ will land in C++23 the additional CRTP-related
template parameter will be removed from this definition.

17
docs/framework/quantities.rst
View File

@ -7,7 +7,6 @@ A :term:`quantity` is a concrete amount of a unit for a specified dimension
with a specific representation and is represented in the library with a
`quantity` class template.
.. _quantity-construction:
Construction
------------
@ -198,6 +197,7 @@ The above code can be fixed in one of the below ways:
inline constexpr auto km_per_h = km / h;
Speed auto v = 220 / 2 * km_per_h;
Dimension-specific Concepts
---------------------------
@ -266,8 +266,8 @@ units like CGS.
.. seealso::
Please refer to :ref:`avg_speed` example for more information on different
kinds of interfaces supported by the library.
Please refer to :ref:`examples/avg_speed:avg_speed` example for more
information on different kinds of interfaces supported by the library.
Working With Constrained Deduced Quantity Types
@ -295,8 +295,8 @@ but often we would like to know a specific type too. We have two options here:
.. seealso::
More information on this subject can be found in :ref:`Conversions and Casting`
chapter.
More information on this subject can be found in the
:ref:`framework/conversions_and_casting:Conversions and Casting` chapter.
Dimensionless Quantities
@ -315,7 +315,7 @@ are zero".
.. seealso::
Reasoning for the above design is provided in
:ref:`Why a dimensionless quantity is not just an fundamental arithmetic type?`
:ref:`faq:Why a dimensionless quantity is not just an fundamental arithmetic type?`
To simplify the usage of the dimensionless quantity a following concept and alias template
are provided::
@ -351,5 +351,6 @@ is expressed as a ratio of kilometers and megaparsecs.
.. seealso::
More information on dimensionless quantities can be found in
:ref:`Implicit conversions of dimensionless quantities`.
More information on dimensionless quantities can be found in the
:ref:`framework/conversions_and_casting:Implicit conversions of dimensionless quantities`
chapter.

31
docs/framework/quantity_kinds.rst
View File

@ -7,16 +7,14 @@ A quantity kind is a quantity of more specific usage.
It is represented in the library with a `quantity_kind` class template.
.. _quantity-point-construction:
Kind creation
Kind Creation
-------------
We need a `kind` to represent the more specific usage of a quantity::
struct radius : kind<radius, si::dim_length> {};
Quantities of kind `radius` represent a radius.
Quantities of kind ``radius`` represent a radius.
They are clearly distinct from more generic usages of length quantities.
@ -40,23 +38,26 @@ the value to the `quantity_kind` class template constructor::
quantity_kind<radius, si::kilometre, double> d = 123 * km; // ERROR
Differences to quantity
Differences To Quantity
-----------------------
Unlike `quantity`, the library provides:
- no kinds, such as ``radius`` or ``width``, therefore
* no UDLs or unit constants,
* no kind-specific concepts, such as ``Radius``,
(there's the generic `QuantityKind` and kind-specifiable `QuantityKindOf`),
- a slightly different set of operations on quantity kinds
(see the :ref:`Dimensions` chapter).
(see the :ref:`framework/dimensions:Quantity Kinds` chapter).
Quantity point kind
-------------------
A quantity point kind is the analogous of a quantity point for quantity kinds.
(see the :ref:`Quantity Points` chapter).
Quantity Point Kinds
--------------------
A quantity point kind is the analogous of a quantity point for quantity kinds
(see the :ref:`framework/quantity_points:Quantity Points` chapter).
They are represented in the library with a `quantity_point_kind` class template.
@ -67,6 +68,10 @@ First, we need a `point_kind` for a `kind`::
Now ``x`` coordinates can be constructed::
quantity_point_kind<x_coordinate, si::metre, int> auto x_pos(123 * m);
// `QuantityPointKindOf<x_coordinate>` with `x_pos.relative()`
// equal to `quantity_kind<width, si::metre, int>(123 * m)`
quantity_point_kind<x_coordinate, si::metre, int> auto x_pos(123 * m); // QuantityPointKindOf<x_coordinate>
auto x = x_pos.relative(); // quantity_kind<width, si::metre, int>(123 * m)
.. seealso::
Please refer to :ref:`examples/glide_computer:glide_computer` example for more
information on the quantity kinds usage.

6
docs/framework/quantity_points.rst
View File

@ -8,8 +8,6 @@ A quantity point is an absolute quantity with respect to zero
`quantity_point` class template.
.. _quantity-point-construction:
Construction
------------
@ -30,7 +28,7 @@ the value to the `quantity_point` class template explicit constructor::
quantity_point<si::dim_length, si::kilometre, double> d = 123_q_km; // ERROR
Differences to quantity
Differences To Quantity
-----------------------
Unlike `quantity`, the library provides:
@ -40,4 +38,4 @@ Unlike `quantity`, the library provides:
- no dimension-specific concepts, such as ``LengthPoint``
(there's the dimension-agnostic `QuantityPoint`),
- a more limited set of operations on quantity points
(see the :ref:`Dimensions` chapter)
(see the :ref:`framework/dimensions:Quantity Points` chapter)

7
docs/framework/text_output.rst
View File

@ -16,8 +16,7 @@ Output Streams
.. tip::
The streaming support is provided via the ``<units/quantity_io.h>`` header
file.
The streaming support is provided via the ``<units/quantity_io.h>`` header file.
The easiest way to print a quantity is to provide its object to the output
stream::
@ -55,6 +54,10 @@ over width, fill, and alignment::
fmt::format
-----------
.. tip::
The text formatting support is provided via the ``<units/format.h>`` header file.
The **mp-units** via ``fmt::format`` provides a fine-grained control over what
and how is being printed on the text output.

9
docs/framework/units.rst
View File

@ -57,7 +57,8 @@ definitions of prefixed units using ``si::metre`` as a reference (i.e.
child class inherited from the instantiation of this `named_unit`
class template. This is called a
:abbr:`CRTP (Curiously Recurring Template Parameter)` Idiom and is used
in many places in this library to provide :ref:`The Downcasting Facility`.
in many places in this library to provide
:ref:`design/downcasting:The Downcasting Facility`.
Hopefully if [P0847]_ will land in C++23 the additional CRTP-related
template parameter will be removed from this definition.
@ -90,7 +91,7 @@ knows how to convert ``si::metre`` to ``si::centimetre`` and vice versa).
More details on custom systems definitions and conversions between
units of the same physical dimension can be found in the
:ref:`Custom Systems` chapter.
:ref:`use_cases/extensions:Custom Systems` chapter.
Derived Units
@ -399,5 +400,5 @@ type here instead.
.. seealso::
To learn more about unknown units please refer to
:ref:`Working with Unknown Dimensions and Their Units` chapter.
To learn more about unknown units please refer to the
:ref:`use_cases/unknown_dimensions:Working with Unknown Dimensions and Their Units` chapter.

4
docs/introduction.rst
View File

@ -14,7 +14,7 @@ general facility for unit conversions.
The library architecture has been designed with flexibility and extensibility
in mind. The demonstrations of the ease of adding new dimensions, their units,
and unit conversions are provided in the :ref:`Examples`.
and unit conversions are provided in the :ref:`examples:Examples`.
Open Source
-----------
@ -61,7 +61,7 @@ To achieve this goal several techniques are applied:
- usage of C++20 concepts,
- using strong types for framework entities (instead of type aliases),
- limiting the number of template arguments to the bare minimum,
- :ref:`The Downcasting Facility`.
- :ref:`design/downcasting:The Downcasting Facility`.
.. important::

2
docs/quick_start.rst
View File

@ -76,4 +76,4 @@ of basic library features::
.. seealso::
You can find more code examples in the :ref:`Examples` chapter.
You can find more code examples in the :ref:`examples:Examples` chapter.

69
docs/reference/core/concepts.rst
View File

@ -14,7 +14,7 @@ Concepts
.. concept:: template<typename T> Prefix
A concept matching a symbol prefix. Satisfied by all instantiations of :class:`prefix`.
A concept matching a symbol prefix. Satisfied by all instantiations of :struct:`prefix`.
.. concept:: template<ratio R> UnitRatio
@ -71,13 +71,13 @@ Concepts
.. concept:: template<typename T> QuantityValue
A concept matching types that can be used as a `Quantity` representation type. Satisfied
by types that match :expr:`(!Quantity<T>) && (!QuantityLike<T>) && (!WrappedQuantity<T>) && std::regular<T>`
by types that match ``(!Quantity<T>) && (!QuantityLike<T>) && (!WrappedQuantity<T>) && std::regular<T>``
and satisfy one of the following:
- if :expr:`common_type_with<T, std::intmax_t>` is ``true``, then :expr:`std::common_type_t<T, std::intmax_t>`
- if ``common_type_with<T, std::intmax_t>`` is ``true``, then ``std::common_type_t<T, std::intmax_t>``
must at least provide binary multiplication and division operators,
- otherwise, :expr:`T::value_type` must be valid, :expr:`common_type_with<T::value_type, std::intmax_t>` be
``true``, and :expr:`std::common_type_t<T::value_type, std::intmax_t>` must at least provide binary
- otherwise, ``T::value_type`` must be valid, ``common_type_with<T::value_type, std::intmax_t>`` be
``true``, and ``std::common_type_t<T::value_type, std::intmax_t>`` must at least provide binary
multiplication and division operators with itself and ``T``.
.. concept:: template<typename T> QuantityPoint
@ -85,6 +85,26 @@ Concepts
A concept matching all quantity points in the library. Satisfied by all instantiations of
:class:`quantity_point`.
.. concept:: template<typename T> Kind
A concept matching all kind types. Satisfied by all kind types derived from an specialization of
:class:`kind`.
.. concept:: template<typename T> PointKind
A concept matching all point kind types. Satisfied by all point kind types derived from an specialization of
:class:`point_kind`.
.. concept:: template<typename T> QuantityKind
A concept matching all quantity kinds in the library. Satisfied by all specializations of
:class:`quantity_kind`.
.. concept:: template<typename T> QuantityPointKind
A concept matching all quantity point kinds in the library. Satisfied by all specializations of
:class:`quantity_point_kind`.
.. concept:: template<typename Dim, template<typename...> typename DimTemplate> DimensionOfT
A concept matching all dimensions being the instantiations derived from the provided dimension
@ -95,7 +115,44 @@ Concepts
A concept matching all quantities with a dimension being the instantiation derived from
the provided dimension class template.
.. concept:: template<typename T, typename Dim> QuantityOf
.. concept:: template<typename Q, typename Dim> QuantityOf
A concept matching all quantities with a dimension being the instantiation derived from
the provided dimension type.
.. concept:: template<typename Q1, typename Q2> QuantityEquivalentTo
A concept matching two equivalent quantities. Satisfied by quantities having equivalent dimensions.
.. concept:: template<typename QP, typename Dim> QuantityPointOf
A concept matching all quantity points with a dimension being the instantiation derived from
the provided dimension type.
.. concept:: template<typename QP1, typename QP2> QuantityPointEquivalentTo
A concept matching two equivalent quantity points. Satisfied by quantity points having equivalent
dimensions.
.. concept:: template<typename QK, typename K> QuantityKindOf
A concept matching only quantity kinds of a specific kind.
:tparam QK: Quantity kind to verify.
:tparam K: Kind type to use for verification.
.. concept:: template<typename QK1, typename QK2> QuantityKindEquivalentTo
A concept matching two equivalent quantity kinds. Satisfied by quantity kinds having equivalent kinds.
.. concept:: template<typename QPK, typename PK> QuantityPointKindOf
A concept matching only quantity point kinds of a specific point kind.
:tparam QPK: Quantity point kind to verify.
:tparam PK: Point kind type to use for verification.
.. concept:: template<typename QPK1, typename QPK2> QuantityPointKindEquivalentTo
A concept matching two equivalent quantity point kinds. Satisfied by quantity point kinds having
equivalent kinds.

2
docs/reference/core/downcasting.rst
View File

@ -1,6 +1,8 @@
The Downcasting Facility
========================
.. doxygenenum:: downcast_mode
.. concept:: template<typename T> Downcastable
.. doxygenstruct:: units::downcast_base

3
docs/reference/core/types.rst
View File

@ -6,6 +6,9 @@ Types
types/quantity
types/quantity_point
types/kind
types/quantity_kind
types/quantity_point_kind
types/dimensions
types/units
types/prefixes

8
docs/reference/core/types/kind.rst Normal file
View File

@ -0,0 +1,8 @@
Kinds
=====
.. doxygenstruct:: units::kind
:members:
.. doxygenstruct:: units::point_kind
:members:

6
docs/reference/core/types/quantity_kind.rst Normal file
View File

@ -0,0 +1,6 @@
Quantity Kind
=============
.. doxygenclass:: units::quantity_kind
:members:
:undoc-members:

6
docs/reference/core/types/quantity_point_kind.rst Normal file
View File

@ -0,0 +1,6 @@
Quantity Point Kind
===================
.. doxygenclass:: units::quantity_point_kind
:members:
:undoc-members:

2
docs/usage.rst
View File

@ -125,7 +125,7 @@ downcast_mode
**Defaulted to**: ``on``
Specifies how :ref:`The Downcasting Facility` works:
Specifies how :ref:`design/downcasting:The Downcasting Facility` works:
- ``off`` - no downcasting at all
- ``on`` - downcasting always forced -> compile-time errors in case of duplicated definitions

12
docs/use_cases/custom_representation_types.rst
View File

@ -217,10 +217,11 @@ operations.
`treat_as_floating_point`
^^^^^^^^^^^^^^^^^^^^^^^^^
In the :ref:`Conversions and Casting` chapter we learned that the conversions provided by the
library's framework treat floating-point representation types differently than the integral
ones. This behavior can also be extended to the custom representation types with
`treat_as_floating_point` customization point which default definition is::
In the :ref:`framework/conversions_and_casting:Conversions and Casting` chapter we learned
that the conversions provided by the library's framework treat floating-point representation
types differently than the integral ones. This behavior can also be extended to the custom
representation types with `treat_as_floating_point` customization point which default
definition is::
template<QuantityValue Rep>
inline constexpr bool treat_as_floating_point = std::is_floating_point_v<Rep>;
@ -303,4 +304,5 @@ representation types with::
.. seealso::
For more examples of custom representation types usage please refer to the
:ref:`Linear Algebra vs. Quantities` chapter and the :ref:`measurement` example.
:ref:`use_cases/linear_algebra:Linear Algebra vs. Quantities` chapter and the
:ref:`examples/measurement:measurement` example.

3
docs/use_cases/extensions.rst
View File

@ -309,4 +309,5 @@ In such a situation the standalone system may be a better choice here.
.. seealso::
More information on extending the library can be found in the
:ref:`Using Custom Representation Types` chapter.
:ref:`use_cases/custom_representation_types:Using Custom Representation Types`
chapter.

5
docs/use_cases/linear_algebra.rst
View File

@ -61,7 +61,8 @@ types provided to a `quantity` class template.
.. seealso::
More information on providing custom representation types for `quantity` can be
found in the :ref:`Using Custom Representation Types` chapter.
found in the :ref:`use_cases/custom_representation_types:Using Custom Representation Types`
chapter.
With this the above vector definitions can be rewritten as follows::
@ -84,4 +85,4 @@ output:
.. seealso::
For more examples of Linear Algebra definition and operations please refer to
the :ref:`linear_algebra` example.
the :ref:`examples/linear_algebra:linear_algebra` example.

12
docs/use_cases/unknown_dimensions.rst
View File

@ -10,12 +10,14 @@ detail.
What is an unknown dimension?
-----------------------------
As we learned in the :ref:`Dimensions` chapter, in most cases the result of multiplying
or dividing two quantities of specific dimensions is a quantity of yet another dimension.
As we learned in the :ref:`framework/dimensions:Dimensions` chapter, in most cases the result
of multiplying or dividing two quantities of specific dimensions is a quantity of yet another
dimension.
If such a resulting dimension is predefined by the user (and a proper header file with its
definition is included in the current translation unit) :ref:`The Downcasting Facility`
will determine its type. The same applies to the resulting unit. For example:
definition is included in the current translation unit)
:ref:`design/downcasting:The Downcasting Facility` will determine its type.
The same applies to the resulting unit. For example:
.. code-block::
:emphasize-lines: 1,7,9
@ -83,7 +85,7 @@ following::
.. seealso::
Another good example of unknown dimension usage can be found in the
:ref:`box_example`::
:ref:`examples/box_example:box_example`::
std::cout << "float rise rate = " << box.fill_level(measured_mass) / fill_time << '\n';

4
src/include/units/bits/basic_concepts.h
View File

@ -222,7 +222,7 @@ concept kind_impl_ =
/**
* @brief A concept matching all kind types
*
* Satisfied by all kind types derived from an specialization of :class:`kind`.
* Satisfied by all kind types derived from an specialization of @c kind.
*/
template<typename T>
concept Kind =
@ -241,7 +241,7 @@ struct _point_kind_base;
/**
* @brief A concept matching all point kind types
*
* Satisfied by all point kind types derived from an specialization of :class:`point_kind`.
* Satisfied by all point kind types derived from an specialization of @c point_kind.
*/
template<typename T>
concept PointKind = kind_impl_<T, detail::_point_kind_base>;

20
src/include/units/bits/quantity_of.h
View File

@ -76,6 +76,11 @@ concept QuantityOfT = Quantity<Q> && DimensionOfT<typename Q::dimension, DimTemp
template<typename Q, typename Dim>
concept QuantityOf = Quantity<Q> && Dimension<Dim> && equivalent<typename Q::dimension, Dim>;
/**
* @brief A concept matching two equivalent quantities
*
* Satisfied by quantities having equivalent dimensions.
*/
template<typename Q1, typename Q2>
concept QuantityEquivalentTo = Quantity<Q1> && QuantityOf<Q2, typename Q1::dimension>;
@ -88,6 +93,11 @@ concept QuantityEquivalentTo = Quantity<Q1> && QuantityOf<Q2, typename Q1::dimen
template<typename QP, typename Dim>
concept QuantityPointOf = QuantityPoint<QP> && Dimension<Dim> && equivalent<typename QP::dimension, Dim>;
/**
* @brief A concept matching two equivalent quantity points
*
* Satisfied by quantity points having equivalent dimensions.
*/
template<typename QP1, typename QP2>
concept QuantityPointEquivalentTo = QuantityPoint<QP1> && QuantityPointOf<QP2, typename QP1::dimension>;
@ -100,6 +110,11 @@ concept QuantityPointEquivalentTo = QuantityPoint<QP1> && QuantityPointOf<QP2, t
template<typename QK, typename K>
concept QuantityKindOf = QuantityKind<QK> && Kind<K> && equivalent<typename QK::kind_type, K>;
/**
* @brief A concept matching two equivalent quantity kinds
*
* Satisfied by quantity kinds having equivalent kinds.
*/
template<typename QK1, typename QK2>
concept QuantityKindEquivalentTo = QuantityKind<QK1> && QuantityKindOf<QK2, typename QK1::kind_type>;
@ -112,6 +127,11 @@ concept QuantityKindEquivalentTo = QuantityKind<QK1> && QuantityKindOf<QK2, type
template<typename QPK, typename PK>
concept QuantityPointKindOf = QuantityPointKind<QPK> && PointKind<PK> && equivalent<typename QPK::point_kind_type, PK>;
/**
* @brief A concept matching two equivalent quantity point kinds
*
* Satisfied by quantity point kinds having equivalent kinds.
*/
template<typename QPK1, typename QPK2>
concept QuantityPointKindEquivalentTo =
QuantityPointKind<QPK1> && QuantityPointKindOf<QPK2, typename QPK1::point_kind_type>;

2
src/include/units/customization_points.h
View File

@ -78,7 +78,7 @@ struct quantity_values {
* The type trait should provide the following nested type aliases: @c dimension, @c unit, @c rep,
* and a static member function @c count(T) that will return the raw value of the quantity.
*
* Usage example can be found in units/chrono.h header file.
* Usage example can be found in @c units/chrono.h header file.
*
* @tparam T the type to provide support for
*/