Programming focused quantities

[Jashweii]

I'm posting this in view of having read the slides & skimmed through the paper for the proposed standardised Quantity & Unit library, I haven't personally used the library though I have wanted something similar in the past.

I think the library is very useful but is almost exclusively geared towards SI-style scientific and engineering "end-"domains of programs, and extensibility in terms of new units. I think programming itself has its own types of quantity, unit and conversion that have very similar problems that don't or almost fit the mould (e.g. new operations). I wanted to bring some basic examples of the problem space up, not in the hope of them getting solved any time soon, but in case they raise any questions for the design or forwards compatibility (or a sort of sideways extensibility). For a bikeshed example, the namespace if there was a different system of non-SI units.

1. Index related. Many of these relate to non-integral length also (apart from endianness and iterators).

   • 0 vs 1 indexing (akin to affine space origin)

   • Index in bits, bytes, megabytes, mebibytes, elements with size S and [S inclusive/exclusive] stride U...
     Element type could produce incomparable quantities.

   • Index vs offset vs size vs stride vs alignment (related quantities of the same kind that sometimes are the same)

   • Functions taking many integral parameters (easily mixed up)

   • Indices into different things (quantities of the same kind)

   • Inclusive or exclusive indices [perhaps better as an orthogonal interval library? I would imagine overlap with quantities though]

   • Modular: negative (-1 as last) and circular (wrap around) indices.
     This could also be useful for angles (only sometimes) and perhaps length/distance (e.g. around a disk).

     The paper does briefly reference another paper on this, but without the focus on units.
     I'm not sure whether it would be a better idea to do it on the quantity or the representation, on the quantity could lead to improved accuracy when other types are involved.
     (But probably wouldn't in general without over-complicating things.)

     Perhaps more importantly though the bounds are tied to the unit.
     If an angle is in [-π,π] radians and gets converted to half turns, it should be in [-1, 1] half turns or [-π, π] radians (bounded by a comparable unit), not [-π, π] half turns (problem delegated to representation).
     This is perhaps a more general problem than e.g. knowing your value is going to be non-negative (but perhaps it then relates to affine spaces?).
     I would imagine the ideal solution would look something like quantity[_point]<periodic<Q, start, end>, T> or periodic<quantity_point<Q, T>, start, end>. E.g. quantity<periodic<angle, -π, π>, double>.
     [If one of these worked, you could also imagine a bounded or saturated version.]

   • Endianness of network bytes (as a unit)

   • Iterators & pointers as positions, indices and difference type as deltas
     Including e.g. adding raw byte offsets to typed pointers.

2. Masks (very common in conjunction with enums)

   • Bit vs bit mask (different quantities often with the same representation type)
   • Single set bit (1 << N) vs bit index N (different representation - sort of like different units for the same thing).

   It's not uncommon to end up working with all three, and having to convert between and avoid confusing them despite the same type, which is error prone and tedious for all the same reasons.

[mpusz]

@Jashweii, thanks a lot for your feedback. This is very interesting, and I admit that even though I thought about it and thought if that would be possible, I never tried to code it.

but is almost exclusively geared towards SI-style scientific and engineering "end-"domains of programs, and extensibility in terms of new units. I think programming itself has its own types of quantity, unit and conversion that have very similar problems that don't or almost fit the mould

This is not entirely true. In our docs we have an entire chapter on Dimensionless Quantities. We also have a workshop on Strongly-Typed Counts.

Index related

Index is technically a quantity point. So you may define "0 vs 1 indexing" with them and relative origins: https://godbolt.org/z/x4r1xTE5E. I know it is a bit hacky and the syntax may not be perfect, but it works. It can be extended to other cases as well, easily.

Masks (very common in conjunction with enums)

As long as indexes, offsets, and strides are quantities, I would argue that masks are not. You can't add numerically two masks or divide it by a scalar. This is why, even though I could provide some hacky solution even today, it is probably best not to use this library.

[Jashweii]

So instead of extending classes, it seems feasible based on what you're saying with masks to re-use the unit framework and create bespoke quantity[_point]-like templates with more, less, or entirely different operations. Is it possible to also leverage the symbolic constants in any way, or would it not work for the same reason? It doesn't necessarily have to encode 2 to the power of n, if n itself is used to mean 2's exponent.

Here are some other similar examples in the same vein as circular quantities that might benefit from the same treatment:

• signed integers: different types of modulo for negative numbers (but perhaps the two bounds on circular/periodic already determines this? Not sure)
• saturated (operations/conversions clamp to bounds) - not sure if this is physically realistic and works with SI units
• bounded but not clamped (inclusive, exclusive, half bounded)
  In terms of operation safety there are multiple useful options:
  • Operations with compile time constants that adjust bounds (this also applies to the other normalised version, but it's not always the operation you want)
  • Operations with runtime values that drop bounds
  • Unsafe operations that preserve bounds and are checked by contract/exception
• conversions between these for compatible bounds

[mpusz]

I am working on your use cases and have some progress. Type-safe indices are described here: https://mpusz.github.io/mp-units/latest/how_to_guides/advanced_usage/typed_indices.

Circular (wrap-around) quantities are still WIP, but we already have support for https://mpusz.github.io/mp-units/latest/users_guide/framework_basics/the_affine_space/#range-validated-quantity-points.

Please share feedback :-)

[Jashweii]

It looks good so far

Docs example: I've been trying the bounds example on Godbolt, gcc trunk, -std=c++26, and it complains

1. The quantity_bounds specialisations aren't in the mp_units namespace
2. deg isn't namespace qualified/used
3. I think it's missing the systems includes for si and isq
4. If I fix the above I still get CTAD failed, no matching function for 'quantity_point(mp_units::quantity<mp_units::non_si::degree(), double>)'

So I'm just going by what the docs are saying and the source code.

• Can the quantities interoperate with different units? E.g. quantity_bounds are in degrees, how does this work with radians?
  Does it still support being constructed with radians, and leave the bounds in degrees but multiply them during conversion?
• Is it not possible to have absolute bounds on quantity differences?
• Is it possible to have half bounded ranges? Assuming it isn't tied to the representation type, then you can't just assume infinities or specific integer/type limits.
• One other scenario I was thinking about is when you change bounds frequently (e.g. during a function) and don't want to specify each, potentially with the current setup that could be achieved by putting bounds in a template. But that relates to what I was saying before that sometimes you have a constant amount to offset/multiply by and actually want that to alter the bounds. So not sure if this is a bit against the grain of specialising for bounds.
• Mostly optimisation & might not affect standardisation - several of the enforce_bounds implementations could avoid loops with division or mod/fmod (but some fmod implementations are quite inaccurate for large values). Those loops can actually run forever on large enough floats (conversely might affect anyone using really small chemistry/physics bounds).

I haven't tried running the examples for typed indices but it looks exactly like I was thinking about.
For 2D it could relate to vector quantities (but I think that's a stub in the C++ paper anyway).

[mpusz]

and it complains

Yeah, sorry. It is still a work in progress. Here is a working example: https://godbolt.org/z/Yx6PcvYsd. I will improve the docs with the latest version as well.

Can the quantities interoperate with different units?

Yes.

Is it not possible to have absolute bounds on quantity differences?

Does it make sense? I think it could work for absolute quantities in V3, but I feel that deltas should be unbounded (especially since we may often get strange partial results of some calculations). Do you agree, or am I missing some important use cases?

Is it possible to have half bounded ranges?

Yes. I have halfline mentioned in the docs on my local branch. Will be committed soon.

One other scenario...

I am having a hard time understanding what you mean here... Can you provide a specific example? Do you mean something like https://mpusz.github.io/mp-units/latest/users_guide/framework_basics/representation_types/#magnitude-aware-scaling?

For 2D it could relate to vector quantities (but I think that's a stub in the C++ paper anyway).

In the paper yeas, but we have docs about it here: https://mpusz.github.io/mp-units/latest/blog/2025/01/15/bringing-quantity-safety-to-the-next-level/ and here https://mpusz.github.io/mp-units/latest/blog/2025/06/16/introducing-absolute-quantities/#scalar-and-vector-quantities.

[Jashweii]

I think you can bound deltas meaningfully but I'm not sure how important it is to support.

For the other thing, I'm imagining a situation where you're manipulating a value to get it into a certain range, and so you have it at different ranges intermediately. The two examples that come to mind are (1) range reduction (e.g. for a trig approximation) and (2) sometimes you do this sort of thing with integers for indexing. Maybe this doesn't make as much sense to do when working with quantities anyway, and the use case obviously isn't very clear.
But for a code example suppose you had a bounded delta d with bounds [N, M]. There could be a wrapper type adjust{X} (constant expression) such that:

d / adjust{X} // bounds: [N/X, M/X]
d - adjust{X} // bounds: [N-X, M-X]
d % adjust{X} // bounds: [1-|X| if |X| < 0 else 0, |X|-1] for integral X (replace 1 with 0 for floating)

etc.