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

Описание

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

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

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

format

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

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

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

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

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


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

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

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

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


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

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

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


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

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

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


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

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

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


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

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

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

args

...

Возвращаемые значения

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

Список изменений

Версия	Описание
4.0.6	Добавлена поддержка нумерации/изменения порядка аргументов

Примеры

Пример #6 sprintf(): заполнение нулями


<?php
$n =  43951789;
$u = -43951789;
$c = 65; // ASCII 65 is 'A'

// заметьте, двойной %% выводится как одинарный '%'
printf("%%b = '%b'\n", $n); // двоичное представление
printf("%%c = '%c'\n", $c); // выводит символ ascii, аналогично функции chr()
printf("%%d = '%d'\n", $n); // обычное целое число
printf("%%e = '%e'\n", $n); // научная нотация
printf("%%u = '%u'\n", $n); // беззнаковое целое представление положительного числа
printf("%%u = '%u'\n", $u); // беззнаковое целое представление отрицательного числа
printf("%%f = '%f'\n", $n); // представление числа с плавающей точкой
printf("%%o = '%o'\n", $n); // восьмеричное представление
printf("%%s = '%s'\n", $n); // строка
printf("%%x = '%x'\n", $n); // шестнадцатеричное представление (нижний регистр)
printf("%%X = '%X'\n", $n); // шестнадцатеричное представление (верхний регистр)

printf("%%+d = '%+d'\n", $n); // описатель знака с положительным целым числом
printf("%%+d = '%+d'\n", $u); // описатель знака с отрицательным целым числом
?>

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

%b = '10100111101010011010101101'
%c = 'A'
%d = '43951789'
%e = '4.39518e+7'
%u = '43951789'
%u = '4251015507'
%f = '43951789.000000'
%o = '247523255'
%s = '43951789'
%x = '29ea6ad'
%X = '29EA6AD'
%+d = '+43951789'
%+d = '-43951789'

Пример #7 printf(): описатели строк


<?php
$s = 'monkey';
$t = 'many monkeys';

printf("[%s]\n",      $s); // обычный вывод строки
printf("[%10s]\n",    $s); // выравнивание вправо с пробелами
printf("[%-10s]\n",   $s); // выравнивание влево с пробелами
printf("[%010s]\n",   $s); // дополнение нулями также работает со строками
printf("[%'#10s]\n",  $s); // использование собственного дополняющего символа '#'
printf("[%10.10s]\n", $t); // выравнивание влево с обрезкой в 10 символов
?>

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

[monkey]
[    monkey]
[monkey    ]
[0000monkey]
[####monkey]
[many monke]

Пример #8 sprintf(): целые числа, дополненные нулями


<?php
$isodate = sprintf("%04d-%02d-%02d", $year, $month, $day);
?>

Пример #9 sprintf(): форматирование денежных величин


<?php
$money1 = 68.75;
$money2 = 54.35;
$money = $money1 + $money2;
// echo $money выведет "123.1";
$formatted = sprintf("%01.2f", $money);
// echo $formatted выведет "123.10"
?>

Пример #10 sprintf(): научная нотация


<?php
$number = 362525200;

echo sprintf("%.3e", $number); // выведет 3.625e+8
?>

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

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