PrefixType renamed to PrefixFamily + units hierarchy PNG fixed

docs/DESIGN.md

@@ -97,12 +97,12 @@ All below class templates indirectly derive from a `scaled_unit` class template
   - Defines a named, in most cases base or coherent unit that is then passed to a dimension's
     definition.
   - A named unit may be used by other units defined with the prefix of the same type, unless
-    `no_prefix` is provided for `PrefixType` template parameter (in such a case it is impossible
+    `no_prefix` is provided for `PrefixFamily` template parameter (in such a case it is impossible
     to define a prefixed unit based on this one).
 - `named_scaled_unit`
   - Defines a new named unit that is a scaled version of another unit.
   - Such unit can be used by other units defined with the prefix of the same type, unless
-    `no_prefix` is provided for `PrefixType` template parameter (in such a case it is impossible
+    `no_prefix` is provided for `PrefixFamily` template parameter (in such a case it is impossible
     to define a prefixed unit based on this one).
 - `prefixed_unit`
   - Defines a new unit that is a scaled version of another unit by the provided prefix.
@@ -115,26 +115,26 @@ All below class templates indirectly derive from a `scaled_unit` class template
   - All of the units provided should also be a named ones so it is possible to create a deduced
     symbol text.
 
-Some of the above types depend on `PrefixType` and `no_prefix`. `PrefixType` is a concept that
+Some of the above types depend on `PrefixFamily` and `no_prefix`. `PrefixFamily` is a concept that
 is defined as:
 
 ```cpp
 template<typename T>
-concept PrefixType = std::derived_from<T, prefix_type>;
+concept PrefixFamily = std::derived_from<T, prefix_family>;
 ```
 
-where `prefix_type` is just an empty tag type used to identify the beginning of prefix types
+where `prefix_family` is just an empty tag type used to identify the beginning of prefix types
 hierarchy and `no_prefix` is one of its children:
 
 ```cpp
-struct prefix_type {};
+struct prefix_family {};
-struct no_prefix : prefix_type {};
+struct no_prefix : prefix_family {};
 ```
 
 Concrete prefix derives from a `prefix` class template:
 
 ```cpp
-template<typename Child, PrefixType PT, basic_fixed_string Symbol, Ratio R>
+template<typename Child, PrefixFamily PT, basic_fixed_string Symbol, Ratio R>
   requires (!std::same_as<PT, no_prefix>)
 struct prefix;
 ```
@@ -151,7 +151,7 @@ Coming back to units, here are a few examples of unit definitions:
 namespace units::si {
 
 // prefixes
-struct prefix : prefix_type {};
+struct prefix : prefix_family {};
 struct centi : units::prefix<centi, prefix, "c", ratio<1, 1, -2>> {};
 struct kilo : units::prefix<kilo, prefix, "k", ratio<1, 1, 3>> {};
 
@@ -508,7 +508,7 @@ a series of checks:
   dimension:
   - prefix:
     - if ratio of the scaled unit is `1`, than no prefix is being printed,
-    - otherwise, if `PrefixType` template parameter of a reference unit is different than
+    - otherwise, if `PrefixFamily` template parameter of a reference unit is different than
       `no_prefix`, and if the ratio of scaled unit matches the ratio of a prefix of a specified
       type, than the symbol of this prefix will be used,
     - otherwise, non-standard ratio (i.e. `2 [60]Hz`) will be printed.
@@ -781,7 +781,7 @@ adds support for digital information quantities. In summary it adds:
     ```cpp
     namespace units::data {
 
-    struct prefix : prefix_type {};
+    struct prefix : prefix_family {};
 
     struct kibi : units::prefix<kibi, prefix, "Ki", ratio<    1'024>> {};
     struct mebi : units::prefix<mebi, prefix, "Mi", ratio<1'048'576>> {};

docs/framework/units.rst

@@ -219,7 +219,7 @@ complete list of all the :term:`SI` prefixes supported by the library::
 
     namespace si {
 
-    struct prefix : prefix_type {};
+    struct prefix : prefix_family {};
 
     struct yocto  : units::prefix<yocto,  prefix, "y",  ratio<1, 1, -24>> {};
     struct zepto  : units::prefix<zepto,  prefix, "z",  ratio<1, 1, -21>> {};
@@ -249,7 +249,7 @@ domain::
 
     namespace data {
 
-    struct prefix : prefix_type {};
+    struct prefix : prefix_family {};
 
     struct kibi : units::prefix<kibi, prefix, "Ki", ratio<                    1'024>> {};
     struct mebi : units::prefix<mebi, prefix, "Mi", ratio<                1'048'576>> {};
@@ -322,11 +322,11 @@ of a `scaled_unit` class template:
 
     #direction: right
 
-    [scaled_unit<Ratio, Unit>]<:-[unit<Child>]
+    [scaled_unit<UnitRatio, Unit>]<:-[unit<Child>]
-    [scaled_unit<Ratio, Unit>]<:-[named_unit<Child, Symbol, PrefixType>]
+    [scaled_unit<UnitRatio, Unit>]<:-[named_unit<Child, Symbol, PrefixFamily>]
-    [scaled_unit<Ratio, Unit>]<:-[named_scaled_unit<Child, Symbol, PrefixType, Ratio, Unit>]
+    [scaled_unit<UnitRatio, Unit>]<:-[named_scaled_unit<Child, Symbol, PrefixFamily, Ratio, Unit>]
-    [scaled_unit<Ratio, Unit>]<:-[prefixed_unit<Child, Prefix, Unit>]
+    [scaled_unit<UnitRatio, Unit>]<:-[prefixed_unit<Child, Prefix, Unit>]
-    [scaled_unit<Ratio, Unit>]<:-[deduced_unit<Child, Dimension, Unit, Unit...>]
+    [scaled_unit<UnitRatio, Unit>]<:-[deduced_unit<Child, Dimension, Unit, Unit...>]
 
 `scaled_unit` is a class template used exclusively by the library's framework
 and user should not instantiate it by him/her-self. However the user can sometimes

docs/reference/concepts.rst

@@ -5,58 +5,69 @@ Concepts
 
 .. note::
 
-  All names defined in this chapter reside in the :any:`units` namespace unless specified otherwise.
+    All names defined in this chapter reside in the :any:`units` namespace unless
+    specified otherwise.
 
-.. concept:: template<typename T> PrefixType
+.. concept:: template<typename T> PrefixFamily
 
-  Satisfied by all types derived from :class:`prefix_type`.
+    A concept matching a prefix family. Satisfied by all types derived from :class:`prefix_family`.
 
 .. concept:: template<typename T> Prefix
 
-  Satisfied by all instantiations of :class:`prefix`.
+    A concept matching a symbol prefix. Satisfied by all instantiations of :class:`prefix`.
 
 .. concept:: template<typename T> Ratio
 
-  Satisfied by all instantiations of :class:`ratio`.
+    A concept matching a ratio. Satisfied by all instantiations of :class:`ratio`.
 
 .. concept:: template<typename R> UnitRatio
 
-  Satisfied by all types that satisfy :expr:`Ratio<R>` and for which :expr:`R::num > 0` and :expr:`R::den > 0`.
+    A concept matching unit's ratio. Satisfied by all types that satisfy :expr:`Ratio<R>` and
+    for which :expr:`R::num > 0` and :expr:`R::den > 0`.
 
 .. concept:: template<typename T> BaseDimension
 
-  Satisfied by all dimension types derived from instantiation of :class:`base_dimension`.
+    A concept matching all base dimensions in the library. Satisfied by all dimension types
+    derived from the instantiation of :class:`base_dimension`.
 
 .. concept:: template<typename T> Exponent
 
-  Satisfied by all instantiations of :class:`exp`.
+    A concept matching dimension's exponents. Satisfied by all instantiations of :class:`exp`.
 
 .. concept:: template<typename T> DerivedDimension
 
-  Satisfied by all dimension types derived from instantiation of :class:`detail::derived_dimension_base`.
+    A concept matching all derived dimensions in the library. Satisfied by all dimension
+    types derived from the instantiation of :class:`detail::derived_dimension_base`.
 
 .. concept:: template<typename T> Dimension
 
-  Satisfied by all dimension types for which either :expr:`BaseDimension<T>` or :expr:`DerivedDimension<T>` is ``true``.
+    A concept matching all dimensions in the library. Satisfied by all dimension types for
+    which either :expr:`BaseDimension<T>` or :expr:`DerivedDimension<T>` is ``true``.
 
 .. concept:: template<typename T> Unit
 
-  Satisfied by all unit types derived from instantiation of :class:`scaled_unit`.
+    A concept matching all unit types in the library. Satisfied by all unit types derived
+    from the instantiation of :class:`scaled_unit`.
 
 .. concept:: template<typename U, typename D> UnitOf
 
-  Satisfied by all unit types that satisfy :expr:`Unit<U>`, :expr:`Dimension<D>`, and for which
+    A concept matching only units of a specified dimension. Satisfied by all unit types that
-  :expr:`U::reference` and :expr:`dimension_unit<D>::reference` denote the same unit type.
+    satisfy :expr:`Unit<U>`, :expr:`Dimension<D>`, and for which :expr:`U::reference` and
+    :expr:`dimension_unit<D>::reference` denote the same unit type.
+
+    :tparam U: Type to verify against concept constraints.
+    :tparam D: Dimension type to use for verification.
 
 .. concept:: template<typename T> Quantity
 
-  Satisfied by all instantiations of :class:`quantity`.
+    A concept matching all quantities in the library. Satisfied by all instantiations of :class:`quantity`.
 
 .. concept:: template<typename T> WrappedQuantity
 
-  Satisfied by all wrapper types that satisfy :expr:`Quantity<typename T::value_type>` recursively
+    A concept matching types that wrap quantity objects. Satisfied by all wrapper types that
-  (i.e. :expr:`std::optional<si::length<si::metre>>`).
+    satisfy :expr:`Quantity<typename T::value_type>` recursively
+    (i.e. :expr:`std::optional<si::length<si::metre>>`).
 
 .. concept:: template<typename T> Scalar
 
-  Satisfied by types that satisfy :expr:`(!Quantity<T>) && (!WrappedQuantity<T>) && std::regular<T>`.
+    A concept matching non-Quantity types. Satisfied by types that satisfy :expr:`(!Quantity<T>) && (!WrappedQuantity<T>) && std::regular<T>`.

src/include/units/bits/to_string.h

@@ -64,7 +64,7 @@ constexpr auto ratio_text()
   }
 }
 
-template<typename Ratio, typename PrefixType>
+template<typename Ratio, typename PrefixFamily>
 constexpr auto prefix_or_ratio_text()
 {
   if constexpr(Ratio::num == 1 && Ratio::den == 1 && Ratio::exp == 0) {
@@ -72,11 +72,11 @@ constexpr auto prefix_or_ratio_text()
     return basic_fixed_string("");
   }
   else {
-    if constexpr (!std::is_same_v<PrefixType, no_prefix>) {
+    if constexpr (!std::is_same_v<PrefixFamily, no_prefix>) {
       // try to form a prefix
-      using prefix = downcast<detail::prefix_base<PrefixType, Ratio>>;
+      using prefix = downcast<detail::prefix_base<PrefixFamily, Ratio>>;
 
-      if constexpr(!std::is_same_v<prefix, prefix_base<PrefixType, Ratio>>) {
+      if constexpr(!std::is_same_v<prefix, prefix_base<PrefixFamily, Ratio>>) {
         // print as a prefixed unit
         return prefix::symbol;
       }
@@ -149,7 +149,7 @@ constexpr auto unit_text()
     // print as a prefix or ratio of a coherent unit
     using coherent_unit = dimension_unit<Dim>;
     using ratio = ratio_divide<typename U::ratio, typename coherent_unit::ratio>;
-    auto prefix_txt = prefix_or_ratio_text<ratio, typename U::reference::prefix_type>();
+    auto prefix_txt = prefix_or_ratio_text<ratio, typename U::reference::prefix_family>();
 
     if constexpr(has_symbol<coherent_unit>) {
       // use predefined coherent unit symbol

src/include/units/concepts.h

@@ -42,11 +42,16 @@ concept basic_arithmetic = // exposition only
 
 } // namespace detail
 
-// PrefixType
+// PrefixFamily
-struct prefix_type;
+struct prefix_family;
 
+/**
+ * @brief A concept matching a prefix family
+ * 
+ * Satisfied by all types derived from `prefix_family`
+ */
 template<typename T>
-concept PrefixType = std::derived_from<T, prefix_type>;
+concept PrefixFamily = std::derived_from<T, prefix_family>;
 
 // Prefix
 // TODO gcc:92150
@@ -56,11 +61,16 @@ concept PrefixType = std::derived_from<T, prefix_type>;
 //   template<typename T>
 //   inline constexpr bool is_prefix = false;
 
-//   template<typename PrefixType, Ratio R, basic_fixed_string Symbol>
+//   template<typename PrefixFamily, Ratio R, basic_fixed_string Symbol>
-//   inline constexpr bool is_prefix<prefix<PrefixType, R, Symbol>> = true;
+//   inline constexpr bool is_prefix<prefix<PrefixFamily, R, Symbol>> = true;
 
 // }  // namespace detail
 
+/**
+ * @brief A concept matching a symbol prefix
+ * 
+ * Satisfied by all instantiations of `prefix`.
+ */
 template<typename T>
 //  concept Prefix = detail::is_prefix<T>;
 concept Prefix = true;
@@ -73,11 +83,19 @@ inline constexpr bool is_ratio = false;
 
 } // namespace detail
 
+/**
+ * @brief A concept matching a ratio
+ * 
+ * Satisfied by all instantiations of `ratio`.
+ */
 template<typename T>
 concept Ratio = detail::is_ratio<T>;
 
-
+/**
-// UnitRatio
+ * @brief A concept matching unit's ratio
+ * 
+ * Satisfied by all types that satisfy `Ratio<R>` and for which `R::num > 0` and `R::den > 0`
+ */
 template<typename R>
 concept UnitRatio = Ratio<R> && R::num > 0 && R::den > 0; // double negatives not allowed
 
@@ -85,10 +103,14 @@ concept UnitRatio = Ratio<R> && R::num > 0 && R::den > 0; // double negatives no
 template<UnitRatio R, typename U>
 struct scaled_unit;
 
+/**
+ * @brief A concept matching all unit types in the library
+ * 
+ * Satisfied by all unit types derived from the instantiation of :class:`scaled_unit`.
+ */
 template<typename T>
 concept Unit = is_derived_from_instantiation<T, scaled_unit>;
 
-// BaseDimension
 template<basic_fixed_string Symbol, Unit U>
   requires U::is_named
 struct base_dimension;
@@ -112,6 +134,11 @@ inline constexpr bool is_base_dimension<base_dimension<Name, Params...>> = true;
 
 }  // namespace detail
 
+/**
+ * @brief A concept matching all base dimensions in the library.
+ * 
+ * Satisfied by all dimension types derived from the instantiation of `base_dimension`.
+ */
 template<typename T>
 concept BaseDimension = detail::is_base_dimension<typename T::base_type_workaround>;
 
@@ -123,6 +150,11 @@ inline constexpr bool is_exp = false;
 
 }  // namespace detail
 
+/**
+ * @brief A concept matching dimension's exponents.
+ * 
+ * Satisfied by all instantiations of :class:`exp`.
+ */
 template<typename T>
 concept Exponent = detail::is_exp<T>;
 
@@ -135,10 +167,20 @@ struct derived_dimension_base;
 
 } // namespace detail
 
+/**
+ * @brief A concept matching all derived dimensions in the library.
+ * 
+ * Satisfied by all dimension types derived from the instantiation of `detail::derived_dimension_base`.
+ */
 template<typename T>
 concept DerivedDimension = is_instantiation<downcast_base_t<T>, detail::derived_dimension_base>;
 
 // Dimension
+/**
+ * @brief A concept matching all dimensions in the library. 
+ * 
+ * Satisfied by all dimension types for which either `BaseDimension<T>` or `DerivedDimension<T>` is `true`.
+ */
 template<typename T>
 concept Dimension = BaseDimension<T> || DerivedDimension<T>;
 
@@ -163,6 +205,15 @@ struct dimension_unit_impl<D> {
 template<Dimension D>
 using dimension_unit = detail::dimension_unit_impl<D>::type;
 
+/**
+ * @brief A concept matching only units of a specified dimension.
+ * 
+ * Satisfied by all unit types that satisfy `Unit<U>`, `Dimension<D>`, and for which
+ * `U::reference` and `dimension_unit<D>::reference` denote the same unit type.
+ * 
+ * @tparam U Type to verify.
+ * @tparam D Dimension type to use for verification.
+ */
 template<typename U, typename D>
 concept UnitOf =
   Unit<U> &&
@@ -177,6 +228,11 @@ inline constexpr bool is_quantity = false;
 
 }  // namespace detail
 
+/**
+ * @brief A concept matching all quantities in the library.
+ * 
+ * Satisfied by all instantiations of :class:`quantity`.
+ */
 template<typename T>
 concept Quantity = detail::is_quantity<T>;
 
@@ -193,11 +249,22 @@ inline constexpr bool is_wrapped_quantity<T> = Quantity<typename T::value_type>
 
 }  // namespace detail
 
+/**
+ * @brief A concept matching types that wrap quantity objects.
+ * 
+ * Satisfied by all wrapper types that satisfy `Quantity<typename T::value_type>`
+ * recursively (i.e. `std::optional<si::length<si::metre>>`).
+ */
 template<typename T>
 concept WrappedQuantity = detail::is_wrapped_quantity<T>;
 
 // Scalar
+/**
+ * @brief A concept matching non-Quantity types.
+ * 
+ * Satisfied by types that satisfy `(!Quantity<T>) && (!WrappedQuantity<T>) && std::regular<T>`.
+ */
 template<typename T>
-concept Scalar = (!Quantity<T>) && (!WrappedQuantity<T>) && std::regular<T>; // && std::totally_ordered<T>;// && detail::basic_arithmetic<T>;
+concept Scalar = (!Quantity<T>) && (!WrappedQuantity<T>) && std::regular<T>; // TODO: && std::totally_ordered<T>;// && detail::basic_arithmetic<T>;
 
 }  // namespace units

src/include/units/data/prefixes.h

@@ -26,7 +26,7 @@
 
 namespace units::data {
 
-struct prefix : prefix_type {};
+struct prefix : prefix_family {};
 
 struct kibi : units::prefix<kibi, prefix, "Ki", ratio<                    1'024>> {};
 struct mebi : units::prefix<mebi, prefix, "Mi", ratio<                1'048'576>> {};

src/include/units/physical/si/prefixes.h

@@ -26,7 +26,7 @@
 
 namespace units::si {
 
-struct prefix : prefix_type {};
+struct prefix : prefix_family {};
 
 // clang-format off
 struct yocto  : units::prefix<yocto,  prefix, "y",      ratio<1, 1, -24>> {};

src/include/units/prefix.h

@@ -29,11 +29,11 @@
 namespace units {
 
 /**
- * @brief The base for all prefix types
+ * @brief The base for all prefix families
  *
- * Every prefix type should inherit from this type to satisfy PrefixType concept.
+ * Every prefix family should inherit from this type to satisfy PrefixFamily concept.
  */
-struct prefix_type {};
+struct prefix_family {};
 
 /**
  * @brief No prefix possible for the unit
@@ -41,13 +41,13 @@ struct prefix_type {};
  * This is a special prefix type tag specifying that the unit can not be scaled with any kind
  * of the prefix.
  */
-struct no_prefix : prefix_type {};
+struct no_prefix : prefix_family {};
 
 namespace detail {
 
-template<PrefixType PT, Ratio R>
+template<PrefixFamily PT, Ratio R>
 struct prefix_base : downcast_base<prefix_base<PT, R>> {
-  using prefix_type = PT;
+  using prefix_family = PT;
   using ratio = R;
 };
 
@@ -68,7 +68,7 @@ struct prefix_base : downcast_base<prefix_base<PT, R>> {
  * @tparam Symbol a text representation of the prefix
  * @tparam R factor to be used to scale a unit
  */
-template<typename Child, PrefixType PT, basic_fixed_string Symbol, Ratio R>
+template<typename Child, PrefixFamily PT, basic_fixed_string Symbol, Ratio R>
   requires (!std::same_as<PT, no_prefix>)
 struct prefix : downcast_child<Child, detail::prefix_base<PT, R>> {
   static constexpr auto symbol = Symbol;

src/include/units/unit.h

@@ -72,7 +72,7 @@ struct same_unit_reference : std::is_same<typename U1::reference, typename U2::r
 template<typename Child>
 struct unit : downcast_child<Child, scaled_unit<ratio<1>, Child>> {
   static constexpr bool is_named = false;
-  using prefix_type = no_prefix;
+  using prefix_family = no_prefix;
 };
 
 /**
@@ -94,11 +94,11 @@ struct unknown_coherent_unit : unit<unknown_coherent_unit> {};
  * @tparam Symbol a short text representation of the unit
  * @tparam PT no_prefix or a type of prefix family
  */
-template<typename Child, basic_fixed_string Symbol, PrefixType PT>
+template<typename Child, basic_fixed_string Symbol, PrefixFamily PT>
 struct named_unit : downcast_child<Child, scaled_unit<ratio<1>, Child>> {
   static constexpr bool is_named = true;
   static constexpr auto symbol = Symbol;
-  using prefix_type = PT;
+  using prefix_family = PT;
 };
 
 /**
@@ -115,11 +115,11 @@ struct named_unit : downcast_child<Child, scaled_unit<ratio<1>, Child>> {
  * @tparam R a scale to apply to U
  * @tparam U a reference unit to scale
  */
-template<typename Child, basic_fixed_string Symbol, PrefixType PT, UnitRatio R, Unit U>
+template<typename Child, basic_fixed_string Symbol, PrefixFamily PT, UnitRatio R, Unit U>
 struct named_scaled_unit : downcast_child<Child, scaled_unit<ratio_multiply<R, typename U::ratio>, typename U::reference>> {
   static constexpr bool is_named = true;
   static constexpr auto symbol = Symbol;
-  using prefix_type = PT;
+  using prefix_family = PT;
 };
 
 /**
@@ -134,12 +134,12 @@ struct named_scaled_unit : downcast_child<Child, scaled_unit<ratio_multiply<R, t
  * @tparam U reference unit
  */
 template<typename Child, Prefix P, Unit U>
-  requires U::is_named && std::same_as<typename P::prefix_type, typename U::prefix_type>
+  requires U::is_named && std::same_as<typename P::prefix_family, typename U::prefix_family>
 struct prefixed_unit :
     downcast_child<Child, scaled_unit<ratio_multiply<typename P::ratio, typename U::ratio>, typename U::reference>> {
   static constexpr bool is_named = true;
   static constexpr auto symbol = P::symbol + U::symbol;
-  using prefix_type = no_prefix;
+  using prefix_family = no_prefix;
 };
 
 /**
@@ -161,14 +161,14 @@ template<typename Child, DerivedDimension Dim, Unit U, Unit... URest>
 struct deduced_unit : downcast_child<Child, detail::deduced_unit<Dim, U, URest...>> {
   static constexpr bool is_named = false;
   static constexpr auto symbol = detail::deduced_symbol_text<Dim, U, URest...>();
-  using prefix_type = no_prefix;
+  using prefix_family = no_prefix;
 };
 
-// template<typename Child, Dimension Dim, basic_fixed_string Symbol, PrefixType PT, Unit U, Unit... Us>
+// template<typename Child, Dimension Dim, basic_fixed_string Symbol, PrefixFamily PT, Unit U, Unit... Us>
 // struct named_deduced_derived_unit : downcast_child<Child, detail::deduced_derived_unit<Dim, U, Us...>> {
 //   static constexpr bool is_named = true;
 //   static constexpr auto symbol = Symbol;
-//   using prefix_type = PT;
+//   using prefix_family = PT;
 // };
 
 }  // namespace units