String 関数
PHP マニュアル

sprintf

フォーマットされた文字列を返す

説明

string sprintf(string $format, mixed ...$values)

フォーマット文字列 format に基づき生成された文字列を返します。

パラメータ

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進数値(大文字)として表現されます。

警告

c 指定子はパディングと幅を無視します

警告

文字列と 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 を発生させていました。

変更履歴

バージョン 説明
8.0.0 この関数は、失敗時に false を返さなくなりました。
8.0.0 引数の数が0だった場合、 ValueError がスローされるようになりました。 これより前のバージョンでは、代わりに E_WARNING を発生させていました。
8.0.0 [width] の値が0より小さかったり、 PHP_INT_MAX より大きい場合に、 ValueError をスローするようになりました。 これより前のバージョンでは、代わりに E_WARNING を発生させていました。
8.0.0 [precision] の値が0より小さかったり、 PHP_INT_MAX より大きい場合に、 ValueError をスローするようになりました。 これより前のバージョンでは、代わりに E_WARNING を発生させていました。
8.0.0 引数が必要な数より少なかった場合、 ArgumentCountError がスローされるようになりました。 これより前のバージョンでは、代わりに 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

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

<?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 埋める文字を指定する

<?php
echo 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