Question about V2 and migration to it

[HazardyKnusperkeks]

Hi there,

I'm using this library quite some time now, but only with a very limited number of units. I've wrapped it into some typedefs and written my own (fmt) formatter, because yours couldn't what I wanted, at least at that time.

Since I am about to add some new units to my wrapper I checked for updates and found V2. This seems to be quite different, is there any documentation on how to migrate from V1 to V2?

My use cases (up until now) are like:

Units::Byte<std::int64_t> bytes = 1 * KiB;
Units::Byte<std::int64_t> secondByte{2 * B};
Units::KibiByte<std::int64_t> kibiBytes{1 * KiB};
auto result = bytes + Units::Byte<std::int64_t>{kibiBytes};

So I'd like to have a (prefixed) quantity as template on the underlying type, and the V1 references, I don't care how they are called in V2 and how this is implemented.

[JohelEGP]

There's some general documentation here: https://github.com/mpusz/units/pull/397/files.
What you're interested in starts at https://github.com/mpusz/units/pull/391/files#diff-39f66401b6ff6abb5554246bb5c308c479a45b284b7c0f8be1a238a0e36b7533R77.

[HazardyKnusperkeks]

Thanks I'll have a look at it. Although the diff id in the 2nd link does not exist. I just browse the complete change.

[JohelEGP]

This one points to the file: test/unit_test/static/iec80000_test.cpp https://github.com/mpusz/units/pull/391/files#diff-39f66401b6ff6abb5554246bb5c308c479a45b284b7c0f8be1a238a0e36b7533.

[mpusz]

@HazardyKnusperkeks Thanks for the interest in the library 😉

The V2, unfortunately, is still WIP (Work In Progress) on a branch which even does not properly compile now. I hope to finish it for gcc-12 in the next month or so and then make other compilers work with it as well. All of this takes a lot of time 😢

V2 will be a big breaking change, so definitely some changes to the codebase will be needed. The changes are in class templates, namespace names, header file names, and files layout. You can find some look and feel and rationale for V2 here: https://github.com/train-it-eu/conf-slides/blob/master/2023.04%20-%20ACCU%202023/mp-units%20-%20Lessons%20learned%20and%20a%20new%20library%20design.pdf.

In the V2, your example code can look like this:

quantity<byte, std::int64_t> bytes = 1 * KiB;
quantity<byte, std::int64_t> secondByte = 2 * B;
quantity<kibi<byte>, std::int64_t> kibiBytes = 1 * KiB;
auto result = bytes + kibiBytes[byte];

or

auto bytes = (std::int64_t{1} * KiB)[byte];
auto secondByte = std::int64_t{2} * B;
auto kibiBytes = std::int64_t{1} * KiB;
auto result = bytes + kibiBytes;

or

quantity<storage_capacity[byte], std::int64_t> bytes = (std::int64_t{1} * KiB)[byte];
quantity<storage_capacity[byte], std::int64_t> secondByte = 2 * B;
quantity<storage_capacity[kibi<byte>], std::int64_t> kibiBytes = 1 * KiB;
auto result = bytes + kibiBytes[byte];

It is up to you to choose the one you prefer. Of course, you can provide user-specific helpers (i.e. alias templates) to have any desired syntax.

and written my own (fmt) formatter, because yours couldn't what I wanted, at least at that time.

Could you please share what is your desired formatting and how it differs from the one provided in the library. Please note, that the V2 already provides nice extensions in this domain as well. You can find samples in the below links:

• https://github.com/mpusz/units/blob/8ef6d409b2df8e9fef1d35b0c07af9661eb85209/test/unit_test/runtime/fmt_test.cpp#L258-L342
• https://github.com/mpusz/units/blob/v2_framework/test/unit_test/static/unit_symbol_test.cpp

[JohelEGP]

Add

void foo(quantity<hPa>) {}

and it wouldn't be ambiguous, right?
IIRC, that's valid, and the type of 1 * hPa.
Is there any encouragement to actually add the quantity to the unit?
Or will it be necessary to teach to do it? And risk unsafe code otherwise.
If so, it's worth considering making quantity<hPa> illegal and 1 * hPa be some other type.

[mpusz]

and it wouldn't be ambiguous, right?

Right, but passing 1 * Pa could be ambiguous again?

Is there any encouragement to actually add the quantity to the unit?
Or will it be necessary to teach to do it? And risk unsafe code otherwise.
If so, it's worth considering making quantity illegal and 1 * hPa be some other type.

I like to think that in V2, we have two modes: easy and advanced. Easy mode is quantity_spec agnostic. If you do not care about specific quantity types, you are encouraged to use this easy mode. It is less to type and compiler errors and the debugger will deal with shorter types as well. As we discussed with @chiphogg, most users will probably be interested in such a use case, and this it the mode that all other units libraries on the market operate. Advanced mode is available in mp-units only and allows specifying a concrete quantity type. This gets useful only in cases when you have multiple quantities of the same kind in the hierarchy. If I am not wrong, ISQ defines only one quantity of pressure, so there might not be a need for using strong quantity_spec with it unless the user will define their own like above mentioned calibrated_pressure and uncalibrated_pressure. All other generic libraries can provide interfaces like quantity<hPa>, and strong quantity types defined by some users (when needed) should be able to benefit from those. This is why quantity<pressure[hPa]> is convertible to quantity<hPa>. Said that I believe that feature is really useful, and making such syntax illegal will be a mistake and a burden for many users.

[chiphogg]

Au's QuantityPoint behaves a little differently. The only constructors we have are from other QuantityPoints as appropriate.

We explicitly don't have a constructor from a Quantity. If you have a Quantity, the only way to "turn it into a QuantityPoint" is to add it to some other QuantityPoint.

The reason is that the "quantity to quantity point" conversion is ambiguous, especially if it takes place across an API boundary where users can easily miss that such a conversion is taking place. For example: what if you have a quantity of Celsius, and you pass it to an API expecting a temperature quantity point? You'll get a very different answer if the units are Celsius versus, say, Kelvins.

By contrast, adding to a pre-existing quantity point is perfectly unambiguous. It's always crystal clear what the right answer is, even if you mix together quantities and quantity points of different units to your heart's content.

(And where do you get that pre-existing QuantityPoint in Au? Via a "quantity point maker", which takes a raw numeric type. For example, celsius_pt(20) makes a QuantityPoint<Celsius, int>.)

---

Now back to mp-units. 🙂

I'd say definitely nix the implicit constructor (as you already concluded).

I'd also rather get rid of the explicit constructor, too. I think if end users decide to define an alias for the quantity_point of their preferred units, whether kelvins or celsius, then they should be able to do so safely --- and even be able to change the unit later, without fear! If you have an explicit quantity-to-quantity-point constructor, then you don't know what my_temperature_point_t{20 * C} (I think that's the syntax!) will actually do: it could give a temperature point of 20 C, or -253.15 C. That's why I'd rather lose the explicit constructor: something like zero_celsius + 20 * C, where zero_celsius is a quantity point, is safe and clear.

[mpusz]

I'd also rather get rid of the explicit constructor, too

I like your rationale, but I do not have a good idea of how to initialize quantity_point if we remove the constructor that takes a quantity. Providing just a number is not an option, as we agreed in #434 and implemented for V2. So instead of doing quantity_point<isq::length[si::metre]>(42), we should pass 42 * m to a quantity_point constructor. 42 * m syntax means a quantity in V2 already. I think that it is not a big issue. The quantity value passed to a constructor is a delta from the quantity_points point origin. If that is clearly stated in the docs, I do not think it will cause confusion. Additional benefit is that with this syntax CTAD works great so we can write quantity_point{42 * m} and it works just fine (at least unless you want to introduce a custom point origin).

We could make 42 * m to result in a different type than a quantity as mentioned by @JohelEGP recently. However, I think that would not be a good idea as it would complicate the design by adding yet another abstraction, It would also force most of the users to type more to get the same results. I think that 42 * m syntax is so cute that it would be a shame for it to not result in a quantity type 😉

However, if you have some idea on a better syntax to construct a quantity_point please let me know.

[chiphogg]

I like your rationale, but I do not have a good idea of how to initialize quantity_point if we remove the constructor that takes a quantity. Providing just a number is not an option, as we agreed in #434 and implemented for V2. So instead of doing quantity_point<isq::length[si::metre]>(42), we should pass 42 * m to a quantity_point constructor. 42 * m syntax means a quantity in V2 already. I think that it is not a big issue. The quantity value passed to a constructor is a delta from the quantity_points point origin. If that is clearly stated in the docs, I do not think it will cause confusion. [...]

If the quantity_point unit is named explicitly at the callsite, I agree. I think this will happen in the great majority of cases. I can think of two cases where we're still vulnerable. First, when end users choose an alias that abstracts away the unit choice. Second, when they change their choice of unit in a way that won't show up at every callsite (say, a vector<quantity_point<U>>).

We could make 42 * m to result in a different type than a quantity as mentioned by @JohelEGP recently. However, I think that would not be a good idea as it would complicate the design by adding yet another abstraction, It would also force most of the users to type more to get the same results. I think that 42 * m syntax is so cute that it would be a shame for it to not result in a quantity type 😉

Yes, fully agree: what we have already here is awesome, and we shouldn't mess with it.

However, if you have some idea on a better syntax to construct a quantity_point please let me know.

In Au, the reason this all works is because we've already set up this "maker" dance, for both Quantity and QuantityPoint. The raw number QuantityPoint constructor is private (which is consistent with #434), and the corresponding QuantityPointMaker can access it because it's a friend. e.g.,

// Inside the library:
constexpr auto celsius_pt = QuantityPointMaker<Celsius>{};

// In end user code:
constexpr auto room_temperature = celsius_pt(20);
// (produces `QuantityPoint<Celsius, int>`)

Now the real question: should mp-units switch to a "maker" approach for quantity_point? That, I don't know. What's idiomatic for Au may or may not fit with the idioms of mp-units. And, it would mean defining a bunch of extra symbols (the equivalents of Au's celsius_pt, meters_pt, etc.).

I think it's worth pondering over time, and not deciding swiftly. Maybe it will become more clear, the way the dilemmas about downcasting and UDLs did. 🙂