書式指定構文: printf および wprintf 関数

printf と wprintf 系のさまざまな関数では、書式設定文字列と省略可能な引数を受け取り、書式設定された文字のシーケンスを出力として生成します。 書式設定文字列には、0 個以上のディレクティブが含まれています。ディレクティブとは、出力する文字リテラル、または出力で引数を書式設定する方法を指定するためのエンコードされた変換指定です。 この記事では、書式設定文字列内の変換指定をエンコードするために使用する構文について説明します。 これらの関数の一覧については、「ストリーム入出力」を参照してください。

変換指定は、次に示す形式のように、省略可能なフィールドと必須フィールドで構成されます。

%[flags][width][.precision][size]type

変換指定の各フィールドには、特定の書式オプションまたは変換指定子を示す文字または数値を設定します。 必須の type フィールドには、引数に適用する変換の種類を指定します。 省略可能な flags、 width、および precision フィールドは、先頭のスペースやゼロ、揃え、表示精度などの他の形式の側面を制御します。 size フィールドには、変換される引数のサイズを指定します。

変換指定の基本的な構成は、パーセント記号と type 文字のみです。 たとえば、%s は文字の変換を指定しています。 パーセント記号の文字を出力するには、%% を使用します。 パーセント記号の後に書式設定フィールドとして意味をなさない文字が続く場合は、無効なパラメーター ハンドラーが呼び出されます。 詳細については、「 パラメーターの検証」を参照してください。

type 変換指定子

type 変換指定子の文字は、対応する引数を文字、文字列、ポインター、整数、浮動小数点数のいずれの型として解釈するかを指定します。 type 文字だけが必須の変換指定フィールドで、省略可能なフィールドをその後に続けて指定します。

書式設定文字列に続く引数は、対応する type 文字と、省略可能な size プレフィックスに従って解釈されます。 文字型 char および wchar_t の変換は c または C を使用して指定し、1 バイト文字列とマルチバイトまたはワイド文字の文字列の変換は、書式設定に使用する関数に応じて s または S を使用して指定します。 c および s を使用して指定された文字引数と文字列引数は、printf ファミリの関数では char および char* として解釈され、wprintf ファミリの関数では wchar_t および wchar_t* と解釈されます。 C および S を使用して指定された文字引数と文字列引数は、printf ファミリの関数では wchar_t および wchar_t* として解釈され、wprintf ファミリの関数では char および char* と解釈されます。 この動作は Microsoft 固有です。 歴史的な理由から、 wprintf 関数は c と s を使用して wchar_t 文字を参照し、 C と S は狭い文字を指定します。

short、int、long、long long などの整数型とその unsigned のバリアントは、d、i、o、u、x、X を使用して指定します。 float、double、long double などの浮動小数点型は、a、A、e、E、f、F、g、G を使用して指定します。 size プレフィックスで変更しない場合、既定では、整数引数は int 型に強制変換され、浮動小数点引数は double 型に強制変換されます。 64 ビット システムでは、intは 32 ビットの値であるため、ll または I64 のプレフィックス size を使用しない限り、出力用に書式設定されると、64 ビット整数は切り捨てられます。 p で指定されるポインター型では、プラットフォームの既定のポインター サイズが使用されます。

type フィールドの文字

Visual Studio 2015 以降のバージョンでは、浮動小数点変換指定子 (a、 A、 e、 E、 f、 F、 g、 G) に対応する引数が無限、不定、または NaN の場合、書式設定された出力は C99 標準に準拠します。 書式設定された出力を次の表に示します。

これらの文字列には、プレフィックスとして記号を付ける場合があります。 浮動小数点の type 変換指定子文字が大文字の場合、出力も大文字で書式設定されます。 たとえば、書式指定子が %f ではなく %F の場合、無限大は inf ではなく INF のように書式設定されます。 scanf 関数は、これらの文字列も解析できるため、printf 関数と scanf 関数でこれらの値をラウンドトリップすることができます。

Visual Studio 2015 より前のバージョンでは、CRT で無限大、不定値、NaN の値の出力に対して、次のような非標準の別形式が使用されていました。

これらの文字列は、プレフィックスとして記号が付いている可能性があり、フィールドの幅と精度に応じて書式設定が異なる場合があり、通常とは異なる効果がある場合があります。 たとえば、printf("%.2f\n", INFINITY) は 1.#J のように出力されました。これは、#INF の有効桁数が 2 桁に "丸められた" ためです。

フラグ ディレクティブ

変換仕様の最初の省略可能なフィールドには、 flag ディレクティブが含まれています。 このフィールドには、0 個以上のフラグ文字が含まれており、出力の理由を指定し、符号、ブランク、先行ゼロ、小数点、および 8 進数および 16 進数のプレフィックスの出力を制御します。 変換指定には、複数のフラグ ディレクティブを設定できます。フラグは任意の順序で設定できます。

フラグ文字

幅指定

変換指定では、省略可能な幅指定フィールドを flags 文字の後に指定します。 width 引数は、出力される最小文字数を制御する負でない 10 進整数です。 出力値の文字数が指定された幅よりも小さい場合は、最小文字数に到達するまで値の左または右に空白が追加されます。左か右かは、左揃えのフラグ (-) が指定されているかどうかによって決まります。 width に 0 というプレフィックスが付けられている場合は、無限大または NaN への変換を除いて、最小文字数に到達するまで整数または浮動小数点数の変換の先頭にゼロが追加されます。

幅指定では、値の切り捨ては行われません。 出力値の文字数が指定された幅よりも大きい場合、または width が指定されていない場合は、値のすべての文字が出力され、有効桁数指定が適用されます。

幅指定がアスタリスク (*) の場合は、引数リストから int 引数によって値が提供されます。 次の例で示すように、引数リストでは、書式設定される値の前に width 引数を指定する必要があります。

printf("%0*d", 5, 3); /* 00003 is output */

変換指定に width の値がないか、あっても小さい場合、出力値の切り捨ては行われません。 変換の結果が width の値より大きい場合は、変換結果が含まれるようにフィールドが拡張されます。

精度指定

変換指定の 3 番目の省略可能フィールドは精度指定です。 これはピリオド (.) とそれに続く負ではない 10 進整数から構成されます。これは、変換の種類に応じて、出力される文字列の文字数、小数点以下桁数、または有効桁数を指定します。

幅指定とは異なり、精度指定では、出力値が切り捨てられることや、浮動小数点値が丸め処理される場合があります。 次の例で示すように、precision が 0 と指定され、変換される値が 0 の場合は、結果に何も出力されません。

printf( "%.0d", 0 ); /* No characters output */

精度指定がアスタリスク (*) の場合は、引数リストから int 引数によって値が提供されます。 次の例で示すように、引数リストでは、書式設定される値の前に precision 引数を指定する必要があります。

printf( "%.*f", 3, 3.14159265 ); /* 3.142 output */

次の表で示すように、type 文字によって、precision の解釈、または precision が省略されている場合には既定の有効桁数が決定されます。

有効桁数の値が型に与える影響

引数サイズ指定

変換指定の size フィールドは、type 変換指定子の引数長さ修飾子です。 type フィールドの size フィールド プレフィックス (hh、h、j、l (小文字の L)、L、ll、t、w、z、I (大文字の i)、I32、I64) では、修飾する変換指定子に応じて、対応する引数の "サイズ" (long、short、32 ビット、64 ビット、1 バイト、またはワイド文字) を指定します。 次の表に示すように、printf 系の関数および wprintf 系の関数では、これらのサイズ プレフィックスを type 文字と共に使用して、引数のサイズの解釈を指定できます。 一部の引数型においては、size フィールドは省略可能です。 サイズ プレフィックスを指定しない場合、フォーマッタは整数の引数 (たとえば、符号付きまたは符号なしの char、short、int、long および列挙型) を 32 ビットの int 型として使用します。また、浮動小数点引数 float、double、および long double を 64 ビットの double 型として使用します。 この動作は、可変引数リストの既定の引数の昇格規則と一致します。 引数の昇格の詳細については、「後置式」の「省略記号と既定の引数」に関するページを参照してください。 32 ビット システムと 64 ビット システムの両方で、64 ビット整数の引数の変換指定には ll または I64 のサイズ プレフィックスを含める必要があります。 それ以外の場合はフォーマッタの動作は未定義になります。

32 ビットおよび 64 ビットのコードでは、一部の型のサイズは異なります。 たとえば、 size_t は x86 用にコンパイルされたコードでは 32 ビットですが、 x64 用にコンパイルされたコードでは 64 ビットになります。 可変幅の型がプラットフォームに依存しない書式設定コードを作成するには、可変幅引数サイズ修飾子を使用します。 代わりに、64 ビットの引数サイズ修飾子を使用して、可変幅引数の型を明示的に 64 ビットに昇格させます。 Microsoft 固有の I (大文字の i) 引数サイズ修飾子では可変幅の整数の引数を処理しますが、移植性を考慮して、型に固有の j、t、z 修飾子を使用することをお勧めします。

printf および wprintf 書式指定子のサイズ プレフィックス

型 ptrdiff_t と size_t は、32 ビット プラットフォーム上では __int32 または unsigned __int32、64 ビット プラットフォーム上では __int64 または unsigned __int64 です。 サイズ プレフィックス I (大文字の i)、j、t、z は、プラットフォームに適切な引数の幅を受け取ります。

Visual C++ では、long double は別個の型ですが、これには double と同じ内部表現があります。

hc または hC の型指定子は、printf 関数の c および wprintf 関数の C と同じ意味です。 lc、lC、wc、または wC の型指定子は、printf 関数の C および wprintf 関数の c と同じ意味です。 hs または hS の型指定子は、printf 関数の s および wprintf 関数の S と同じ意味です。 ls、lS、ws、または wS の型指定子は、printf 関数の S および wprintf 関数の s と同じ意味です。

関連項目

printf、 _printf_l、 wprintf、 _wprintf_l
printf_s、 _printf_s_l、 wprintf_s、 _wprintf_s_l
printf_p 位置指定パラメーター