説明
string sprintf(string $format, mixed ...$values)
パラメータ
-
format
-
0個以上のディレクティブで構成されるフォーマット文字列:
変換結果に直接コピーされる通常文字列 (% は除きます)
と、変換仕様。
これらのいずれも、自分が持つパラメータを取得します。
変換の仕様は、以下のプロトタイプに従います:
%[argnum$][flags][width][.precision]specifier.
Argnum
何番目の引数を変換の対象にするかを指定するために、
数値の後にドル記号 $ を続けます。
フラグ一覧
| フラグ |
説明 |
- |
与えられたフィールドの幅を左寄せにします。
右寄せがデフォルトです。
|
+ |
正の数値の前に付ける + 符号です;
デフォルトは、負の数にだけマイナスの符号が数値の前に付きます。
|
(space) |
スペースに変換される詰め物です。
これがデフォルトです。
|
0 |
数値の左側を0埋めします。
s 指定子を使うと、
右側にも0埋めできます。
|
'(char) |
指定された (char) で埋めます。
|
Width
(最小で)何文字がこの変換結果に含まれるかを数値で指定するか、
* を指定します。
* を指定した場合、
指定子によってフォーマットされる値の前に、
幅を追加の数値として指定します。
Precision
ピリオド . の後に数値を続けるか、
* を続けますが、
その意味は指定子に依存します:
-
e, E,
f と F
指定子の場合:
小数点の後に表示する桁数 (デフォルトでは、この値は6です)
-
g, G,
h, H 指定子の場合:
表示する最大の有効桁数
-
s 指定子の場合:
文字列を切り捨てる時点、つまり、文字列の最大の長さを設定します。
注意:
明示的に精度を指定せず、ピリオドを指定した場合、精度は0として扱われます。
* を使った場合、
精度は指定子によってフォーマットされる値の前に、
追加の数値として指定します。
指定子の一覧
| 指定子 |
説明 |
% |
文字通り、パーセント文字です。
引数は不要です。
|
b |
引数は整数として扱われ、2進数値として表現されます。
|
c |
引数は整数として扱われ、ASCII文字として表現されます。
|
d |
引数は整数として扱われ、(符号付き)10進数値として表現されます。
|
e |
引数は科学的記法で表現された値(e.g. 1.2e+2)として扱われます。
|
E |
e 指定子に似ていますが、
大文字を使います(e.g. 1.2E+2)
|
f |
引数は小数として扱われ、浮動小数点数値として表現されます(ロケールを考慮します)。
|
F |
引数は小数として扱われ、浮動小数点数値として表現されます(ロケールを考慮しません)。
|
g |
汎用フォーマット
P を精度を表す、ゼロでない値とします。
精度が省略された場合、Pの値は6です。
精度に0を指定した場合、Pの値は1になります。
この場合、 E 指定子の変換結果は、
X乗になります。
P > X ≥ −4 の場合、E
指定子の変換結果となり、精度は、P − (X + 1) になります。
そうでない場合、e 指定子の変換結果となり、
精度は、P - 1 になります。
|
G |
g 指定子に似ていますが、
E と f を使います。
|
h |
g 指定子に似ていますが、
F を使います。
PHP 8.0.0 以降で利用可能です。
|
H |
g 指定子に似ていますが、
E と F を使います。
PHP 8.0.0 以降で利用可能です。
|
o |
引数は整数として扱われ、8進数値として表現されます。
|
s |
引数は文字列として扱われ、文字列として表現されます。
|
u |
引数は整数として扱われ、符号なし10進数値として表現されます。
|
x |
引数は整数として扱われ、16進数値(小文字)として表現されます。
|
X |
引数は整数として扱われ、16進数値(大文字)として表現されます。
|
警告
文字列と width
指定子を、1文字の表現に1バイト以上必要な文字セットと一緒に使おうとすると、
期待しない結果になるかもしれません。
値は、指定子の型に合うように強制されます:
型のハンドリング
| 型 |
指定子 |
| string |
s |
| int |
d,
u,
c,
o,
x,
X,
b
|
| float |
e,
E,
f,
F,
g,
G,
h,
H
|
-
values
-
戻り値
フォーマット文字列 format
に基づき生成された文字列を返します。
エラー / 例外
PHP 8.0.0 以降では、
引数の数が0の場合に ValueError
がスローされます。
これより前のバージョンでは、代わりに E_WARNING
を発生させていました。
PHP 8.0.0 以降では、
[width] の値が0より小さかったり、
PHP_INT_MAX より大きい場合に、
ValueError がスローされます。
これより前のバージョンでは、代わりに E_WARNING
を発生させていました。
PHP 8.0.0 以降では、
[precision] の値が0より小さかったり、
PHP_INT_MAX より大きい場合に、
ValueError がスローされます。
これより前のバージョンでは、代わりに E_WARNING
を発生させていました。
PHP 8.0.0 以降では、
引数が必要な数より少なかった場合、
ArgumentCountError
がスローされます。
これより前のバージョンでは、代わりに false を返し、E_WARNING
を発生させていました。
例
例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
$num = 5;
$location = 'tree';
$format = 'The %s contains %d monkeys';
echo sprintf($format, $num, $location);
?>
ここで、問題が発生します。フォーマット文字列における置換指示子の順番は、
コードにおける引数の順番と一致していません。
だからといってコードを変更するのではなく、
むしろ置換指示子が参照するフォーマット文字列のほうで指示を行う方が望ましいでしょう。
フォーマット文字列を次のように書き換えてみましょう。
例3 順序付きの置換指示子
<?php
$num = 5;
$location = 'tree';
$format = 'The %2$s contains %1$d monkeys';
echo sprintf($format, $num, $location);
?>
こうすることによるもうひとつの利点は、
同じ置換指示子を複数回使用する際にコードに引数を追加せずにすむことです。
例4 置換指示子を繰り返し使う
<?php
$num = 5;
$location = 'tree';
$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
echo sprintf("%'.9d\n", 123);
echo sprintf("%'.09d\n", 123);
?>
例6 他の指定子と一緒に位置指定子を使う
<?php
$num = 5;
$location = 'tree';
$format = 'The %2$s contains %1$04d monkeys';
echo sprintf($format, $num, $location);
?>
The tree contains 0005 monkeys
例7 sprintf: 整数を0埋めする
<?php
$year = 2005;
$month = 5;
$day = 6;
$isodate = sprintf("%04d-%02d-%02d", $year, $month, $day);
echo $isodate, PHP_EOL;
?>
例8 sprintf: 通貨をフォーマットする
<?php
$money1 = 68.75;
$money2 = 54.35;
$money = $money1 + $money2;
echo $money, PHP_EOL;
$formatted = sprintf("%01.2f", $money);
echo $formatted, PHP_EOL;
?>
例9 sprintf: 科学的記法
<?php
$number = 362525200;
echo sprintf("%.3e", $number), PHP_EOL;
?>
参考
- printf
- fprintf
- vprintf
- vsprintf
- vfprintf
- sscanf
- fscanf
- number_format
- date