std::printf, std::fprintf, std::sprintf, std::snprintf

 

C++

編譯器支援

自由（freestanding）與宿主（hosted）

語言

標準庫

標準庫標頭檔案

具名要求

特性測試宏 (C++20)

語言支援庫

概念庫 (C++20)

診斷庫

記憶體管理庫

超程式設計庫 (C++11)

通用工具庫

容器庫

迭代器庫

範圍庫 (C++20)

演算法庫

字串庫

文字處理庫

數值庫

日期和時間庫

輸入/輸出庫

檔案系統庫 (C++17)

併發支援庫 (C++11)

執行控制庫 (C++26)

技術規範

符號索引

外部庫

 

輸入/輸出庫

I/O 操縱器

列印函式 (C++23)

C 風格 I/O

緩衝區

basic_streambuf

basic_filebuf

basic_stringbuf

basic_spanbuf (C++23)

strstreambuf (C++98/26*)

basic_syncbuf (C++20)

流

抽象

ios_base

basic_ios

basic_istream

basic_ostream

basic_iostream

檔案 I/O

basic_ifstream

basic_ofstream

basic_fstream

字串 I/O

basic_istringstream

basic_ostringstream

basic_stringstream

陣列 I/O

basic_ispanstream (C++23)

basic_ospanstream (C++23)

basic_spanstream (C++23)

istrstream (C++98/26*)

ostrstream (C++98/26*)

strstream (C++98/26*)

同步輸出

basic_osyncstream (C++20)

型別

streamoff

streamsize

fpos

錯誤類別介面

iostream_category (C++11)

io_errc (C++11)

 

C 風格 I/O

型別和物件
FILE fpos_t	stdinstdoutstderr
函式
檔案訪問 fopen freopen fclose fflush fwide setbuf setvbuf 直接輸入/輸出 fread fwrite 非格式化輸入/輸出 fgetcgetc fgets fputcputc fputs getchar gets (直到 C++14) putchar puts ungetc fgetwcgetwc fgetws fputwcputwc fputws getwchar putwchar ungetwc 格式化輸入 scanffscanfsscanf vscanfvfscanfvsscanf (C++11起)(C++11起)(C++11起)     wscanffwscanfswscanf vwscanfvfwscanfvswscanf (C++11起)(C++11起)(C++11起)	格式化輸出 printffprintfsprintfsnprintf (C++11起) vprintfvfprintfvsprintfvsnprintf (C++11起)     wprintffwprintfswprintf vwprintfvfwprintfvswprintf 檔案定位 ftell fgetpos fseek fsetpos rewind 錯誤處理 clearerr feof ferror perror 檔案操作 remove rename tmpfile tmpnam

 

定義於標頭檔案 <cstdio>
int printf( const char* format, ... );	(1)
int fprintf( std::FILE* stream, const char* format, ... );	(2)
int sprintf( char* buffer, const char* format, ... );	(3)
int snprintf( char* buffer, std::size_t buf_size, const char* format, ... );	(4)	(C++11 起)

從給定位置載入資料，將其轉換為字元字串等效項，並將結果寫入各種目標。

1) 將結果寫入 stdout。

2) 將結果寫入檔案流 stream。

3) 將結果寫入字元字串 buffer。

4) 將結果寫入字元字串 buffer。最多寫入 buf_size - 1 個字元。除非 buf_size 為零，否則結果字元字串將以空字元終止。如果 buf_size 為零，則不寫入任何內容，buffer 可以是空指標，但是仍會計算並返回返回值（不包括空終止符的寫入位元組數）。

如果對 sprintf 或 snprintf 的呼叫導致重疊物件之間進行復制，則行為是未定義的（例如 sprintf(buf, "%s text", buf);）。

引數

stream	-	要寫入的輸出檔案流
buffer	-	要寫入的字元字串指標
buf_size	-	最多可以寫入 buf_size - 1 個字元，再加上空終止符
format	-	指向以 null 結尾的多位元組字串的指標，指定如何解釋資料
...	-	指定要列印的資料的引數。如果在預設引數提升後，任何引數的型別與相應轉換說明符所期望的型別（期望型別是提升型別或提升型別的相容型別）不符，或者引數少於 format 所要求的數量，則行為未定義。如果引數多於 format 所要求的數量，則多餘的引數會被評估並忽略

format 字串由普通位元組字元（除了 %）組成，它們被不變地複製到輸出流中，以及轉換說明符。每個轉換說明符具有以下格式：

• 前導 % 字元。

• (可選) 一個或多個修改轉換行為的標誌

• -: 轉換結果在欄位內左對齊（預設情況下右對齊）。
• +: 有符號轉換的符號總是前置在轉換結果之前（預設情況下，結果只有在為負時才前置減號）。
• 空格: 如果有符號轉換的結果不以符號字元開頭，或者為空，則在結果前置空格。如果存在 + 標誌，則忽略此標誌。
• #: 執行轉換的替代形式。具體效果請參見下表，否則行為未定義。
• 0: 對於整數和浮點數轉換，使用前導零填充欄位，而不是空格字元。對於整數，如果明確指定了精度，則忽略此標誌。對於使用此標誌的其他轉換，會導致未定義行為。如果存在 - 標誌，則忽略此標誌。

• (可選) 整數值或 *，指定最小欄位寬度。如果需要，結果會用空格字元填充（預設），右對齊時在左側填充，左對齊時在右側填充。當使用 * 時，寬度由一個額外的 int 型別引數指定，該引數出現在待轉換引數之前，如果提供了精度引數，則出現在精度引數之前。如果該引數的值為負，則表示指定了 - 標誌和正欄位寬度（注意：這是最小寬度：值永遠不會被截斷）。

• (可選) . 後跟整數或 *，或兩者皆無，指定轉換的精度。當使用 * 時，精度由一個額外的 int 型別引數指定，該引數出現在待轉換引數之前，但在提供最小欄位寬度引數之後（如果已提供）。如果此引數的值為負，則忽略它。如果既未使用數字也未使用 *，則精度視為零。有關精度的具體效果，請參見下表。

• (可選) 長度修飾符，指定引數的大小（與轉換格式說明符結合使用，指定相應引數的型別）。

• 轉換格式說明符。

以下格式說明符可用：

轉換 說明符	解釋	預期 引數型別
長度修飾符→		hh	h	無	l	ll	j	z	t	L
僅自 C++11 起可用→		是				是	是	是	是
%	寫入字面量 %。完整的轉換說明符必須是 %%。	不適用	不適用	不適用	不適用	不適用	不適用	不適用	不適用	不適用
c	寫入單個字元。 引數首先轉換為 unsigned char。 如果使用 l 修飾符，則引數首先轉換為字元字串，如同透過 %ls 使用 wchar_t[2] 引數進行轉換。	不適用	不適用	int	std::wint_t	不適用	不適用	不適用	不適用	不適用
s	寫入字元字串。 引數必須是指向字元陣列初始元素的指標。 精度 指定要寫入的最大位元組數。如果未指定精度，則寫入每個位元組直到（但不包括）第一個空終止符。 如果使用 l 說明符，則引數必須是指向 wchar_t 陣列初始元素的指標，該陣列將轉換為 char 陣列，如同透過呼叫 std::wcrtomb 並使用零初始化的轉換狀態。	不適用	不適用	char*	wchar_t*	不適用	不適用	不適用	不適用	不適用
d i	將有符號整數轉換為十進位制表示 [-]dddd。 精度 指定要出現的最小位數。預設精度為 1。 如果轉換值和精度都為 ​0​，則轉換結果為空字元。 對於 z 修飾符，期望的引數型別是 std::size_t 的有符號版本。	signed char	short	int	long	long long	std::intmax_t	※	std::ptrdiff_t	不適用
o	將無符號整數轉換為八進位制表示 oooo。 精度 指定要出現的最小位數。預設精度為 1。 如果轉換值和精度都為 ​0​，則轉換結果為空字元。 在替代實現中，如果需要，精度會增加，以寫入一個前導零。在這種情況下，如果轉換值和精度都為 ​0​，則寫入單個 ​0​。	unsigned char	unsigned short	unsigned int	unsigned long	unsigned long long	std::uintmax_t	std::size_t	std::ptrdiff_t 的無符號版本	不適用
x X	將無符號整數轉換為十六進位制表示 hhhh。 對於 x 轉換，使用字母 abcdef。 對於 X 轉換，使用字母 ABCDEF。 精度 指定要出現的最小位數。預設精度為 1。 如果轉換值和精度都為 ​0​，則轉換結果為空字元。 在替代實現中，如果轉換值非零，則在結果前新增 0x 或 0X。									不適用
u	將無符號整數轉換為十進位制表示 dddd。 精度 指定要出現的最小位數。 預設精度為 1。 如果轉換值和精度都為 ​0​，則轉換結果為空字元。									不適用
f F (C++11起)	將浮點數轉換為十進位制表示法，樣式為 [-]ddd.ddd。 精度 指定小數點字元後要出現的準確位數。 預設精度為 6。 在替代實現中，即使後面沒有數字，也會寫入小數點字元。 關於無窮大和非數字的轉換樣式，請參見註釋。	不適用	不適用	double	double (C++11起)	不適用	不適用	不適用	不適用	long double
e E	將浮點數轉換為十進位制指數表示法。 對於 e 轉換，使用樣式 [-]d.ddd e±dd。 對於 E 轉換，使用樣式 [-]d.ddd E±dd。 指數至少包含兩位數字，只有在必要時才使用更多數字。 如果值為 ​0​，則指數也為 ​0​。 精度 指定小數點字元後要出現的準確位數。 預設精度為 6。 在替代實現中，即使後面沒有數字，也會寫入小數點字元。 關於無窮大和非數字的轉換樣式，請參見註釋。	不適用	不適用			不適用	不適用	不適用	不適用
a A (C++11)	將浮點數轉換為十六進位制指數表示法。 對於 a 轉換，使用樣式 [-] 0xh.hhh p±d。 對於 A 轉換，使用樣式 [-] 0Xh.hhh P±d。 如果引數是規範化浮點值，則第一個十六進位制數字不是 0。 如果值為 ​0​，則指數也為 ​0​。 精度 指定十六進位制小數點字元後要出現的準確位數。 預設精度足以精確表示該值。 在替代實現中，即使後面沒有數字，也會寫入小數點字元。 關於無窮大和非數字的轉換樣式，請參見註釋。	不適用	不適用			不適用	不適用	不適用	不適用
g G	根據值和精度，將浮點數轉換為十進位制或十進位制指數表示法。 對於 g 轉換樣式，將執行樣式 e 或 f 的轉換。 對於 G 轉換樣式，將執行樣式 E 或 f(C++11 前)F(C++11 起) 的轉換。 令 P 等於精度（如果非零），如果未指定精度則為 6，如果精度為 ​0​ 則為 1。然後，如果使用樣式 E 的轉換將具有指數 X： 如果 P > X ≥ −4，則轉換使用樣式 f 或 F(C++11 起)，精度為 P − 1 − X。 否則，轉換使用樣式 e 或 E，精度為 P − 1。 除非請求替代表示，否則會刪除尾隨零，如果不再有小數部分，也會刪除小數點字元。 關於無窮大和非數字的轉換樣式，請參見註釋。	不適用	不適用			不適用	不適用	不適用	不適用
n	返回此函式呼叫目前已寫入的字元數。 結果被寫入到引數指向的值。 說明符不得包含任何標誌、欄位寬度或精度。 對於 z 修飾符，期望的引數型別是 S*，其中 S 是 std::size_t 的有符號版本。	signed char*	short*	int*	long*	long long*	std::intmax_t*	※	std::ptrdiff_t*	不適用
p	寫入一個實現定義的字元序列，定義一個指標。	不適用	不適用	void*	不適用	不適用	不適用	不適用	不適用	不適用
備註
浮點轉換函式將無窮大轉換為 inf 或 infinity。具體使用哪一個由實現定義。 非數字轉換為 nan 或 nan(char_sequence)。具體使用哪一個由實現定義。 轉換 F、E、G、A 輸出 INF、INFINITY、NAN。 用於列印 char、unsigned char、signed char、short 和 unsigned short 的轉換說明符期望 預設引數提升後的提升型別，但在列印其值之前，它將轉換為 char、unsigned char、signed char、short 和 unsigned short。由於在呼叫可變引數函式時發生的提升，傳遞這些型別的值是安全的。 固定寬度字元型別（std::int8_t 等）的正確轉換說明符定義在標頭檔案 <cinttypes> 中（儘管 PRIdMAX、PRIuMAX 等是 %jd、%ju 等的同義詞）。 記憶體寫入轉換說明符 %n 是格式字串依賴使用者輸入時常見的安全漏洞目標。 每個轉換說明符的操作之後都有一個序列點；這允許在同一變數中儲存多個 %n 結果，或者在極端情況下，在同一次呼叫中列印被早期 %n 修改的字串。 如果轉換說明符無效，則行為未定義。

返回值

1,2) 成功時寫入的字元數，或發生錯誤時的負值。

3) 成功時寫入的字元數（不包括終止空字元），或發生錯誤時的負值。

4) 如果成功，對於足夠大的緩衝區，將寫入的字元數（不包括終止空字元），或發生錯誤時的負值。因此，當且僅當返回值為非負且小於 buf_size 時，（空終止的）輸出才被完全寫入。

備註

POSIX 指定在錯誤時設定 errno。它還指定了額外的轉換說明符，最值得注意的是支援引數重新排序（n$ 緊接在 % 之後表示第 n 個引數）。

呼叫 std::snprintf 時，將 buf_size 設定為零，將 buffer 設定為空指標非常有用（當可以接受雙次呼叫開銷時），用於確定容納輸出所需的緩衝區大小

auto fmt = "sqrt(2) = %f";
int sz = std::snprintf(nullptr, 0, fmt, std::sqrt(2));
std::vector<char> buf(sz + 1); // note +1 for null terminator
std::sprintf(buf.data(), fmt, std::sqrt(2)); // certain to fit

示例

執行此程式碼

#include <cinttypes>
#include <cstdint>
#include <cstdio>
#include <limits>
 
int main()
{
    const char* s = "Hello";
    std::printf("Strings:\n"); // same as std::puts("Strings:");
    std::printf("\t[%10s]\n", s);
    std::printf("\t[%-10s]\n", s);
    std::printf("\t[%*s]\n", 10, s);
    std::printf("\t[%-10.*s]\n", 4, s);
    std::printf("\t[%-*.*s]\n", 10, 4, s);
 
    std::printf("Characters:\t%c %%\n", 'A');
 
    std::printf("Integers:\n");
    std::printf("\tDecimal:    \t%i %d %.6i %i %.0i %+i %i\n",
                                  1, 2,   3, 0,   0,  4,-4);
    std::printf("\tHexadecimal:\t%x %x %X %#x\n",
                                  5,10,10,  6);
    std::printf("\tOctal:      \t%o %#o %#o\n",
                                 10, 10,  4);
 
    std::printf("Floating point:\n");
    std::printf("\tRounding:\t%f %.0f %.32f\n", 1.5, 1.5, 1.3);
    std::printf("\tPadding:\t%05.2f %.2f %5.2f\n", 1.5, 1.5, 1.5);
    std::printf("\tScientific:\t%E %e\n", 1.5, 1.5);
    std::printf("\tHexadecimal:\t%a %A\n", 1.5, 1.5);
    std::printf("\tSpecial values:\t0/0=%g 1/0=%g\n", 0.0/0.0, 1.0/0.0);
 
    std::printf("Variable width control:\n");
    std::printf("\tright-justified variable width: '%*c'\n", 5, 'x');
    int r = std::printf("\tleft-justified variable width : '%*c'\n", -5, 'x');
    std::printf("(the last printf printed %d characters)\n", r);
 
    std::printf("Fixed-width types:\n");
    std::uint32_t val = std::numeric_limits<std::uint32_t>::max();
    std::printf("\tLargest 32-bit value is %" PRIu32 " or %#" PRIx32 "\n",
                                                 val,            val);
}

可能的輸出

Strings:
	[     Hello]
	[Hello     ]
	[     Hello]
	[Hell      ]
	[Hell      ]
Characters:	A %
Integers:
	Decimal:    	1 2 000003 0  +4 -4
	Hexadecimal:	5 a A 0x6
	Octal:      	12 012 04
Floating point:
	Rounding:	1.500000 2 1.30000000000000004440892098500626
	Padding:	01.50 1.50  1.50
	Scientific:	1.500000E+00 1.500000e+00
	Hexadecimal:	0x1.8p+0 0X1.8P+0
	Special values:	0/0=-nan 1/0=inf
Variable width control:
	right-justified variable width: '    x'
	left-justified variable width : 'x    '
(the last printf printed 41 characters)
Fixed-width types:
	Largest 32-bit value is 4294967295 or 0xffffffff

參見

wprintffwprintfswprintf	向 stdout、檔案流或緩衝區列印格式化的寬字元輸出 (函式)
vprintfvfprintfvsprintfvsnprintf (C++11起)	將格式化輸出列印到 stdout、檔案流或緩衝區 使用可變引數列表 (函式)
fputs	將字元字串寫入檔案流 (函式)
scanffscanfsscanf	從 stdin、檔案流或緩衝區讀取格式化輸入 (函式)
to_chars (C++17)	將整數或浮點值轉換為字元序列 (函式)
print (C++23)	使用引數的格式化表示列印到 stdout 或檔案流 (函式模板)
println (C++23)	與 std::print 相同，但每次列印都以額外的換行符終止 (函式模板)
C 文件 for printf, fprintf, sprintf, snprintf