SvSoft.SimpleUnits 1.0.0

SimpleUnits

.NET library for representing units and doing simple unit conversions between different scales.

Why not use UnitsNet

There are some mature unit libraries out there, e. g. https://github.com/angularsen/UnitsNet. But it seems that they do not allow easy programmatic instantiation of custom units.

Sometimes, legacy systems bestowe upon us some lovely units of measurement such as "deciminute" or "milliminute" (looking at you, SPS). I could not create a unit representation of deciminute in UnitsNet. Thus, this small library was born to support it.

Limitations

This library is about simple representation and conversion. It does not claim to be performant, I did not even benchmark it.

Usage

Find built-in scales and units in the static classes Scales and Units respectively. Use UnitConversion.Convert to convert a value between units. Use Unit.From to create a unit programmatically from existing scales and units.

Create ad-hoc units

Using the deciminute example from above, we can create custom units programmatically on-the-fly like this:

var deciMinute = Unit.From(Scales.Deci, Units.Minute);

In this case, the custom unit is based on a built-in scale (deci) and a built-in unit (minute). Programmatically creating units is useful for e. g. domain representation of units that are parsed from some configuration format.

Convert between units

You can then convert some value given in some unit to some other unit.

type-safe

If you know the units by their static type, you can convert between like this:

double valueInDeciMinutes = 23.5;
double valueInSeconds = UnitConversion.Convert(
  valueInDeciMinutes,
  from: deciMinute,
  to: Units.Second);
Assert.AreEqual(141, valueInSeconds);

The Convert method is compile-time safe in the sense that only units based on the same base unit can be converted into each other. In this case, the base unit of both source unit deciminute and target unit second is Second.

dynamic

If you have some IUnits without statically knowing what they are, you can try converting between them like this:

IUnit unitMilliSeconds = Unit.From(Scales.Milli, SIBaseUnits.Second);
IUnit unitMicroSeconds = Unit.From(Scales.Micro, SIBaseUnits.Second);
double valueMilliSeconds = 120;

var conversionResult = UnitConversion.TryConvert(valueMilliSeconds, unitMilliSeconds, unitMicroSeconds);

var convertedValue = Assert.IsType<UnitConversionResult<double>.Success>(conversionResult).Value;
convertedValue.Should().Be(120_000);

If the units are not compatible, you get a failure with more information.

Do your own thing

Implement your own scale with the IScale interface. Implement your own unit by inheriting from Unit<TBaseUnit>. Implement your own base unit by inheriting from BaseUnit<TSelf>.

You can declare any base unit you like. They are just a way of expressing conversion compatibility. They are in particular not restricted to SI base units.