Skip to main content
Version: 2.13.14

Format and parse metric numerals

Orientation​

Use ToMetric for compact decimal magnitudes such as 123.5k, and FromMetric when an input follows Humanizer’s metric syntax. MetricNumeralFormats selects a symbol, SI prefix name, short-scale word, long-scale word, and optional spacing. These APIs follow the current numeric culture.

Example​

The example pins en-US, controls decimals, emits an SI prefix name, and parses a symbol:

Program.cs
using System.Globalization;
using Humanizer;

CultureInfo.CurrentCulture = CultureInfo.GetCultureInfo("en-US");
CultureInfo.CurrentUICulture = CultureInfo.GetCultureInfo("en-US");

var symbol = 123_456.ToMetric(decimals: 1);
var name = 1_000d.ToMetric(
    MetricNumeralFormats.WithSpace | MetricNumeralFormats.UseName);
var parsed = "1.5k".FromMetric();

AssertEqual("123.5k", symbol);
AssertEqual("1 kilo", name);
AssertEqual(1500d, parsed);

Console.WriteLine($"{symbol}; {name}; {parsed}");

static void AssertEqual<T>(T expected, T actual)
{
    if (!EqualityComparer<T>.Default.Equals(expected, actual))
        throw new InvalidOperationException($"Expected '{expected}', got '{actual}'.");
}

Select the representation​

MetricNumeralFormats is a flags enum:

  • WithSpace inserts a space before the suffix.
  • UseName emits an SI prefix name such as kilo.
  • UseShortScaleWord emits words such as billion.
  • UseLongScaleWord emits the selected long-scale equivalent.

The nullable decimals argument controls rounding and trailing digits. Leave both options unset for the default representation.

Parse supported forms​

FromMetric accepts a numeric value followed by a supported SI symbol or prefix name, with optional whitespace. It returns double and throws ArgumentException for invalid syntax. Short- and long-scale words produced by ToMetric are display forms and do not round-trip through FromMetric.

Pitfall​

Metric prefixes are powers of 1000 and are unrelated to ByteSize’s binary multiples. The supported exponent range stops before 10^27 and below 10^-27; out-of-range values throw. Because there is no culture parameter, scope CurrentCulture when parsing or exact output matters.

Version notes​

Metric conversion spans the documented corpus, but Humanizer 3 removed older boolean formatting overloads in favor of MetricNumeralFormats. The executable uses the selected version's formatting API and runs against that package.