Форматирует число как денежную величину

Описание

money_format(string $format, float $number): string

Функция money_format() форматирует число в аргументе number как денежную величину. Эта функция вызывает функцию strfmon() языка C, но преобразовывает только одно число за один вызов.

Список параметров

format

Описание формата состоит из:

символа %
необязательных флагов
необязательной ширины поля
необязательной точности до запятой
необязательной точности после запятой
обязательного описателя преобразования

Флаги

Параметр принимает следующие флаги:

=f: Символ =, за которым следует ещё один символ f, задаёт символ заполнения. По умолчанию — пробел.
^: Отключает группировку символов (определяемую текущей локалью).
+ или (: Задаёт способ форматирования положительных и отрицательных значений. При использовании + будут использоваться аналоги символов + и - из текущей локали. Если указана (, отрицательные числа будут заключены в скобки. По умолчанию +.
!: Подавляет вывод символа валюты.
-: При установке флага поля выравниваются влево (с отбивкой вправо), вместо выравнивания по умолчанию вправо (с отбивкой влево).

Ширина поля

w: Строка из десятичных цифр, которая задаёт минимальную ширину поля. Поле выравнивается вправо, если не указали флаг -. Значение по умолчанию равняется 0.

Точность до запятой

#n

Максимальное количество цифр (n), которое ожидается до запятой. Это обычно используется при выводе значений одно под другим, чтобы десятичные точки располагались в одной колонке, при этом используется символ заполнения, если число цифр меньше n. Если число цифр больше n, этот параметр игнорируется.

Разделители групп вставляются перед добавлением символов заполнения, если группировку не отключили флагом ^. Разделители групп не вставляются между символами заполнения, даже если заполнитель — цифра.

В целях выравнивания каждый символ наподобие символа валюты или знакового символа, который появился до или после числа в отформатированном выводе, дополняются пробелами, чтобы сделать положительные и отрицательные форматы одинаковой длины.

Точность после запятой

.p: Точка, за которой идёт p десятичных цифр. Десятичная точка и цифры после неё не выводятся, если значение флага p равно нулю. При пропуске параметра число знаков после запятой определяется текущими языковыми настройками. Перед форматированием число округляется до заданного количества знаков.

Описатель преобразования

i: Используется международный денежный формат из текущей локали (например, для американской локали: USD 1,234.56).
n: Используется национальный денежный формат из текущей локали (например, для локали de_DE: EU1.234,56).
%: Вставляет символ %.

number

Форматируемое число.

Возвращаемые значения

Функция возвращает отформатированную строку. Символы перед и после описания формата возвращаются без изменений. При передачи в аргументе number нечислового значения функция вернёт значение null и выдаст ошибку уровня E_WARNING.

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

Версия	Описание
8.0.0	Функцию удалили.
7.4.0	Функция устарела. Вместо неё пользуются методом NumberFormatter::formatCurrency().

Примеры

Пример #1 Пример форматирования числа функцией money_format()

Проиллюстрируем применение этой функции для разных локалей и разных описаний формата.

<?php

$number = 1234.56;

// Международный формат в локали en_US
setlocale(LC_MONETARY, 'en_US');
echo money_format('%i', $number) . "\n";
// USD 1,234.56

// Итальянский национальный формат с 2 знаками после запятой
setlocale(LC_MONETARY, 'it_IT');
echo money_format('%.2n', $number) . "\n";
// Eu 1.234,56

// Форматирование отрицательных чисел
$number = -1234.5672;

// Национальный формат США, со скобками
// для отрицательных чисел и 10 знаков до запятой
setlocale(LC_MONETARY, 'en_US');
echo money_format('%(#10n', $number) . "\n";
// ($        1,234.57)

// Похоже на предыдущий формат, но с добавлением 2 знаков после запятой
// и символом '*' в качестве заполнителя
echo money_format('%=*(#10.2n', $number) . "\n";
// ($********1,234.57)

// Выравнивание влево, ширина 14 знаков, 8 знаков до запятой,
// 2 знака после запятой, без разбиения на группы
// с использованием  международного формата в локали de_DE.
setlocale(LC_MONETARY, 'de_DE');
echo money_format('%=*^-14#8.2i', 1234.56) . "\n";
// Eu 1234,56****

// А теперь добавим текст перед и после описанием формата
setlocale(LC_MONETARY, 'en_GB');
$fmt = 'Итоговая сумма: %i (после скидки в 10 %%)';
echo money_format($fmt, 1234.56) . "\n";
// Итоговая сумма: GBP 1,234.56 (после 10-процентной скидки)

?>

Примечания

Замечание:
Функция money_format() будет доступна только в системах с поддержкой функции strfmon. ОС Windows не поддерживает этот системный вызов, поэтому в Windows функция money_format() не содержит определения.

Замечание:
На работу этой функции влияет установка категории LC_MONETARY текущей локали. Перед вызовом функции рекомендуют установить функцией setlocale() локаль, которая соответствует настройкам форматирования денежных единиц.

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

setlocale() - Устанавливает региональные настройки
sscanf() - Разбирает строку по условиям формата
sprintf() - Возвращает отформатированную строку
printf() - Выводит отформатированную строку
number_format() - Форматирует число с группировкой классов многозначного числа