sprintf

(PHP 4, PHP 5, PHP 7, PHP 8)

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

Описание

sprintf(string $format, mixed ...$values): string

Функция форматирует строку по условиям, которые передали в параметр format.

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

format

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

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

Argnum

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

Флаги

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

Ширина

Либо целое число, которое указывает, сколько символов (минимум) должно получиться в результате преобразования, либо *. Если указали символ *, ширина задаётся как дополнительное целое значение, которое предшествует значению, которое отформатировал спецификатор.

Точность

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

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

Замечание: Если указали точку без последующего значения точности, точность будет считаться за 0. Если указали символ *, точность задаётся как дополнительное целое значение, которое предшествует значению, которое отформатировал спецификатор.

Спецификаторы
Спецификатор Описание
% Символ процента. Аргументы не требуются.
b Аргумент рассматривается как целое число и печатается в бинарном представлении.
c Аргумент рассматривается как целое число и печатается как символ из таблицы ASCII с соответствующим кодом.
d Аргумент рассматривается как целое число и печатается как целое число со знаком.
e Аргумент считается за число в научной нотации (т. е. 1.2e+2).
E Аргумент аналогичен спецификатору e, но с заглавным символом (т. е. 1.2E+2).
f Аргумент считается за число с плавающей точкой (с учётом локали).
F Аргумент считается за число с плавающей точкой (без учёта локали).
g

Общий формат.

Пусть P равно точности, если точность не равна нулю, 6, если точность не задали, или 1, если точность равна 0. Тогда, если преобразование со стилем «E» будет иметь показатель степени X:

Если P > X ≥ −4, преобразование будет в стиле «f» и точность будет P - (X + 1). Иначе преобразование будет в стиле «e» и точность будет P - 1.

G Аргумент аналогичен спецификатору g, но использует спецификаторы E и f.
h Аргумент аналогичен спецификатору g, но использует спецификатор F. Доступен с PHP 8.0.0.
H Аргумент аналогичен спецификатору g, но использует спецификаторы E и F. Доступен с PHP 8.0.0.
o Аргумент рассматривается как целое число и печатается в восьмеричном представлении.
s Аргумент рассматривается и печатается как строка.
u Аргумент рассматривается как целое число и печатается как беззнаковое целое число.
x Аргумент рассматривается как целое число и печатается в шестнадцатеричном представлении (буквы будут в нижнем регистре).
X Аргумент рассматривается как целое число и печатается в шестнадцатеричном представлении (буквы будут в верхнем регистре).

Внимание

Спецификатор c игнорирует спецификаторы преобразования дополнения и ширины.

Внимание

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

Функция приведёт переменные к типу, который соответствует спецификатору:

Обработка типов
Тип Спецификатор
string s
int d, u, c, o, x, X, b
float e, E, f, F, g, G, h, H

values

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

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

Ошибки

Начиная с PHP 8.0.0, если количество аргументов равно нулю, выбрасывается исключение ValueError. До PHP 8.0.0 вместо этого выдавалась ошибка уровня E_WARNING.

Начиная с PHP 8.0.0, если [width] меньше нуля или больше PHP_INT_MAX, выбрасывается исключение ValueError. До PHP 8.0.0 вместо этого выдавалась ошибка уровня E_WARNING.

Начиная с PHP 8.0.0, если [precision] меньше нуля или больше PHP_INT_MAX, выбрасывается исключение ValueError. До PHP 8.0.0 вместо этого выдавалась ошибка уровня E_WARNING.

Начиная с PHP 8.0.0, если аргументов задано меньше, чем требуется, выбрасывается исключение ArgumentCountError. До PHP 8.0.0 вместо этого выдавалась ошибка уровня E_WARNING.

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

Версия Описание
8.0.0 Функция больше не возвращает false, если возникла ошибка.
8.0.0 Выбрасывает исключение ValueError, если количество аргументов равно нулю; раньше функция выдавала ошибку уровня E_WARNING.
8.0.0 Выбрасывает исключение ValueError, если [width] меньше нуля или больше PHP_INT_MAX; раньше функция выдавала ошибку уровня E_WARNING.
8.0.0 Выбрасывает исключение ValueError, если [precision] меньше нуля или больше PHP_INT_MAX; раньше функция выдавала ошибку уровня E_WARNING.
8.0.0 Выбрасывает исключение ArgumentCountError, если аргументов задано меньше, чем требуется; раньше функция выдавала ошибку уровня E_WARNING.

Примеры

Пример #1 Перестановка аргументов

Строка формата поддерживает нумерацию и перестановку аргументов.

<?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

Теперь представим, что строку форматирования определяет отдельный файл интернационализации, в котором строку формата записали вот так:

Пример #2 Неправильный порядок аргументов

Строка формата поддерживает нумерацию и перестановку аргументов.

<?php

$num
= 5;
$location = 'tree';

$format = 'The %s contains %d monkeys';
echo
sprintf($format, $num, $location);

?>

Возникла проблема. Порядок заменителей в строке формата не соответствует порядку аргументов в коде. Лучше бы оставить код без изменений и только указать в строке формата, на какие аргументы ссылаются заполнители. Перепишем строку формата вот так:

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

<?php

$num
= 5;
$location = 'tree';

$format = 'The %2$s contains %1$d monkeys';
echo
sprintf($format, $num, $location);

?>

Дополнительное преимущество заключается в том, что функция разрешает повторять заполнители и не добавлять дополнительные аргументы в код.

Пример #4 Повторение заполнителя

<?php

$num
= 5;
$location = 'tree';

$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$ указывают сразу после знака процента %, перед другими спецификаторами, как в следующем примере.

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

<?php

echo sprintf("%'.9d\n", 123);
echo
sprintf("%'.09d\n", 123);

?>

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

......123
000000123

Пример #6 Спецификатор позиции в комбинации с другими спецификаторами

<?php

$num
= 5;
$location = 'tree';

$format = 'The %2$s contains %1$04d monkeys';
echo
sprintf($format, $num, $location);

?>

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

The tree contains 0005 monkeys

Пример #7 Добавление ведущих нулей перед целочисленными значениями функцией sprintf()

<?php

$year
= 2005;
$month = 5;
$day = 6;

$isodate = sprintf("%04d-%02d-%02d", $year, $month, $day);
echo
$isodate, PHP_EOL;

?>

Пример #8 Форматирование денежных сумм функцией sprintf()

<?php

$money1
= 68.75;
$money2 = 54.35;
$money = $money1 + $money2;
echo
$money, PHP_EOL;

$formatted = sprintf("%01.2f", $money);
echo
$formatted, PHP_EOL;

?>

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

123.1
123.10

Пример #9 Вывод чисел в научной нотации функцией sprintf()

<?php

$number
= 362525200;

echo
sprintf("%.3e", $number), PHP_EOL;

?>

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

3.625e+8

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

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