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

 

C++

コンパイラサポート

フリースタンディングとホスト

言語

標準ライブラリ

標準ライブラリヘッダー

名前付き要件

機能テストマクロ (C++20)

言語サポートライブラリ

コンセプトライブラリ (C++20)

診断ライブラリ

メモリ管理ライブラリ

メタプログラミングライブラリ (C++11)

汎用ユーティリティライブラリ

コンテナライブラリ

イテレータライブラリ

Rangesライブラリ (C++20)

アルゴリズムライブラリ

文字列ライブラリ

テキスト処理ライブラリ

数値ライブラリ

日付と時刻ライブラリ

入出力ライブラリ

ファイルシステムライブラリ (C++17)

並行サポートライブラリ (C++11)

実行制御ライブラリ (C++26)

Technical specifications (技術仕様)

シンボルインデックス

外部ライブラリ

 

入出力ライブラリ

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	-	データをどのように解釈するかを指定する、ヌル終端されたマルチバイト文字列へのポインタ
...	-	出力するデータを指定する引数。デフォルト引数昇格の後、対応する変換指定子が期待する型と引数の型が異なる場合 (期待される型は昇格された型または昇格された型と互換性のある型)、または format が要求する引数よりも少ない場合、動作は未定義です。format が要求する引数よりも多い場合、余分な引数は評価され無視されます。

format 文字列は、出力ストリームにそのままコピーされる通常のバイト文字 (% を除く) と、変換指定子で構成されます。各変換指定子は以下の形式を持ちます。

• 先頭の % 文字。

• (オプション) 変換の動作を変更する1つ以上のフラグ

• -: 変換の結果はフィールド内で左寄せされます (デフォルトは右寄せ)。
• +: 符号付き変換の結果には常に符号が前置されます (デフォルトでは負の場合にのみマイナスが前置されます)。
• space: 符号付き変換の結果が符号文字で始まらない場合、または空の場合、スペースが結果の前に付加されます。+ フラグが存在する場合は無視されます。
• #: 変換の代替形式が実行されます。正確な効果については以下の表を参照してください。それ以外の場合、動作は未定義です。
• 0: 整数および浮動小数点数の変換の場合、フィールドのパディングにはスペース文字ではなく先行ゼロが使用されます。整数数の場合、精度が明示的に指定されている場合は無視されます。このフラグを使用する他の変換では、未定義の動作が発生します。- フラグが存在する場合は無視されます。

• (オプション) 最小フィールド幅を指定する整数値または *。必要に応じて、結果はスペース文字でパディングされます (デフォルト)。右寄せの場合は左側に、左寄せの場合は右側にパディングされます。* が使用される場合、幅は int 型の追加の引数によって指定されます。この引数は変換される引数の前に現れ、精度が指定されている場合は精度の引数の前に現れます。引数の値が負の場合、- フラグが指定され、正のフィールド幅になります (注: これは最小幅であり、値が切り捨てられることはありません)。

• (オプション) . の後に整数値または * が続くか、どちらも続かない精度を指定します。* が使用される場合、精度は int 型の追加の引数によって指定されます。この引数は変換される引数の前に現れますが、最小フィールド幅が指定されている場合はその引数の後に現れます。この引数の値が負の場合、無視されます。数値も * も使用されない場合、精度はゼロとみなされます。精度の正確な効果については以下の表を参照してください。

• (オプション) 引数のサイズを指定する長さ修飾子 (変換フォーマット指定子と組み合わせて、対応する引数の型を指定します)。

• 変換フォーマット指定子。

以下のフォーマット指定子が利用可能です

変換 指定子	説明	期待される 引数型
長さ修飾子→		hh	h	なし	l	ll	j	z	t	L
C++11からのみ利用可能→		はい				はい	はい	はい	はい
%	リテラル % を書き込みます。完全な変換指定子は %% でなければなりません。	N/A	N/A	N/A	N/A	N/A	N/A	N/A	N/A	N/A
c	単一の文字を書き込みます。 引数はまず unsigned char に変換されます。 l 修飾子が使用される場合、引数はまず wchar_t[2] 引数を持つ %ls と同様に文字列に変換されます。	N/A	N/A	int	std::wint_t	N/A	N/A	N/A	N/A	N/A
s	文字列を書き込みます。 引数は文字配列の最初の要素へのポインタでなければなりません。 精度は書き込まれる最大バイト数を指定します。精度が指定されていない場合、最初のヌル終端文字まで (それを含まない) すべてのバイトを書き込みます。 l 指定子が使用される場合、引数は wchar_t の配列の最初の要素へのポインタでなければなりません。これは、ゼロ初期化された変換状態を持つ std::wcrtomb の呼び出しによって char 配列に変換されるかのようになります。	N/A	N/A	char*	wchar_t*	N/A	N/A	N/A	N/A	N/A
d i	符号付き整数を10進数表現 [-]dddd に変換します。 精度は表示される最小桁数を指定します。デフォルトの精度は 1 です。 変換された値と精度の両方が ​0​ の場合、変換結果は文字になりません。 z 修飾子の場合、期待される引数型は std::size_t の符号付きバージョンです。	signed char	short	int	long	long long	std::intmax_t	※	std::ptrdiff_t	N/A
o	符号なし整数を8進数表現 oooo に変換します。 精度は表示される最小桁数を指定します。デフォルトの精度は 1 です。 変換された値と精度の両方が ​0​ の場合、変換結果は文字になりません。 代替実装では、必要に応じて精度が増加され、先行ゼロが1つ書き込まれます。その場合、変換された値と精度の両方が ​0​ の場合、単一の ​0​ が書き込まれます。	unsigned char	unsigned short	unsigned int	unsigned long	unsigned long long	std::uintmax_t	std::size_t	std::ptrdiff_t の符号なしバージョン	N/A
x X	符号なし整数を16進数表現 hhhh に変換します。 x 変換文字には abcdef が使用されます。 X 変換文字には ABCDEF が使用されます。 精度は表示される最小桁数を指定します。デフォルトの精度は 1 です。 変換された値と精度の両方が ​0​ の場合、変換結果は文字になりません。 代替実装では、変換された値がゼロ以外の場合、結果に 0x または 0X がプレフィックスとして付けられます。									N/A
u	符号なし整数を10進数表現 dddd に変換します。 精度は表示される最小桁数を指定します。 デフォルトの精度は 1 です。 変換された値と精度の両方が ​0​ の場合、変換結果は文字になりません。									N/A
f F (C++11)	浮動小数点数を [-]ddd.ddd の形式で10進数表記に変換します。 精度は小数点文字の後に表示される桁の厳密な数を指定します。 デフォルトの精度は 6 です。 代替実装では、小数点文字の後に桁がない場合でも小数点文字が書き込まれます。 無限大および非数変換のスタイルについては注釈を参照してください。	N/A	N/A	double	double (C++11)	N/A	N/A	N/A	N/A	long double
e E	浮動小数点数を10進指数表記に変換します。 e 変換スタイルには [-]d.ddd e±dd が使用されます。 E 変換スタイルには [-]d.ddd E±dd が使用されます。 指数は少なくとも2桁を含み、必要な場合にのみそれ以上の桁が使用されます。 値が ​0​ の場合、指数も ​0​ です。 精度は小数点文字の後に表示される桁の厳密な数を指定します。 デフォルトの精度は 6 です。 代替実装では、小数点文字の後に桁がない場合でも小数点文字が書き込まれます。 無限大および非数変換のスタイルについては注釈を参照してください。	N/A	N/A			N/A	N/A	N/A	N/A
a A (C++11)	浮動小数点数を16進指数表記に変換します。 a 変換スタイルには [-] 0xh.hhh p±d が使用されます。 A 変換スタイルには [-] 0Xh.hhh P±d が使用されます。 引数が正規化された浮動小数点値の場合、最初の16進数字は 0 ではありません。 値が ​0​ の場合、指数も ​0​ です。 精度は16進小数点文字の後に表示される桁の厳密な数を指定します。 デフォルトの精度は値の正確な表現に十分です。 代替実装では、小数点文字の後に桁がない場合でも小数点文字が書き込まれます。 無限大および非数変換のスタイルについては注釈を参照してください。	N/A	N/A			N/A	N/A	N/A	N/A
g G	浮動小数点数を値と精度に応じて10進数または10進指数表記に変換します。 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/A	N/A			N/A	N/A	N/A	N/A
n	この関数への呼び出しによってこれまでに書き込まれた文字数を返します。 結果は引数が指す値に書き込まれます。 指定子には、フラグ、フィールド幅、または精度を含めることはできません。 z 修飾子の場合、期待される引数型は S* です。ここで S は std::size_t の符号付きバージョンです。	signed char*	short*	int*	long*	long long*	std::intmax_t*	※	std::ptrdiff_t*	N/A
p	ポインタを定義する実装定義の文字シーケンスを書き込みます。	N/A	N/A	void*	N/A	N/A	N/A	N/A	N/A	N/A
注釈
浮動小数点変換関数は無限大を 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と同じだが、各出力の末尾に改行が追加される点が異なる (関数テンプレート)
printf, fprintf, sprintf, snprintf のC言語ドキュメント