sprintf

(PHP 4, PHP 5, PHP 7)

sprintfВозвращает отформатированную строку

Описание

sprintf ( string $format [, mixed $... ] ) : string

Возвращает строку, созданную с использованием строки формата format.

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

format

Строка формата состоит из нуля или более директив: обычные символы (за исключением %), которые просто выводятся без изменения и спецификаторы преобразования, каждый из которых требует передачи своего параметра.

Спецификаторы преобразования имеют следующий формат: %[argnum$][flags][width][.precision]specifier.

Argnum

Целое число, за которым следует знак доллара $, чтобы указать, какой числовой аргумент обрабатывать при преобразовании.

Флаги
Флаг Описание
- Выравнивание по левому краю в пределах заданной ширины поля; По умолчанию выравнивание происходит по правому краю.
+ Печатает плюс + у не отрицательных чисел; По умолчанию знак печатается только у отрицательных чисел.
(space) Дополняет результат пробелами. Это поведение по умолчанию.
0 Дополняет числа нулями (только слева). Со спецификатором s также может дополнять нулями справа.
'(char) Дополняет результат символом (char).

Ширина

Целое число, определяющее минимальное количество символов, которое будет напечатано.

Точность

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

  • Для спецификаторов e, E, f и F: задает количество цифр после десятичной запятой (по умолчанию 6).
  • Для спецификаторов g и G: задает максимальное значение печатаемых значащих цифр.
  • Для спецификатора s: задает ограничение максимального количества символов в строке, которые будут выведены.

Замечание: Если указана точка без последующего значения точности, то точность будет считаться за 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

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

  • printf() - Выводит отформатированную строку
  • fprintf() - Записывает отформатированную строку в поток
  • vprintf() - Выводит отформатированную строку
  • vsprintf() - Возвращает отформатированную строку
  • vfprintf() - Записывает отформатированную строку в поток
  • sscanf() - Разбирает строку в соответствии с заданным форматом
  • fscanf() - Обрабатывает данные из файла в соответствии с форматом
  • number_format() - Форматирует число с разделением групп
  • date() - Форматирует вывод системной даты/времени