The best quantity creation helper

[mpusz]

Right now we have three different kinds of quantity creation helpers:

• Units Aliases
• Quantity References
• User-Defined Literals

We should try to choose the best one that will remain in the library. All others will eventually be removed and only one will end up in the final product (C++ Standard???).

All of them are described in detail in the Quantity Construction Helpers documentation chapter.

To get more gut feeling of each option you can also compare the examples in the following three directories:

• example/aliases
• example/references
• example/literals

Please familiarize yourself with the documentation mentioned above and then vote, comment, or provide feedback on the below options.

Also, if I didn't account for some important feature in the documentation, please let me know in the comments below and I will update the docs.

[mpusz]

Aliases

using namespace units::aliases::isq;
si::length::km<> d(123);
si::speed::km_per_h<int> v(70);

or

using namespace units::aliases::isq;
si::length::km d(123.);
si::speed::km_per_h v(70);

or

using namespace units::aliases::isq::si;
auto d = km(123.);
auto v = km_per_h(70);

[mpusz]

Thanks @kwikius 😃

[mpusz]

References

using namespace units::isq::si::references;
auto d = 123. * km;
auto v = 70 * (km / h);

[mpusz]

Literals

using namespace units::isq::si::literals;
auto d = 123._q_km;
auto v = 70_q_km_per_h;

[kwikius]

https://github.com/mpusz/units/blob/master/example/references/clcpp_response.cpp#L43
https://github.com/mpusz/units/blob/master/example/references/clcpp_response.cpp#L69
https://github.com/mpusz/units/blob/master/example/references/capacitor_time_curve.cpp#L47
https://github.com/mpusz/units/blob/master/example/references/experimental_angle.cpp#L27

Enough said I think. short names in global namespace is unacceptable.

Why not just keep both the other two. They are both useful in different places

[mpusz]

I assume that your comment applies to References rather than Literals, right? So would you prefer to leave Literals and Aliases?

[kwikius]

Yes, I should have put it above. I often use literals and aliases together. ( That is also important since I dont use downcasting, but I still think downcasting is too restrictive. It is preferable to have anonymous quantities to which you provide a name if you wish, but we covered that before...) In most cases you just want to initialise with some default value.When you are reviewing the code things are now unambiguous for even causal reviewer. Code review is a really important but underrated part of units library even for single developer some time later.

si::time::us rise_time = 98_q_us;

It would be nice to have both the above and allow the underlying type to be modified. Is that not now possible in the language?

si::time::us<int> rise_time = 98_q_us;

---

Incidentally when I do use value initialisation I always use the curly brace init syntax, since the other is grammatically ambiguous with functions. Again this helps the reviewer, but you cant enforce it in the language as far as I know. Would be another nice feature if you could:

si::time::us<int> rise_time{98}; // OK rise_time is a variable but...
si::time::us rise_time(foo);// now quite hard to figure if rise_time is a variable or a function

---

The shorter names have issues since they can be ambiguous. This is fine if used locally but for a library I think it is preferable to just provide the longer but unambiguous versions:

min t; // time or angle?
si::angle::min theta; // ok
si::time::min t2;  // ok

[ghost]

You say that all but one of theses features will be eventually removed. In the case of references, would it mean removing the reference template altogether or removing only the variables associated with specific quantities?

[mpusz]

I think that the reference class template will remain even when references would not be used as a quantity creation helper. I find them really useful for some use cases:

https://github.com/mpusz/units/blob/ab66455fb12175e22b229629e0a3c9432264398b/example/kalman_filter/kalman.h#L45-L48

https://github.com/mpusz/units/blob/ab66455fb12175e22b229629e0a3c9432264398b/example/kalman_filter/kalman.h#L68-L76

Having a dimension as a value would also help a lot, but that would break the downcasting functionality...

[ghost]

OK, if the reference template stays in no matter what, then it is also easy for the user to define a creation helper from it, so it wouldn't be the worst if reference creation helpers were gone. The same goes for aliases. Defining literals takes more effort, but I also find them least helpful. Aliases and references seem to be about equally useful.

Here is one more thing to consider: aliases are useful beyond being quantity creation helpers. When you are just defining quantity values, you don't really need to name their types. But when you want to include a quantity as a member in a class, you pretty much need to write out the full type and this is where aliases come in very handy. So I would say that references should stay as creation helpers and ideally aliases should also stay for a separate reason.

[TheoFletcher]

I'm new to using this library, but here are some of my initial thoughts on quantity creation.

I'm not a fan of user-defined literals. You've put plenty of reasons why they aren't a good choice in the documentation, all of which I agree with. On the other hand, I think references are really useful and readable. To me, an expression like = (5.0 * m) / (2.0 * s) genuinely reflects how units work conceptually, and it's a good translation of how you'd write such a thing on paper. I've used a few units libraries in Python, and quantity creation like this seems to be pretty standard. So overall this feels like the easiest way.

However, I'm not sure declaring a huge list of references as is currently implemented is the best way. As pointed out above, short variable names that can be imported into the global namespace aren't a good idea. Also, shortened names makes the link between the unit and its reference more confusing e.g.: it isn't immediately clear that si::reference::cm relates to si::centimetre. The other issue is it requires implementing separate references for every unit. This feels like a lot more code, a lot of places to make mistakes and most of our users will only use a handful of them anyway.

Why not leave creating references entirely up to the user? It keeps the relationship to the corresponding quantity clear, the user can pick a shortened name that won't conflict, and they would have to do this anyway for any derived unit. Also pairs well with aliases:

// User code
constexpr auto &m = quantity<si::dim_length, metre>::reference;
constexpr auto &km = si::length<si::kilometre>::reference;

I think aliases are a good idea as well, and they are useful beyond construction (as more readable class members and function arguments). However, for the same reasons as above, I'm not sure implementing a huge list of aliases is the best way. This is especially true for unit-specific aliases. I don't think si::length::metre<> is any more readable or convenient than si::length<si::metre>. If anything, I personally find it less readable: the variable isn't a metre, its a length with units of metres. At some point the user will want to define their own dimension, at which point they'll need to define their own alias as well, so why not leave all aliases up to the user?

I did have an idea for defining aliases while cutting down on extra code, but I have limited working of the internals of the library so please feel free to critique. Instead of defining a dimension (dim_length) and then an alias (length), could you just define the alias and then access the dimension with length<>::dimension? We maintain one public class per dimension, but we get access to an alias and the dimension class.

template<Unit U = metre, Representation Rep = double>
using length = quantity<base_dimension<"L", metre>, U, Rep>;

// Use internal namespace for dimension classes too long to declare in the quantity definition
namespace internal {
    struct dim_area : derived_dimension<dim_area, square_metre, exponent<length<>::dimension, 2>> {};
}

template<Unit U = square_metre, Representation Rep = double>
using area = quantity<internal::dim_area, U, Rep>;

TLDR: User-defined literals bad, references and aliases good. Leave actually creating references and aliases up to the user: it saves on a lot of code, and you'll never cover all the possibilities the user might need anyway.