(PHP 4, PHP 5, PHP 7, PHP 8)
sprintf — Возвращает отформатированную строку
Функция форматирует строку по условиям, которые передали в параметр format
.
format
Строка формата состоит из нуля или более директив:
обычные символы (за исключением %
), которые
просто выводятся без изменения,
и спецификаторы преобразования, каждый из которых
требует передачи своего параметра.
Спецификатор преобразования соответствует прототипу:
%[argnum$][flags][width][.precision]specifier
.
Целое число, за которым следует знак доллара $
,
чтобы указать, какой числовой аргумент обрабатывать при преобразовании.
Флаг | Описание |
---|---|
- |
Выравнивание по левому краю в пределах заданной ширины поля; По умолчанию выравнивание происходит по правому краю. |
+ |
Печатает плюс + у не отрицательных чисел;
По умолчанию знак печатается только у отрицательных чисел.
|
(пробел) |
Дополняет результат пробелами. Это поведение по умолчанию. |
0 |
Дополняет числа нулями (только слева).
Со спецификатором s также может
дополнять нулями справа.
|
' (символ) |
Дополняет результат символом (символ). |
Либо целое число, которое указывает, сколько символов (минимум) должно получиться в результате преобразования,
либо *
.
Если указали символ *
, ширина задаётся как дополнительное целое значение,
которое предшествует значению, которое отформатировал спецификатор.
Точка .
, за которой необязательно следует целое число
или символ *
, значение которых зависит от спецификатора:
e
, E
,
f
и F
:
задаёт количество цифр после десятичной запятой (значение по умолчанию равно 6).
g
,G
,
h
и H
:
задаёт максимальное значение печатаемых значащих цифр.
s
: задаёт ограничение
максимального количества символов в строке, которые выведет функция.
Замечание: Если указали точку без последующего значения точности, точность будет считаться за 0. Если указали символ
*
, точность задаётся как дополнительное целое значение, которое предшествует значению, которое отформатировал спецификатор.
Спецификатор | Описание |
---|---|
% |
Символ процента. Аргументы не требуются. |
b |
Аргумент рассматривается как целое число и печатается в бинарном представлении. |
c |
Аргумент рассматривается как целое число и печатается как символ из таблицы ASCII с соответствующим кодом. |
d |
Аргумент рассматривается как целое число и печатается как целое число со знаком. |
e |
Аргумент считается за число в научной нотации (т. е. 1.2e+2). |
E |
Аргумент аналогичен спецификатору e ,
но с заглавным символом (т. е. 1.2E+2).
|
f |
Аргумент считается за число с плавающей точкой (с учётом локали). |
F |
Аргумент считается за число с плавающей точкой (без учёта локали). |
g |
Общий формат. Пусть P равно точности, если точность не равна нулю, 6, если точность не задали, или 1, если точность равна 0. Тогда, если преобразование со стилем «E» будет иметь показатель степени X: Если P > X ≥ −4, преобразование будет в стиле «f» и точность будет P - (X + 1). Иначе преобразование будет в стиле «e» и точность будет P - 1. |
G |
Аргумент аналогичен спецификатору g , но использует
спецификаторы E и f .
|
h |
Аргумент аналогичен спецификатору g , но использует
спецификатор F .
Доступен с PHP 8.0.0.
|
H |
Аргумент аналогичен спецификатору g , но использует
спецификаторы E и F .
Доступен с PHP 8.0.0.
|
o |
Аргумент рассматривается как целое число и печатается в восьмеричном представлении. |
s |
Аргумент рассматривается и печатается как строка. |
u |
Аргумент рассматривается как целое число и печатается как беззнаковое целое число. |
x |
Аргумент рассматривается как целое число и печатается в шестнадцатеричном представлении (буквы будут в нижнем регистре). |
X |
Аргумент рассматривается как целое число и печатается в шестнадцатеричном представлении (буквы будут в верхнем регистре). |
Спецификатор c
игнорирует спецификаторы преобразования дополнения и ширины.
Попытка использовать комбинацию спецификаторов строки и ширины с кодировками, которые требуют больше одного байта на символ, иногда даёт неожиданные результаты.
Функция приведёт переменные к типу, который соответствует спецификатору:
Тип | Спецификатор |
---|---|
string | s |
int |
d ,
u ,
c ,
o ,
x ,
X ,
b
|
float |
e ,
E ,
f ,
F ,
g ,
G ,
h ,
H
|
values
Функция возвращает строку, которую создала по условиям
строки форматирования format
.
Начиная с PHP 8.0.0, если количество аргументов равно нулю, выбрасывается исключение ValueError.
До PHP 8.0.0 вместо этого выдавалась ошибка уровня E_WARNING
.
Начиная с PHP 8.0.0, если [width]
меньше нуля или больше PHP_INT_MAX
,
выбрасывается исключение ValueError.
До PHP 8.0.0 вместо этого выдавалась ошибка уровня E_WARNING
.
Начиная с PHP 8.0.0, если [precision]
меньше нуля или больше PHP_INT_MAX
,
выбрасывается исключение ValueError.
До PHP 8.0.0 вместо этого выдавалась ошибка уровня E_WARNING
.
Начиная с PHP 8.0.0, если аргументов задано меньше, чем требуется, выбрасывается исключение ArgumentCountError.
До PHP 8.0.0 вместо этого выдавалась ошибка уровня E_WARNING
.
Версия | Описание |
---|---|
8.0.0 |
Функция больше не возвращает false , если возникла ошибка.
|
8.0.0 |
Выбрасывает исключение ValueError, если количество аргументов равно нулю;
раньше функция выдавала ошибку уровня E_WARNING .
|
8.0.0 |
Выбрасывает исключение ValueError, если [width]
меньше нуля или больше PHP_INT_MAX ;
раньше функция выдавала ошибку уровня E_WARNING .
|
8.0.0 |
Выбрасывает исключение ValueError, если [precision]
меньше нуля или больше PHP_INT_MAX ;
раньше функция выдавала ошибку уровня E_WARNING .
|
8.0.0 |
Выбрасывает исключение ArgumentCountError, если аргументов задано меньше, чем требуется;
раньше функция выдавала ошибку уровня E_WARNING .
|
Пример #1 Перестановка аргументов
Строка формата поддерживает нумерацию и перестановку аргументов.
<?php
$num = 5;
$location = 'tree';
$format = 'There are %d monkeys in the %s';
echo sprintf($format, $num, $location);
?>
Результат выполнения приведённого примера:
There are 5 monkeys in the tree
Теперь представим, что строку форматирования определяет отдельный файл интернационализации, в котором строку формата записали вот так:
Пример #2 Неправильный порядок аргументов
Строка формата поддерживает нумерацию и перестановку аргументов.
<?php
$num = 5;
$location = 'tree';
$format = 'The %s contains %d monkeys';
echo sprintf($format, $num, $location);
?>
Возникла проблема. Порядок заменителей в строке формата не соответствует порядку аргументов в коде. Лучше бы оставить код без изменений и только указать в строке формата, на какие аргументы ссылаются заполнители. Перепишем строку формата вот так:
Пример #3 Порядок заполнителей
<?php
$num = 5;
$location = 'tree';
$format = 'The %2$s contains %1$d monkeys';
echo sprintf($format, $num, $location);
?>
Дополнительное преимущество заключается в том, что функция разрешает повторять заполнители и не добавлять дополнительные аргументы в код.
Пример #4 Повторение заполнителя
<?php
$num = 5;
$location = 'tree';
$format = 'The %2$s contains %1$d monkeys.
That\'s a nice %2$s full of %1$d monkeys.';
echo sprintf($format, $num, $location);
?>
При перестановке аргументов спецификатор позиции
n$
указывают сразу
после знака процента %
, перед другими
спецификаторами, как в следующем примере.
Пример #5 Указание символа заполнения
<?php
echo sprintf("%'.9d\n", 123);
echo sprintf("%'.09d\n", 123);
?>
Результат выполнения приведённого примера:
......123 000000123
Пример #6 Спецификатор позиции в комбинации с другими спецификаторами
<?php
$num = 5;
$location = 'tree';
$format = 'The %2$s contains %1$04d monkeys';
echo sprintf($format, $num, $location);
?>
Результат выполнения приведённого примера:
The tree contains 0005 monkeys
Пример #7 Добавление ведущих нулей перед целочисленными значениями функцией sprintf()
<?php
$year = 2005;
$month = 5;
$day = 6;
$isodate = sprintf("%04d-%02d-%02d", $year, $month, $day);
echo $isodate, PHP_EOL;
?>
Пример #8 Форматирование денежных сумм функцией sprintf()
<?php
$money1 = 68.75;
$money2 = 54.35;
$money = $money1 + $money2;
echo $money, PHP_EOL;
$formatted = sprintf("%01.2f", $money);
echo $formatted, PHP_EOL;
?>
Результат выполнения приведённого примера:
123.1 123.10
Пример #9 Вывод чисел в научной нотации функцией sprintf()
<?php
$number = 362525200;
echo sprintf("%.3e", $number), PHP_EOL;
?>
Результат выполнения приведённого примера:
3.625e+8