vsprintf

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

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

説明

vsprintf(string $format, array $values): string

sprintf()と動作は同じですが、可変長の引数ではなく配列を引数とします。

パラメータ

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 以降では、引数が必要な数より少なかった場合、 ValueError がスローされます。これより前のバージョンでは、代わりに 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	引数が必要な数より少なかった場合、 ValueError がスローされるようになりました。これより前のバージョンでは、代わりに `E_WARNING` を発生させていました。

例

例1 vsprintf(): 整数のゼロ埋め

<?php
print vsprintf("%04d-%02d-%02d", explode('-', '1988-8-1'));
?>

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

1988-08-01

参考

printf() - フォーマット済みの文字列を出力する
sprintf() - フォーマットされた文字列を返す
fprintf() - フォーマットされた文字列をストリームに書き込む
vprintf() - フォーマットされた文字列を出力する
vfprintf() - フォーマットされた文字列をストリームに書き込む
sscanf() - フォーマット文字列に基づき入力を処理する
fscanf() - フォーマットに基づきファイルからの入力を処理する
number_format() - 数字を千の位毎にグループ化してフォーマットする
date() - Unixタイムスタンプを書式化する

Found A Problem?

Learn How To Improve This Page • Submit a Pull Request • Report a Bug

＋add a note

User Contributed Notes 10 notes

down

spectrumcat ¶

8 years ago

Instead of inventing own functions in case you'd like to use array keys as placeholder names and replace corresponding array values in a string, just use the str_replace:

$string = 'Hello %name!';
$data = array(
  '%name' => 'John'
);

$greeting = str_replace(array_keys($data), array_values($data), $string);

down

crash ¶

3 years ago

Note that this function now throws an ValueError* as of PHP 8.0 if there is an error:

$ php -r 'var_dump(vsprintf("%d", []));'
> Fatal error: Uncaught ValueError: The arguments array must contain 1 items, 0 given in Command line code:1

*ValueError is new in PHP 8.0, so if you want to make your code compatible to PHP 7.x you should test that the arguments array has the correct length.

down

Josef Kufner ¶

12 years ago

<?php

/**

 * Like vsprintf, but accepts $args keys instead of order index.

 * Both numeric and strings matching /[a-zA-Z0-9_-]+/ are allowed.

 *

 * Example: vskprintf('y = %y$d, x = %x$1.1f', array('x' => 1, 'y' => 2))

 * Result:  'y = 2, x = 1.0'

 *

 * $args also can be object, then it's properties are retrieved

 * using get_object_vars().

 *

 * '%s' without argument name works fine too. Everything vsprintf() can do

 * is supported.

 *

 * @author Josef Kufner <jkufner(at)gmail.com>

 */

function vksprintf($str, $args)

{

    if (is_object($args)) {

        $args = get_object_vars($args);

    }

    $map = array_flip(array_keys($args));

    $new_str = preg_replace_callback('/(^|[^%])%([a-zA-Z0-9_-]+)\$/',

            function($m) use ($map) { return $m[1].'%'.($map[$m[2]] + 1).'$'; },

            $str);

    return vsprintf($new_str, $args);

}

?>

down

steven at nevvix dot com ¶

6 years ago

<?php
/**
 * Return a formatted string like vsprintf() with named placeholders.
 *
 * When a placeholder doesn't have a matching key in `$args`,
 *   the placeholder is returned as is to see missing args.
 * @param string $format
 * @param array $args
 * @param string $pattern
 * @return string
 */
function p($format, array $args, $pattern="/\{(\w+)\}/") {
    return preg_replace_callback($pattern, function ($matches) use ($args) {
        return @$args[$matches[1]] ?: $matches[0];
    }, $format);
}

$args = ["database"=>"people", "user"=>"staff", "pass"=>"pass123", "host"=>"localhost"];

// With PHP-like placeholders: the variable is embedded in a string "{$database}" but without the dollar sign
$format = <<<SQL
CREATE DATABASE IF NOT EXISTS {database};
GRANT ALL PRIVILEGES ON {database_name}.* TO '{user}'@'{host}';
SET PASSWORD = PASSWORD('{pass}');
SQL;
echo p($format, $args);
/*
Result:

CREATE DATABASE IF NOT EXISTS people;
GRANT ALL PRIVILEGES ON {database_name}.* TO 'staff'@'localhost';
SET PASSWORD = PASSWORD('pass123');

The `{database_name}` placeholder doesn't exist as a matching key in `$args` so it's returned as is.
*/

// With Ruby-like placeholders
$format = <<<SQL
CREATE DATABASE IF NOT EXISTS :database;
GRANT ALL PRIVILEGES ON :database_name.* TO ':user'@':host';
SET PASSWORD = PASSWORD(':pass');
SQL;
echo p($format, $args, "/:(\w+)/");
/*
Result:

CREATE DATABASE IF NOT EXISTS people;
GRANT ALL PRIVILEGES ON :database_name.* TO 'staff'@'localhost';
SET PASSWORD = PASSWORD('pass123');

The `:database_name` placeholder doesn't exist as a matching key in `$args` so it's returned as is.
*/

down

www dot wesley at gmail dot com ¶

16 years ago

vnsprintf is equal to vsprintf except for associative, signed or floating keys.

vnsprintf supports for example "%assocKey$05d", "%-2$'+10s" and "%3.2$05u", vsprintf doesn't

vnsprintf( '%2$d', $array) [2nd value] is equal to vsprintf( '%2$d', $array) [2nd value]
vnsprintf( '%+2$d', $array) [key = 2] is equal to vnsprintf( '%2.0$d', $array) [key = 2]
vnsprintf( '%+2$d', $array) [key = 2] is different of vsprintf( '%+2$d', $array) [unsupported]

When you use signed or floating keys, vnsprintf searchs for the signed truncated key of the original array

Note¹: vnsprintf does not support for example "%someKeyf" (floating number, key = someKey) or "%+03d" (signed decimal number, key = 3), you should use "%someKey$f" or "%+03$d" respectively.
Note²: "%+03d" (or "%1$+03d") will be interpreted as signed zero-padded decimal number

<?php
function vnsprintf( $format, array $data)
{
    preg_match_all( '/ (?<!%) % ( (?: [[:alpha:]_-][[:alnum:]_-]* | ([-+])? [0-9]+ (?(2) (?:\.[0-9]+)? | \.[0-9]+ ) ) ) \$ [-+]? \'? .? -? [0-9]* (\.[0-9]+)? \w/x', $format, $match, PREG_SET_ORDER | PREG_OFFSET_CAPTURE);
    $offset = 0;
    $keys = array_keys($data);
    foreach ( $match as &$value )
    {
        if ( ( $key = array_search( $value[1][0], $keys) ) !== FALSE || ( is_numeric( $value[1][0]) && ( $key = array_search( (int)$value[1][0], $keys) ) !== FALSE ) ) {
            $len = strlen( $value[1][0]);
            $format = substr_replace( $format, 1 + $key, $offset + $value[1][1], $len);
            $offset -= $len - strlen( $key);
        }
    }
    return vsprintf( $format, $data);
}

$examples = array(
    2.8=>'positiveFloat',    // key = 2 , 1st value
    -3=>'negativeInteger',    // key = -3 , 2nd value
    'my_name'=>'someString'    // key = my_name , 3rd value
);

echo vsprintf( "%%my_name\$s = '%my_name\$s'\n", $examples);    // [unsupported]
echo vnsprintf( "%%my_name\$s = '%my_name\$s'\n", $examples);    // output : "someString"

echo vsprintf( "%%2.5\$s = '%2.5\$s'\n", $examples);        // [unsupported]
echo vnsprintf( "%%2.5\$s = '%2.5\$s'\n", $examples);        // output : "positiveFloat"

echo vsprintf( "%%+2.5\$s = '%+2.5\$s'\n", $examples);        // [unsupported]
echo vnsprintf( "%%+2.5\$s = '%+2.5\$s'\n", $examples);        // output : "positiveFloat"

echo vsprintf( "%%-3.2\$s = '%-3.2\$s'\n", $examples);        // [unsupported]
echo vnsprintf( "%%-3.2\$s = '%-3.2\$s'\n", $examples);        // output : "negativeInteger"

echo vsprintf( "%%2\$s = '%2\$s'\n", $examples);            // output : "negativeInteger"
echo vnsprintf( "%%2\$s = '%2\$s'\n", $examples);            // output : [= vsprintf]

echo vsprintf( "%%+2\$s = '%+2\$s'\n", $examples);        // [unsupported]
echo vnsprintf( "%%+2\$s = '%+2\$s'\n", $examples);        // output : "positiveFloat"

echo vsprintf( "%%-3\$s = '%-3\$s'\n", $examples);        // [unsupported]
echo vnsprintf( "%%-3\$s = '%-3\$s'\n", $examples);        // output : "negativeInteger"
?>

down

jon at ardentcreative dot co dot uk ¶

18 years ago

This can be used for quick and dirty internationalization:

<?php
$GLOBALS['strings']['example'] = "There are %d people.";

// Loads a phrase from the translations list in lang/$lang/phrases.php
function t() {
    $args = func_get_args();
    $nArgs = func_num_args();
    
    $phrase = array_shift($args);
    $nArgs--;
    
    include_once("../lang/" . lang() . "/phrases.php");
    if (isset($GLOBALS['strings'][$phrase])) {
        return vsprintf($GLOBALS['strings'][$phrase], $args);
    } else {
        return '<span style="color: #ff0000">Untranslated string: ' . $phrase . '</span>';
    }
}
?>

down

Roadster ¶

18 years ago

Please note: The same functionality (sortof) can be attained between version 4.0.4 and 4.1.0 using call_user_func_array.

Example:

call_user_func_array("sprintf", $arg)

First element of $arg is the format. This rescued me in a situation where version 4.1.0 wasn't available.

down

dee jay simple zero07 at geemail dawt co ¶

11 years ago

Using a heredoc with vprintf:



<?php

$string = <<<THESTRING

I like the state of %1\$s <br />

I picked: %2\$d as a number, <br />

I also picked %2\$d as a number again <br />

%3\$s<br />

THESTRING;



$returnText = vprintf(  $string, array('Oregon','7','I Love Oregon')  );



echo $returnText;

?>

down

jed at NOSPAM dot jed dot bz ¶

20 years ago

vsprintf() accepts arrays with any keys, so the array_shift() technique is unnecessary when writing a printf-type function. Any parameters you require are easily unset from the array you retrieve with func_get_args():

<?php

function mysprintf($format) {
    $args = func_get_args();
    unset($args[0]); /* get rid of "$format" */
    return vsprintf($format, $args);
}

/* I use this technique in production code as follows: */
function logf($target, $string) {
    $args = func_get_args();
    unset($args[0], $args[1]);
    fprintf($GLOBALS['config']['logtargets'][$target],
        "[%s] %s\n", date('H:i'), wordwrap(vsprintf($string, $args), 75, '\n\r '));
}

/* e.g.:
    logf(DEBUG, "Oops! %s", mysql_error());
 */

?>

array_shift() and other costly array operations aren't required, as far as I know. I could be wrong.

down

ASchmidt at Anamera dot net ¶

7 years ago

It's necessary to clearly how to apply argument swapping when using an array of arguments. One might be tempted to use %0$ to reference $args[0].

In reality, the position specifier is always the array index+1:

$args[0]  is referenced by %1$...
$args[1]  is referenced by %2$... 
etc.

Similarly, the first subpattern of a RegEx match would be found in $matches[1], the second in $match[2], etc. However if the $matches array is used as arguments to vsprint(), then the position specifier is subpattern+1:

preg_match( $pattern, $subject, $matches );
vsprintf( 'Full Match = %1$s, first Subpattern = %2$s, second Subpattern = %3$s', $matches );

＋add a note