sprintf

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

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

    Описание

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

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

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

    format

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

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

    Argnum

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

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

    Ширина

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

    Точность

    Точка ., с последующим целым числом, либо *, значение которого зависит от спецификатора:

    • Для спецификаторов 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 игнорирует значения ширины и дополнения

    Внимание

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

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

    Обработка типов
    ТипСпецификатор
    strings
    intd, u, c, o, x, X, b
    floate, 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 Argument swapping

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

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

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

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

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

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

    Дополнительным приятным моментом является то, что мы можем использовать один параметр для нескольких подстановок.

    <?php
    $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$ должен стоять сразу же за символом процента (%), до любого другого спецификатора, как показано ниже.

    Пример #2 Использование символа заполнения

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

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

    ......123 000000123

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

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

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

    The tree contains 0005 monkeys

    Пример #4 sprintf(): целое с лидирующими нулями

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

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

    <?php
    $money1     = 68.75;
    $money2 = 54.35;
    $money = $money1 + $money2;
    echo     $money;
    echo     "\n";
    $formatted = sprintf("%01.2f", $money);
    echo     $formatted;
    ?>

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

    123.1 123.10

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

    <?php
    $number     = 362525200;

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

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

    3.625e+8

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

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