From 60dd2cb304a25760016a29ba704ca448745dd4af Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Johel=20Ernesto=20Guerrero=20Pe=C3=B1a?= Date: Thu, 24 Oct 2024 10:36:44 -0400 Subject: [PATCH] docs(ref): fill [qty.ref] --- docs/api_reference/src/CMakeLists.txt | 1 + docs/api_reference/src/quantities.tex | 314 +++++++++++++++++++++++++- 2 files changed, 312 insertions(+), 3 deletions(-) diff --git a/docs/api_reference/src/CMakeLists.txt b/docs/api_reference/src/CMakeLists.txt index 28e29d64ec..a6aa88576e 100644 --- a/docs/api_reference/src/CMakeLists.txt +++ b/docs/api_reference/src/CMakeLists.txt @@ -21,6 +21,7 @@ jegp_add_standardese_sources( # Latex commands. [[\\href{([^}]+)}{([^}]+)};HREF(\1)(\2)]] # Macros extensions. + [[\\txtrm;\\textrm]] [[\\refcpp{([^}]+)};REFCPP(\1)]] [[\\irefcpp{([^}]+)};~(REFCPP(\1))]] [[\\refcppx{([^}]+)}{([^}]+)};REFCPPX(\1)(\2)]] diff --git a/docs/api_reference/src/quantities.tex b/docs/api_reference/src/quantities.tex index ee96f135d6..1a44d792de 100644 --- a/docs/api_reference/src/quantities.tex +++ b/docs/api_reference/src/quantities.tex @@ -227,7 +227,7 @@ // \ref{qty.unit.types}, types template<@\libconcept{Unit}@ From, @\libconcept{Unit}@ To> -consteval bool convertible(From from, To to); +consteval bool @\liboverload{convertible}{\cname{Unit}}@(From from, To to); template<@\libconcept{Magnitude}@ auto M, @\libconcept{Unit}@ U> requires @\seebelownc@ @@ -302,6 +302,9 @@ inline constexpr auto @\libglobal{ppm}@ = parts_per_million; +consteval @\libconcept{QuantitySpec}@ auto get_quantity_spec(@\libconcept{AssociatedUnit}@ auto u); +consteval @\libconcept{Unit}@ auto @\liboverload{get_unit}{\cname{AssociatedUnit}}@(@\libconcept{AssociatedUnit}@ auto u) { return u; } + consteval @\libconcept{Unit}@ auto get_common_unit(@\libconcept{Unit}@ auto... us) requires @\seebelownc@; @@ -335,6 +338,68 @@ // \ref{qty.ref}, reference +template +concept @\deflibconcept{Reference}@ = @\seebelownc@; + +template +concept @\deflibconcept{ReferenceOf}@ = @\seebelownc@; + +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{}; +} + +template Rep = std::remove_cvref_t> + requires(!@\exposconceptnc{OffsetUnit}@) +constexpr quantity operator*(FwdRep&& lhs, R r); + +template Rep = std::remove_cvref_t> + requires(!@\exposconceptnc{OffsetUnit}@) +constexpr quantity operator/(FwdRep&& lhs, R); + +template> +constexpr @\libconcept{Quantity}@ auto operator*(FwdQ&& q, R); + +template> +constexpr @\libconcept{Quantity}@ auto operator/(FwdQ&& q, R); + +template<@\libconcept{Reference}@ R, typename Rep> + requires @\libconcept{RepresentationOf}@, get_quantity_spec(R{}).character> +constexpr auto operator*(R, Rep&&) = delete; + +template<@\libconcept{Reference}@ R, typename Rep> + requires @\libconcept{RepresentationOf}@, get_quantity_spec(R{}).character> +constexpr auto operator/(R, Rep&&) = delete; + +template<@\libconcept{Reference}@ R, typename Q> + requires @\libconcept{Quantity}@> +constexpr auto operator*(R, Q&&) = delete; + +template<@\libconcept{Reference}@ R, typename Q> + requires @\libconcept{Quantity}@> +constexpr auto operator/(R, Q&&) = delete; + +consteval @\libconcept{AssociatedUnit}@ auto get_common_reference(@\libconcept{AssociatedUnit}@ auto u1, + @\libconcept{AssociatedUnit}@ auto u2, + @\libconcept{AssociatedUnit}@ auto... rest) + requires @\seebelownc@; + +template<@\libconcept{Reference}@ R1, @\libconcept{Reference}@ R2, @\libconcept{Reference}@... Rest> +consteval @\libconcept{Reference}@ auto get_common_reference(R1 r1, R2 r2, Rest... rest) + requires @\seebelownc@; + // \ref{qty.rep}, representation // \ref{qty.rep.traits}, traits @@ -1415,8 +1480,8 @@ if constexpr (sizeof...(qs) == 1) return q1; else if constexpr (sizeof...(qs) == 2) { - using QQ1 = decltype(remove_kind(q1)); - using QQ2 = decltype(remove_kind(q2)); + using QQ1 = decltype(@\exposidnc{remove-kind}@(q1)); + using QQ2 = decltype(@\exposidnc{remove-kind}@(q2)); if constexpr (^Q1 == ^Q2) return q1; @@ -2114,6 +2179,16 @@ \tcode{\exposidnc{expr-pow}(u)}. \end{itemdescr} +\begin{itemdecl} +consteval @\libconcept{QuantitySpec}@ auto @\liboverload{get_quantity_spec}{\cname{AssociatedUnit}}@(@\libconcept{AssociatedUnit}@ auto u); +\end{itemdecl} + +\begin{itemdescr} +\pnum +\returns +TBD. +\end{itemdescr} + \begin{itemdecl} consteval @\libconcept{Unit}@ auto @\libglobal{get_common_unit}@(@\libconcept{Unit}@ auto... us) requires @\seebelownc@; @@ -2220,8 +2295,241 @@ \begin{itemdecl} template concept @\deflibconcept{Reference}@ = @\libconcept{AssociatedUnit}@ || @\exposidnc{is-specialization-of}@(^T, ^reference); + +template +concept @\deflibconcept{ReferenceOf}@ = @\libconcept{Reference}@ && @\libconcept{QuantitySpecOf}@; \end{itemdecl} +\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; + } + + template + friend consteval auto operator*(reference, reference) + -> @\exposidnc{reference-t}@ + { + return {}; + } + + template<@\libconcept{AssociatedUnit}@ U2> + friend consteval auto operator*(reference, U2) + -> @\exposidnc{reference-t}@ + { + return {}; + } + + template<@\libconcept{AssociatedUnit}@ U1> + friend consteval auto operator*(U1, reference) + -> @\exposidnc{reference-t}@ + { + return {}; + } + + template + friend consteval auto operator/(reference, reference) + -> @\exposidnc{reference-t}@ + { + return {}; + } + + template<@\libconcept{AssociatedUnit}@ U2> + friend consteval auto operator/(reference, U2) + -> @\exposidnc{reference-t}@ + { + return {}; + } + + template<@\libconcept{AssociatedUnit}@ U1> + friend consteval auto operator/(U1, reference) + -> @\exposidnc{reference-t}@ + { + return {}; + } + + friend consteval auto @\liboverload{inverse}{reference}@(reference) { return @\exposidnc{reference-t}@{}; } + + template + requires(Den != 0) + friend consteval auto @\liboverload{pow}{reference}@(reference) + { + return @\exposidnc{reference-t}@(Q{}), pow(U{})>{}; + } + + friend consteval auto @\liboverload{sqrt}{reference}@(reference) { return @\exposidnc{reference-t}@{}; } + friend consteval auto @\liboverload{cbrt}{reference}@(reference) { return @\exposidnc{reference-t}@{}; } + + template + friend consteval bool @\liboverload{convertible}{reference}@(reference, reference) + { + return implicitly_convertible(Q{}, Q2{}) && convertible(U{}, U2{}); + } + + template<@\libconcept{AssociatedUnit}@ U2> + friend consteval bool convertible(reference, U2 u2) + { + return implicitly_convertible(Q{}, get_quantity_spec(u2)) && convertible(U{}, u2); + } + + template<@\libconcept{AssociatedUnit}@ U1> + friend consteval bool convertible(U1 u1, reference) + { + return implicitly_convertible(get_quantity_spec(u1), Q{}) && convertible(u1, U{}); + } +}; + +} +\end{codeblock} + +\pnum +\tcode{reference} represents the reference of a quantity\irefiev{112-01-01}. +The reference is the unit of measurement \tcode{U}\irefiev{112-01-14} +used to measure a value of the quantity \tcode{Q}\irefiev{112-01-28}. + +\begin{itemdecl} +template Rep = std::remove_cvref_t> + requires(!@\exposconceptnc{OffsetUnit}@) +constexpr quantity @\libmember{operator*}{reference}@(FwdRep&& lhs, R r); +\end{itemdecl} + +\begin{itemdescr} +\pnum +\effects +Equivalent to: +\tcode{return quantity{std::forward(lhs), r};} +\end{itemdescr} + +\begin{itemdecl} +template Rep = std::remove_cvref_t> + requires(!@\exposconceptnc{OffsetUnit}@) +constexpr quantity @\libmember{operator/}{reference}@(FwdRep&& lhs, R); +\end{itemdecl} + +\begin{itemdescr} +\pnum +\effects +Equivalent to: +\tcode{return quantity{std::forward(lhs), inverse(R{})};} +\end{itemdescr} + +\begin{itemdecl} +template> +constexpr @\libconcept{Quantity}@ auto @\libmember{operator*}{reference}@(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} + +\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<@\libconcept{Reference}@ R, typename Rep> + requires @\libconcept{RepresentationOf}@, get_quantity_spec(R{}).character> +constexpr auto operator*(R, Rep&&) = delete; + +template<@\libconcept{Reference}@ R, typename Rep> + requires @\libconcept{RepresentationOf}@, get_quantity_spec(R{}).character> +constexpr auto operator/(R, Rep&&) = delete; + +template<@\libconcept{Reference}@ R, typename Q> + requires @\libconcept{Quantity}@> +constexpr auto operator*(R, Q&&) = delete; + +template<@\libconcept{Reference}@ R, typename Q> + requires @\libconcept{Quantity}@> +constexpr auto operator/(R, Q&&) = delete; +\end{itemdecl} + +\begin{itemdescr} +\pnum +\recommended +Suggest swapping the operands. +\end{itemdescr} + +\begin{itemdecl} +consteval @\libconcept{AssociatedUnit}@ auto @\libglobal{get_common_reference}@(@\libconcept{AssociatedUnit}@ auto u1, + @\libconcept{AssociatedUnit}@ auto u2, + @\libconcept{AssociatedUnit}@ auto... rest) + requires @\seebelownc@; +\end{itemdecl} + +\begin{itemdescr} +\pnum +The expression in the \fakegrammarterm{requires-clause} is equivalent to: +\begin{codeblock} +requires { + get_common_quantity_spec(get_quantity_spec(u1), get_quantity_spec(u2), + get_quantity_spec(rest)...); + { get_common_unit(u1, u2, rest...) } -> AssociatedUnit; +} +\end{codeblock} + +\pnum +\returns +\tcode{get_common_unit(u1, u2, rest...)}. +\end{itemdescr} + +\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) + requires @\seebelownc@; +\end{itemdecl} + +\begin{itemdescr} +\pnum +The expression in the \fakegrammarterm{requires-clause} is equivalent to: +\begin{codeblock} +requires { + get_common_quantity_spec(get_quantity_spec(r1), get_quantity_spec(r2), + get_quantity_spec(rest)...); + get_common_unit(get_unit(r1), get_unit(r2), get_unit(rest)...); +} +\end{codeblock} + +\pnum +\returns +\begin{codeblock} +@\exposidnc{reference-t}@{}; +\end{codeblock} +\end{itemdescr} + \rSec1[qty.rep]{Representation} \rSec2[qty.rep.traits]{Traits}