Q: extension of units with non-unit NTTPs - what's recommended?

[RalphSteinhagen]

Thanks for this great and very useful addition to C++. Have been working/building particle accelerators for a couple of years now and this seems to nicely tackle a common source of errors in our (and probably many other similarly critical) projects at the source! Well done and hope that it will make it into C++23! 👍

We are modernising/reimplementing our serialiser that will rely on templates using NTTP to document the (domain-object) class member's unit, description (typ. a human-readable constant string) and other meta-information (other NTTPs).

Until now, we haven't used the unit for compile-time strong type-checks but I find your library and reasoning very appealing in that respect.

How would one go about including also other NTTP-type meta information in your approach? I.e. should we:
a) make a custom wrapper around your unit templates and hope for the best that our wrapper is as light-weight and efficient as yours -- that is -- it compiles away to nothing (i.e. using constexpr), or
b) are the already provisions in your unit templates for additional meta-data (string constants, other NTTP objects, etc.) to annotate the member variables?

This more of an open question for advice and possible feature request... Any help or suggestion would be much appreciated.

[mpusz]

I am happy that the library is useful in your field of experience 😃

Talking about NTTPs we use them only for ratio and symbol_text so far. Maybe at some point also exp will be an NTTP. I do not think we are going to have more of them although @JohelEGP is working on a POC (#248).

Regarding your question, I am not sure what kind of extensions do you mean. I think that according to a Single Responsibility Principle we should not extend library's types with information that is not needed by the library's engine. If you want to store additional information I would suggest providing custom wrappers/aggregates that will store both the information for the dimensional analysis as well as your additional information for serialization, etc.

Regarding your question about annotating member variables I think that the bests is to wait for reflection in the C++ language 😉 Until then you may look for some library-based solutions but I do not have experience in those.

[RalphSteinhagen]

@mpusz thanks for your quick reply.

Then option 'a)' it is. Presently we have something like

 constexpr Annotated<float,  "°C", "specific description ...">          val1 = 23.;

where I would follow up your recommendation and replace the first unit bit with your library template (and hoping that my wrapper remains as feather-light as yours).

Regarding your question about annotating member variables I think that the bests is to wait for reflection in the C++ language > wink Until then you may look for some library-based solutions but I do not have experience in those.

That's exactly what we are working on. 😉 We are working on a temporary solution within our middle-ware library that will be eventually superseded once the list of class members are also accessible in C++23/26 via static reflection.

Thanks again for your quick reply and recommendation... much appreciated!

[RalphSteinhagen]

@mpusz may I trouble you and get some help to get me jump-started? I have been experimenting on compiler-explorer but am unsure from which quantity template I need to derive and how much needs to be overridden for my use-case. Any help/hint would be welcome. Thanks in advance.

The MVP I got so far:

#define UNITS_REFERENCES
#define UNITS_LITERALS
#include <iostream>
#include <type_traits>
#include <units/quantity.h>
#include <units/quantity_cast.h>
#include <units/quantity_io.h>
#include <units/isq/si/length.h>
#include <units/isq/si/speed.h>


template<size_t N>
struct StringLiteral { // stand-in NTTP for extending units
    char value[N+1]{};

    constexpr StringLiteral(const char (&str)[N]) {
        std::copy_n(str, N, value);
        value[N] = '\0'; // force terminatation
    }
};

template<units::Representation Rep, units::Unit U, const StringLiteral description = "">
class Annotate : public units::quantity<U, Rep> {    
    template<typename T> // N.B. extend this for custom classes using type-traits to query nicer class-type name
    constexpr const char *getNicerTypeName() const noexcept {
        if (std::is_same<T, std::byte>::value)   { return "byte"; }
        if (std::is_same<T, char>::value)        { return "char"; }
        if (std::is_same<T, short>::value)       { return "short"; }
        if (std::is_same<T, int>::value)         { return "int"; }
        if (std::is_same<T, long>::value)        { return "long"; }
        if (std::is_same<T, float>::value)       { return "float"; }
        if (std::is_same<T, double>::value)      { return "double"; }
        if (std::is_same<T, std::string>::value) { return "string"; }
    
        return typeid(T).name();
    }
    public:
    // default constructor needed or can we inherit from 'quantity'
    // do I need to overload the space-ship '<=>' and other operators or can I rely on the inherited one?
    //constexpr char const *getUnit() const noexcept { return U.name(); } // here: transform to base-unit and return named value
    constexpr char const *getDescription() const noexcept { return description.value; }
    constexpr char const *getTypeName() const noexcept { return getNicerTypeName<Rep>(); }

    // friend constexpr std::ostream &operator<<(std::ostream &os, const Annotate& m) { return units::quantity::operator<<(os, m); }
};


int counter=0; // just for debugging
template<units::Representation Rep, units::Unit U, const StringLiteral description = "">
constexpr void printMetaInfo(const Annotate<Rep, U, description>& value) {
    std::cout << "value" << ++counter << ": '" << value << "' type: '" << value.getTypeName() << "' unit: '" << value.getUnit() << "' description: '" << value.getDescription() << "'\n";
}


int main() {
    using namespace units::isq;
    using namespace units::isq::si;
    using namespace units::isq::si::literals;
    using namespace units::isq::si::references;

    constexpr Speed auto valUnit = 110 * (km / h);

    constexpr Annotate<double, metre_per_second,  "custom description for velocity value">   val1(10.0 * (km /h));
    constexpr Annotate<double, metre_per_second,  "custom description for velocity value">   val2 = valUnit;
    constexpr Annotate<float, metre,  "custom description for length value">                 val3 = 100.0f * (km);
    
    printMetaInfo(val1);
    printMetaInfo(val2);
    printMetaInfo(val3);

    constexpr Speed auto val3 = units::quantity_cast<si::speed<si::metre_per_second>>(110 * (km / h));
    constexpr Speed auto val4 = units::quantity_cast<si::speed<si::metre_per_second>>(val1);
    std::cout << "value3: '" << val3 << "'\n";
    std::cout << "value4: '" << val4 << "'\n";
    return quantity_cast<metre_per_second>(valUnit).number();
}

P.S. mini side-question: have you/someone be able to use this when transpilling to WASM? The newer clang versions for x86_64 seem to work fine now.

[RalphSteinhagen]

@mpusz I am but a dwarf when I saw your meta-programming talk. Well done.

I finally got some time and picked up the wrapper concept idea mentioned above. Rather than defining the quantity struct as a delegate member in the wrapper, I decided to directly inherit from

template<Dimension D, UnitOf<D> U, Representation Rep = double>
class quantity { /* [..] */ }

in order to benefit from perfect operator forwarding. I also needed to defined two wrapper since quanity seems to be able to wrap only fundamental types and not arbitrary structs (saw the LA proposal regarding this in the issues 👍). This works to first order, but noticed that the existing Quantity concept does not recognise the wrapper as constexpr bool units::detail::is_quantity<quantity<D, U, Rep>> since this function basically checks for the number (3) and type of parameter. I was wondering whether this could be generified (see proposal below).

template<typename T>
inline constexpr bool is_quantity_new = requires { typename T::dimension;  typename T::unit;  typename T::rep; };

This could be possibly extended for checking for the actual concept compatibilities for each type (ie. checking that 'T::dimension' is Dimension compatible). Check also using class inheritance and template instantiations matches but the use of multiple template types together with NTTPs makes this a rather complex (impossible?) topic. Maybe you have an idea for a better/simpler solution?

Also found two additional issues: one that may be linked to is_quantity and missing operator forwarding and that may the root cause for a run-time crash 😲) and another minor one linked to constexpr concatenation of `basic_fixed_string' (I guess, everyone declares his/her own NTTP string literal these days -- curiously found many libraries that declare these 😄 ).

I was wondering whether you (or anybody else knowledgeable) could comment on this. I am also unsure regarding the constructor and other operator forwarding that may be necessary. E.g. the implicit constexpr operator R&() { return *this; } casting specifically to the quantity base class isn't called at all.

Many thanks in advance. Any help, hint, or suggestions would be highly appreciated.

The annotated (now working) wrapper example also at compiler-explorer:

#include <iostream>
#include <iostream>
#include <string>

#include <units/concepts.h>
#include <units/quantity.h>
#include <units/quantity_cast.h>
#include <units/quantity_io.h>
#include <units/isq/si/length.h>
#include <units/isq/si/speed.h>

template<typename T> // N.B. extend this for custom classes using type-traits to query nicer class-type name
constexpr const char *getNicerTypeName() noexcept {
    if (std::is_same<T, std::byte>::value)   { return "byte"; }
    if (std::is_same<T, char>::value)        { return "char"; }
    if (std::is_same<T, short>::value)       { return "short"; }
    if (std::is_same<T, int>::value)         { return "int"; }
    if (std::is_same<T, long>::value)        { return "long"; }
    if (std::is_same<T, float>::value)       { return "float"; }
    if (std::is_same<T, double>::value)      { return "double"; }
    if (std::is_same<T, std::string>::value) { return "string"; }
    
    return typeid(T).name();
}

template<typename T> concept ClassType = std::is_class<T>::value;
template<typename T> concept NonClassType = !std::is_class<T>::value;

template<typename Rep, typename Q = units::dimensionless<units::one>, const units::basic_fixed_string description = "" /*, more user-specific NTTPs */, typename T2 = void> struct Annotate;

template<NonClassType Rep, units::Quantity Q, const units::basic_fixed_string description>
struct Annotate<Rep, Q, description> : public units::quantity<typename Q::dimension, typename Q::unit, Rep> {
    using dimension = typename Q::dimension;
    using unit = typename Q::unit;
    using rep = Rep;
    using R = units::quantity<dimension, unit, Rep>;
    using String = std::string_view;
    constexpr Annotate() : R() {};
    constexpr explicit (!std::is_trivial_v<Rep>) Annotate(const R& t) : R(t) {}
    constexpr explicit (!std::is_trivial_v<Rep>) Annotate(R&& t) : R(std::move(t)) {}
    
    constexpr Annotate &operator=(const R& t) {  R::operator= (t); return *this; }
    constexpr Annotate &operator=(R&& t) { R::operator= (std::move(t)); return *this; }   

    //[[nodiscard]] constexpr const String getUnit() const noexcept { return String(units::detail::unit_text<dimension, unit>().ascii().c_str()); } // fails - mangled printout
    [[nodiscard]] /*constexpr*/ const std::string getUnit() const noexcept { return std::string(units::detail::unit_text<dimension, unit>().ascii().c_str()); } // OK
    [[nodiscard]] constexpr const String getDescription() const noexcept { return description.c_str(); } // -> API description
    [[nodiscard]] constexpr const String getTypeName() const noexcept { return getNicerTypeName<Rep>(); } // -> API description
    // [..]

   constexpr R& value() { return *this; }
   constexpr const R& value() const { return *this; }
   constexpr operator R&() { return *this; } // not implicitly called -> require 'value()' in user-code to explicitly handle quantities
   constexpr operator const R&() const { return *this; }
};



template<ClassType T, typename Q, const units::basic_fixed_string description>
struct Annotate<T, Q, description> : T {
    using String = std::string_view;
    constexpr Annotate(): T() {}
    //explicit (!std::is_trivial_v<T>) 
    constexpr Annotate(const T& t) : T(t) {}
    //explicit (!std::is_trivial_v<T>) 
    constexpr Annotate(T&& t) : T(std::move(t)) {}

    template<class... S>
	explicit Annotate(S&&... v) : T{std::forward<S>(v)...} {}

   template<class S , std::enable_if_t<std::is_constructible<T, std::initializer_list<S>>::value, int> = 0>
    Annotate(std::initializer_list<S> init) : T(init) {}

   template<typename U>
   requires (std::is_assignable<T, U>::value)
   Annotate(const U& u) : T(u) {}

   template<typename U>
   requires (std::is_assignable<T, U>::value)
   Annotate(U&& u) : T(std::move(u)) {}

   [[nodiscard]] constexpr const String getUnit() const noexcept { return ""; } // 'no unit' -> API description
   [[nodiscard]] constexpr const String getDescription() const noexcept { return description.c_str(); } // -> API description
   [[nodiscard]] constexpr const String getTypeName() const noexcept { return getNicerTypeName<T>(); } // -> API description
   
   constexpr operator T&() { return *this; }
   constexpr operator const T&() const { return *this; }

   std::ostream& operator<<(std::ostream& os) noexcept {
       return os << *this;
   }
};


namespace units::detail {
    // existing/nominal implementation in 'quantity.h':
    //template<typename D, typename U, typename Rep>
    //inline constexpr bool is_quantity<quantity<typename Q::dimension, typename Q::unit, Rep>> = true;

    // new proposed implementation to allow for derived/co-use in other templates
    template<typename T>
    requires units::is_derived_from_specialization_of<T, units::quantity> &&
        requires { 
    typename T::dimension;
    typename T::unit;
    typename T::rep; 
    requires Dimension<typename T::dimension>; 
    requires Unit<typename T::unit>; 
    requires Representation<typename T::rep>;
    }
    inline constexpr bool is_quantity<T> = true;
}

int counter = 0; // just for debugging
template<typename Rep, units::Quantity Q, const units::basic_fixed_string description = "">
constexpr void printMetaInfo(const Annotate<Rep, Q, description> &value) {
    std::cout << "value" << counter++ << ": '" << value << "' type: '" << value.getTypeName() << "' unit: '" << value.getUnit() << "' description: '" << value.getDescription() << "'\n";
}

// ############# user code ################
struct CustomUserStruct {
    double x = 1;
    double y = 2;
    double z = 3;
};

// N.B. 'operator<<' replaced by generic compile-time reflection
std::ostream& operator<<(std::ostream& os, const CustomUserStruct &m) noexcept { 
    return os << "{x:" << m.x << ", y: " << m.y << ", z: " << m.z << '}';
}

using namespace units::isq;
using namespace units::isq::si;
using NoUnit = units::dimensionless<units::one>;
using namespace std::literals;

constexpr Speed auto valUnit = 110._q_km_per_h;

struct DomainObject {
    si::speed<metre_per_second>                                                                 raw = valUnit;
    Annotate<int, si::speed<metre_per_second>, "description">                                   val0 = quantity_cast<si::speed<si::metre_per_second, int>>(valUnit);
    Annotate<double, si::speed<metre_per_second>,  "custom description for velocity value">     val1;
    Annotate<float, si::length<metre>,  "custom description for length value">                  val2;
    Annotate<float, si::time<second>,  "custom description for duration">                       val3;        
    Annotate<short, NoUnit, "no unit">                                                          val4;
    Annotate<std::string, NoUnit, "string documentation">                                       val5 = "Hello World!";
    Annotate<CustomUserStruct, NoUnit, "user-defined object1">                                  val6 = CustomUserStruct{1.1, 2.2, 3.3};
    Annotate<CustomUserStruct, NoUnit, "user-defined object2">                                  val7{1.1, 2.2, 3.3};

    DomainObject() : val1(10.0_q_km_per_h), val2(100.0_q_m), val3(9.8_q_s) {};
};


constexpr Speed auto avg_speed(Length auto d, Time auto t) {
  return d / t;
}

int main() {
    DomainObject data;    

    printMetaInfo(data.val0);
    printMetaInfo(data.val1);
    printMetaInfo(data.val2);
    printMetaInfo(data.val3);
    printMetaInfo(data.val4);
    printMetaInfo(data.val5);
    printMetaInfo(data.val6);
    printMetaInfo(data.val7);
    
    Speed auto fastRunnerVelocity = avg_speed(data.val2, data.val3);
    std::cout << "a fast athlete can run: " << fastRunnerVelocity << '\n';

    data.val2.number() = data.val2.number() + 20; // N.B. needed for raw serialiser read/write access - OK

    data.raw = 10.0_q_km_per_h;
    data.val1 = 12.0_q_km_per_h;

    std::cout << std::boolalpha;
    std::cout << "is_quantity_new data: " << units::detail::is_quantity<decltype(data)> << '\n'; // OK
    std::cout << "is_quantity raw:  " << units::detail::is_quantity<decltype(data.raw)>  << '\n';  // OK
    std::cout << "is_quantity val0: " << units::detail::is_quantity<decltype(data.val0)> << '\n'; // now OK (with mod of is_quantity<T>)
    std::cout << "is_quantity val5: " << units::detail::is_quantity<decltype(data.val5)> << '\n'; // OK
}

EDIT: fixed assignment operator calling base quantity class.
EDIT-2: fixed new is_quantity concept function proposal