Skip to content
xc

NumberFormatter

NumberFormatter turns a Number into display text and reads such text back (NSNumberFormatter in shape): 1234567 as 1,234,567, 1299.5 as $1,299.50, 0.25 as 25%. From 0.72.

#import "NumberFormatter.xc"   // not in the Foundation umbrella: import it by name

Overview

Section titled “Overview”
NumberFormatter* f = NumberFormatter.decimal();
f.format(Number.withI64((i64)1234567));                                   // "1,234,567"
NumberFormatter.currency(String.withCString("$")).format(Number.withDouble(1299.5d));  // "$1,299.50"
NumberFormatter.percent().format(Number.withDouble(0.256d));              // "26%"

A formatter is a set of choices, held in public fields you may change:

FieldDefault
String* prefix""before the digits: a currency symbol
String* suffix""after them: %, a unit
bool groupingtrueseparate thousands
String* groupSeparator","
String* decimalSeparator"."
u8 minimumFractionDigits0pad with zeros to this many
u8 maximumFractionDigits3round to this many
i64 multiplier1100 for a percentage

Rounding. Integers are formatted exactly. A double is rounded to maximumFractionDigits as C’s printf rounds it (to the nearest, with ties to even on the binary value, so 2.675 is 2.67: the double is just below it). Trailing zeros past minimumFractionDigits are then dropped. A minus sign goes before the prefix (-$5.00), and a value that rounds to zero has none.

NumberFormatter* eu = NumberFormatter.decimal();
eu.groupSeparator = String.withCString(".");
eu.decimalSeparator = String.withCString(",");
eu.format(Number.withDouble(1234567.891d));      // "1.234.567,891"

Topics

Section titled “Topics”

Styles · decimal · currency · percent

Formatting · format · formatI64 · formatDouble · formatFixed

Parsing · parse

Styles

Section titled “Styles”

decimal

Section titled “decimal”
static NumberFormatter* decimal(void)

Grouped, up to three fraction digits: 1,234.567. Also what new NumberFormatter() gives.

currency

Section titled “currency”
static NumberFormatter* currency(String* symbol)

symbol in front and exactly two fraction digits: $1,299.00.

percent

Section titled “percent”
static NumberFormatter* percent(void)

Times 100, % after, no fraction digits: 0.256 is 26%.

↑ Topics

Formatting

Section titled “Formatting”

format

Section titled “format”
String* format(Number* n)

n as text, through formatI64 or formatDouble by its kind; a null n is "".

formatI64

Section titled “formatI64”
String* formatI64(i64 v)

An integer, exactly (in double only if the multiplier would overflow it), padded with minimumFractionDigits zeros.

formatDouble

Section titled “formatDouble”
String* formatDouble(double v)

A double, rounded as described above. NaN is NaN; an infinity is ∞ between the prefix and suffix.

formatFixed

Section titled “formatFixed”
String* formatFixed(i64 scaled, u8 decimals)

A fixed-point value in units of 10-decimals, exactly: 129900 with 2 decimals is 1,299.00. The fraction always has decimals digits, whatever the least and most are. What money kept in cents wants.

↑ Topics

Parsing

Section titled “Parsing”

parse

Section titled “parse”
Number* parse(String* text)

The Number that text shows, or null if it is not one. The prefix and suffix are optional, a leading - may come before or after the prefix, grouping separators are ignored, and the result is divided by the multiplier. Text with no decimal separator gives an int when it fits and the multiplier divides it: "300%" is 3, "25%" is 0.25.

↑ Topics