From f83396e20380af758a2da91b0825cf2ef511afcf Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Johel=20Ernesto=20Guerrero=20Pe=C3=B1a?= Date: Sat, 30 Nov 2024 14:35:55 -0400 Subject: [PATCH] docs(ref): review [qty.ref] --- docs/api_reference/src/quantities.tex | 277 +++++++++++++++++--------- 1 file changed, 186 insertions(+), 91 deletions(-) diff --git a/docs/api_reference/src/quantities.tex b/docs/api_reference/src/quantities.tex index 57fe5b014..218fd1864 100644 --- a/docs/api_reference/src/quantities.tex +++ b/docs/api_reference/src/quantities.tex @@ -172,7 +172,7 @@ // \ref{qty.spec.hier.algos}, hierarchy algorithms -// \ref{qty.spec.conv.algos}, conversion +// \ref{qty.spec.conv}, conversion consteval bool implicitly_convertible(@\libconcept{QuantitySpec}@ auto from, @\libconcept{QuantitySpec}@ auto to); consteval bool explicitly_convertible(@\libconcept{QuantitySpec}@ auto from, @\libconcept{QuantitySpec}@ auto to); @@ -381,7 +381,7 @@ template consteval std::string_view unit_symbol(U); -// \ref{qty.ref.syn}, class template \tcode{reference} +// \ref{qty.ref.concepts}, concepts template concept @\deflibconcept{Reference}@ = @\seebelownc@; @@ -389,20 +389,12 @@ template concept @\deflibconcept{ReferenceOf}@ = @\seebelownc@; +// \ref{qty.ref.syn}, class template \tcode{reference} + template<@\libconcept{QuantitySpec}@ Q, @\libconcept{Unit}@ U> struct reference; -template -consteval @\libconcept{QuantitySpec}@ auto @\liboverload{get_quantity_spec}{reference}@(reference) -{ - return Q{}; -} - -template -consteval @\libconcept{Unit}@ auto @\liboverload{get_unit}{reference}@(reference) -{ - return U{}; -} +// \ref{qty.ref.ops}, operations template Rep = std::remove_cvref_t> @@ -412,7 +404,7 @@ template Rep = std::remove_cvref_t> requires(!@\exposconceptnc{OffsetUnit}@) -constexpr quantity operator/(FwdRep&& lhs, R); +constexpr @\libconcept{Quantity}@ operator/(FwdRep&& lhs, R); template> constexpr @\libconcept{Quantity}@ auto operator*(FwdQ&& q, R); @@ -436,6 +428,14 @@ requires @\libconcept{Quantity}@> constexpr auto operator/(R, Q&&) = delete; +// \ref{qty.ref.obs}, observers + +template +consteval @\libconcept{QuantitySpec}@ auto get_quantity_spec(reference); + +template +consteval @\libconcept{Unit}@ auto get_unit(reference); + consteval @\libconcept{AssociatedUnit}@ auto get_common_reference(@\libconcept{AssociatedUnit}@ auto u1, @\libconcept{AssociatedUnit}@ auto u2, @\libconcept{AssociatedUnit}@ auto... rest) @@ -2024,7 +2024,7 @@ \rSec3[qty.spec.hier.algos]{Hierarchy algorithms} -\rSec4[qty.spec.conv.algos]{Conversion} +\rSec4[qty.spec.conv]{Conversion} \indexlibrarymember{implicitly_convertible}{QuantitySpec} \begin{itemdecl} @@ -3375,105 +3375,89 @@ \end{codeblock} \end{itemdescr} -\rSec2[qty.ref.syn]{Class template \tcode{reference}} - -\begin{codeblock} -namespace mp_units { +\rSec2[qty.ref.concepts]{Concepts} +\begin{itemdecl} template concept @\deflibconcept{Reference}@ = @\libconcept{AssociatedUnit}@ || (@\exposidnc{is-specialization-of}@()); +\end{itemdecl} + +A type \tcode{T} that satisfies \tcode{Reference} +represents the reference of a quantity\irefiev{112-01-01}. +\begin{itemdecl} template concept @\deflibconcept{ReferenceOf}@ = @\libconcept{Reference}@ && @\libconcept{QuantitySpecOf}@; +\end{itemdecl} + +\rSec2[qty.ref.syn]{Class template \tcode{reference}} + +\indexlibrarymember{operator*}{reference} +\indexlibrarymember{operator*}{AssociatedUnit} +\indexlibrarymember{operator/}{reference} +\indexlibrarymember{operator/}{AssociatedUnit} +\indexlibrarymember{inverse}{reference} +\indexlibrarymember{pow}{reference} +\indexlibrarymember{sqrt}{reference} +\indexlibrarymember{cbrt}{reference} +\begin{codeblock} +namespace mp_units { template<@\libconcept{QuantitySpec}@ auto Q, @\libconcept{Unit}@ auto U> using @\exposidnc{reference-t}@ = reference; template<@\libconcept{QuantitySpec}@ Q, @\libconcept{Unit}@ U> struct @\libglobal{reference}@ { - template - friend consteval bool operator==(reference, reference) - { - return Q{} == Q2{} && U{} == U2{}; - } - - template<@\libconcept{AssociatedUnit}@ U2> - friend consteval bool operator==(reference, U2 u2) - { - return Q{} == get_quantity_spec(u2) && U{} == u2; - } + // \ref{qty.ref.ops}, operations template friend consteval auto operator*(reference, reference) - -> @\exposidnc{reference-t}@ - { - return {}; - } + -> @\exposidnc{reference-t}@; template<@\libconcept{AssociatedUnit}@ U2> friend consteval auto operator*(reference, U2) - -> @\exposidnc{reference-t}@ - { - return {}; - } + -> @\exposidnc{reference-t}@; template<@\libconcept{AssociatedUnit}@ U1> friend consteval auto operator*(U1, reference) - -> @\exposidnc{reference-t}@ - { - return {}; - } + -> @\exposidnc{reference-t}@; template friend consteval auto operator/(reference, reference) - -> @\exposidnc{reference-t}@ - { - return {}; - } + -> @\exposidnc{reference-t}@; template<@\libconcept{AssociatedUnit}@ U2> friend consteval auto operator/(reference, U2) - -> @\exposidnc{reference-t}@ - { - return {}; - } + -> @\exposidnc{reference-t}@; template<@\libconcept{AssociatedUnit}@ U1> friend consteval auto operator/(U1, reference) - -> @\exposidnc{reference-t}@ - { - return {}; - } + -> @\exposidnc{reference-t}@; - friend consteval auto @\liboverload{inverse}{reference}@(reference) { return @\exposidnc{reference-t}@{}; } + friend consteval auto inverse(reference) -> @\exposidnc{reference-t}@; template requires(Den != 0) - friend consteval auto @\liboverload{pow}{reference}@(reference) - { - return @\exposidnc{reference-t}@(Q{}), pow(U{})>{}; - } + friend consteval auto pow(reference) -> @\exposidnc{reference-t}@(Q{}), pow(U{})>; + friend consteval auto sqrt(reference) -> @\exposidnc{reference-t}@; + friend consteval auto cbrt(reference) -> @\exposidnc{reference-t}@; - friend consteval auto @\liboverload{sqrt}{reference}@(reference) { return @\exposidnc{reference-t}@{}; } - friend consteval auto @\liboverload{cbrt}{reference}@(reference) { return @\exposidnc{reference-t}@{}; } + // \ref{qty.ref.cmp}, comparison template - friend consteval bool @\liboverload{convertible}{reference}@(reference, reference) - { - return implicitly_convertible(Q{}, Q2{}) && convertible(U{}, U2{}); - } + friend consteval bool operator==(reference, reference); template<@\libconcept{AssociatedUnit}@ U2> - friend consteval bool convertible(reference, U2 u2) - { - return implicitly_convertible(Q{}, get_quantity_spec(u2)) && convertible(U{}, u2); - } + friend consteval bool operator==(reference, U2 u2); + + template + friend consteval bool convertible(reference, reference); + + template<@\libconcept{AssociatedUnit}@ U2> + friend consteval bool convertible(reference, U2 u2); template<@\libconcept{AssociatedUnit}@ U1> - friend consteval bool convertible(U1 u1, reference) - { - return implicitly_convertible(get_quantity_spec(u1), Q{}) && convertible(u1, U{}); - } + friend consteval bool convertible(U1 u1, reference); }; } @@ -3483,60 +3467,78 @@ \tcode{reference} represents the reference of a quantity\irefiev{112-01-01}. The unit of measurement \tcode{U}\irefiev{112-01-14} is used to measure a value of the quantity \tcode{Q}\irefiev{112-01-28}. +\begin{note} +\tcode{reference} is typically implicitly instantiated +when specifying that a unit measures a more specific quantity. +\begin{example} +\begin{codeblock} +using namespace si::unit_symbols; +auto x = 1 * m; // measures a length +auto y = 1 * isq::width[m]; // measures a width +auto z = 1 * isq::diameter[m]; // measures a diameter +\end{codeblock} +\end{example} +\end{note} +\rSec2[qty.ref.ops]{Operations} + +\pnum +Each member function with a \fakegrammarterm{trailing-return-type} +of \tcode{-> \exposidnc{reference-t}} +returns \tcode{\{\}}. + +\indexlibrarymember{operator*}{Representation} +\indexlibrarymember{operator*}{Reference} \begin{itemdecl} template Rep = std::remove_cvref_t> requires(!@\exposconceptnc{OffsetUnit}@) -constexpr quantity @\libmember{operator*}{reference}@(FwdRep&& lhs, R r); +constexpr quantity operator*(FwdRep&& lhs, R r); \end{itemdecl} \begin{itemdescr} \pnum \effects Equivalent to: -\tcode{return quantity{std::forward(lhs), r};} +\tcode{return quantity\{std::forward(lhs), r\};} \end{itemdescr} +\indexlibrarymember{operator*}{Representation} +\indexlibrarymember{operator*}{Reference} \begin{itemdecl} template Rep = std::remove_cvref_t> requires(!@\exposconceptnc{OffsetUnit}@) -constexpr @\libconcept{Quantity}@ @\libmember{operator/}{reference}@(FwdRep&& lhs, R); +constexpr @\libconcept{Quantity}@ operator/(FwdRep&& lhs, R); \end{itemdecl} \begin{itemdescr} \pnum \effects Equivalent to: -\tcode{return quantity{std::forward(lhs), inverse(R{})};} +\tcode{return quantity\{std::forward(lhs), inverse(R\{\})\};} \end{itemdescr} +\indexlibrarymember{operator*}{Quantity} +\indexlibrarymember{operator*}{Reference} +\indexlibrarymember{operator/}{Quantity} +\indexlibrarymember{operator/}{Reference} \begin{itemdecl} template> -constexpr @\libconcept{Quantity}@ auto @\libmember{operator*}{reference}@(FwdQ&& q, R); +constexpr @\libconcept{Quantity}@ auto operator*(FwdQ&& q, R); +template> +constexpr @\libconcept{Quantity}@ auto operator/(FwdQ&& q, R); \end{itemdecl} \begin{itemdescr} \pnum -\effects -Equivalent to: -\begin{codeblock} -return quantity{std::forward(q).@\exposidnc{numerical-value}@, Q::reference * R{}}; -\end{codeblock} -\end{itemdescr} - -\begin{itemdecl} -template> -constexpr @\libconcept{Quantity}@ auto @\libmember{operator/}{reference}@(FwdQ&& q, R); -\end{itemdecl} +Let \tcode{@} be the \fakegrammarterm{operator}. -\begin{itemdescr} \pnum \effects Equivalent to: \begin{codeblock} -return quantity{std::forward(q).@\exposidnc{numerical-value}@, Q::reference / R{}}; +return quantity{std::forward(q).@\exposidnc{numerical-value}@, Q::reference @\atsign@ R{}}; \end{codeblock} \end{itemdescr} @@ -3564,6 +3566,98 @@ Suggest swapping the operands. \end{itemdescr} +\rSec2[qty.ref.cmp]{Comparison} + +\indexlibrarymember{operator==}{reference} +\begin{itemdecl} +template +friend consteval bool operator==(reference, reference); +\end{itemdecl} + +\begin{itemdescr} +\pnum +\returns +\tcode{Q\{\} == Q2\{\} \&\& U\{\} == U2\{\}}. +\end{itemdescr} + +\indexlibrarymember{operator==}{reference} +\indexlibrarymember{operator==}{AssociatedUnit} +\begin{itemdecl} +template<@\libconcept{AssociatedUnit}@ U2> +friend consteval bool operator==(reference, U2 u2); +\end{itemdecl} + +\begin{itemdescr} +\pnum +\returns +\tcode{Q\{\} == get_quantity_spec(u2) \&\& U\{\} == u2}. +\end{itemdescr} + +\indexlibrarymember{convertible}{reference} +\begin{itemdecl} +template +friend consteval bool convertible(reference, reference); +\end{itemdecl} + +\begin{itemdescr} +\pnum +\returns +\tcode{implicitly_convertible(Q\{\}, Q2\{\}) \&\& convertible(U\{\}, U2\{\})}. +\end{itemdescr} + +\indexlibrarymember{convertible}{reference} +\indexlibrarymember{convertible}{AssociatedUnit} +\begin{itemdecl} +template<@\libconcept{AssociatedUnit}@ U2> +friend consteval bool convertible(reference, U2 u2); +\end{itemdecl} + +\begin{itemdescr} +\pnum +\returns +\tcode{implicitly_convertible(Q\{\}, get_quantity_spec(u2)) \&\& convertible(U\{\}, u2)}. +\end{itemdescr} + +\indexlibrarymember{convertible}{reference} +\indexlibrarymember{convertible}{AssociatedUnit} +\begin{itemdecl} +template<@\libconcept{AssociatedUnit}@ U1> +friend consteval bool convertible(U1 u1, reference); +\end{itemdecl} + +\begin{itemdescr} +\pnum +\returns +\tcode{implicitly_convertible(get_quantity_spec(u1), Q\{\}) \&\& convertible(u1, U\{\})}. +\end{itemdescr} + +\rSec2[qty.ref.obs]{Observers} + +\indexlibrarymember{get_quantity_spec}{reference} +\begin{itemdecl} +template +consteval @\libconcept{QuantitySpec}@ auto get_quantity_spec(reference); +\end{itemdecl} + +\begin{itemdescr} +\pnum +\returns +\tcode{Q\{\}}. +\end{itemdescr} + +\indexlibrarymember{get_unit}{reference} +\begin{itemdecl} +template +consteval @\libconcept{Unit}@ auto get_unit(reference); +\end{itemdecl} + +\begin{itemdescr} +\pnum +\returns +\tcode{U\{\}}. +\end{itemdescr} + +\indexlibrarymember{get_common_reference}{AssociatedUnit} \begin{itemdecl} consteval @\libconcept{AssociatedUnit}@ auto @\libglobal{get_common_reference}@(@\libconcept{AssociatedUnit}@ auto u1, @\libconcept{AssociatedUnit}@ auto u2, @@ -3588,6 +3682,7 @@ \end{codeblock} \end{itemdescr} +\indexlibrarymember{get_common_reference}{reference} \begin{itemdecl} template<@\libconcept{Reference}@ R1, @\libconcept{Reference}@ R2, @\libconcept{Reference}@... Rest> consteval @\libconcept{Reference}@ auto @\libglobal{get_common_reference}@(R1 r1, R2 r2, Rest... rest)