(PHP 4, PHP 5, PHP 7)
sprintf — Возвращает отформатированную строку
Возвращает строку, созданную с использованием строки формата
format
.
format
Строка формата состоит из нуля или более директив: обычные символы (за исключением %), которые просто выводятся без изменения и спецификаторы преобразования, каждый из которых требует передачи своего параметра.
Спецификаторы преобразования имеют следующий формат: %[flags][width][.precision]specifier.
Флаг | Описание |
---|---|
- | Выравнивание по левому краю в пределах заданной ширины поля; По умолчанию выравнивание происходит по правому краю. |
+ | Печатает плюс + у не отрицательных чисел; По умолчанию знак печатается только у отрицательных чисел. |
(space) | Дополняет результат пробелами. Это поведение по умолчанию. |
0 | Дополняет числа нулями (только слева). Со спецификатором s также может дополнять нулями справа. |
'(char) | Дополняет результат символом (char). |
Целое число, определяющее минимальное количество символов, которое будет напечатано.
Точка . с последующим целым числом, работающая по разному для разных спецификаторов:
Замечание: Если указана точка без последующего значения точности, то точность будет считаться за 0.
Замечание: Попытка использовать спецификатор позиции со значением больше, чем
PHP_INT_MAX
приведет к выводу предупреждения.
Спецификатор | Описание |
---|---|
% | Символ процента. Аргументы не требуются. |
b | Аргумент рассматривается как целое число и печатается в бинарном представлении. |
c | Аргумент рассматривается как целое число и печатается как символ из таблицы ASCII с соответствующим кодом. |
d | Аргумент рассматривается как целое число и печатается как целое число со знаком. |
e | Аргумент считается за число в научной нотации (т.е. 1.2e+2). Начиная с PHP 5.2.1, спецификатор точности задает количество цифр после десятичной запятой. В более ранних версиях он задавал общее количество значащих цифр (т.е. после запятой выводилось на 1 символ меньше). |
E | Аналогично спецификатору e, но использует заглавные символы (т.е. 1.2E+2). |
f | Аргумент считается за число с плавающей точкой (с учетом локали). |
F | Аргумент считается за число с плавающей точкой (без учета локали). Доступно с PHP 5.0.3. |
g |
Общий формат. Пусть P равно точности, если она не равно нулю, 6 - если точность не задана и 1, если точность задана как 0. Тогда, если преобразование со стилем "E" будет иметь показатель степени X: Если P > X ≥ −4, преобразование будет в стиле "f" и точность будет P − (X + 1). В обратном случае, преобразование будет в стиле "e" и точность будет P − 1. |
G | Аналогично спецификатору g, но использует E и F. |
o | Аргумент рассматривается как целое число и печатается в восмеричном представлении. |
s | Аргумент рассматривается и печатается как строка. |
u | Аргумент рассматривается как целое число и печатается как беззаковое целое число. |
x | Аргумент рассматривается как целое число и печатается в шестнадцатеричном представлении (буквы будут в нижнем регистре). |
X | Аргумент рассматривается как целое число и печатается в шестнадцатеричном представлении (буквы будут в верхнем регистре). |
Спецификатор c игнорирует значения ширины и дополнения
Попытка использовать спецификаторы с указанием ширины для строки в многобайтовой кодировке может привести к неожиданным результатам.
Переменные будут приведены к подходящему для спецификатора типу:
Тип | Спецификатор |
---|---|
string | s |
integer | d, u, c, o, x, X, b |
double | g, G, e, E, f, F |
...
Возвращает строку, отформатированную в соответствии с форматом
format
, или FALSE
в случае возникновения ошибки.
Пример #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