vsprintf
Operates as sprintf() but accepts an array of arguments, rather than a variable number of arguments.
Parameters
The format string is composed of zero or more directives: ordinary characters (excluding % ) that are copied directly to the result and conversion specifications, each of which results in fetching its own parameter.
A conversion specification follows this prototype: %[argnum$][flags][width][.precision]specifier .
Argnum
An integer followed by a dollar sign $ , to specify which number argument to treat in the conversion.
| Flag | Description |
|---|---|
| — | Left-justify within the given field width; Right justification is the default |
| + | Prefix positive numbers with a plus sign + ; Default only negative are prefixed with a negative sign. |
| (space) | Pads the result with spaces. This is the default. |
| 0 | Only left-pads numbers with zeros. With s specifiers this can also right-pad with zeros. |
| ‘ (char) | Pads the result with the character (char). |
Width
Either an integer that says how many characters (minimum) this conversion should result in, or * . If * is used, then the width is supplied as an additional integer value preceding the one formatted by the specifier.
Precision
- For e , E , f and F specifiers: this is the number of digits to be printed after the decimal point (by default, this is 6).
- For g , G , h and H specifiers: this is the maximum number of significant digits to be printed.
- For s specifier: it acts as a cutoff point, setting a maximum character limit to the string.
Note: If the period is specified without an explicit value for precision, 0 is assumed. If * is used, the precision is supplied as an additional integer value preceding the one formatted by the specifier.
Let P equal the precision if nonzero, 6 if the precision is omitted, or 1 if the precision is zero. Then, if a conversion with style E would have an exponent of X:
If P > X ≥ −4, the conversion is with style f and precision P − (X + 1). Otherwise, the conversion is with style e and precision P − 1.
The c type specifier ignores padding and width
Attempting to use a combination of the string and width specifiers with character sets that require more than one byte per character may result in unexpected results
Variables will be co-erced to a suitable type for the specifier:
| Type | Specifiers |
|---|---|
| string | s |
| int | d , u , c , o , x , X , b |
| float | e , E , f , F , g , G , h , H |
Return Values
Return array values as a formatted string according to format .
Errors/Exceptions
As of PHP 8.0.0, a ValueError is thrown if the number of arguments is zero. Prior to PHP 8.0.0, a E_WARNING was emitted instead.
As of PHP 8.0.0, a ValueError is thrown if [width] is less than zero or bigger than PHP_INT_MAX . Prior to PHP 8.0.0, a E_WARNING was emitted instead.
As of PHP 8.0.0, a ValueError is thrown if [precision] is less than zero or bigger than PHP_INT_MAX . Prior to PHP 8.0.0, a E_WARNING was emitted instead.
As of PHP 8.0.0, a ValueError is thrown when less arguments are given than required. Prior to PHP 8.0.0, false was returned and a E_WARNING emitted instead.
Changelog
| Version | Description |
|---|---|
| 8.0.0 | This function no longer returns false on failure. |
| 8.0.0 | Throw a ValueError if the number of arguments is zero; previously this function emitted a E_WARNING instead. |
| 8.0.0 | Throw a ValueError if [width] is less than zero or bigger than PHP_INT_MAX ; previously this function emitted a E_WARNING instead. |
| 8.0.0 | Throw a ValueError if [precision] is less than zero or bigger than PHP_INT_MAX ; previously this function emitted a E_WARNING instead. |
| 8.0.0 | Throw a ValueError when less arguments are given than required; previously this function emitted a E_WARNING instead. |
Examples
Example #1 vsprintf() : zero-padded integers
The above example will output:
See Also
- printf() — Output a formatted string
- sprintf() — Return a formatted string
- fprintf() — Write a formatted string to a stream
- vprintf() — Output a formatted string
- vfprintf() — Write a formatted string to a stream
- sscanf() — Parses input from a string according to a format
- fscanf() — Parses input from a file according to a format
- number_format() — Format a number with grouped thousands
- date() — Format a Unix timestamp
User Contributed Notes 10 notes
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);
/**
* 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
*/
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 );
>
?>
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.
/**
* 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 «» but without the dollar sign
$format = CREATE DATABASE IF NOT EXISTS ;
GRANT ALL PRIVILEGES ON .* TO »@»;
SET PASSWORD = PASSWORD(»);
SQL;
echo p ( $format , $args );
/*
Result:
CREATE DATABASE IF NOT EXISTS people;
GRANT ALL PRIVILEGES ON .* TO ‘staff’@’localhost’;
SET PASSWORD = PASSWORD(‘pass123’);
The « placeholder doesn’t exist as a matching key in `$args` so it’s returned as is.
*/
// With Ruby-like placeholders
$format = 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.
*/
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) Php array format string is equal to vnsprintf( ‘%2.0$d’, $array) Php array format string
vnsprintf( ‘%+2$d’, $array) Php array format string 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
$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»
?>