Units.NET

Changes

Overview

Installing via NuGet

dotnet add package UnitsNet

Build Targets

Extension Packages

UnitsNet.NumberExtensions.CS14 (C# 14 Extension Members)

dotnet add package UnitsNet.NumberExtensions.CS14

usingUnitsNet.NumberExtensions.NumberToLength;// C# 14 extension members syntax, without paranthesesLengthdistance=5.Meters;// Instead of Length.FromMeters(5)

UnitsNet.NumberExtensions (Classic)

dotnet add package UnitsNet.NumberExtensions

usingUnitsNet.NumberExtensions.NumberToLength;// Classic extension methods, with parenthesesLengthdistance=5.Meters();// Instead of Length.FromMeters(5)

Static Typing

// ConstructLengthmeter=Length.FromMeters(1);LengthtwoMeters=newLength(2,LengthUnit.Meter);// Convertdoublecm=meter.Centimeters;// 100doubleyards=meter.Yards;// 1.09361doublefeet=meter.Feet;// 3.28084doubleinches=meter.Inches;// 39.3701// Pass quantity types instead of values to avoid conversion mistakes and communicate intentstringPrintPersonWeight(Massweight){// Compile error! Newtons belong to Force, not Mass. A common source of confusion.doubleweightNewtons=weight.Newtons;// Convert to the unit of choice - when you need itreturn$"You weigh{weight.Kilograms:F1} kg.";}

Operator Overloads

// ArithmeticLengthl1=2*Length.FromMeters(1);Lengthl2=Length.FromMeters(1)/2;Lengthl3=l1+l2;// Construct between unitsLengthdistance=Speed.FromKilometersPerHour(80)*TimeSpan.FromMinutes(30);Accelerationa1=Speed.FromKilometersPerHour(80)/TimeSpan.FromSeconds(2);Accelerationa2=Force.FromNewtons(100)/Mass.FromKilograms(20);RotationalSpeedr=Angle.FromDegrees(90)/TimeSpan.FromSeconds(2);

Culture and Localization

varusEnglish=newCultureInfo("en-US");varrussian=newCultureInfo("ru-RU");varoneKg=Mass.FromKilograms(1);// ToString() uses CurrentCulture for abbreviation language number formatting. This is consistent with the behavior of the .NET Framework,// where DateTime.ToString() uses CurrentCulture for the whole string, likely because mixing an english date format with a russian month name might be confusing.CultureInfo.CurrentCulture=russian;stringkgRu=oneKg.ToString();// "1 кг"// ToString() with specific culture and custom string format patternstringmgUs=oneKg.ToUnit(MassUnit.Milligram).ToString(usEnglish,"unit: {1}, value: {0:F2}");// "unit: mg, value: 1.00"stringmgRu=oneKg.ToUnit(MassUnit.Milligram).ToString(russian,"unit: {1}, value: {0:F2}");// "unit: мг, value: 1,00"// Parse measurement from stringMasskg=Mass.Parse("1.0 kg",usEnglish);// Parse unit from string, a unit can have multiple abbreviationsRotationalSpeedUnitrpm1=RotationalSpeed.ParseUnit("rpm");// RotationalSpeedUnit.RevolutionPerMinuteRotationalSpeedUnitrpm2=RotationalSpeed.ParseUnit("r/min");// RotationalSpeedUnit.RevolutionPerMinute// Get default abbreviation for a unit, the first if more than one is defined in Length.json for Kilogram unitstringkgAbbreviation=Mass.GetAbbreviation(MassUnit.Kilogram);// "kg"

Gotcha: AmbiguousUnitParseException

Dynamically Parse Quantities and Convert to Units

Quantity - Enumerate quantities and units at runtime

string[]names=Quantity.Names;// ["Length", "Mass", ...]QuantityInfo[]qis=Quantity.Infos;// All quantities and their units, types, values.// Look up quantity by name.QuantityInfolengthInfo=Quantity.ByName["Length"];UnitInfo[]lengthUnits=lengthInfo.UnitInfos;// Look up unit by enum value (note: for extensibility, will instead look up by name in the future)UnitInfocmInfo=Quantity.GetUnitInfo(LengthUnit.Centimeter);

QuantityInfo - Information about a quantity

// Different ways to look up the quantity info.QuantityInfolengthInfo=Quantity.ByName["Length"];lengthInfo=Length.Info;lengthInfo=Length.FromMeters(1).QuantityInfo;// The quantity information.lengthInfo.Name;// "Length"lengthInfo.UnitInfos;// UnitInfo[] for its units Centimeter, Meter, etc.lengthInfo.BaseUnitInfo;// UnitInfo for LengthUnit.MeterlengthInfo.BaseDimensions;// {"Length": 1, "Mass": 0, ...}lengthInfo.UnitType;// typeof(LengthUnit)lengthInfo.ValueType;// typeof(Length)lengthInfo.Zero;// Length.Zero

UnitInfo - Information about a unit

// Different ways to look up the unit info.varcm=Quantity.GetUnitInfo(LengthUnit.Centimeter);if(Quantity.TryGetUnitInfo(LengthUnit.Centimeter,outUnitInfotryGetCm)){cm=tryGetCm;}// The unit information.cm.Value;// Enum value: LengthUnit.Centimetercm.Name;// "Centimeter"cm.PluralName;// "Centimeters"cm.BaseUnits;// {"Length": Centimeter, "Mass": null, "Time": null, ...}

Construct quantity

IQuantityquantity=Quantity.From(3,LengthUnit.Centimeter);// Lengthif(Quantity.TryFrom(3,LengthUnit.Centimeter,outIQuantityquantity2)){}

IQuantityquantity=Quantity.From(value:3,quantityName:"Length",unitName:"Centimeter");if(Quantity.TryFrom(value:3,quantityName:"Length",unitName:"Centimeter",outIQuantity?quantity2)){}

// Length with unit LengthUnit.CentimeterIQuantityquantity=Quantity.FromUnitAbbreviation(3,"cm");if(Quantity.TryFromUnitAbbreviation(3,"cm",outIQuantity?quantity2)){}

Parse quantity

IQuantityquantity=Quantity.Parse(typeof(Length),"3 cm");// Lengthif(Quantity.TryParse(typeof(Length),"3cm",outIQuantityquantity2){}

Parse unit

Enumunit=UnitsNetSetup.Default.UnitParser.Parse("cm",typeof(LengthUnit));// LengthUnit.Centimeterif(UnitsNetSetup.Default.UnitParser.TryParse("cm",typeof(LengthUnit),outEnumunit2)){// Use unit2 as LengthUnit.Centimeter}

Convert quantity to unit - IQuantity and Enum

// Assume these are passed in at runtime, we don't know their values or typeEnumuserSelectedUnit=LengthUnit.Millimeter;IQuantityquantity=Length.FromCentimeters(3);// Later we convert to a unitquantity.ToUnit(userSelectedUnit).Value;// 30quantity.ToUnit(userSelectedUnit).Unit;// LengthUnit.Millimeterquantity.ToUnit(userSelectedUnit).ToString();// "30 mm"quantity.ToUnit(PressureUnit.Pascal);// Throws exception, not compatiblequantity.As(userSelectedUnit);// 30

Convert quantity to unit - From/To Enums

UnitConverter.Convert(1,LengthUnit.Centimeter,LengthUnit.Millimeter);// 10 mm

Convert quantity to unit - Names or abbreviation strings

UnitConverter.ConvertByName(1,"Length","Centimeter","Millimeter");// 10 mmUnitConverter.ConvertByAbbreviation(1,"Length","cm","mm");// 10 mm

Custom units

Map between unit enum values and unit abbreviations

// Map unit enum values to unit abbreviationsvarunitAbbreviations=UnitsNetSetup.Default.UnitAbbreviations;unitAbbreviations.MapUnitToDefaultAbbreviation(HowMuchUnit.Some,"sm");unitAbbreviations.GetDefaultAbbreviation(HowMuchUnit.Some);// "sm"UnitsNetSetup.Default.UnitParser.Parse<HowMuchUnit>("sm");// HowMuchUnit.Some

Convert between units of custom quantity

varunitConverter=UnitsNetSetup.Default.UnitConverter;unitConverter.SetConversionFunction<HowMuch>(HowMuchUnit.Lots,HowMuchUnit.Some, x=>newHowMuch(x.Value*2,HowMuchUnit.Some));unitConverter.SetConversionFunction<HowMuch>(HowMuchUnit.Tons,HowMuchUnit.Lots, x=>newHowMuch(x.Value*10,HowMuchUnit.Lots));unitConverter.SetConversionFunction<HowMuch>(HowMuchUnit.Tons,HowMuchUnit.Some, x=>newHowMuch(x.Value*20,HowMuchUnit.Some));varfrom=newHowMuch(10,HowMuchUnit.Tons);IQuantityConvert(HowMuchUnittoUnit)=>unitConverter.GetConversionFunction<HowMuch>(from.Unit,toUnit)(from);Console.WriteLine($"Convert 10 tons to:");Console.WriteLine(Convert(HowMuchUnit.Some));// 200 smConsole.WriteLine(Convert(HowMuchUnit.Lots));// 100 ltsConsole.WriteLine(Convert(HowMuchUnit.Tons));// 10 tns

Parse custom quantity

// Map custom units to abbreviationsvarunitAbbreviationsCache=UnitsNetSetup.Default.UnitAbbreviations;unitAbbreviationsCache.MapUnitToAbbreviation(HowMuchUnit.Some,"sm");unitAbbreviationsCache.MapUnitToAbbreviation(HowMuchUnit.ATon,"tn");varquantityParser=UnitsNetSetup.Default.QuantityParser;// "1 sm" => new HowMuch(1, HowMuchUnit.Some)HowMuchq=quantityParser.Parse<HowMuch,HowMuchUnit>(str:"1 sm",formatProvider:null,fromDelegate:(value,unit)=>newHowMuch((double)value,unit));

// Alternatively, create your own instances to not change the global singleton instances.varunitAbbreviationsCache=UnitAbbreviationsCache.CreateDefault();// or .CreateEmpty()unitAbbreviationsCache.MapUnitToAbbreviation(HowMuchUnit.Some,"sm");unitAbbreviationsCache.MapUnitToAbbreviation(HowMuchUnit.ATon,"tn");varquantityParser=newQuantityParser(unitAbbreviationsCache);

Example: Unit converter app

Populate quantity selector

this.Quantities=Quantity.Names;// string[]// orthis.Quantities=Quantity.Infos.Select(i=>i.Name).ToList();

Update unit lists when selecting new quantity

QuantityInfoquantityInfo=Quantity.ByName[quantityName];_units.Clear();foreach(EnumunitValueinquantityInfo.UnitInfos.Select(ui=>ui.Value)){_units.Add(newUnitListItem(unitValue));}

Update calculation on unit selection changed

doubleconvertedValue=UnitConverter.Convert(FromValue,// numeric valueSelectedFromUnit.UnitEnumValue,// Enum, such as LengthUnit.MeterSelectedToUnit.UnitEnumValue);// Enum, such as LengthUnit.Centimeter

Example: WPF app using IValueConverter to parse input

Precision and Accuracy

Serialize to JSON, XML and more

Want To Contribute?

Continuous Integration

Who are Using UnitsNet?

Swing Catalyst and Motion Catalyst, Norway

PK Sound, Canada

Microsoft.IoT.Devices

Crawlspace

ANSYS, Inc. (ANSYS Discovery Live)

Primoris Sigma Stargen

Harrington Hoists, Inc. (A Subsidiary of KITO Americas, Inc.)

Structural Analysis Format - SDK project

Top Usages by GitHub Repos

Units.NET on other platforms