sprintf

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

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

Описание

function 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