sprintf

(PHP 4, PHP 5, PHP 7)

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

説明

sprintf ( string $format [, mixed $... ] ) : string

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

パラメータ

format

0個以上のディレクティブで構成されるフォーマット文字列: 変換結果に直接コピーされる通常文字列 (% は除きます) と、変換仕様。 これらのいずれも、自分が持つパラメータを取得します。

変換の仕様は、以下のプロトタイプに従います: %[argnum$][flags][width][.precision]specifier.

Argnum

何個の引数を変換の対象にするかを指定するために、 数値の後にドル記号 $ を続けます。

フラグ一覧
フラグ 説明
- 与えられたフィールドの幅を左寄せにします。 右寄せがデフォルトです。
+ 正の数値の前に付ける + 符号です; デフォルトは、負の数にだけマイナスの符号が数値の前に付きます。
(space) スペースに変換される詰め物です。 これがデフォルトです。
0 数値の左側を0埋めします。 s 指定子を使うと、 右側にも0埋めできます。
'(char) 指定された (char) で埋めます。

Width

(最小で)何文字がこの変換結果に含まれるかを数値で指定します。

Precision

ピリオド . の後に数値を続けますが、 その意味は指定子に依存します:

  • e, E, fF 指定子の場合: 小数点の後に表示する桁数 (デフォルトでは、この値は6です)
  • gG 指定子の場合: 表示する最大の有効桁数
  • 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 指定子に似ていますが、 Ef を使います。
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

...

返り値

フォーマット文字列 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 埋める文字を指定する

<?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() - ローカルの日付/時刻を書式化する