NumberFormatter

class NumberFormatter (View source)

Programs store and operate on numbers using a locale-independent binary representation. When displaying or printing a number it is converted to a locale-specific string. For example, the number 12345.67 is "12,345.67" in the US, "12 345,67" in France and "12.345,67" in Germany.

By invoking the methods provided by the NumberFormatter class, you can format numbers, currencies, and percentages according to the specified or default locale. NumberFormatter is locale-sensitive so you need to create a new NumberFormatter for each locale. NumberFormatter methods format primitive-type numbers, such as double and output the number as a locale-specific string. For currencies you can use currency format type to create a formatter that returns a string with the formatted number and the appropriate currency sign. Of course, the NumberFormatter class is unaware of exchange rates so, the number output is the same regardless of the specified currency. This means that the same number has different monetary values depending on the currency locale. If the number is 9988776.65 the results will be: 9 988 776,65 € in France 9.988.776,65 € in Germany $9,988,776.65 in the United States In order to format percentages, create a locale-specific formatter with percentage format type. With this formatter, a decimal fraction such as 0.75 is displayed as 75%. For more complex formatting, like spelled-out numbers, the rule-based number formatters are used.

Constants

CURRENCY_ACCOUNTING

PATTERN_DECIMAL

Decimal format defined by pattern
DECIMAL

Decimal format
CURRENCY

Currency format
PERCENT

Percent format
SCIENTIFIC

Scientific format
SPELLOUT

Spellout rule-based format
ORDINAL

Ordinal rule-based format
DURATION

Duration rule-based format
PATTERN_RULEBASED

Rule-based format defined by pattern
IGNORE

Alias for PATTERN_DECIMAL
DEFAULT_STYLE

Default format for the locale
ROUND_CEILING

Rounding mode to round towards positive infinity.
ROUND_FLOOR

Rounding mode to round towards negative infinity.
ROUND_DOWN

Rounding mode to round towards zero.
ROUND_UP

Rounding mode to round away from zero.
ROUND_HALFEVEN

Rounding mode to round towards the "nearest neighbor" unless both neighbors are equidistant, in which case, round towards the even neighbor.
ROUND_HALFDOWN

Rounding mode to round towards "nearest neighbor" unless both neighbors are equidistant, in which case round down.
ROUND_HALFUP

Rounding mode to round towards "nearest neighbor" unless both neighbors are equidistant, in which case round up.
PAD_BEFORE_PREFIX

Pad characters inserted before the prefix.
PAD_AFTER_PREFIX

Pad characters inserted after the prefix.
PAD_BEFORE_SUFFIX

Pad characters inserted before the suffix.
PAD_AFTER_SUFFIX

Pad characters inserted after the suffix.
PARSE_INT_ONLY

Parse integers only.
GROUPING_USED

Use grouping separator.
DECIMAL_ALWAYS_SHOWN

Always show decimal point.
MAX_INTEGER_DIGITS

Maximum integer digits.
MIN_INTEGER_DIGITS

Minimum integer digits.
INTEGER_DIGITS

Integer digits.
MAX_FRACTION_DIGITS

Maximum fraction digits.
MIN_FRACTION_DIGITS

Minimum fraction digits.
FRACTION_DIGITS

Fraction digits.
MULTIPLIER

Multiplier.
GROUPING_SIZE

Grouping size.
ROUNDING_MODE

Rounding Mode.
ROUNDING_INCREMENT

Rounding increment.
FORMAT_WIDTH

The width to which the output of format() is padded.
PADDING_POSITION

The position at which padding will take place. See pad position constants for possible argument values.
SECONDARY_GROUPING_SIZE

Secondary grouping size.
SIGNIFICANT_DIGITS_USED

Use significant digits.
MIN_SIGNIFICANT_DIGITS

Minimum significant digits.
MAX_SIGNIFICANT_DIGITS

Maximum significant digits.
LENIENT_PARSE

Lenient parse mode used by rule-based formats.
POSITIVE_PREFIX

Positive prefix.
POSITIVE_SUFFIX

Positive suffix.
NEGATIVE_PREFIX

Negative prefix.
NEGATIVE_SUFFIX

Negative suffix.
PADDING_CHARACTER

The character used to pad to the format width.
CURRENCY_CODE

The ISO currency code.
DEFAULT_RULESET

The default rule set. This is only available with rule-based formatters.
PUBLIC_RULESETS

The public rule sets. This is only available with rule-based formatters. This is a read-only attribute. The public rulesets are returned as a single string, with each ruleset name delimited by ';' (semicolon).
DECIMAL_SEPARATOR_SYMBOL

The decimal separator.
GROUPING_SEPARATOR_SYMBOL

The grouping separator.
PATTERN_SEPARATOR_SYMBOL

The pattern separator.
PERCENT_SYMBOL

The percent sign.
ZERO_DIGIT_SYMBOL

Zero.
DIGIT_SYMBOL

Character representing a digit in the pattern.
MINUS_SIGN_SYMBOL

The minus sign.
PLUS_SIGN_SYMBOL

The plus sign.
CURRENCY_SYMBOL

The currency symbol.
INTL_CURRENCY_SYMBOL

The international currency symbol.
MONETARY_SEPARATOR_SYMBOL

The monetary separator.
EXPONENTIAL_SYMBOL

The exponential symbol.
PERMILL_SYMBOL

Per mill symbol.
PAD_ESCAPE_SYMBOL

Escape padding character.
INFINITY_SYMBOL

Infinity symbol.
NAN_SYMBOL

Not-a-number symbol.
SIGNIFICANT_DIGIT_SYMBOL

Significant digit symbol.
MONETARY_GROUPING_SEPARATOR_SYMBOL

The monetary grouping separator.
TYPE_DEFAULT

Derive the type from variable type
TYPE_INT32

Format/parse as 32-bit integer
TYPE_INT64

Format/parse as 64-bit integer
TYPE_DOUBLE

Format/parse as floating point value
deprecated TYPE_CURRENCY

Format/parse as currency value
ROUND_TOWARD_ZERO Since: 8.4

ROUND_AWAY_FROM_ZERO Since: 8.4

ROUND_HALFODD Since: 8.4

DECIMAL_COMPACT_SHORT Since: 8.5

DECIMAL_COMPACT_LONG Since: 8.5

CURRENCY_ISO Since: 8.5

CURRENCY_PLURAL Since: 8.5

CASH_CURRENCY Since: 8.5

CURRENCY_STANDARD Since: 8.5

Methods

__construct(string $locale, int $style, string $pattern = null)

Create a number formatter

static NumberFormatter|null
create(string $locale, int $style, string $pattern = null)

(PHP 5 >= 5.3.0, PECL intl >= 1.0.0)
Create a number formatter

string|false
format(int|float $num, int $type = 0)

(PHP 5 >= 5.3.0, PECL intl >= 1.0.0)
Format a number

int|float|false
parse(string $string, int $type = NumberFormatter::TYPE_DOUBLE, int $offset = null)

(PHP 5 >= 5.3.0, PECL intl >= 1.0.0)
Parse a number

string|false
formatCurrency(float $amount, string $currency)

(PHP 5 >= 5.3.0, PECL intl >= 1.0.0)
Format a currency value

float|false
parseCurrency(string $string, string $currency, int $offset = null)

(PHP 5 >= 5.3.0, PECL intl >= 1.0.0)
Parse a currency number

bool
setAttribute(int $attribute, int $value)

(PHP 5 >= 5.3.0, PECL intl >= 1.0.0)
Set an attribute

int|float|false
getAttribute(int $attribute)

(PHP 5 >= 5.3.0, PECL intl >= 1.0.0)
Get an attribute

bool
setTextAttribute(int $attribute, string $value)

(PHP 5 >= 5.3.0, PECL intl >= 1.0.0)
Set a text attribute

string|false
getTextAttribute(int $attribute)

(PHP 5 >= 5.3.0, PECL intl >= 1.0.0)
Get a text attribute

bool
setSymbol(int $symbol, string $value)

(PHP 5 >= 5.3.0, PECL intl >= 1.0.0)
Set a symbol value

string|false
getSymbol(int $symbol)

(PHP 5 >= 5.3.0, PECL intl >= 1.0.0)
Get a symbol value

bool
setPattern(string $pattern)

(PHP 5 >= 5.3.0, PECL intl >= 1.0.0)
Set formatter pattern

string|false
getPattern()

(PHP 5 >= 5.3.0, PECL intl >= 1.0.0)
Get formatter pattern

string|false
getLocale(int $type = 0)

(PHP 5 >= 5.3.0, PECL intl >= 1.0.0)
Get formatter locale

int
getErrorCode()

(PHP 5 >= 5.3.0, PECL intl >= 1.0.0)
Get formatter's last error code.

string
getErrorMessage()

(PHP 5 >= 5.3.0, PECL intl >= 1.0.0)
Get formatter's last error message.

Details

at line 1018
__construct(string $locale, int $style, string $pattern = null)

Create a number formatter

Creates a number formatter.

Parameters

string $locale

Locale in which the number would be formatted (locale name, e.g. en_CA).
int $style

Style of the formatting, one of the format style constants. If NumberFormatter::PATTERN_DECIMAL or NumberFormatter::PATTERN_RULEBASED is passed then the number format is opened using the given pattern, which must conform to the syntax described in ICU DecimalFormat documentation or ICU RuleBasedNumberFormat documentation, respectively.
string $pattern [optional]

at line 1053
static NumberFormatter|null create(string $locale, int $style, string $pattern = null)

(PHP 5 >= 5.3.0, PECL intl >= 1.0.0)
Create a number formatter

Parameters

string $locale

Locale in which the number would be formatted (locale name, e.g. en_CA).

int $style

Style of the formatting, one of the format style constants. If NumberFormatter::PATTERN_DECIMAL or NumberFormatter::PATTERN_RULEBASED is passed then the number format is opened using the given pattern, which must conform to the syntax described in ICU DecimalFormat documentation or ICU RuleBasedNumberFormat documentation, respectively.

string $pattern

[optional]

Pattern string if the chosen style requires a pattern.

Return Value

NumberFormatter|null

NumberFormatter object or FALSE on error.

at line 1078
string|false format(int|float $num, int $type = 0)

(PHP 5 >= 5.3.0, PECL intl >= 1.0.0)
Format a number

Parameters

int|float $num

The value to format. Can be integer or float, other values will be converted to a numeric value.

int $type

[optional]

The formatting type to use.

Return Value

string|false

the string containing formatted value, or FALSE on error.

at line 1101
int|float|false parse(string $string, int $type = NumberFormatter::TYPE_DOUBLE, int $offset = null)

(PHP 5 >= 5.3.0, PECL intl >= 1.0.0)
Parse a number

Parameters

string $string

The string to parse for the number.
int $type

[optional]

The formatting type to use. By default, NumberFormatter::TYPE_DOUBLE is used.

int $offset

[optional]

Offset in the string at which to begin parsing. On return, this value will hold the offset at which parsing ended.

Return Value

int|float|false

The value of the parsed number or FALSE on error.

at line 1120
string|false formatCurrency(float $amount, string $currency)

(PHP 5 >= 5.3.0, PECL intl >= 1.0.0)
Format a currency value

Parameters

float $amount

The numeric currency value.

string $currency

The 3-letter ISO 4217 currency code indicating the currency to use.

Return Value

string|false

String representing the formatted currency value.

at line 1142
float|false parseCurrency(string $string, string $currency, int $offset = null)

(PHP 5 >= 5.3.0, PECL intl >= 1.0.0)
Parse a currency number

Parameters

string $string
string $currency

Parameter to receive the currency name (3-letter ISO 4217 currency code).

int $offset

[optional]

Offset in the string at which to begin parsing. On return, this value will hold the offset at which parsing ended.

Return Value

float|false

The parsed numeric value or FALSE on error.

at line 1158
bool setAttribute(int $attribute, int $value)

(PHP 5 >= 5.3.0, PECL intl >= 1.0.0)
Set an attribute

Parameters

int $attribute

Attribute specifier - one of the numeric attribute constants.

int $value

The attribute value.

Return Value

bool

TRUE on success or FALSE on failure.

at line 1174
int|float|false getAttribute(int $attribute)

(PHP 5 >= 5.3.0, PECL intl >= 1.0.0)
Get an attribute

Parameters

int $attribute

Attribute specifier - one of the numeric attribute constants.

Return Value

int|float|false

Return attribute value on success, or FALSE on error.

at line 1192
bool setTextAttribute(int $attribute, string $value)

(PHP 5 >= 5.3.0, PECL intl >= 1.0.0)
Set a text attribute

Parameters

int $attribute

Attribute specifier - one of the text attribute constants.

string $value

Text for the attribute value.

Return Value

bool

TRUE on success or FALSE on failure.

at line 1208
string|false getTextAttribute(int $attribute)

(PHP 5 >= 5.3.0, PECL intl >= 1.0.0)
Get a text attribute

Parameters

int $attribute

Attribute specifier - one of the text attribute constants.

Return Value

string|false

Return attribute value on success, or FALSE on error.

at line 1225
bool setSymbol(int $symbol, string $value)

(PHP 5 >= 5.3.0, PECL intl >= 1.0.0)
Set a symbol value

Parameters

int $symbol

Symbol specifier, one of the format symbol constants.

string $value

Text for the symbol.

Return Value

bool

TRUE on success or FALSE on failure.

at line 1241
string|false getSymbol(int $symbol)

(PHP 5 >= 5.3.0, PECL intl >= 1.0.0)
Get a symbol value

Parameters

int $symbol

Symbol specifier, one of the format symbol constants.

Return Value

string|false

The symbol string or FALSE on error.

at line 1256
bool setPattern(string $pattern)

(PHP 5 >= 5.3.0, PECL intl >= 1.0.0)
Set formatter pattern

Parameters

string $pattern

Pattern in syntax described in ICU DecimalFormat documentation.

Return Value

bool

TRUE on success or FALSE on failure.

at line 1265
string|false getPattern()

(PHP 5 >= 5.3.0, PECL intl >= 1.0.0)
Get formatter pattern

Return Value

string|false

Pattern string that is used by the formatter, or FALSE if an error happens.

at line 1281
string|false getLocale(int $type = 0)

(PHP 5 >= 5.3.0, PECL intl >= 1.0.0)
Get formatter locale

Parameters

int $type

[optional]

You can choose between valid and actual locale ( Locale::VALID_LOCALE, Locale::ACTUAL_LOCALE, respectively). The default is the actual locale.

Return Value

string|false

The locale name used to create the formatter.

at line 1293
int getErrorCode()

(PHP 5 >= 5.3.0, PECL intl >= 1.0.0)
Get formatter's last error code.

Return Value

int

error code from last formatter call.

at line 1303
string getErrorMessage()

(PHP 5 >= 5.3.0, PECL intl >= 1.0.0)
Get formatter's last error message.

Return Value

string

error message from last formatter call.