Add strongly typed quantities to your code and get merrily on with your life.
No more magic constants found on Stack Overflow, no more second-guessing the unit of parameters and variables.
Units.NET gives you all the common units of measurement and the conversions between them. It is lightweight and thoroughly tested. If you have read this far, it is exactly what you are looking for and then some.
See Upgrading from 3.x to 4.x.
- .NET Standard 2.0
- .NET 4.0
- Windows Runtime Component for UWP apps (WinJS or C++)
- 95 quantities with 1000+ units generated from JSON by C# CLI app
- 2500+ unit tests on conversions and localizations
- Conforms to Microsoft's open-source library guidance, in particular:
- SourceLink to step into source code of NuGet package while debugging
- Strong naming to make the library available to all developers
- Immutable structs that implement
IEquatable,IComparable - Statically typed quantities and units to avoid mistakes and communicate intent
- Operator overloads for arithmetic on quantities
- Parse and ToString() supports cultures and localization
- Dynamically parse and convert quantities and units
- Example: Creating a unit converter app
- Example: WPF app using IValueConverter to parse quantities from input
- Precision and accuracy
- Serializable with JSON.NET
- Extensible with custom units
- Contribute if you are missing some units
- Continuous integration posts status reports to pull requests and commits
- Who are using this?
Run the following command in the Package Manager Console or go to the NuGet site for the complete relase history.
// Construct
Length meter = Length.FromMeters(1);
Length twoMeters = new Length(2, LengthUnit.Meter);
// Convert
double cm = meter.Centimeters; // 100
double yards = meter.Yards; // 1.09361
double feet = meter.Feet; // 3.28084
double inches = meter.Inches; // 39.3701
// Pass quantity types instead of values to avoid conversion mistakes and communicate intent
string PrintPersonWeight(Mass weight)
{
// Compile error! Newtons belong to Force, not Mass. A common source of confusion.
double weightNewtons = weight.Newtons;
// Convert to the unit of choice - when you need it
return $"You weigh {weight.Kilograms:F1} kg.";
}// Arithmetic
Length l1 = 2 * Length.FromMeters(1);
Length l2 = Length.FromMeters(1) / 2;
Length l3 = l1 + l2;
// Construct between units
Length distance = Speed.FromKilometersPerHour(80) * TimeSpan.FromMinutes(30);
Acceleration a1 = Speed.FromKilometersPerHour(80) / TimeSpan.FromSeconds(2);
Acceleration a2 = Force.FromNewtons(100) / Mass.FromKilograms(20);
RotationalSpeed r = Angle.FromDegrees(90) / TimeSpan.FromSeconds(2);The culture for abbreviations defaults to Thread.CurrentUICulture and falls back to US English if not defined. Thread.CurrentCulture affects number formatting unless a custom culture is specified. The relevant methods are:
- ToString()
- GetAbbreviation()
- Parse/TryParse()
- ParseUnit/TryParseUnit()
var usEnglish = new CultureInfo("en-US");
var russian = new CultureInfo("ru-RU");
var oneKg = Mass.FromKilograms(1);
// ToString() uses CurrentUICulture for abbreviation language and CurrentCulture for number formatting
Thread.CurrentThread.CurrentUICulture = russian;
string kgRu = oneKg.ToString(); // "1 кг"
// ToString() with specific culture and custom string format pattern
string mgUs = oneKg.ToUnit(MassUnit.Milligram).ToString(usEnglish, "unit: {1}, value: {0:F2}"); // "unit: mg, value: 1.00"
string mgRu = oneKg.ToUnit(MassUnit.Milligram).ToString(russian, "unit: {1}, value: {0:F2}"); // "unit: мг, value: 1,00"
// Parse measurement from string
Mass kg = Mass.Parse("1.0 kg", usEnglish);
// Parse unit from string, a unit can have multiple abbreviations
RotationalSpeedUnit rpm1 = RotationalSpeed.ParseUnit("rpm"); // RotationalSpeedUnit.RevolutionPerMinute
RotationalSpeedUnit rpm2 = 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 unit
string kgAbbreviation = Mass.GetAbbreviation(MassUnit.Kilogram); // "kg"Some units of a quantity have the same abbreviation, which means .Parse() is not able to know what unit you wanted.
Unfortunately there is no built-in way to avoid this, either you need to ensure you don't pass in input that cannot be parsed or you need to write your own parser that has more knowledge of preferred units or maybe only a subset of the units.
Example:
Length.Parse("1 pt") throws AmbiguousUnitParseException with message Cannot parse "pt" since it could be either of these: DtpPoint, PrinterPoint.
Sometimes you need to work with quantities and units at runtime, such as parsing user input.
There are a handful of classes to help with this:
- Quantity for parsing and constructing quantities as well as looking up units, names and quantity information dynamically
- UnitConverter for converting values to a different unit, with only strings or enum values
- UnitParser for parsing unit abbreviation strings, such as
"cm"toLengthUnit.Centimeter
Quantity is the go-to class for looking up information about quantities at runtime.
string[] Quantity.Names; // ["Length", "Mass", ...]
QuantityType[] Quantity.Types; // [QuantityType.Length, QuantityType.Mass, ...]
QuantityInfo[] Quantity.Infos; // Information about all quantities and their units, types, values etc., see more below
QuantityInfo Quantity.GetInfo(QuantityType.Length); // Get information about LengthQuantityInfo makes it easy to enumerate names, units, types and values for the quantity type.
This is useful for populating lists of quantities and units for the user to choose.
QuantityInfo lengthInfo = Quantity.GetInfo(QuantityType.Length); // You can get it statically here
lengthInfo = Length.Info; // or statically per quantity
lengthInfo = Length.Zero.QuantityInfo; // or dynamically from quantity instances
lengthInfo.Name; // "Length"
lengthInfo.QuantityType; // QuantityType.Length
lengthInfo.UnitNames; // ["Centimeter", "Meter", ...]
lengthInfo.Units; // [LengthUnit.Centimeter, LengthUnit.Meter, ...]
lengthInfo.UnitType; // typeof(LengthUnit)
lengthInfo.ValueType; // typeof(Length)
lengthInfo.Zero; // Length.ZeroAll you need is the value and the unit enum value.
IQuantity quantity = Quantity.From(3, LengthUnit.Centimeter); // Length
if (Quantity.TryFrom(3, LengthUnit.Centimeter, out IQuantity quantity2))
{
}Parse any string to a quantity instance of the given the quantity type.
IQuantity quantity = Quantity.Parse(typeof(Length), "3 cm"); // Length
if (Quantity.TryParse(typeof(Length), "3cm", out IQuantity quantity2)
{
}UnitParser parses unit abbreviation strings to unit enum values.
Enum unit = UnitParser.Default.Parse("cm", typeof(LengthUnit)); // LengthUnit.Centimeter
if (UnitParser.Default.TryParse("cm", typeof(LengthUnit), out Enum unit2))
{
// Use unit2 as LengthUnit.Centimeter
}Convert any IQuantity instance to a different unit by providing a target unit enum value.
// Assume these are passed in at runtime, we don't know their values or type
Enum userSelectedUnit = LengthUnit.Millimeter;
IQuantity quantity = Length.FromCentimeters(3);
// Later we convert to a unit
quantity.ToUnit(userSelectedUnit).Value; // 30
quantity.ToUnit(userSelectedUnit).Unit; // LengthUnit.Millimeter
quantity.ToUnit(userSelectedUnit).ToString(); // "30 mm"
quantity.ToUnit(PressureUnit.Pascal); // Throws exception, not compatible
quantity.As(userSelectedUnit); // 30Useful when populating lists with unit enum values for the user to choose.
UnitConverter.Convert(1, LengthUnit.Centimeter, LengthUnit.Millimeter); // 10 mmSometimes you only have strings to work with, that works too!
UnitConverter.ConvertByName(1, "Length", "Centimeter", "Millimeter"); // 10 mm
UnitConverter.ConvertByAbbreviation(1, "Length", "cm", "mm"); // 10 mmSource code for Samples/UnitConverter.Wpf
Download (release 2018-11-09 for Windows)
This example shows how you can create a dynamic unit converter, where the user selects the quantity to convert, such as Temperature, then selects to convert from DegreeCelsius to DegreeFahrenheit and types in a numeric value for how many degrees Celsius to convert.
The quantity list box contains QuantityType values such as QuantityType.Length and the two unit list boxes contain Enum values, such as LengthUnit.Meter.
Use Quantity to enumerate all quantity type enum values, such as QuantityType.Length and QuantityType.Mass.
this.Quantities = Quantity.Types; // QuantityType[]So user can only choose from/to units compatible with the quantity type.
QuantityInfo quantityInfo = Quantity.GetInfo(quantityType);
_units.Clear();
foreach (Enum unitValue in quantityInfo.Units)
{
_units.Add(unitValue);
}Using UnitConverter to convert by unit enum values as given by the list selection "Length" and unit names like "Centimeter" and "Meter".
double convertedValue = UnitConverter.Convert(
FromValue, // numeric value
SelectedFromUnit.UnitEnumValue, // Enum, such as LengthUnit.Meter
SelectedToUnit.UnitEnumValue); // Enum, such as LengthUnit.Centimeter
The purpose of this app is to show how to create an IValueConverter in order to bind XAML to quantities.
A base unit is chosen for each unit class, represented by a double value (64-bit), and all conversions go via this unit. This means that there will always be a small error in both representing other units than the base unit as well as converting between units.
Units.NET was intended for convenience and ease of use, not highly accurate conversions, but I am open to suggestions for improvements.
The tests accept an error up to 1E-5 for most units added so far. Exceptions include units like Teaspoon, where the base unit cubic meter is a lot bigger. In many usecases this is sufficient, but for others this may be a showstopper and something you need to be aware of.
For more details, see Precision.
Important! We cannot guarantee backwards compatibility, although we will strive to do that on a "best effort" basis and bumping the major nuget version when a change is necessary.
The base unit of any unit should be treated as volatile as we have changed this several times in the history of this library already. Either to reduce precision errors of common units or to simplify code generation. An example is Mass, where the base unit was first Kilogram as this is the SI unit of mass, but in order to use powershell scripts to generate milligrams, nanograms etc. it was easier to choose Gram as the base unit of Mass.
This project is still early and many units and conversions are not yet covered. If you are missing something, please help by contributing or ask for it by creating an issue.
Please read the wiki on Adding a New Unit.
Generally adding a unit involves adding or modifying Common/UnitDefinitions/*.json files and running generate-code.bat to regenerate the source code and test code stubs, then manually implementing the new unit conversion constants in the test code.
- Fork the repo
- Do work on branches such as feature/add-myunit and fix/34
- Create a pull request
AppVeyor performs the following:
- Build and test all branches
- Build and test pull requests, notifies on success or error
- Deploy nugets on master branch, if nuspec versions changed
It would be awesome to know who are using this library. If you would like your project listed here, create an issue or edit the README.md and send a pull request. Max logo size is 300x35 pixels and should be in .png, .gif or .jpg formats.
Sports performance applications for Windows and iOS, that combine high-speed video with sensor data to bring facts into your training and visualize the invisible forces at work
Units.NET started here in 2007 when reading strain gauge measurements from force plates and has been very useful in integrating a number of different sensor types into our software and presenting the data in the user's preferred culture and units.
https://www.swingcatalyst.com (for golf)
https://www.motioncatalyst.com (everything else)
- Andreas Gullberg Larsen, CTO ([email protected])
Award-winning performers and composers put everything they’ve got into their music. PK Sound makes sure their fans will hear it all – brilliantly, precisely, consistently.
PK Sound uses UnitsNet in Kontrol - the remote control counterpart to Trinity, the world's only robotic line array solution.
http://www.pksound.ca/pk-sound/announcing-the-official-release-of-kontrol/ (for an idea of what the Kontrol project is)
http://www.pksound.ca/trinity/ (the speakers that Kontrol currently controls)
http://www.pksound.ca/ (everything else)
- Jules LaPrairie, Kontrol software team member
Microsoft.IoT.Devices extends Windows IoT Core and makes it easier to support devices like sensors and displays. It provides event-driven access for many digital and analog devices and even provides specialized wrappers for devices like joystick, rotary encoder and graphics display.
http://aka.ms/iotdevices (home page including docs)
http://www.nuget.org/packages/Microsoft.IoT.Devices (NuGet package)
Software for creating printable hex maps for use in pen and paper RPGs. Both a user-friendly app and a high-level library for generating labelled hexmaps.
https://bitbucket.org/MartinEden/Crawlspace
- Martin Eden, project maintainer
ANSYS Discovery Live provides instantaneous 3D simulation, tightly coupled with direct geometry modeling, to enable interactive design exploration and rapid product innovation. It is an interactive experience in which you can manipulate geometry, material types or physics inputs, then instantaneously see changes in performance.
https://www.ansys.com https://www.ansys.com/products/3d-design/ansys-discovery-live
- Tristan Milnthorp, Principal Software Architect ([email protected])
Stargen is a decades old software to create realistic planets and satellites from a given Star. It's based on work from various scientists and been used for years. Primoris Sigma Stargen is a C# port of the utility that makes it a Framework to extend it with new algorithms for planetary formation and physics equations.
https://github.com/ebfortin/primoris.universe.stargen
Harrington Hoists, Inc. is located in Manheim, PA, Elizabethtown, PA, South Holland, IL and Corona, CA. Harrington is a leading manufacturer of manual, electric and air chain hoists as well as wire rope hoists and crane products serving the North American material handling industry.
Harrington uses UnitsNet in their internal software to perform many different calculations related to crane dimensioning, girder strength, electrical safety verification, etc.
https://www.harringtonhoists.com
https://kito.com
- Luke Westfall, Design Automation Engineer