sprintf

(PHP 4, PHP 5, PHP 7)

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

Описание

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

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

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

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().

Внимание

The c type specifier ignores padding and width

args

...

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

Возвращает строку, отформатированную в соответствии со строкой format, или FALSE в случае возникновения ошибки.

Примеры

Пример #7 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'

Пример #8 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]

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

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

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

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

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

<?php
$number 
362525200;

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

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

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