Upgrading from 3.x to 4.x

These are the usecases we expect most consumers to have to deal with when upgrading.

UnitSystem changes

UnitSystem abbreviations => UnitAbbreviationsCache

For looking up or mapping custom unit abbreviations for unit enum types only known at runtime, use UnitAbbreviationsCache instead of UnitSystem:

var abbreviations = UnitAbbreviationsCache.Default;
abbreviations.GetAllUnitAbbreviationsForQuantity(typeof(LengthUnit)); // ["cm", "dm",...]
abbreviations.GetUnitAbbreviations(typeof(LengthUnit), 6); // ["ft", "'", "`"]
abbreviations.GetDefaultAbbreviation(typeof(LengthUnit), 1); // "cm"
abbreviations.MapUnitToAbbreviation(typeof(LengthUnit), 1, new CultureInfo("en-US"), "foo"); // add custom abbreviation for centimeter

Looking up abbreviations for static quantity types, you can use Length.Units as before.

UnitSystem parsing => UnitParser

Dynamic parsing of unit abbreviations, where unit enum type is only known at runtime, is now done by UnitParser:

var parser = UnitParser.Default;
parser.Parse("cm", typeof(LengthUnit)); // 1
parser.TryParse("cm", typeof(LengthUnit), out object val); // returns true, val = 1

For static parsing, you can use Length.ParseUnit("cm") as before.

UnitSystem.DefaultCulture => GlobalConfiguration.DefaultCulture

To change the default culture used by ToString() in quantities:

GlobalConfiguration.DefaultCulture = new CultureInfo("en-US"); // instead of UnitSystem.DefaultCulture

Removed static methods on UnitSystem

Use UnitParser.Default or UnitAbbreviationsCache.Default instead, or create an instance for the culture of your own choice.

Quantity types

Nullable From-methods removed

int? val = null;

// Instead of this
Length? l = Length.FromMeters(val);

// Do this, or create your own convenience factory method
Length? l = val == null ? (Length?)null : Length.FromMeters(val.Value);

Remove unit parameter from ToString() methods

// Instead of
myLength.ToString(LengthUnit.Centimeter); // "100 cm"

// Do this
myLength.ToUnit(LengthUnit.Centimeter).ToString(); // "100 cm"

Stricter parsing

// Instead of
var l = Length.Parse("5ft 3in"); // Throws FormatException

// Do this, special case for feet/inches
var l = Length.ParseFeetInches("5ft 3in");

// Everything else only supports these formats
var l = Length.Parse("1cm");
var l = Length.Parse("1 cm");
var l = Length.Parse("1  cm"); // Multi-space allowed
var l = Length.Parse(" 1 cm "); // Input is trimmed

Change Temperature arithmetic back to use base unit Kelvin

Instead of a special case for Temperature, we now have the exact same arithmetic as for other quantities. Previously subtracting two temperatures would return a TemperatureDelta. Instead, you can now add and subtract two temperatures and they will return a new Temperature with addition/subtraction performed in base unit Kelvin while maintaining the left hand argument's unit.

Temperature celsius30, celsius20; // Assume assigned..

// Before
var x = celsius30 + celsius20; // Not possible
TemperatureDelta deltaCelsius10 = celsius30 - celsius20; // delta 10 degrees Celsius

// After - this can get confusing if you are working with Celsius or Fahrenheit
Temperature celsius323 = celsius30 + celsius20;
Temperature minus263Celsius = celsius30 - celsius20;

// For addition/subtraction when working with Celsius or Fahrenheit, you probably want to use TemperatureDelta
TemperatureDelta deltaCelsius20 = TemperatureDelta.FromDegreesCelsius(20);
Temperature celsius50 = celsius30 + deltaCelsius20;
Temperature celsius10 = celsius30 - deltaCelsius20;

// Or use these convenience methods
Temperature deltaCelsius10 = celsius30.ToDelta(celsius20);
TemperatureDelta deltaCelsius10 = TemperatureDelta.FromTemperatures(celsius30, celsius20);

Length2d removed

Provide your own or use Area if applicable.

Number extension methods removed

Either create your own or use From factory methods.

Length m = 1.Meters(); // No longer possible
Length m = Length.FromMeters(1); // Use this instead