v5 Release

[angularsen]

Fixes #180

Work in progress, please use this PR to discuss the changes and report any problems.

Breaking changes 💥

~~Rename BaseUnit to ConversionBaseUnit~~ #795 Default number format should be CultureInfo.CurrentCulture, not CurrentUICulture

Removed 🔥

Remove targets: net40, net47, Windows Runtime Component. Remove QuantityType enum Remove IQuantity.Units and .UnitNames Remove IEquatable<T> and equality operators/methods Remove GlobalConfiguration Remove obsolete and deprecated code. Remove Molarity ctor and operator overloads json: Remove UnitsNetJsonConverter

TODO

Add back IEquatable<T>, but implement as strict equality with tuple of quantity name + unit + value. https://github.com/angularsen/UnitsNet/issues/1017#issuecomment-1028401955

https://github.com/angularsen/UnitsNet/issues/1067

[angularsen]

@tmilnthorp @lipchev The V5 release branch is rolling. If there is anything you are eager to include/remove, then please give a heads up here. I hope to make this release in not too long.

I'll be going through #180 to see what seems like low-hanging fruit and try to get those, but don't wait for me if you want to do some of them.

One thing I'm looking to remove is UnitSystem, BaseUnits and BaseDimension as per #630 and #651, until the design is more complete, easier to use and maybe extensible. I'm interested to know if you are using this today so that removing it would cause problems for you.

[lipchev]

I think we can include the GetHashCode and IComparable tests/fixes in #838 (even if we removed IEquatable).

[lipchev]

As far as the UnitSystems - last I checked the implementation was ok for review. Or at least as a starting point (e.g. for v5). I didn't remove the BaseDimensions, but that could be done in a consequent step (with little change the current implementation). The only major thing missing was editing the remaining json files (adding default SI value). I don't have a particular need for it right now, but I think there could be potential uses for it- even beyond just the standard unit system.

[lipchev]

Also, if we would be breaking things- please consider also #983

[ebfortin]

I don't know if it's here that we should discuss breaks in v5 but here I go. Yesterday I upgraded to v5 alpha 3 to test it on one of my project and I got an error for the == operator. Going back to 4.x resolved the issue. I don't have the error details on hand right now.

[angularsen]

@ebfortin Thanks, could you please report back with the exact error and what you would expect instead? There are many breaking changes in v5, but if you found something that seems incorrect then it would be good to know.

[ebfortin]

@ebfortin Thanks, could you please report back with the exact error and what you would expect instead? There are many breaking changes in v5, but if you found something that seems incorrect then it would be good to know.

Severity Code Description Error CS0019 Operator '==' cannot be applied to operands of type 'ElectricPotential' and 'ElectricPotential'

[angularsen]

@ebfortin Right, it's in the breaking changes list.

Remove IEquatable and equality operators/methods

The reasoning is that comparing equality of two quantities should use the Equals() methods, where you can specify the accepted error. Internally, the quantity may be represented by double or decimal, so it is prone to subtle rounding errors.

[ebfortin]

Hmmm ok I see. At first I wrote that we should keep == and IEquatable since we have == for doubles and when you use it you know there are rounding errors possible. But I just realized that in my use case I shouldn't use == so the very reason you removed it. So thanks for that. I'll change my code and update to 5.

Télécharger Outlook pour Androidhttps://aka.ms/AAb9ysg

---

De : Andreas Gullberg Larsen @.***> Envoyé : vendredi 26 novembre 2021 20 h 35 À : angularsen/UnitsNet Cc : Étienne Fortin; Mention Objet : Re: [angularsen/UnitsNet] v5 Release (PR #982)

@ebfortinhttps://github.com/ebfortin Right, it's in the breaking changes list.

Remove IEquatable and equality operators/methods

The reasoning is that comparing equality of two quantities should use the Equals() methods, where you can specify the accepted error. Internally, the quantity may be represented by double or decimal, so it is prone to subtle rounding errors.

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHubhttps://github.com/angularsen/UnitsNet/pull/982#issuecomment-980482892, or unsubscribehttps://github.com/notifications/unsubscribe-auth/ABNYDWOEYHMW5D2LXKCMMWTUOAYXFANCNFSM5HFGGE7A. Triage notifications on the go with GitHub Mobile for iOShttps://apps.apple.com/app/apple-store/id1477376905?ct=notification-email&mt=8&pt=524675 or Androidhttps://play.google.com/store/apps/details?id=com.github.android&referrer=utm_campaign%3Dnotification-email%26utm_medium%3Demail%26utm_source%3Dgithub.

[tmilnthorp]

I didn't see this sorry.

One thing I'm looking to remove is UnitSystem, BaseUnits and BaseDimension

I think UnitSystem can go, but BaseDimensions and BaseUnits are useful and I'd like to see them stay. BaseDimensions and BaseUnits apply to all units. They help you know things like Length * Length= Area as well as the conversions needed for different units in that calculation (e.g. 2m * 2in = 0.1016 m^2).

[angularsen]

I think UnitSystem can go, but BaseDimensions and BaseUnits are useful and I'd like to see them stay

Thanks, that is useful to know. I am open to keep it, but I feel it would help me to learn what it can be used for in practice. I have not used them myself and am not sure what some good use cases are.

I find tests on BaseDimensions and BaseUnits isolated, but I can't seem to find any tests or examples where they are used together in a meaningful way. Some notes on the below points would help describe why they are useful and what future work may look like. Then we could document it in the wiki for future reference.

• What are some practical use cases for BaseDimensions/BaseUnits as it stands today? Or with future work?
• We can multiply base dimensions Length^1 * Length^1 = Length^2, but how do we arrive at Area?
• Isn't there ambiguity in that multiple quantities share the same base dimensions? F.ex. ApparentEnergy, Energy, RotationalStiffness and Torque seems to have L=2, M=1, T=-2.
• Some quantities don't seem to map to base dimensions, such as Angle or VitaminA. Is it fine to just leave them out?

If we keep them, how about renaming them to SiBaseDimensions and SiBaseUnits?

[tmilnthorp]

I think UnitSystem can go, but BaseDimensions and BaseUnits are useful and I'd like to see them stay

Thanks, that is useful to know. I am open to keep it, but I feel it would help me to learn what it can be used for in practice. I have not used them myself and am not sure what some good use cases are.

I find tests on BaseDimensions and BaseUnits isolated, but I can't seem to find any tests or examples where they are used together in a meaningful way. Some notes on the below points would help describe why they are useful and what future work may look like. Then we could document it in the wiki for future reference.

• What are some practical use cases for BaseDimensions/BaseUnits as it stands today? Or with future work?
• We can multiply base dimensions Length^1 * Length^1 = Length^2, but how do we arrive at Area?
• Isn't there ambiguity in that multiple quantities share the same base dimensions? F.ex. ApparentEnergy, Energy, RotationalStiffness and Torque seems to have L=2, M=1, T=-2.
• Some quantities don't seem to map to base dimensions, such as Angle or VitaminA. Is it fine to just leave them out?

If we keep them, how about renaming them to SiBaseDimensions and SiBaseUnits?

It was for future work, sorry I dropped off for a bit. Hoping to come back here 😃

To answer your questions:

What are some practical use cases for BaseDimensions/BaseUnits as it stands today? Or with future work?

I'd like to use BaseDimensions/BaseUnits in Multiply/Divide methods (and later in code like #984). We can actually generate these statically. For example, you know that Length * Length = Area. This uses BaseDimensions. For BaseUnits, Let's take Speed for example. We currently have a custom method: public static Speed operator /(Length length, Duration duration). This could be generated dynamically. There's also the issue that this will only return Speed.FromMetersPerSecond. That isn't too useful if you passed a Length of Feet and want like-units. Base units would let you dynamically construct 1000ft / 1s = 1000fps (Speed.FeetPerSecond)

We can multiply base dimensions Length^1 * Length^1 = Length^2, but how do we arrive at Area?

You find the Quantities where Info.BaseDimensions.Length == 2.

Isn't there ambiguity in that multiple quantities share the same base dimensions? F.ex. ApparentEnergy, Energy, RotationalStiffness and Torque seems to have L=2, M=1, T=-2.

Yes. That is where things get tricky. We need to figure something out there, as you can't overload based on return type. We could just vary the method names.

Some quantities don't seem to map to base dimensions, such as Angle or VitaminA. Is it fine to just leave them out?

VitaminA is an odd one, I will say. It is in fact a Mass for a particular substance, so it does have a base unit. Angle is correctly identified as Dimensionless.

[angularsen]

Added a TODO: Add back IEquatable<T>, but implement as strict equality with tuple of quantity name + unit + value. https://github.com/angularsen/UnitsNet/issues/1017#issuecomment-1028401955

[angularsen]

@tmilnthorp What do you think about this?

If we keep them, how about renaming them to SiBaseDimensions and SiBaseUnits?

Primarily want to distinguish from Length.BaseUnit and "BaseUnit" in JSON. I also think it helps to be explicit that these are related SI unit system.

[tmilnthorp]

@tmilnthorp What do you think about this?

If we keep them, how about renaming them to SiBaseDimensions and SiBaseUnits?

Primarily want to distinguish from Length.BaseUnit and "BaseUnit" in JSON. I also think it helps to be explicit that these are related SI unit system.

These are not related to SI. All units have dimensionality and base units

• Inches is a base quantity (non-SI obviously)
  • Dimensions
    • Length: 1
  • Base unit
    • Inch
• Square inches is a derived quantity
  • Dimensions
    • Length: 2
  • Base unit
    • Inch
• Miles per hour is a derived quantity (length / time)
  • Dimensions (length / time)
    • Length: 1
    • Time: -1
  • Base units
    • Length: miles
    • Time: hour

For 60mph you can see the miles unit goes in the numerator (length dimension of +1) and hours go in the denominator (time dimension of -1).

See https://en.m.wikipedia.org/wiki/International_System_of_Quantities#Derived_quantities and https://en.wikipedia.org/wiki/Dimensional_analysis

[tmilnthorp]

I wonder if we should name Length.BaseUnit something like ReferenceUnit. That's really what we have: a reference unit (Meter for Length) to do conversions from Inch -> Meter -> Mile (for example).

[angularsen]

I wonder if we should name Length.BaseUnit something like ReferenceUnit

Yes, I initially tried ConversionBaseUnit, but it's just cumbersome and long so I reverted it. ReferenceUnit is a decent alternative.

Regarding SI, you are probably right. It just seemed to me that there exists multiple unit systems beyond SI, and I was probing whether we should consider supporting anything other than SI? I can't really find any units systems that are widely used today. Do you know of any?

Unit systems:

• CGS: centimeters-grams-second. Introduced in 1832, predecessor of SI.
• MKS: meter-kilogram-second. Introduced in the 1940s, predecessor of SI, successor to CGS.
• SI: Introduced in the 1960s.
• FPS: foot–pound–second. and its 3 variants: British Graviational, English Engineering, Absolute English. Replaced by SI?

If there are no other unit systems we would like to support, then I guess the naming BaseUnits would suffice and be unambiguous.

[codecov[bot]]

Codecov Report

Base: 85% // Head: 86% // Increases project coverage by +0% :tada:

Coverage data is based on head (0838cd4) compared to base (7519a21). Patch has no changes to coverable lines.

:exclamation: Current head 0838cd4 differs from pull request most recent head ac3d3cd. Consider uploading reports for the commit ac3d3cd to get more accurate results

Additional details and impacted files

@@           Coverage Diff            @@
##           master    #982     +/-   ##
========================================
  Coverage      85%     86%             
========================================
  Files         326     321      -5     
  Lines       52805   48165   -4640     
========================================
- Hits        45329   41713   -3616     
+ Misses       7476    6452   -1024     

Impacted Files	Coverage Δ
UnitsNet/QuantityValue.cs	49% <0%> (-30%)	:arrow_down:
UnitsNet/UnitMath.cs	84% <0%> (-16%)	:arrow_down:
UnitsNet/QuantityFormatter.cs	92% <0%> (-3%)	:arrow_down:
...Serialization.JsonNet/UnitsNetBaseJsonConverter.cs	93% <0%> (-3%)	:arrow_down:
UnitsNet/CustomCode/Wrappers/ReferencePressure.cs	94% <0%> (-2%)	:arrow_down:
...Serialization.JsonNet/AbbreviatedUnitsConverter.cs	86% <0%> (-2%)	:arrow_down:
UnitsNet/GeneratedCode/Quantities/Information.g.cs	87% <0%> (-1%)	:arrow_down:
UnitsNet/GeneratedCode/Quantities/Power.g.cs	88% <0%> (-1%)	:arrow_down:
UnitsNet/GeneratedCode/Quantities/BitRate.g.cs	88% <0%> (-1%)	:arrow_down:
UnitsNet/GeneratedCode/Quantities/Level.g.cs	78% <0%> (-1%)	:arrow_down:
... and 147 more

Help us with your feedback. Take ten seconds to tell us how you rate us. Have a feature suggestion? Share it here.

:umbrella: View full report at Codecov.
:loudspeaker: Do you have feedback about the report comment? Let us know in this issue.

[stale[bot]]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.