PHP 8.3.4 Released!

vsprintf

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

vsprintfBiçemli bir dizge döndürür

Açıklama

vsprintf(string $biçem, array $değerler): string

Değişken sayıda değer yerine bunları bir dizi içinde kabul etmesi dışında sprintf() gibidir.

Bağımsız Değişkenler

biçem

Biçem dizgesi sıfır veya daha fazla yönergeden oluşur: doğrudan sonuca kopyalanmış sıradan karakterler (% hariç) ve dönüşüm belirtimleri, her biri kendi bağımsız değişkeninin getirilmesiyle sonuçlanır.

Bir dönüşüm belirtiminin sözdizimi: %[degnum$][seçenekler][genişlik][.hassasiyet]belirteç.

degnum

Ardına bir dolar imi $ konmuş bir tamsayı; dönüşümde ele alınacak bağımsız değişken sayısını belirler.

seçenekler
Seçenek Açıklama
- Verilen alan genişliğinde sola dayalı; Sağa dayalılık öntanımlıdır.
+ Pozitif sayıların önüne artı imi konur; Öntanımlı olarak sadece negatif sayılara eksi imi konur.
(boşluk) Sonuca boşluklarla dolgu yapar. Bu öntanımlıdır.
0 Sayılar sadece soldan sıfırla doldurulur. s belirteçleri ile sağ taraf da sıfırla doldurulur.
'(krk) Sonuca (krk) karakteri ile dolgu yapılır.

genişlik

Bu dönüşümün kaç karakterle sonuçlanacağının belirtildiği tamsayı veya *. * kullanılmışsa, genişlik, belirtici tarafından biçimlendirilmiş değerden önce ek bir tamsayı değeri olarak sağlanır.

hassasiyet

Bir nokta . ve ardından anlamı belirtece bağlı olan seçimlik bir tamsayı veya *:

  • e, E, f ve F belirteçleri için: ondalık noktadan sonra yazdırılacak rakam sayısı (6 öntanımlıdır)
  • g ve G, h ve H belirteçleri için: yazdırılacak maksimum anlamlı basamak sayısı.
  • s belirteci için: dizeye azami karakter sınırı koyan bir kesme noktası gibi davranır.

Bilginize: Nokta, hassasiyet için açık bir değer olmadan belirtilirse, 0 varsayılır. * kullanılmışsa, genişlik, belirtici tarafından biçimlendirilmiş değerden önce ek bir tamsayı değeri olarak sağlanır.

Belirteçler
Belirteç Açıklama
% Yüzde karakteri. Değer gerekmez.
b Değer bir tamsayı olarak ele alınır ve ikil bir sayı olarak gösterilir.
c Değer bir tamsayı olarak ele alınır ve ASCII bir karakter olarak gösterilir.
d Değer bir tamsayı olarak ele alınır ve (işaretli) bir ondalık sayı olarak gösterilir.
e Değer bilimsel bir gösterim (örn. 1.2e+2) olarak ele alınır. Hassasiyet belirteci,ondalık noktadan sonraki basamakların sayısını ifade eder.
E e belirteci gibi, farklı olarak büyük harf kullanır (örn. 1.2E+2).
f Değer kayan noktalı sayı olarak ele alınır ve kayan noktalı sayı olarak gösterilir (yerele uygun).
F Değer kayan noktalı sayı olarak ele alınır ve kayan noktalı sayı olarak gösterilir (yerele bakmaz) PHP 5.0.3 ve sonrasında kullanılabilir.
g

Genel biçem.

P sıfırdan farklı hassasiyet olsun, hassasiyet verilmemişse 6, hassasiyet sıfır ise 1 olsun. E tarzındaki dönüşümün üssü X ise:

P > X ≥ −4 ise, dönüşüm f tarzı ve hassasiyet P − (X + 1) olur. Aksi takdirde, dönüşüm e tarzı ve hassasiyet P − 1 olur.

G g gibidir fakat E ve f kullanır.
h g gibidir fakat F kullanır. PHP 8.0.0 ve sonrasında kullanılabilir.
H ggibidir fakat E ve F kullanır. PHP 8.0.0 ve sonrasında kullanılabilir.
o Değer bir tamsayı olarak ele alınır ve sekizlik bir sayı olarak gösterilir.
s Değer bir dizge olarak ele alınır ve gösterilir.
u Değer bir tamsayı olarak ele alınır ve işaretsiz bir ondalık sayı olarak gösterilir.
x Değer bir tamsayı olarak ele alınır ve onaltılık bir sayı olarak gösterilir (küçük harfli).
X Değer bir tamsayı olarak ele alınır ve onaltılık bir sayı olarak gösterilir (büyük harfli).

Uyarı

c tür belirteci dolguyu ve genişliği yoksayar.

Uyarı

Karakter başına birden fazla bayt gerektiren karakter kümeleriyle dizge ve genişlik belirteçlerini bir arada kullanmaya çalışmak, beklenmeyen sonuçlar verebilir

Değişkenler, belirteç için uygun bir türe zorlanacaktır:

Tür Yönetimi
Tür Belirteçler
string s
int d, u, c, o, x, X, b
double e, E, f, F, g, G, h, H

değerler

biçem dizgesine göre değerlendirilecek değerlerden oluşan dizi.

Dönen Değerler

değerler dizisindeki değerler biçem dizgesine göre değerlendirilerek, oluşturulan dizge döner.

Hatalar/İstisnalar

PHP 8.0.0 ve sonrasında, bağımsız değişken sayısı sıfırsa ValueError oluşuyor. PHP 8.0.0 öncesinde bunun yerine bir E_WARNING uyarısı verilirdi.

PHP 8.0.0 ve sonrasında, [width] (genişlik) sıfırdan küçükse veya PHP_INT_MAX'tan büyükse bir ValueError oluşuyor. PHP 8.0.0 öncesinde, bir E_WARNING uyarısı verilirdi.

PHP 8.0.0 ve sonrasında, [precision] (hassasiyet) sıfırdan küçükse veya PHP_INT_MAX'tan büyükse bir ValueError oluşuyor. PHP 8.0.0 öncesinde, bir E_WARNING uyarısı verilirdi.

PHP 8.0.0 ve sonrasında, gereğinden daha az bağımsız değişken verildiğinde bir ArgumentCountError oluşuyor. PHP 8.0.0 öncesinde, bir E_WARNING uyarısı verilirdi.

Sürüm Bilgisi

Sürüm: Açıklama
8.0.0 Bu işlev başarısızlık durumunda artık false döndürmüyor.
8.0.0 Bağımsız değişken sayısı sıfırsa ValueError oluşuyor. Evvelce bunun yerine bir E_WARNING uyarısı verilirdi.
8.0.0 [width] (genişlik) sıfırdan küçükse veya PHP_INT_MAX'tan büyükse bir ValueError oluşuyor; evvelce bir E_WARNING uyarısı verilirdi.
8.0.0 [precision] (hassasiyet) sıfırdan küçükse veya PHP_INT_MAX'tan büyükse bir ValueError oluşuyor; evvelce bir E_WARNING uyarısı verilirdi.
8.0.0 Gereğinden daha az bağımsız değişken verildiğinde bir ArgumentCountError oluşuyor; evvelce bir E_WARNING uyarısı verilirdi.

Örnekler

Örnek 1 - vsprintf() ve sıfır dolgulu tamsayılar

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

Yukarıdaki örneğin çıktısı:

1988-08-01

Ayrıca Bakınız

  • printf() - Biçemli bir dizge çıktılar
  • sprintf() - Biçemli bir dizge döndürür
  • fprintf() - Biçemli dizgeyi bir akıma yazar
  • vprintf() - Biçemli bir dizge çıktılar
  • vfprintf() - Biçemli dizgeyi bir akıma yazar
  • sscanf() - Girdi dizgesini belli bir biçeme göre yorumlar
  • fscanf() - Bir dosyadaki girdiyi belli bir biçeme göre çözümler
  • number_format() - Sayıyı binlik bölümlere ayırır
  • date() - Unix zaman damgasını biçimlendirir

add a note

User Contributed Notes 10 notes

up
46
spectrumcat
7 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);
up
13
Josef Kufner
11 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);
}
?>
up
4
crash
2 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.
up
1
steven at nevvix dot com
5 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.
*/
up
4
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>';
}
}
?>
up
4
Roadster
17 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.
up
3
www dot wesley at gmail dot com
15 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"
?>
up
2
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;
?>
up
1
jed at NOSPAM dot jed dot bz
19 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.
up
1
ASchmidt at Anamera dot net
6 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 );
To Top