= Printf 組込みコマンド
:encoding: UTF-8
:lang: ja
//:title: Yash マニュアル - Printf 組込みコマンド

dfn:[Printf 組込みコマンド]はオペランドを整形して出力します。

[[syntax]]
== 構文

- +printf {{書式}} [{{値}}...]+

[[description]]
== 説明

Printf コマンドはオペランドで指定した{{書式}}に従って{{値}}を整形し、標準出力に出力します。{zwsp}link:_echo.html[Echo コマンド]とは異なり、出力の最後には自動的に改行は付きません。

書式の指定の仕方は C 言語の printf 関数とよく似ています。書式の中では +%+ で始まる変換指定と +\+ で始まるエスケープシーケンスを使用できます。書式に含まれる変換指定とエスケープ以外の文字はそのまま出力します。

[[convspec]]
=== 変換指定

変換指定はパーセント記号 (+%+) から始まります。

+%%+ 以外の変換指定は、対応する値をとります。変換指定は、値を特定の形式に整形して出力します。変換指定と値は与えられた順番に対応付けられます。値が余った場合は、全ての値を処理し終わるまで書式の整形・出力を繰り返します。値が足りない場合は、空文字列 (文字列に関する変換指定の場合) または 0 (数値に関する変換指定の場合) を仮定します。値が一つも与えられていない場合は、書式は一度だけ出力されます。

利用可能な変換指定は以下の通りです。

+%d+::
+%i+:: 整数の値を (符号付き) 十進整数として出力します。
+%u+:: 整数の値を (符号なし) 十進非負整数として出力します。
+%o+:: 整数の値を (符号なし) 八進非負整数として出力します。
+%x+:: 整数の値を小文字の (符号なし) 十六進非負整数として出力します。
+%X+:: 整数の値を大文字の (符号なし) 十六進非負整数として出力します。
+%f+:: 実数の値を小文字の (符号付き) 小数として出力します。
+%F+:: 実数の値を大文字の (符号付き) 小数として出力します。
+%e+:: 実数の値を小文字の (符号付き) 指数表記小数で出力します。
+%E+:: 実数の値を大文字の (符号付き) 指数表記小数で出力します。
+%g+:: 値の大きさや精度に応じて +%f+ と +%e+ のどちらかの形式で出力します。
+%G+:: 値の大きさや精度に応じて +%F+ と +%E+ のどちらかの形式で出力します。
+%c+:: 文字列の値の最初の文字を出力します。
+%s+:: 文字列の値をそのまま出力します。
+%b+::
文字列の値を、エスケープシーケンスを解釈しながら出力します。ここで使えるエスケープシーケンスは link:_echo.html[echo コマンド]で使えるエスケープシーケンスと同じです。
+%%+:: パーセント記号 (+%+) を出力します。

+%g+ と +%G+ では、小数の指数部が -5 以上精度以下の時に +%f+ または +%F+ を、それ以外の時に +%e+ または +%E+ を使用します。

+%%+ 以外の変換指定では、最初の +%+ の直後に変換指定フラグ・フィールド幅・精度をこの順で指定できます。これらを指定することで出力の形式を細かく調整できます。

[[convspec-flags]]
==== 変換指定フラグ

指定できる変換指定フラグは以下の通りです。フラグを複数指定しても構いません。

マイナス (+-+)::
このフラグを指定すると、指定したフィールド幅の中で値を左に寄せて出力します。このフラグを指定しない場合、値は右に寄ります。

プラス (+&#x2B;+)::
数値の符号 (正号または負号) を必ず出力します。

空白文字 (+&#x20;+)::
出力する数値に符号 (正号または負号) が付かない場合は、符号の代わりに空白文字を出力します。

+#+::
値を別形式で出力します。
変換指定が +%o+ の場合、出力する八進数の先頭に必ず一桁以上の 0 が付くように、必要に応じて 0 を付加します。
変換指定が +%x+ (または +%X+) の場合、値が 0 でなければ数値の先頭に +0x+ (または +0X+) を付加します。
変換指定が +%e+, +%E+, +%f+, +%F+, +%g+, +%G+ の場合、小数点の後に数字がない場合でも小数点を省略しないようにします。また変換指定が +%g+, +%G+ の場合、小数点の後に 0 以外の数字がない場合でも 0 を省略しないようにします。

ゼロ (+0+)::
変換指定が +%d+, +%i+, +%u+, +%o+, +%x+, +%X+, +%e+, +%E+, +%f+, +%F+, +%g+, +%G+ の場合、出力が指定したフィールド幅いっぱいになるまで数値の先頭に 0 を付加します。
+
マイナスフラグが指定されている場合、このフラグは無視されます。
+
変換指定が +%d+, +%i+, +%u+, +%o+, +%x+, +%X+ で、精度が指定されている場合、このフラグは無視されます。

[[convspec-width]]
==== フィールド幅

フィールド幅は、先頭に 0 の付かない十進整数の形で指定します。

フィールド幅は出力の最低バイト数を指示します。出力のバイト数がフィールド幅に満たないときは、バイト数がフィールド幅に一致するまで空白文字を付加します。

[[convspec-precision]]
==== 精度

精度は、ピリオド (+.+) の直後に十進整数を置いたものの形で指定します。ピリオドの後に整数がなければ、0 が指定してあるものとみなします。

変換指定が +%d+, +%i+, +%u+, +%o+, +%x+, +%X+ の場合、精度は出力の最低桁数を指示します。数値が最低桁数に満たない場合は最低桁数に達するまで先頭に 0 を付加します。精度が指定されていない場合、精度は 1 とみなします。

変換指定が +%e+, +%E+, +%f+, +%F+ の場合、精度は小数点以降の桁数を指示します。精度が指定されていない場合、精度は 6 とみなします。

変換指定が +%g+, +%G+ の場合、精度は数値の最大有効桁数を指示します。精度が指定されていない場合、精度は 6 とみなします。

変換指定が +%s+, +%b+ の場合、精度は出力する文字列の最大バイト数を指示します。精度が指定されていない場合、精度は無限大とみなします。

[[convspec-examples]]
==== 例

変換指定 +%f+ にゼロフラグを指定し、フィールド幅に 8、精度に 3 を指定する場合、最終的な変換指定は +%08.3f+ となります。この変換指定に対して値 12.34 を与えると、出力は +0012.340+ となります。

[[escapes]]
=== エスケープシーケンス

書式の中で使えるエスケープシーケンスは以下の通りです。

+\a+::
ベル文字 (ASCII コード番号 7)
+\b+::
バックスペース (ASCII コード番号 8)
+\f+::
フォームフィード (ASCII コード番号 12)
+\n+::
改行文字 (ASCII コード番号 10)
+\r+::
復帰文字 (ASCII コード番号 13)
+\t+::
水平タブ (ASCII コード番号 9)
+\v+::
垂直タブ (ASCII コード番号 11)
+\\+::
バックスラッシュ
+\"+::
二重引用符
+\'+::
一重引用符 (アポストロフィー)
+&#x5C;{{xxx}}+::
八進数 {{xxx}} (最大三桁) で表わされるコード番号の文字

[[operands]]
== オペランド

{{書式}}::
出力する文字列の書式です。

{{値}}::
変換指定が出力する値 (数値または文字列) です。
+
数値を値として指定する際、一重または二重引用符の後に何か文字を置いたものを指定することで、その文字のコード番号を数値として指定できます。例えば +3+ という文字のコード番号が 51 ならば、 `printf '%d' '"3'` は +51+ を出力します。

[[exitstatus]]
== 終了ステータス

エラーがない限り printf コマンドの終了ステータスは 0 です。

[[notes]]
== 補足

POSIX では、マルチバイト文字の扱いについて厳密に定義していません。+%s+ 変換指定で精度を指定した場合や、+%c+ 変換指定を使用する場合、値にマルチバイト文字が含まれていると適切な出力が得られないかもしれません。Yash では、マルチバイト文字は全てワイド文字に変換してから処理するので、マルチバイト文字の一部のバイトだけが出力されるようなことはありません。

シェルが非 link:posix.html[POSIX 準拠モード]で、システム上で ``long double'' 浮動小数点数が使用可能な場合は、実数の変換指定は ``long double'' で処理されます。それ以外の場合は ``double'' で処理されます。

// vim: set filetype=asciidoc expandtab:
