sprintf

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

format

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

Каждый описатель преобразований состоит из знака процента (%), за которым следует один или более дополнительных элементов (в том порядке, в котором они здесь перечислены):

1. Необязательный описатель знака, указывающий как знак (- или +) будет применен к числу. По умолчанию используется только знак минус, если число отрицательное. Этот описатель заставляет положительные числа также отображать знак плюс.
2. Необязательный описатель заполнения, который определяет, какой символ будет использоваться для дополнения результата до необходимой длины. Это может быть пробел или 0. По умолчанию используется пробел. Альтернативный символ может быть указан с помощью одиночной кавычки (‘). См. примеры ниже.
3. Необязательный описатель выравнивания, определяющий выравнивание влево или вправо. По умолчанию выравнивается вправо, — используется для выравнивания влево.
4. Необязательное число, описатель ширины, определяющий минимальное число символов, которое будет содержать результат этого преобразования.
5. Необязательный описатель точности, указанный в виде точки (.), после которой следует необязательная строка из десятичных чисел, определяющая, сколько десятичных разрядов отображать для чисел с плавающей точкой. При использовании со строками этот описатель выступает в роли обрезающей точки, устанавливающей максимальный лимит символов. Также между точкой и цифрой можно указать символ, используемый при дополнении числа.

6. Описатель типа, определяющий, как трактовать тип данных аргумента. Допустимые типы:

   • % — символ процента. Аргумент не используется.
   • b — аргумент трактуется как целое и выводится в виде двоичного числа.
   • c — аргумент трактуется как целое и выводится в виде символа с соответствующим кодом ASCII.
   • d — аргумент трактуется как целое и выводится в виде десятичного числа со знаком.
   • e — аргумент трактуется как число в научной нотации (например, 1.2e+2). Описатель точности указывает на количество знаков после запятой, начиная с версии PHP 5.2.1. В более ранних версиях он обозначал количество значащих цифр (на один знак меньше).
   • E — аналогично %e, но использует заглавную букву (например, 1.2E+2).
   • f — аргумент трактуется как число с плавающей точкой и также выводится в зависимости от локали.
   • F — аргумент трактуется как число с плавающей точкой и также выводится, но без зависимости от локали. Доступно, начиная с версии PHP 5.0.3.
   • g — выбирает самую краткую запись из %e и %f.
   • G — выбирает самую краткую запись из %E и %f.
   • o — аргумент трактуется как целое и выводится в виде восьмеричного числа.
   • s — аргумент трактуется как строка.
   • u — аргумент трактуется как целое и выводится в виде десятичного числа без знака.
   • x — аргумент трактуется как целое и выводится в виде шестнадцатеричного числа (в нижнем регистре).
   • X — аргумент трактуется как целое и выводится в виде шестнадцатеричного числа (в верхнем регистре).

Переменные будут преобразованы в соответвующий тип для спецификатора:

Обработка типов

Тип	Спецификатор
string	s
integer	d, u, c, o, x, X, b
double	g, G, e, E, f, F

Внимание

Попытка использовать комбинацию строк и спецификаторов ширины с кодировками, которые требуют более одного байта на символ, может привести к неожиданным результатам.

В строке формата поддерживается нумерация и изменение порядка параметров. Например:

Пример #1 Изменение порядка параметров

<?php
$num = 5;
$location = 'дереве';

$format = '%d обезьян сидят на %s';
echo sprintf($format, $num, $location);
?>

 

Этот код выведет «5 обезьян сидят на дереве». Теперь представьте, что строка формата содержится в отдельном файле, который потом будет переведен на другой язык, и мы переписываем ее в таком виде:

Пример #2 Изменение порядка параметров

<?php
$format = 'На %s сидят %d обезьян';
echo sprintf($format, $num, $location);
?>

 

Появляется проблема: порядок описателей преобразования не соответствует порядку аргументов. Мы не хотим менять код, и нам нужно указать, какому аргументу соответствует тот или иной описатель преобразования.

Пример #3 Изменение порядка параметров

<?php
$format = 'На %2$s сидят %1$d обезьян';
echo sprintf($format, $num, $location);
?>

 

Нумерация аргументов имеет еще одно применение: она позволяет вывести один и тот же аргумент несколько раз без передачи функции дополнительных параметров.

Пример #4 Изменение порядка параметров

<?php
$format = 'На %2$s сидят %1$d обезьян.
           Как здорово, когда на %2$s сидят %1$d обезьян.';
echo sprintf($format, $num, $location);
?>

 

При изменении порядка параметров описатель позиции n$ должен идти сразу за знаком процента (%) прежде всех остальных описателей, как показано в примере ниже.

Пример #5 Указание дополняющего символа

<?php
echo sprintf("%'.9d\n", 123);
echo sprintf("%'.09d\n", 123);
?>
Результат выполнения данного примера:

......123
000000123

 

Пример #6 Использование описателя позиции и совместно с другими описателями

<?php
$format = 'На %2$s сидят %1$04d обезьян';
echo sprintf($format, $num, $location);
?>

 

Результат выполнения данного примера:

На дереве сидят 0005 обезьян

Замечание:

Попытка использовать спецификатор позиции, больший чем PHP_INT_MAX, приведет к генерации предупреждения функцией sprintf().

Внимание

Описатель типа c игнорирует дополнение строки и ее ширину

args

...