(PHP 5, PHP 7, PHP 8)
fprintf — Записывает отформатированную строку в поток
Записывает строку, созданную с использованием строки формата format
, в поток, дескриптор которого передаётся в параметре stream
.
stream
Ресурс (resource) указателя файловой системы, который часто создают функцией fopen().
format
Строка формата состоит из нуля или более директив: обычные символы (за исключением %
), которые просто выводятся без изменения, и спецификаторы преобразования, каждый из которых требует передачи своего параметра.
Спецификаторы преобразования имеют следующий формат: %[argnum$][flags][width][.precision]specifier
.
Целое число, за которым следует знак доллара $
, чтобы указать, какой числовой аргумент обрабатывать при преобразовании.
Флаг | Описание |
---|---|
- | Выравнивание по левому краю в пределах заданной ширины поля; По умолчанию выравнивание происходит по правому краю. |
+ | Печатает плюс + у не отрицательных чисел; По умолчанию знак печатается только у отрицательных чисел. |
(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
игнорирует значения ширины и дополнения
Попытка использовать спецификаторы с указанием ширины для строки в многобайтовой кодировке может привести к неожиданным результатам.
Переменные будут приведены к подходящему для спецификатора типу:
Тип | Спецификатор |
---|---|
string | s |
int | d , u , c , o , x , X , b |
float | e , 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 fprintf(): заполнение нулями
<?php
if (!($fp = fopen('date.txt', 'w'))) {
return;
}
fprintf($fp, "%04d-%02d-%02d", $year, $month, $day);
// запишет форматированную ISO-дату в файл date.txt
?>
Пример #2 fprintf(): форматирование денежных величин
<?php
if (!($fp = fopen('currency.txt', 'w'))) {
return;
}
$money1 = 68.75;
$money2 = 54.35;
$money = $money1 + $money2;
// echo $money выведет "123.1";
$len = fprintf($fp, '%01.2f', $money);
// строка "123.10" записана в файл currency.txt
echo "записано $len байт в файл currency.txt";
// используйте возвращаемое из fprintf значение для определения количества записанных байт
?>