string-formatting.md

String formatting

Quantity formatting applies a .NET numeric format string to the value and appends the localized abbreviation of the quantity's current unit.

Length length = Length.FromCentimeters(Math.PI);

length.ToString();                                      // 3.141592653589793 cm
length.ToString("F2", CultureInfo.InvariantCulture);   // 3.14 cm
$"Length: {length:N3}";                                // Length: 3.142 cm with an en-US current culture

The parameterless overload uses the general (G) numeric format. Formatting honors the supplied IFormatProvider, or CultureInfo.CurrentCulture when none is supplied.

length.ToString(CultureInfo.GetCultureInfo("nb-NO")); // 3,141592653589793 cm
length.ToString(CultureInfo.GetCultureInfo("ru-RU")); // 3,141592653589793 см

Convert the quantity before formatting when a different unit is required:

Length meters = length.ToUnit(LengthUnit.Meter);
string text = meters.ToString("G3", CultureInfo.InvariantCulture); // 0.0314 m

Numeric formats

UnitsNet accepts standard and custom .NET numeric formats, including:

Intent	Format	Example
General notation with a precision	G3	3.14 cm
Fixed decimal places	F2	3.14 cm
Grouped number with fixed decimals	N2	1,234.50 cm
Scientific notation	E2	3.14E+000 cm
Up to two decimal places	0.##	3.14 cm
Grouped with up to two decimal places	#,##0.##	1,234.5 cm

Currency (C) and percent (P) formats are rejected because adding currency or percent symbols to a physical quantity is misleading.

See .NET standard numeric format strings and .NET custom numeric format strings for the complete syntax.

Unit abbreviations

Use the generated quantity API to get the primary localized abbreviation explicitly:

string abbreviation = Length.GetAbbreviation(LengthUnit.Foot);
string localized = Length.GetAbbreviation(LengthUnit.Meter, CultureInfo.GetCultureInfo("ru-RU"));

Use the configured abbreviation cache when every accepted abbreviation is needed. This includes runtime customizations made through UnitsNetSetup:

IReadOnlyList<string> abbreviations = UnitsNetSetup.Default.UnitAbbreviations
    .GetUnitAbbreviations(LengthUnit.Foot, CultureInfo.InvariantCulture);
// "ft", "'", "′"