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