トップページ　→関数リファレンス　→テキスト処理　→文字列　→String 関数

関数・クラス解説

sprintf

version:PHP 4, PHP 5, PHP 7 (公式)

文字列を指定されたフォーマットで整形して返却

フォーマット

string | false : sprintf ( string $format , mixed ...$values )

パラメータ

string $format （必須）
フォーマット形式を指定します。printf()をはじめとする多くのフォーマット出力関連関数と同様です。
以下を参照してください。

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

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

フラグ一覧
フラグ説明
- 与えられたフィールドの幅を左寄せにします。右寄せがデフォルトです。
+ 正の数値の前に付ける + 符号です; デフォルトは、負の数にだけマイナスの符号が数値の前に付きます。
(space) スペースに変換される詰め物です。これがデフォルトです。
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 を使います。
h g 指定子に似ていますが、F を使います。PHP 8.0.0 以降で利用可能です。
H g 指定子に似ていますが、E と F を使います。PHP 8.0.0 以降で利用可能です。
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

mixed ...$values
フォーマットしたい文字列を指定します。

返値 string | false
フォーマット文字列 format に基づき生成された文字列を返します。失敗した場合に FALSE を返します。

解説

この関数では渡した文字列を、format によって指定されたフォーマットで整形した文字列を返却します。同様の関数にprintfが存在しますが、違いは、printf が処理結果を画面へ「出力」して表示するのに対して、このsprintf では、処理結果を返り値として「返却」します。つまり、printf では単体で画面表示を行いますが、sprintf で画面出力したい場合は「echo sprintf(...)」とする必要があります。その代わりprintf では変数へ格納することはできません。他にも同様の関数がいくつか存在します。

記述サンプル

//公式より引用
例1 引数の交換
フォーマット文字列における引数の 番号付け/交換 をサポートしています。以下に例を示します。
$num = 5;
$location = 'tree';

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

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

$format = 'The %s contains %d monkeys';
echo sprintf($format, $num, $location);
ここで、問題が発生します。フォーマット文字列における置換指示子の順番は、コードにおける引数の順番と一致していません。だからといってコードを変更するのではなく、むしろ置換指示子が参照するフォーマット文字列のほうで指示を行う方が望ましいでしょう。フォーマット文字列を次のように書き換えてみましょう。


$format = 'The %2$s contains %1$d monkeys';
echo sprintf($format, $num, $location);
こうすることによるもうひとつの利点は、同じ置換指示子を複数回使用する際にコードに引数を追加せずにすむことです。例えば、次のようになります。

$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 埋める文字を指定する
echo sprintf("%'.9d\n", 123);
echo sprintf("%'.09d\n", 123);

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


例3 位置指定子と他の指定との共用
$format = 'The %2$s contains %1$04d monkeys';
echo sprintf($format, $num, $location);

上の例の出力は以下となります。
The tree contains 0005 monkeys


例4 sprintf(): ゼロ埋めされた数値
$isodate = sprintf("%04d-%02d-%02d", $year, $month, $day);


例5 sprintf(): 通貨フォーマット
$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(): 科学的記法
$number = 362525200;
echo sprintf("%.3e", $number);

上の例の出力は以下となります。
3.625e+8

参考リンク

・date　ローカルの日付/時刻を書式化する
・fscanf　フォーマットに基づきファイルからの入力を処理する
・fprintf　指定されたフォーマットの文字列をファイルに書き込む
・number_format　数字を千区切り・小数点の桁などでフォーマットする
・printf　文字列を指定のフォーマットにしたがって出力する
・sscanf　文字列を指定したフォーマットに基づいて整形し返却する
・vfprintf　フォーマットされた文字列をストリームに書き込む
・vprintf　フォーマットされた文字列を出力する
・vsprintf　フォーマットされた文字列を返す

公式リファレンス

書式

sprintf ( string $format , mixed ...$values ) : string|false

説明

フォーマット文字列 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 指定子の場合: 表示する最大の有効桁数
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 を返します。

注意

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

サンプル

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

$num = 5;
$location = 'tree';

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

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

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

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

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

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

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

echo sprintf("%'.9d\n", 123);
echo sprintf("%'.09d\n", 123);

 上の例の出力は以下となります。 
......123
000000123
 例3 位置指定子と他の指定との共用 

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

 上の例の出力は以下となります。 
The tree contains 0005 monkeys
 例4 sprintf(): ゼロ埋めされた数値 

$isodate = sprintf("%04d-%02d-%02d", $year, $month, $day);

 例5 sprintf(): 通貨フォーマット 

$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(): 科学的記法 

$number = 362525200;

echo sprintf("%.3e", $number);

 上の例の出力は以下となります。 
3.625e+8

参考

printf() - フォーマット済みの文字列を出力する

fprintf() - フォーマットされた文字列をストリームに書き込む

vprintf() - フォーマットされた文字列を出力する

vsprintf() - フォーマットされた文字列を返す

vfprintf() - フォーマットされた文字列をストリームに書き込む

sscanf() - フォーマット文字列に基づき入力を処理する

fscanf() - フォーマットに基づきファイルからの入力を処理する

number_format() - 数字を千位毎にグループ化してフォーマットする

date() - ローカルの日付/時刻を書式化する

ワード検索

※入力キーワードが、関数名・説明文・タグに含まれるものを検索

関数名アルファベット別

A	B	C	D	E	F	G	H	I	J
K	L	M	N	O	P	Q	R	S	T
U	V	W	X	Y	Z	_

最終更新一覧

●stristr
　大文字小文字を区別せず文字列を検索し、ヒット箇所以降（あるいは以前）の文字列を返却

●stripslashes
　バックスラッシュでエスケープされた文字列から、バックスラッシュを取り除く

●stripos
　大文字小文字を区別せずに文字列が最初に現れる位置を取得する

●stripcslashes
　addcslashes() でクォートされた文字列をアンクォートする

●strip_tags
　文字列から HTML と PHP のタグを除去して返却

●strcspn
　指定した文字が最初に現れる位置を調べる

●strcoll
　ロケールに基づいて2つの文字列を比較し同じか（あるいは大小）を判定する

●strcmp
　2つの文字列を比較し同じか（あるいは大小）を判定する

●strchr
　strstr() のエイリアス

●strcasecmp
　2つの文字列を比較（大文字小文字を区別せず同じとみなす）

カテゴリー一覧

PHP の振る舞いの変更
 音声フォーマットの操作
 認証サービス
 コマンドライン関連
 圧縮およびアーカイブ
 暗号
 データベース関連
 日付および時刻関連
 ファイルシステム
 自然言語および文字エンコーディング
 画像処理および作成
 メール関連
 数学
 テキスト以外の MIME 型
 プロセス制御
 その他の基本モジュール
 その他のサービス
 検索エンジン用の拡張モジュール
 サーバー固有のモジュール
 セッション関連
 テキスト処理
 変数・データ型関連
 ウェブサービス
 Windows 用のモジュール
 XML 操作
 GUI用の拡張モジュール