String Formatting

Common examples

Assuming computer running with US English culture.

var length = Length.FromCentimeters(3.14159265358979);

// Typical formats
length.ToString(); // 3.14 cm
length.ToString("s4"); // 3.1416 cm

// Localized
length.ToString(new CultureInfo("nb-NO")); // 3,14 cm
length.ToString(new CultureInfo("ru-RU")); // 3,14 см

// Converted
length.As(LengthUnit.Meters).ToString(); // 0.13 m

Standard Quantity Format Strings

Format specifier	Description	Examples
"g"	General quantity pattern. Equivalent to parameterless ToString(). Rounds to 2 significant digits after the radix.	Length.FromFeet(Math.PI).ToString("g") -> 3.14 ft
"sXX"	Significant digits pattern. Rounds the value to XX significant digits after the radix. Defaults to 2.	Length.FromFeet(Math.PI).ToString("s3") -> 3.142 ft Length.FromFeet(3.1).ToString("s3") -> 3.1 ft
"v"	Value pattern. Outputs the quantity value.	Length.FromFeet(Math.PI).ToString("v") -> 3.14159265358979
"aXX"	Unit abbreviation pattern. If more than one abbreviation is defined for the unit, then XX specifies the zero-indexed position in the array of abbreviations. XX defaults to 0. If the position is not found, System.FormatException is thrown.	Length.FromFeet(Math.PI).ToString("a") -> 3.14 ft Length.FromFeet(Math.PI).ToString("a0") -> 3.14 ft Length.FromFeet(Math.PI).ToString("a1") -> 3.14 ' Length.FromFeet(Math.PI).ToString("a2") -> 3.14 ′ Length.FromFeet(Math.PI).ToString("a3") -> System.FormatException
"q"	Quantity name pattern. Outputs the corresponding QuantityType enum name.	Length.FromFeet(Math.PI).ToString("q") -> Length Mass.FromTonnes(Math.PI).ToString("u") -> Mass
"u"	Unit name pattern. Each quantity has a corresponding unit enum, such as Length quantity having LengthUnit unit enum with values Meter, Centimeter etc. This pattern outputs the unit enum name.	Length.FromFeet(Math.PI).ToString("u") -> Foot Mass.FromTonnes(Math.PI).ToString("u") -> Tonne

There are three different overloads of the ToString() method to provide a string representation of a value and its units:

ToString()

• The default base unit is used.
• Ex: Length.FromKilometers(5).ToString() // "5,000 m"
• By default, up to two significant digits after the radix point are used, depending on the value and rounding scenario.
• Ex: Length.FromMeters(1.2345).ToString() // "1.23 m"
• Ex: Length.FromMeters(0.819999999999).ToString() // "0.82 m"

ToString(unit, culture, significantDigitsAfterRadix)

• unit: The unit to convert the base value to.
• Ex: Length.FromMeters(1234).ToString(LengthUnit.Kilometers) // "1.23 km"
• culture: An optional culture used for localization and number formatting. The default value is null which corresponds to InvariantCulture.
• Ex: Length.FromMeters(0.12).ToString(LengthUnit.Meters, new CultureInfo("de-DE")) // "0,12 m"
• significantDigitsAfterRadix: An optional maximum number of significant digits to display after the radix point. The default value is 2.
• Ex: Length.FromMeters(1.123456789).ToString(Length.Meter, null, 4) // "1.1235 m"

ToString(unit, culture, format, args)

• This overload bypasses the default ToString() formatting. Users have exact control over how a value will be formatted using this overload.
• unit: The unit to convert the base value to.
• culture: The culture used for localization and number formatting.
• format: The composite string format.
• args: The composite string format arguments.

Default Formatting Behaviour

The first two ToString() implementations automatically format a value. Depending on the value, one of the following formatting scenarios will be used (where x is the absolute value of the number being formatted):

Interval	Format	Examples
(-∞ ≤ x < 1e-03]	scientific notation	1e-04; 2.13e-05
[1e-03 ≤ x < 1e+03]	fixed point notation	0.001; 0.01; 100
[1e+03 ≤ x < 1e+06]	fixed point notation with digit grouping	1,000; 10,000; 100,000
[1e+06 ≤ x ≤ +∞)	scientific notation	1.1e+06; 3.14e+07

The symbols used for digit grouping and radix point are culture-sensitive. The above examples use CultureInfo.InvariantCulture.

For more examples, refer to the unit tests in UnitSystemTests.cs.