Skip to content

Commit

Permalink
docs(ref): Fill [qty.sym.txt]
Browse files Browse the repository at this point in the history
  • Loading branch information
@JohelEGP
JohelEGP committed Nov 9, 2024
1 parent a39acbb commit d75d845
Showing 1 changed file with 163 additions and 26 deletions.
189 changes: 163 additions & 26 deletions docs/api_reference/src/quantities.tex
View file
Original file line number Diff line number Diff line change
Expand Up @@ -48,8 +48,6 @@

export namespace mp_units {

enum class @\libglobal{text_encoding}@ : std::int8_t { utf8, portable, default_encoding = utf8 };

enum class @\libglobal{quantity_character}@ { scalar, complex, vector, tensor };

// \ref{qty.helpers}, helpers
Expand Down Expand Up @@ -95,7 +93,12 @@

namespace mp_units {

// \ref{qty.symbol.text}, class template \exposid{symbol-text}
// \ref{qty.sym.txt}, class template \exposid{symbol-text}

enum class @\libglobal{text_encoding}@ : std::int8_t { utf8, portable, default_encoding = utf8 };

template<std::size_t N, std::size_t M>
class @\exposidnc{symbol-text}@; // \expos

// \ref{qty.expr.temp}, expression template

Expand All @@ -120,7 +123,7 @@

// \ref{qty.dim.types}, types

template<symbol_text Symbol>
template<@\exposidnc{symbol-text}@ Symbol>
struct base_dimension;

template<typename... Expr>
Expand Down Expand Up @@ -227,7 +230,7 @@

// \ref{qty.mag.types}, types

template<symbol_text Symbol, long double Value>
template<@\exposidnc{symbol-text}@ Symbol, long double Value>
requires(Value > 0)
struct mag_constant;

Expand Down Expand Up @@ -286,39 +289,39 @@
requires @\seebelownc@
struct scaled_unit;

template<symbol_text Symbol, auto...>
template<@\exposidnc{symbol-text}@ Symbol, auto...>
struct named_unit; // \notdef

template<symbol_text Symbol, @\exposconceptnc{QuantityKindSpec}@ auto QS>
template<@\exposidnc{symbol-text}@ Symbol, @\exposconceptnc{QuantityKindSpec}@ auto QS>
requires @\seebelownc@
struct named_unit<Symbol, QS>;

template<symbol_text Symbol, @\exposconceptnc{QuantityKindSpec}@ auto QS, @\libconcept{PointOrigin}@ auto PO>
template<@\exposidnc{symbol-text}@ Symbol, @\exposconceptnc{QuantityKindSpec}@ auto QS, @\libconcept{PointOrigin}@ auto PO>
requires @\seebelownc@
struct named_unit<Symbol, QS, PO>;

template<symbol_text Symbol>
template<@\exposidnc{symbol-text}@ Symbol>
requires @\seebelownc@
struct named_unit<Symbol>;

template<symbol_text Symbol, @\libconcept{Unit}@ auto U>
template<@\exposidnc{symbol-text}@ Symbol, @\libconcept{Unit}@ auto U>
requires @\seebelownc@
struct named_unit<Symbol, U>;

template<symbol_text Symbol, @\libconcept{Unit}@ auto U, @\libconcept{PointOrigin}@ auto PO>
template<@\exposidnc{symbol-text}@ Symbol, @\libconcept{Unit}@ auto U, @\libconcept{PointOrigin}@ auto PO>
requires @\seebelownc@
struct named_unit<Symbol, U, PO>;

template<symbol_text Symbol, @\libconcept{AssociatedUnit}@ auto U, @\exposconceptnc{QuantityKindSpec}@ auto QS>
template<@\exposidnc{symbol-text}@ Symbol, @\libconcept{AssociatedUnit}@ auto U, @\exposconceptnc{QuantityKindSpec}@ auto QS>
requires @\seebelownc@
struct named_unit<Symbol, U, QS>;

template<symbol_text Symbol, @\libconcept{AssociatedUnit}@ auto U, @\exposconceptnc{QuantityKindSpec}@ auto QS,
template<@\exposidnc{symbol-text}@ Symbol, @\libconcept{AssociatedUnit}@ auto U, @\exposconceptnc{QuantityKindSpec}@ auto QS,
@\libconcept{PointOrigin}@ auto PO>
requires @\seebelownc@
struct named_unit<Symbol, U, QS, PO>;

template<symbol_text Symbol, @\libconcept{Magnitude}@ auto M, @\libconcept{PrefixableUnit}@ auto U>
template<@\exposidnc{symbol-text}@ Symbol, @\libconcept{Magnitude}@ auto M, @\libconcept{PrefixableUnit}@ auto U>
requires @\seebelownc@
struct prefixed_unit;

Expand All @@ -335,7 +338,7 @@
} @\libglobal{percent}@;

inline constexpr struct @\libglobal{per_mille}@ final :
named_unit<symbol_text{u8"\u2030" /* @\unicode{2030}{PER MILLE SIGN}@ */, "%o"},
named_unit<@\exposidnc{symbol-text}@{u8"\u2030" /* @\unicode{2030}{PER MILLE SIGN}@ */, "%o"},
mag_ratio<1, 1000> * one> {
} @\libglobal{per_mille}@;

Expand Down Expand Up @@ -1050,7 +1053,141 @@
};
\end{codeblock}

\rSec2[qty.symbol.text]{Class template \exposid{symbol-text}}
\rSec2[qty.sym.txt]{Class template \exposid{symbol-text}}

\indexlibraryglobal{\exposid{symbol-text}}
\begin{codeblock}
namespace mp_units {

template<std::size_t N, std::size_t M>
class @\exposidnc{symbol-text}@ { // \expos
public:
@\exposidnc{fixed-u8string}@<N> @\exposidnc{utf8}@; // \expos
@\exposidnc{fixed-string}@<M> @\exposidnc{portable}@; // \expos

// constructors
constexpr explicit(false) @\exposidnc{symbol-text}@(char portable);
consteval explicit(false) @\exposidnc{symbol-text}@(const char (&portable)[N + 1]);
constexpr explicit(false) @\exposidnc{symbol-text}@(const fixed_string<N>& portable);
consteval @\exposidnc{symbol-text}@(const char8_t (&utf8)[N + 1], const char (&portable)[M + 1]);
constexpr @\exposidnc{symbol-text}@(const fixed_u8string<N>& utf8, const fixed_string<M>& portable);

// observers
constexpr const auto& utf8() const { return @\exposidnc{utf8}@; }
constexpr const auto& portable() const { return @\exposidnc{portable}@; }
constexpr bool empty() const { return utf8().empty(); }

// string operations
template<std::size_t N2, std::size_t M2>
friend constexpr @\exposidnc{symbol-text}@<N + N2, M + M2> operator+(const @\exposidnc{symbol-text}@& lhs,
const @\exposidnc{symbol-text}@<N2, M2>& rhs);

// comparison
template<std::size_t N2, std::size_t M2>
friend constexpr auto operator<=>(const @\exposidnc{symbol-text}@& lhs,
const @\exposidnc{symbol-text}@<N2, M2>& rhs) noexcept;
template<std::size_t N2, std::size_t M2>
friend constexpr bool operator==(const @\exposidnc{symbol-text}@& lhs,
const @\exposidnc{symbol-text}@<N2, M2>& rhs) noexcept;
};

// deduction guides

@\exposidnc{symbol-text}@(char) -> @\exposidnc{symbol-text}@<1, 1>;

template<std::size_t N>
@\exposidnc{symbol-text}@(const char (&)[N]) -> @\exposidnc{symbol-text}@<N - 1, N - 1>;

template<std::size_t N>
@\exposidnc{symbol-text}@(const fixed_string<N>&) -> @\exposidnc{symbol-text}@<N, N>;

template<std::size_t N, std::size_t M>
@\exposidnc{symbol-text}@(const char8_t (&)[N], const char (&)[M]) -> @\exposidnc{symbol-text}@<N - 1, M - 1>;

template<std::size_t N, std::size_t M>
@\exposidnc{symbol-text}@(const fixed_u8string<N>&, const fixed_string<M>&) -> @\exposidnc{symbol-text}@<N, M>;

}
\end{codeblock}

\pnum
\exposid{symbol-text} describes a symbol text.
\exposid{utf8} stores its UTF-8 representation, and
\exposid{portable} stores its portable representation.
\tcode{\exposid{symbol-text}<N, M>} is a structural type\irefcppx{temp.param}{term.structural.type}.

\pnum
In the descriptions that follow,
it is a \Fundescx{Precondition} that
\begin{itemize}
\item
values of \tcode{char} are in the basic literal character set\irefcpp{lex.charset}, and
\item
for a parameter of the form \tcode{const \placeholdernc{CharT} (\&\placeholdernc{txt})[\placeholder{M}]},
\tcode{(\placeholdernc{txt}[\placeholdernc{M} - 1] == \placeholdernc{CharT}())} is \tcode{true}.
\end{itemize}

\begin{itemdecl}
constexpr explicit(false) @\exposidnc{symbol-text}@(char portable);
consteval explicit(false) @\exposidnc{symbol-text}@(const char (&portable)[N + 1]);
constexpr explicit(false) @\exposidnc{symbol-text}@(const fixed_string<N>& portable);
consteval @\exposidnc{symbol-text}@(const char8_t (&utf8)[N + 1], const char (&portable)[M + 1]);
constexpr @\exposidnc{symbol-text}@(const fixed_u8string<N>& utf8, const fixed_string<M>& portable);
\end{itemdecl}

\begin{itemdescr}
\pnum
Let \tcode{lhs} be \tcode{utf8} for the last two constructors,
and otherwise:
\begin{codeblock}
std::bit_cast<@\exposidnc{fixed-u8string}@<N>>(@\exposidnc{basic-fixed-string}@(portable))
\end{codeblock}

\pnum
\effects
Equivalent to the \fakegrammarterm{mem-initializer-list}:
\begin{codeblock}
@\exposid{utf8}@{lhs}, @\exposidnc{portable}@{portable}
\end{codeblock}
\end{itemdescr}

\begin{itemdecl}
template<std::size_t N2, std::size_t M2>
friend constexpr @\exposidnc{symbol-text}@<N + N2, M + M2> operator+(const @\exposidnc{symbol-text}@& lhs,
const @\exposidnc{symbol-text}@<N2, M2>& rhs);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Equivalent to:
\begin{codeblock}
return @\exposidnc{symbol-text}@<N + N2, M + M2>(lhs.utf8() + rhs.utf8(),
lhs.portable() + rhs.portable());
\end{codeblock}
\end{itemdescr}

\begin{itemdecl}
template<std::size_t N2, std::size_t M2>
friend constexpr auto operator<=>(const @\exposidnc{symbol-text}@& lhs,
const @\exposidnc{symbol-text}@<N2, M2>& rhs) noexcept;
template<std::size_t N2, std::size_t M2>
friend constexpr bool operator==(const @\exposidnc{symbol-text}@& lhs,
const @\exposidnc{symbol-text}@<N2, M2>& rhs) noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
Let \tcode{@} be the \fakegrammarterm{operator}.

\pnum
\effects
Equivalent to:
\begin{codeblock}
return std::make_tuple(std::cref(lhs.utf8()), std::cref(lhs.portable())) @\atsign@
std::make_tuple(std::cref(rhs.utf8()), std::cref(rhs.portable()));
\end{codeblock}
\end{itemdescr}

\rSec1[qty.expr.temp]{Expression template}

Expand Down Expand Up @@ -1384,7 +1521,7 @@
}
};

template<symbol_text Symbol>
template<@\exposidnc{symbol-text}@ Symbol>
struct @\libglobal{base_dimension}@ : @\exposidnc{dimension-interface}@ {
static constexpr auto @\exposidnc{symbol}@ = Symbol; // \expos
};
Expand Down Expand Up @@ -2057,7 +2194,7 @@
\begin{codeblock}
namespace mp_units {
template<symbol_text Symbol, long double Value>
template<@\exposidnc{symbol-text}@ Symbol, long double Value>
requires(Value > 0)
struct @\libglobal{mag_constant}@ {
static constexpr auto @\exposidnc{symbol}@ = Symbol; // \expos
Expand Down Expand Up @@ -2410,15 +2547,15 @@
\begin{codeblock}
namespace mp_units {
template<symbol_text Symbol, @\exposconceptnc{QuantityKindSpec}@ auto QS>
template<@\exposidnc{symbol-text}@ Symbol, @\exposconceptnc{QuantityKindSpec}@ auto QS>
requires(!Symbol.empty()) && @\exposconceptnc{BaseDimension}@<std::remove_const_t<decltype(QS.dimension)>>
struct @\libglobal{named_unit}@<Symbol, QS> : @\exposidnc{unit-interface}@ {
using @\exposidnc{base-type}@ = named_unit; // \expos
static constexpr auto @\exposidnc{symbol}@ = Symbol; // \expos
static constexpr auto @\exposidnc{quantity-spec}@ = QS; // \expos
};
template<symbol_text Symbol, @\exposconceptnc{QuantityKindSpec}@ auto QS, @\libconcept{PointOrigin}@ auto PO>
template<@\exposidnc{symbol-text}@ Symbol, @\exposconceptnc{QuantityKindSpec}@ auto QS, @\libconcept{PointOrigin}@ auto PO>
requires(!Symbol.empty()) && @\exposconceptnc{BaseDimension}@<std::remove_const_t<decltype(QS.dimension)>>
struct named_unit<Symbol, QS, PO> : @\exposidnc{unit-interface}@ {
using @\exposidnc{base-type}@ = named_unit; // \expos
Expand All @@ -2427,37 +2564,37 @@
static constexpr auto @\exposidnc{point-origin}@ = PO; // \expos
};
template<symbol_text Symbol>
template<@\exposidnc{symbol-text}@ Symbol>
requires(!Symbol.empty())
struct named_unit<Symbol> : @\exposidnc{unit-interface}@ {
using @\exposidnc{base-type}@ = named_unit; // \expos
static constexpr auto @\exposidnc{symbol}@ = Symbol; // \expos
};
template<symbol_text Symbol, @\libconcept{Unit}@ auto U>
template<@\exposidnc{symbol-text}@ Symbol, @\libconcept{Unit}@ auto U>
requires(!Symbol.empty())
struct named_unit<Symbol, U> : decltype(U)::@\exposidnc{base-type}@ {
using @\exposidnc{base-type}@ = named_unit; // \expos
static constexpr auto @\exposidnc{symbol}@ = Symbol; // \expos
};
template<symbol_text Symbol, @\libconcept{Unit}@ auto U, @\libconcept{PointOrigin}@ auto PO>
template<@\exposidnc{symbol-text}@ Symbol, @\libconcept{Unit}@ auto U, @\libconcept{PointOrigin}@ auto PO>
requires(!Symbol.empty())
struct named_unit<Symbol, U, PO> : decltype(U)::@\exposidnc{base-type}@ {
using @\exposidnc{base-type}@ = named_unit; // \expos
static constexpr auto @\exposidnc{symbol}@ = Symbol; // \expos
static constexpr auto @\exposidnc{point-origin}@ = PO; // \expos
};
template<symbol_text Symbol, @\libconcept{AssociatedUnit}@ auto U, @\exposconceptnc{QuantityKindSpec}@ auto QS>
template<@\exposidnc{symbol-text}@ Symbol, @\libconcept{AssociatedUnit}@ auto U, @\exposconceptnc{QuantityKindSpec}@ auto QS>
requires(!Symbol.empty()) && (QS.dimension == @\exposidnc{get-associated-quantity}@(U).dimension)
struct named_unit<Symbol, U, QS> : decltype(U)::@\exposidnc{base-type}@ {
using @\exposidnc{base-type}@ = named_unit; // \expos
static constexpr auto @\exposidnc{symbol}@ = Symbol; // \expos
static constexpr auto @\exposidnc{quantity-spec}@ = QS; // \expos
};
template<symbol_text Symbol, @\libconcept{AssociatedUnit}@ auto U, @\exposconceptnc{QuantityKindSpec}@ auto QS,
template<@\exposidnc{symbol-text}@ Symbol, @\libconcept{AssociatedUnit}@ auto U, @\exposconceptnc{QuantityKindSpec}@ auto QS,
@\libconcept{PointOrigin}@ auto PO>
requires(!Symbol.empty()) && (QS.dimension == @\exposidnc{get-associated-quantity}@(U).dimension)
struct named_unit<Symbol, U, QS, PO> : decltype(U)::@\exposidnc{base-type}@ {
Expand Down Expand Up @@ -2536,7 +2673,7 @@
\begin{codeblock}
namespace mp_units {
template<symbol_text Symbol, @\libconcept{Magnitude}@ auto M, @\libconcept{PrefixableUnit}@ auto U>
template<@\exposidnc{symbol-text}@ Symbol, @\libconcept{Magnitude}@ auto M, @\libconcept{PrefixableUnit}@ auto U>
requires(!Symbol.empty())
struct prefixed_unit : decltype(M * U)::@\exposidnc{base-type}@ {
using @\exposidnc{base-type}@ = prefixed_unit; // \expos
Expand Down

0 comments on commit d75d845

Please sign in to comment.