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: Символы дополнения вставляются перед суффиксом.

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

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

Версия	Описание
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 — Устанавливает текстовый атрибут