sprintf

パラメータ

format

フォーマット文字列は 0 個以上のディレクティブ（指示子） により構成されます。ディレクティブには、そのまま結果にコピーされる (% を除く) 通常の文字と変換指定子 (conversion specifications) があり、 取り出される際はどちらもそれ自身がパラメータとなります。このことは sprintf() の場合だけでなく printf() の場合も同様です。

各変換指定子は、パーセント記号 (%) の後に これらの要素が一つ以上続いたものになります。

1. オプションの符号指定子。これは、 数値で符号 (- あるいは +) を使用するよう指定します。 デフォルトでは、数値が負の場合の - 符号のみが使用されます。 この指定子により、正の数にも強制的に + 符号をつけることができます。 これは PHP 4.3.0 で追加されました。
2. オプションのパディング指定子。これは、 文字列が正しい長さになるまでどんな文字で埋めるかということを 指定します。これは空白かまたは 0 (文字 '0') のいずれかです。デフォルトでは空白で埋められます。 これ以外のパディング文字を指定するには、その文字の前に 単一引用符 (') を置きます。 後述の例を参照ください。
3. オプションのアラインメント指定子。これは、 結果を左寄せまたは右寄せにしたい場合に指定します。 デフォルトは右寄せです。ここで - 文字を指定すると左寄せとなります。
4. オプションの数字。これは表示幅指定子です。 結果を（最低）何桁にするかを指定します。
5. オプションの精度指定子 (ピリオド (`.') に続けてオプションで桁数指定文字列を書いたもの)。 これは、浮動小数点数に対して数字を何桁まで表示するかを指定します。 文字列に対して使用した場合は、これは切り捨て位置として働きます。 この文字数を超える文字を切り捨てられます。

6. 型指定子。引数を何の型として扱うかを指定します。 指定できる型を以下に示します。

   • % - パーセント文字。引数は不要です。
   • b - 引数を整数として扱い、 2 進数として表現します。
   • c - 引数を整数として扱い、その ASCII 値の文字として表現します。
   • d - 引数を整数として扱い、 10 進数として表現します。
   • e - 引数を科学記法として扱います (例 1.2e+2)。 精度の指定子は、PHP 5.2.1 以降では小数点以下の桁数を表します。 それより前のバージョンでは、有効数字の桁数 (ひとつ小さい値) を意味していました。
   • E - %e と同じですが、 大文字を使います (例 1.2E+2)。
   • u - 引数を整数として扱い、符号無しの 10 進数として表現します。
   • f - 引数を double として扱い、 浮動小数点数として表現します。
   • F - 引数を float として扱い、 浮動小数点数として表現します (ロケールに依存しません)。 PHP 4.3.10 および PHP 5.0.3 以降で使用可能です。
   • g - %e および %f の短縮形。
   • G - %E および %f の短縮形。
   • o - 引数を整数として扱い、 8 進数として表現します。
   • s - 引数を文字列として扱い、表現します。
   • x - 引数を整数として扱い、16 進数として (小文字で)表現します。
   • X - 引数を整数として扱い、16 進数として (大文字で)表現します。

フォーマット文字列における引数の 番号付け/交換 をサポートしています。以下に例を示します。

例1 引数の交換

<?php
$num = 5;
$location = 'tree';

$format = 'There are %d monkeys in the %s';
echo sprintf($format, $num, $location);
?>

この出力は、"There are 5 monkeys in the tree" のようになります。 ここで、フォーマット文字列が別のファイルにある場合を考えてみましょう。 これは、出力を国際化したりする場合に行われる可能性があります。 たとえばフォーマット文字列が次のように書き換えられたとすると、

例2 引数の交換

<?php
$format = 'The %s contains %d monkeys';
echo sprintf($format, $num, $location);
?>

ここで、問題が発生します。フォーマット文字列における置換指示子の順番は、 コードにおける引数の順番と一致していません。 だからといってコードを変更するのではなく、 むしろ置換指示子が参照するフォーマット文字列のほうで指示を行う方が望ましいでしょう。 フォーマット文字列を次のように書き換えてみましょう。

例3 引数の交換

<?php
$format = 'The %2$s contains %1$d monkeys';
echo sprintf($format, $num, $location);
?>

こうすることによるもうひとつの利点は、 同じ置換指示子を複数回使用する際にコードに引数を追加せずにすむことです。 例えば、次のようになります。

例4 引数の交換

<?php
$format = 'The %2$s contains %1$d monkeys.
           That\'s a nice %2$s full of %1$d monkeys.';
echo sprintf($format, $num, $location);
?>

引数の交換を使うときには、 位置指定子 n$ をパーセント記号 (%) の直後に置かなければならず、 間に他の指定を入れてはいけません。次の例を示します。

例5 位置指定子と他の指定との共用

<?php
$format = 'The %2$s contains %1$04d monkeys';
echo sprintf($format, $num, $location);
?>

上の例の出力は以下となります。

The tree contains 0005 monkeys

注意:

PHP_INT_MAX より大きい位置指定子を指定すると、 sprintf() は警告を発します。

args

...