printf

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

    printf — Выводит отформатированную строку

    Описание

    printf(string$format, mixed...$values): int

    Выводит строку, отформатированную в соответствии с аргументом 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

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

    Возвращает длину выводимой строки.

    Ошибки

    Начиная с 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 printf(): различные примеры

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

    Пример #2 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("[%'#*s]\n", 10, $s); // укажите ширину отступа в качестве дополнительного аргумента
    printf("[%10.9s]\n", $t); // выравнивание вправо с отсечкой в 9 символов
    printf("[%-10.9s]\n", $t); // выравнивание влево с отсечкой в 9 символов
    ?>

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

    [monkey] [ monkey] [monkey ] [0000monkey] [####monkey] [####monkey] [ many monk] [many monk ]

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

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