(PHP 4, PHP 5, PHP 7, PHP 8)
sprintf — Возвращает отформатированную строку
Возвращает строку, созданную с использованием строки формата
format.
format
Строка формата состоит из нуля или более директив:
обычные символы (за исключением %), которые
просто выводятся без изменения и
спецификаторы преобразования, каждый из которых
требует передачи своего параметра.
Спецификаторы преобразования имеют следующий формат:
%[argnum$][flags][width][.precision]specifier.
Целое число, за которым следует знак доллара $,
чтобы указать, какой числовой аргумент обрабатывать при преобразовании.
| Флаг | Описание |
|---|---|
- |
Выравнивание по левому краю в пределах заданной ширины поля; По умолчанию выравнивание происходит по правому краю. |
+ |
Печатает плюс + у не отрицательных чисел;
По умолчанию знак печатается только у отрицательных чисел.
|
(space) |
Дополняет результат пробелами. Это поведение по умолчанию. |
0 |
Дополняет числа нулями (только слева).
Со спецификатором s также может
дополнять нулями справа.
|
'(char) |
Дополняет результат символом (char). |
Либо целое число, указывающее, сколько символов (минимум) должно получиться в результате преобразования,
либо *.
Если используется *, то ширина предоставляется как дополнительное целое значение,
предшествующее значению, отформатированному спецификатором.
Точка ., с последующим целым числом,
либо *, значение которого зависит от спецификатора:
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 Argument swapping
Строка формата поддерживает нумерацию и перемешивание аргументов.
<?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
Теперь представим, что строка форматирования задаётся в стороннем файле. Это обычная практика при необходимости поддержки нескольких языков. Представим, что строка была переписана таким образом:
<?php
$format = 'The %s contains %d monkeys';
echo sprintf($format, $num, $location);
?>Упс! У нас проблема - порядок спецификаторов перестал соответствовать порядку аргументов. Так как нам очень не хочется менять код каждый раз, когда меняется формат строки, то мы можем использовать нумерованные аргументы:
<?php
$format = 'The %2$s contains %1$d monkeys';
echo sprintf($format, $num, $location);
?>Дополнительным приятным моментом является то, что мы можем использовать один параметр для нескольких подстановок.
<?php
$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$ должен
стоять сразу же за символом процента (%), до любого
другого спецификатора, как показано ниже.
Пример #2 Использование символа заполнения
<?php
echo sprintf("%'.9d\n", 123);
echo sprintf("%'.09d\n", 123);
?>Результат выполнения данного примера:
......123 000000123
Пример #3 Спецификатор позиции в комбинации с другими спецификаторами
<?php
$format = 'The %2$s contains %1$04d monkeys';
echo sprintf($format, $num, $location);
?>Результат выполнения данного примера:
The tree contains 0005 monkeys
Пример #4 sprintf(): целое с лидирующими нулями
<?php
$isodate = sprintf("%04d-%02d-%02d", $year, $month, $day);
?>Пример #5 sprintf(): форматирование денежных единиц
<?php
$money1 = 68.75;
$money2 = 54.35;
$money = $money1 + $money2;
echo $money;
echo "\n";
$formatted = sprintf("%01.2f", $money);
echo $formatted;
?>Результат выполнения данного примера:
123.1 123.10
Пример #6 sprintf(): научная нотация
<?php
$number = 362525200;
echo sprintf("%.3e", $number);
?>Результат выполнения данного примера:
3.625e+8