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 %.

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

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

classNumberFormatter {

publicconstintPATTERN_DECIMAL;

publicconstintDECIMAL;

publicconstintCURRENCY;

publicconstintPERCENT;

publicconstintSCIENTIFIC;

publicconstintSPELLOUT;

publicconstintORDINAL;

publicconstintDURATION;

publicconstintPATTERN_RULEBASED;

publicconstintIGNORE;

publicconstintCURRENCY_ACCOUNTING;

publicconstintDEFAULT_STYLE;

publicconstintROUND_CEILING;

publicconstintROUND_FLOOR;

publicconstintROUND_DOWN;

publicconstintROUND_UP;

publicconstintROUND_HALFEVEN;

publicconstintROUND_HALFDOWN;

publicconstintROUND_HALFUP;

publicconstintPAD_BEFORE_PREFIX;

publicconstintPAD_AFTER_PREFIX;

publicconstintPAD_BEFORE_SUFFIX;

publicconstintPAD_AFTER_SUFFIX;

publicconstintPARSE_INT_ONLY;

publicconstintGROUPING_USED;

publicconstintDECIMAL_ALWAYS_SHOWN;

publicconstintMAX_INTEGER_DIGITS;

publicconstintMIN_INTEGER_DIGITS;

publicconstintINTEGER_DIGITS;

publicconstintMAX_FRACTION_DIGITS;

publicconstintMIN_FRACTION_DIGITS;

publicconstintFRACTION_DIGITS;

publicconstintMULTIPLIER;

publicconstintGROUPING_SIZE;

publicconstintROUNDING_MODE;

publicconstintROUNDING_INCREMENT;

publicconstintFORMAT_WIDTH;

publicconstintPADDING_POSITION;

publicconstintSECONDARY_GROUPING_SIZE;

publicconstintSIGNIFICANT_DIGITS_USED;

publicconstintMIN_SIGNIFICANT_DIGITS;

publicconstintMAX_SIGNIFICANT_DIGITS;

publicconstintLENIENT_PARSE;

publicconstintPOSITIVE_PREFIX;

publicconstintPOSITIVE_SUFFIX;

publicconstintNEGATIVE_PREFIX;

publicconstintNEGATIVE_SUFFIX;

publicconstintPADDING_CHARACTER;

publicconstintCURRENCY_CODE;

publicconstintDEFAULT_RULESET;

publicconstintPUBLIC_RULESETS;

publicconstintDECIMAL_SEPARATOR_SYMBOL;

publicconstintGROUPING_SEPARATOR_SYMBOL;

publicconstintPATTERN_SEPARATOR_SYMBOL;

publicconstintPERCENT_SYMBOL;

publicconstintZERO_DIGIT_SYMBOL;

publicconstintDIGIT_SYMBOL;

publicconstintMINUS_SIGN_SYMBOL;

publicconstintPLUS_SIGN_SYMBOL;

publicconstintCURRENCY_SYMBOL;

publicconstintINTL_CURRENCY_SYMBOL;

publicconstintMONETARY_SEPARATOR_SYMBOL;

publicconstintEXPONENTIAL_SYMBOL;

publicconstintPERMILL_SYMBOL;

publicconstintPAD_ESCAPE_SYMBOL;

publicconstintINFINITY_SYMBOL;

publicconstintNAN_SYMBOL;

publicconstintSIGNIFICANT_DIGIT_SYMBOL;

publicconstintMONETARY_GROUPING_SEPARATOR_SYMBOL;

publicconstintTYPE_DEFAULT;

publicconstintTYPE_INT32;

publicconstintTYPE_INT64;

publicconstintTYPE_DOUBLE;

publicconstintTYPE_CURRENCY;

public__construct(string$locale, int$style, ?string$pattern = null)

publicstaticcreate(string$locale, int$style, ?string$pattern = null): ?NumberFormatter

publicformatCurrency(float$amount, string$currency): string|false

publicformat(int|float$num, int$type = NumberFormatter::TYPE_DEFAULT): string|false

publicgetAttribute(int$attribute): int|float|false

publicgetErrorCode(): int

publicgetErrorMessage(): string

publicgetLocale(int$type = ULOC_ACTUAL_LOCALE): string|false

publicgetPattern(): string|false

publicgetSymbol(int$symbol): string|false

publicgetTextAttribute(int$attribute): string|false

publicparseCurrency(string$string, string&$currency, int&$offset = null): float|false

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

publicsetAttribute(int$attribute, int|float$value): bool

publicsetPattern(string$pattern): bool

publicsetSymbol(int$symbol, string$value): bool

publicsetTextAttribute(int$attribute, string$value): bool

}

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

Данные стили используются функцией numfmt_create() для определения типа форматирования.

NumberFormatter::PATTERN_DECIMAL: Формат с десятичной точкой заданный шаблоном
NumberFormatter::DECIMAL: Формат с десятичной точкой
NumberFormatter::CURRENCY: денежный формат
NumberFormatter::PERCENT: Процентный формат
NumberFormatter::SCIENTIFIC: Научный формат
NumberFormatter::SPELLOUT: Разобранный формат на основе правил
NumberFormatter::ORDINAL: Числительный формат на основе правил
NumberFormatter::DURATION: Формат длительности на основе правил
NumberFormatter::PATTERN_RULEBASED: Формат на основе правил по шаблону
NumberFormatter::CURRENCY_ACCOUNTING: Формат валюты для учёта, например, ($3.00) для отрицательной суммы в валюте вместо -$3.00. Доступно с PHP 7.4.1 и ICU 53.
NumberFormatter::DEFAULT_STYLE: Формат по умолчанию для локали
NumberFormatter::IGNORE: Псевдоним для PATTERN_DECIMAL

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

NumberFormatter::TYPE_DEFAULT: Тип определяется типом переменной
NumberFormatter::TYPE_INT32: Форматирование/разбор как 32-битного целого
NumberFormatter::TYPE_INT64: Форматирование/разбор как 64-битного целого
NumberFormatter::TYPE_DOUBLE: Форматирование/разбор как рационального (float)
NumberFormatter::TYPE_CURRENCY: Форматирование/разбор как денежной единицы. Устарело, начиная с PHP 8.3.0

Атрибут формата чисел для numfmt_get_attribute() и numfmt_set_attribute().

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

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

NumberFormatter::POSITIVE_PREFIX: Положительный префикс.
NumberFormatter::POSITIVE_SUFFIX: Положительный суффикс.
NumberFormatter::NEGATIVE_PREFIX: Отрицательный префикс.
NumberFormatter::NEGATIVE_SUFFIX: Отрицательный суффикс.
NumberFormatter::PADDING_CHARACTER: Символ для дополнения строки.
NumberFormatter::CURRENCY_CODE: Код денежной единицы ISO.
NumberFormatter::DEFAULT_RULESET: Набор правил по умолчанию. Доступно только для форматирования на основе правил.
NumberFormatter::PUBLIC_RULESETS: Публичный набор правил. Доступно только для форматирования на основе правил. Этот атрибут доступен только на чтение. Публичный набор правил возвращается в виде строки, в которой каждый набор правил отделен точкой с запятой (;).

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

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

Режимы округления для numfmt_get_attribute() и numfmt_set_attribute() с атрибутом NumberFormatter::ROUNDING_MODE.

NumberFormatter::ROUND_CEILING: Округление в сторону положительной бесконечности.
NumberFormatter::ROUND_DOWN: Округление вниз.
NumberFormatter::ROUND_FLOOR: Округление в сторону отрицательной бесконечности.
NumberFormatter::ROUND_HALFDOWN: Округление в сторону "ближайшего соседа" кроме случаев, когда они на одинаковом расстоянии. В этом случае округление вниз.
NumberFormatter::ROUND_HALFEVEN: Округление в сторону "ближайшего соседа" кроме случаев, когда они на одинаковом расстоянии. В этом случае округление к чётному значению.
NumberFormatter::ROUND_HALFUP: Округление в сторону "ближайшего соседа" кроме случаев, когда они на одинаковом расстоянии. В этом случае округление вверх.
NumberFormatter::ROUND_UP: Округление вверх.

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

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

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

Содержание

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