PHP 日本研討會 2024

fprintf

(PHP 5, PHP 7, PHP 8)

fprintf將格式化的字串寫入串流

描述

fprintf(resource $stream, string $format, mixed ...$values): int

根據 format 產生的字串寫入由 stream 指定的串流資源。

參數

stream

一個檔案系統指標 resource,通常使用 fopen() 建立。

format

格式字串由零或多個指令組成:直接複製到結果的普通字元(不包括 %)和轉換規格,每個規格都會導致提取其自身的參數。

轉換規格遵循此原型:%[argnum$][flags][width][.precision]specifier

Argnum

一個整數,後面跟著一個錢字號 $,用於指定要轉換的參數編號。

Flags
Flag 描述
- 在給定的欄位寬度內靠左對齊;預設為靠右對齊
+ 在正數前加上加號 +;預設僅在負數前加上負號。
(空格) 用空格填充結果。這是預設值。
0 僅用零左填充數字。使用 s 指示符時,也可以用零右填充。
'(字元) 用字元 (char) 填充結果。

Width

可以是表示此轉換應產生的字元數(最小值)的整數,也可以是 *。如果使用 *,則寬度將作為一個額外的整數值提供,該值位於由指示符格式化的值之前。

Precision

一個句點 .,可選擇後接一個整數或 *,其含義取決於指示符

  • 對於 eEfF 指示符:這是小數點後要列印的位數(預設情況下,為 6)。
  • 對於 gGhH 指示符:這是要列印的最大有效位數。
  • 對於 s 指示符:它充當截止點,為字串設定最大字元數限制。

注意 如果指定句點但未明確指定精確度,則假定為 0。如果使用 *,則精確度將作為一個額外的整數值提供,該值位於由指示符格式化的值之前。

Specifiers
Specifier 描述
% 一個文字百分比字元。不需要參數。
b 該參數被視為整數,並以二進制數表示。
c 該參數被視為整數,並以該 ASCII 的字元表示。
d 該參數被視為整數,並以(帶正負號的)十進制數表示。
e 該參數被視為科學計數法(例如 1.2e+2)。
E e 指示符類似,但使用大寫字母(例如 1.2E+2)。
f 該參數被視為浮點數,並以浮點數表示(區域設定感知)。
F 該參數被視為浮點數,並以浮點數表示(非區域設定感知)。
g

一般格式。

如果精度為非零,則令 P 等於精度;如果省略精度,則令 P 等於 6;如果精度為零,則令 P 等於 1。然後,如果使用 E 樣式的轉換會使指數為 X

如果 P > X ≥ −4,則轉換使用 f 樣式,精度為 P − (X + 1)。否則,轉換使用 e 樣式,精度為 P − 1。

G g 指示符類似,但使用 Ef
h g 指示符類似,但使用 F。PHP 8.0.0 起可用。
H g 指示符類似,但使用 EF。PHP 8.0.0 起可用。
o 該參數被視為整數,並以八進制數表示。
s 該參數被視為字串並呈現為字串。
u 該參數被視為整數,並以無符號十進制數表示。
x 該參數被視為整數,並以十六進制數表示(使用小寫字母)。
X 該參數被視為整數,並以十六進制數表示(使用大寫字母)。

警告

c 型別指示符會忽略填充和寬度。

警告

嘗試將字串和寬度指示符與每個字元需要多個位元組的字元集組合使用可能會產生意外的結果。

變數將被強制轉換為適合指示符的型別

型別處理
型別 Specifiers
字串 s
整數 ducoxXb
浮點數 eEfFgGhH

回傳值

回傳寫入的字串長度。

錯誤/例外

從 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 之前,會回傳 false 並改為發出 E_WARNING

變更記錄

版本 描述
8.0.0 此函式在失敗時不再回傳 false
8.0.0 如果參數數量為零,則擲回 ValueError;先前此函式改為發出 E_WARNING
8.0.0 如果 [width] 小於零或大於 PHP_INT_MAX,則擲回 ValueError;先前此函式改為發出 E_WARNING
8.0.0 如果 [precision] 小於零或大於 PHP_INT_MAX,則擲回 ValueError;先前此函式改為發出 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 "wrote $len bytes to currency.txt";
// 使用 fprintf 的返回值來確定我們寫入了多少位元組
?>

參見

新增註解

使用者提供的註解 1 個註解

1
Julien MOREAU
3 年前
如果您使用命令列介面(CLI SAPI),您可能會對以下網址描述的 3 個標準輸入/輸出串流(STDIN、STDOUT & STDERR)感興趣: https://php.dev.org.tw/manual/en/features.commandline.io-streams.php
To Top