The NumberFormatter class

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

Введение

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

Вызывая методы этого класса, вы можете форматировать числа, денежные единицы и процентные величины в представлении нужной локали. Класс 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
Форматирование/разбор как денежной единицы

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

Содержание