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 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_ACCOUNTING;

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_HALFEVEN;

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 __construct(string $locale, int $style, ?string $pattern = null)

public static create(string $locale, int $style, ?string $pattern = null): ?NumberFormatter

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

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

public getAttribute(int $attribute): int|float|false

public getErrorCode(): int

public getErrorMessage(): string

public getLocale(int $type = ULOC_ACTUAL_LOCALE): string|false

public getPattern(): string|false

public getSymbol(int $symbol): string|false

public getTextAttribute(int $attribute): string|false

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

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

public setAttribute(int $attribute, int|float $value): bool

public setPattern(string $pattern): bool

public setSymbol(int $symbol, string $value): bool

public setTextAttribute(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 — Устанавливает текстовый атрибут