# The NumberFormatter class

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

## Введение

Программы хранят и оперируют числами в двоичном представлении, которое не зависит от текущих региональных настроек. При выводе на экран или печати числа программы преобразовывают числа в строку по правилам, которые соответствуют региональным параметрам. Число 12345.67 в локали US программа выведет как «12,345.67», во французской локали — как «12 345,67» и как «12.345,67» в немецкой.

Методы класса NumberFormatter форматируют числа, денежные единицы и процентные величины в представлении заданных по умолчанию региональных настроек. Класс NumberFormatter чувствителен к региональным параметрам, поэтому придётся создавать новый экземпляр класса NumberFormatter для каждой локали. Методы класса NumberFormatter форматируют числа примитивного типа наподобие double и выводят число в виде строки, формат которой зависит от текущих региональных параметров.

Для валют можно использовать тип формата денежной единицы, который возвращает строку с отформатированным числом и символом валюты. Естественно, класс NumberFormatter не знает об обменных курсах, так что выводимое число будет одинаковым независимо от установленной валюты. То есть одинаковые числа имеют разную денежную стоимость, которая зависит от настроек региональной валюты. Для числа 9988776.65 результат будет таким:

- 9 988 776,65 € для Франции
- 9.988.776,65 € для Германии
- $9,988,776.65 для США

Чтобы отформатировать процентную величину, создают средство форматирования с типом процентного формата, который соответствует текущим региональным настройкам. Такое средство форматирования отобразит десятичную дробь числа 0.75 как 75 %.

Для более сложного форматирования, например записи чисел в виде текста, работают правила средства форматирования по преобразованию чисел в текст.

## Обзор класса

class NumberFormatter {
/* Константы */
public const int PATTERN_DECIMAL;
public const int DECIMAL;
public const int DECIMAL_COMPACT_SHORT;
public const int DECIMAL_COMPACT_LONG;
public const int CURRENCY;
public const int PERCENT;
public const int SCIENTIFIC;
public const int SPELLOUT;
public const int ORDINAL;
public const int DURATION;
public const int PATTERN_RULEBASED;
public const int IGNORE;
public const int CURRENCY_ISO;
public const int CURRENCY_PLURAL;
public const int CURRENCY_ACCOUNTING;
public const int CASH_CURRENCY;
public const int CURRENCY_STANDARD;
public const int DEFAULT_STYLE;
public const int ROUND_CEILING;
public const int ROUND_FLOOR;
public const int ROUND_DOWN;
public const int ROUND_UP;
public const int ROUND_TOWARD_ZERO;
public const int ROUND_AWAY_FROM_ZERO;
public const int ROUND_HALFEVEN;
public const int ROUND_HALFODD;
public const int ROUND_HALFDOWN;
public const int ROUND_HALFUP;
public const int PAD_BEFORE_PREFIX;
public const int PAD_AFTER_PREFIX;
public const int PAD_BEFORE_SUFFIX;
public const int PAD_AFTER_SUFFIX;
public const int PARSE_INT_ONLY;
public const int GROUPING_USED;
public const int DECIMAL_ALWAYS_SHOWN;
public const int MAX_INTEGER_DIGITS;
public const int MIN_INTEGER_DIGITS;
public const int INTEGER_DIGITS;
public const int MAX_FRACTION_DIGITS;
public const int MIN_FRACTION_DIGITS;
public const int FRACTION_DIGITS;
public const int MULTIPLIER;
public const int GROUPING_SIZE;
public const int ROUNDING_MODE;
public const int ROUNDING_INCREMENT;
public const int FORMAT_WIDTH;
public const int PADDING_POSITION;
public const int SECONDARY_GROUPING_SIZE;
public const int SIGNIFICANT_DIGITS_USED;
public const int MIN_SIGNIFICANT_DIGITS;
public const int MAX_SIGNIFICANT_DIGITS;
public const int LENIENT_PARSE;
public const int POSITIVE_PREFIX;
public const int POSITIVE_SUFFIX;
public const int NEGATIVE_PREFIX;
public const int NEGATIVE_SUFFIX;
public const int PADDING_CHARACTER;
public const int CURRENCY_CODE;
public const int DEFAULT_RULESET;
public const int PUBLIC_RULESETS;
public const int DECIMAL_SEPARATOR_SYMBOL;
public const int GROUPING_SEPARATOR_SYMBOL;
public const int PATTERN_SEPARATOR_SYMBOL;
public const int PERCENT_SYMBOL;
public const int ZERO_DIGIT_SYMBOL;
public const int DIGIT_SYMBOL;
public const int MINUS_SIGN_SYMBOL;
public const int PLUS_SIGN_SYMBOL;
public const int CURRENCY_SYMBOL;
public const int INTL_CURRENCY_SYMBOL;
public const int MONETARY_SEPARATOR_SYMBOL;
public const int EXPONENTIAL_SYMBOL;
public const int PERMILL_SYMBOL;
public const int PAD_ESCAPE_SYMBOL;
public const int INFINITY_SYMBOL;
public const int NAN_SYMBOL;
public const int SIGNIFICANT_DIGIT_SYMBOL;
public const int MONETARY_GROUPING_SEPARATOR_SYMBOL;
public const int TYPE_DEFAULT;
public const int TYPE_INT32;
public const int TYPE_INT64;
public const int TYPE_DOUBLE;
public const int TYPE_CURRENCY;
/* Методы */
public function __construct(string `$locale`, int `$style`, ?string `$pattern` = `null`)
public static function create(string `$locale`, int `$style`, ?string `$pattern` = `null`): ?NumberFormatter
public function format(int|float `$num`, int `$type` = `NumberFormatter::TYPE_DEFAULT`): string|false
public function formatCurrency(float `$amount`, string `$currency`): string|false
public function getAttribute(int `$attribute`): int|float|false
public function getErrorCode(): int
public function getErrorMessage(): string
public function getLocale(int `$type` = `ULOC_ACTUAL_LOCALE`): string|false
public function getPattern(): string|false
public function getSymbol(int `$symbol`): string|false
public function getTextAttribute(int `$attribute`): string|false
public function parse(string `$string`, int `$type` = `NumberFormatter::TYPE_DOUBLE`, int `&$offset` = `null`): int|float|false
public function parseCurrency(string `$string`, string `&$currency`, int `&$offset` = `null`): float|false
public function setAttribute(int `$attribute`, int|float `$value`): bool
public function setPattern(string `$pattern`): bool
public function setSymbol(int `$symbol`, string `$value`): bool
public function setTextAttribute(int `$attribute`, string `$value`): bool
}

## Предопределённые константы

## Типы форматирования

Следующие стили определяют режим форматирования значений функцией numfmt_create().

`NumberFormatter::PATTERN_DECIMAL` int
  Формат десятичных чисел по шаблону.
`NumberFormatter::DECIMAL` int
  Формат десятичных чисел.
`NumberFormatter::DECIMAL_COMPACT_SHORT` int
  Формат десятичных чисел в краткой форме компактной нотации: "23K", "45B". Режим доступен с PHP 8.5.0 и ICU 56.
`NumberFormatter::DECIMAL_COMPACT_LONG` int
  Формат десятичных чисел в длинной форме компактной нотации: "23 thousand", "45 billion". Режим доступен с PHP 8.5.0 и ICU 56.
`NumberFormatter::CURRENCY` int
  Формат валюты.
`NumberFormatter::CURRENCY_ISO` int
  Формат валюты по стандарту ISO: "USD1.00". Режим доступен с PHP 8.5.0.
`NumberFormatter::CURRENCY_PLURAL` int
  Формат денежной суммы со склонением названия валюты в единственном или множественном числе: "1.00 US dollar" и "3.00 US dollars". Режим доступен с PHP 8.5.0.
`NumberFormatter::CASH_CURRENCY` int
  Символ валюты для наличных, без дробной части: "NT$3" вместо "NT$3.23". Режим доступен с PHP 8.5.0 и ICU 54.
`NumberFormatter::CURRENCY_STANDARD` int
  Формат денежной суммы с символом валюты: "$1.00". Отрицательные суммы выводятся не в скобках, как в бухгалтерском формате, а со знаком минуса: "-$1.00". Режим доступен с PHP 8.5.0 и ICU 56.
`NumberFormatter::PERCENT` int
  Процентный формат.
`NumberFormatter::SCIENTIFIC` int
  Научный формат.
`NumberFormatter::SPELLOUT` int
  Формат по правилам представления чисел прописью: "одна тысяча девятьсот девяносто пять" для числа 1995.
`NumberFormatter::ORDINAL` int
  Формат по правилам записи порядковых числительных: "8th".
`NumberFormatter::DURATION` int
  Формат интервала времени по заданным правилам: "7:40" для числа 460 или "5 sec." для числа 5.
`NumberFormatter::PATTERN_RULEBASED` int
  Формат по шаблону на основе правил.
`NumberFormatter::CURRENCY_ACCOUNTING` int
  Бухгалтерский формат денежных сумм. Отрицательные суммы выводятся в скобках, а не со знаком минуса: `($3.00)` вместо `-$3.00`. Режим доступен с PHP 7.4.1 и ICU 53.
`NumberFormatter::DEFAULT_STYLE` int
  Формат по умолчанию для текущих региональных настроек.
`NumberFormatter::IGNORE` int
  Псевдоним режима PATTERN_DECIMAL.

## Спецификаторы числового формата

Константы определяют способ разбора чисел функцией numfmt_parse() или форматирования чисел функцией numfmt_format().

`NumberFormatter::TYPE_DEFAULT` int
  Автоопределение типа значения.
`NumberFormatter::TYPE_INT32` int
  Форматирование или разбор значения как 32-битного целого числа.
`NumberFormatter::TYPE_INT64` int
  Форматирование или разбор значения как 64-битного целого числа.
`NumberFormatter::TYPE_DOUBLE` int
  Форматирование или разбор значения как числа с плавающей точкой.
`NumberFormatter::TYPE_CURRENCY` int
  Форматирование или разбор значения как денежной суммы. Спецификатор устарел с PHP 8.3.0.

## Атрибуты форматирования чисел

Атрибуты определяют формат чисел при обработке значений функциями numfmt_get_attribute() и numfmt_set_attribute().

`NumberFormatter::PARSE_INT_ONLY` int
  Разбирать только целые числа.
`NumberFormatter::GROUPING_USED` int
  Разделять группы разрядов.
`NumberFormatter::DECIMAL_ALWAYS_SHOWN` int
  Выводить десятичную точку даже в числах без дробной части.
`NumberFormatter::MAX_INTEGER_DIGITS` int
  Максимум разрядов в целой части числа.
`NumberFormatter::MIN_INTEGER_DIGITS` int
  Минимум разрядов в целой части числа.
`NumberFormatter::INTEGER_DIGITS` int
  Количество разрядов в целой части числа.
`NumberFormatter::MAX_FRACTION_DIGITS` int
  Максимум разрядов в дробной части числа.
`NumberFormatter::MIN_FRACTION_DIGITS` int
  Минимум разрядов в дробной части числа.
`NumberFormatter::FRACTION_DIGITS` int
  Количество разрядов в дробной части числа.
`NumberFormatter::MULTIPLIER` int
  Множитель.
`NumberFormatter::GROUPING_SIZE` int
  Размер группы разрядов.
`NumberFormatter::ROUNDING_MODE` int
  Режим округления.
`NumberFormatter::ROUNDING_INCREMENT` int
  Шаг округления.
`NumberFormatter::FORMAT_WIDTH` int
  Ширина, до которой вывод метода format() дополняется пробелами.
`NumberFormatter::PADDING_POSITION` int
  Позиция, с которой начинается дополнение. Смотрите описание констант дополнения.
`NumberFormatter::SECONDARY_GROUPING_SIZE` int
  Размер второй группы разрядов.
`NumberFormatter::SIGNIFICANT_DIGITS_USED` int
  Выводить только значащие цифры.
`NumberFormatter::MIN_SIGNIFICANT_DIGITS` int
  Минимум значащих цифр.
`NumberFormatter::MAX_SIGNIFICANT_DIGITS` int
  Максимум значащих цифр.
`NumberFormatter::LENIENT_PARSE` int
  Мягкий режим разбора при форматировании чисел по шаблону на основе правил.

## Атрибуты текстового формата чисел

Атрибуты определяют текстовый формат чисел при обработке значений функциями numfmt_get_text_attribute() и numfmt_set_text_attribute().

`NumberFormatter::POSITIVE_PREFIX` int
  Префикс для положительных чисел и нуля.
`NumberFormatter::POSITIVE_SUFFIX` int
  Суффикс для положительных чисел и нуля.
`NumberFormatter::NEGATIVE_PREFIX` int
  Префикс для отрицательных чисел.
`NumberFormatter::NEGATIVE_SUFFIX` int
  Суффикс для отрицательных чисел.
`NumberFormatter::PADDING_CHARACTER` int
  Символ для дополнения до заданной ширины.
`NumberFormatter::CURRENCY_CODE` int
  Код валюты по стандарту ISO.
`NumberFormatter::DEFAULT_RULESET` int
  Набор правил по умолчанию. Атрибут доступен только для форматирования на основе правил.
`NumberFormatter::PUBLIC_RULESETS` int
  Публичный набор правил. Атрибут доступен только для форматирования на основе правил. Атрибут доступен только для чтения. Публичный набор правил возвращается в виде одной строки, в которой название каждого набора правил отделяется символом ';' — точка с запятой.

## Спецификаторы формата символов

Символы форматирования чисел для numfmt_get_symbol() и numfmt_set_symbol().

`NumberFormatter::DECIMAL_SEPARATOR_SYMBOL` int
  Десятичный разделитель.
`NumberFormatter::GROUPING_SEPARATOR_SYMBOL` int
  Разделитель групп.
`NumberFormatter::PATTERN_SEPARATOR_SYMBOL` int
  Разделитель шаблонов.
`NumberFormatter::PERCENT_SYMBOL` int
  Знак процента.
`NumberFormatter::ZERO_DIGIT_SYMBOL` int
  Ноль.
`NumberFormatter::DIGIT_SYMBOL` int
  Символ представления цифры в шаблоне.
`NumberFormatter::MINUS_SIGN_SYMBOL` int
  Знак минус.
`NumberFormatter::PLUS_SIGN_SYMBOL` int
  Знак плюс.
`NumberFormatter::CURRENCY_SYMBOL` int
  Символ валюты.
`NumberFormatter::INTL_CURRENCY_SYMBOL` int
  Международный символ валюты.
`NumberFormatter::MONETARY_SEPARATOR_SYMBOL` int
  Десятичный разделитель в денежных форматах.
`NumberFormatter::EXPONENTIAL_SYMBOL` int
  Символ экспоненты в научной нотации.
`NumberFormatter::PERMILL_SYMBOL` int
  Символ промилле.
`NumberFormatter::PAD_ESCAPE_SYMBOL` int
  Символ экранирования заполнителя.
`NumberFormatter::INFINITY_SYMBOL` int
  Знак бесконечности.
`NumberFormatter::NAN_SYMBOL` int
  Символ нечисла (англ. Not-a-number, сокр. NaN).
`NumberFormatter::SIGNIFICANT_DIGIT_SYMBOL` int
  Символ значащей цифры.
`NumberFormatter::MONETARY_GROUPING_SEPARATOR_SYMBOL` int
  Разделитель групп для денежного формата.

## Режимы округления

Режимы округления при вызове функций numfmt_get_attribute() и numfmt_set_attribute() с атрибутом `NumberFormatter::ROUNDING_MODE`.

`NumberFormatter::ROUND_AWAY_FROM_ZERO`
  Псевдоним константы `NumberFormatter::ROUND_UP`.
`NumberFormatter::ROUND_CEILING` int
  Округление в сторону положительной бесконечности.
`NumberFormatter::ROUND_DOWN` int
  Округление к меньшему по модулю числу.
`NumberFormatter::ROUND_FLOOR` int
  Округление в сторону отрицательной бесконечности.
`NumberFormatter::ROUND_HALFDOWN` int
  Округление к ближайшему числу; при равном удалении — к меньшему по модулю.
`NumberFormatter::ROUND_HALFEVEN` int
  Округление к ближайшему числу; при равном удалении — к ближайшему чётному.
`NumberFormatter::ROUND_HALFODD`
  Округление к ближайшему нечётному числу.
`NumberFormatter::ROUND_HALFUP` int
  Округление к ближайшему числу; при равном удалении — к большему по модулю.
`NumberFormatter::ROUND_TOWARD_ZERO`
  Псевдоним константы `NumberFormatter::ROUND_DOWN`.
`NumberFormatter::ROUND_UP` int
  Округление к большему по модулю числу.

## Спецификаторы дополнения

Значения позиции дополнения при вызове функций numfmt_get_attribute() и numfmt_set_attribute() с атрибутом `NumberFormatter::PADDING_POSITION`.

`NumberFormatter::PAD_AFTER_PREFIX` int
  Символы дополнения вставляются после префикса.
`NumberFormatter::PAD_AFTER_SUFFIX` int
  Символы дополнения вставляются после суффикса.
`NumberFormatter::PAD_BEFORE_PREFIX` int
  Символы дополнения вставляются перед префиксом.
`NumberFormatter::PAD_BEFORE_SUFFIX` int
  Символы дополнения вставляются перед суффиксом.

## Смотрите также

- » Документация проекта ICU по форматированию
- » ICU. Форматирование чисел
- » ICU. Форматирование десятичных дробей
- » ICU. Форматирование чисел на основе правил

## Список изменений

Версия | Описание
--- | ---
8.5.0 | Добавлены константы `NumberFormatter::DECIMAL_COMPACT_SHORT`, `NumberFormatter::DECIMAL_COMPACT_LONG`, `NumberFormatter::CURRENCY_ISO`, `NumberFormatter::CURRENCY_PLURAL`, `NumberFormatter::CASH_CURRENCY`, `NumberFormatter::CURRENCY_STANDARD`.
8.4.0 | Константы класса стали типизированными.

## Содержание

- NumberFormatter::create — Создаёт средство форматирования чисел
- NumberFormatter::format — Форматирует число
- NumberFormatter::formatCurrency — Форматирует значение валюты
- NumberFormatter::getAttribute — Получает атрибут
- NumberFormatter::getErrorCode — Получает последний код ошибки средства форматирования
- NumberFormatter::getErrorMessage — Получает последнее сообщение об ошибке средства форматирования
- NumberFormatter::getLocale — Получает локаль средства форматирования
- NumberFormatter::getPattern — Получает шаблон средства форматирования
- NumberFormatter::getSymbol — Получает значение символа
- NumberFormatter::getTextAttribute — Получает текстовый атрибут
- NumberFormatter::parse — Разбирает число
- NumberFormatter::parseCurrency — Разбирает номер валюты
- NumberFormatter::setAttribute — Устанавливает значение для атрибута форматирования чисел
- NumberFormatter::setPattern — Устанавливает шаблон средства форматирования
- NumberFormatter::setSymbol — Устанавливает значение символа
- NumberFormatter::setTextAttribute — Устанавливает текстовый атрибут

`↑` and `↓` to navigate • `Enter` to select • `Esc` to close • `/` to open