PHP 8.3.0 RC 6 available for testing

vprintf

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

vprintf输出格式化字符串

说明

vprintf(string $format, array $values): int

根据 formatsprintf() 函数文档中有相关描述)参数指定的格式,在一个格式化字符串中显示多个值。

作用与 printf() 函数类似,但是接收一个数组参数,而不是一系列可变数量的参数。

参数

format

format 字符串通常由零或多个指令组成:普通字符(不包含 %)——直接复制到结果,转换规范——获取每个参数的结果。

转换规范遵循此原型: %[argnum$][flags][width][.precision]specifier.

Argnum

整数后跟美元符号 $,用于指定转换中要处理的参数数量。

标志
标志 说明
- 在指定字段宽度时左对齐,默认右对齐
+ 正数的加号 +前缀,默认负数的前缀是负号。
(space) 空格填充结果。这是默认设置。
0 仅用 0 进行左侧数字填充。使用 s 标志符可以右侧填充。
'(char) 用字符(char)填充结果。

Width

要么是整数,表示转换结果应该有多少个字符(最少),要么是 *。如果使用 *,那么宽度将作为额外的整数值提供,位于格式化符号之前。

Precision

小数点 .,可选的后跟整数或者 *,其含义取决于格式化符号:

  • eEfF 标志符:小数点后需要打印的位数(默认是 6)。
  • gGhH 标志符:这是要打印的最大有效位数。
  • s 标志符:充当分界点,为字符串设置最大字符限制。

注意: 如果小数点没有明确的精度值,则假设是 0。如果使用 *,则精度将作为额外的整数值提供,位于格式化符号之前。

标志符
标志符 说明
% 字面意思的百分号字符。不需要参数。
b 参数视为整数并以二进制数字呈现。
c 参数视为整数并以 ASCII 字符呈现。
d 参数视为整数并以(有符号)十进制数字呈现。
e 参数当做科学符号处理(例如 1.2e+2)。
E e 标志符相同,但使用大写字母(例如 1.2E+2)。
f 参数当做浮点数处理且作为浮点数呈现(locale aware)。
F 参数当做浮点数处理且作为浮点数呈现(non-locale aware)。
g

通用格式。

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.

G Like the g specifier but uses E and f.
h Like the g specifier but uses F. Available as of PHP 8.0.0.
H Like the g specifier but uses E and F. Available as of PHP 8.0.0.
o 参数视为整数并以八进制数字来呈现。
s 参数视为字符串来呈现。
u 参数视为整数并以无符号十进制数字呈现。
x 参数视为整数并作为十六进制数字呈现(带小写字母)。
X 参数视为整数并作为十六进制数字呈现(带大写字母)。

警告

c 类型标志符忽略填充和宽度

警告

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

变量将会强制转换为适合标志符的类型:

类型处理
类型 标志符
string s
int d, u, c, o, x, X, b
float e, E, f, F, g, G, h, H

values

返回值

返回输出字符串的长度。

错误/异常

从 PHP 8.0.0 开始,如果参数个数为零,将抛出 ValueError。在 PHP 8.0.0 之前,会发出 E_WARNING

从 PHP 8.0.0 开始,如果 [width] 小于零或大于 PHP_INT_MAX,则会抛出 ValueError。在 PHP 8.0.0 之前,会发出 E_WARNING

从 PHP 8.0.0 开始,如果 [precision] 小于零或大于 PHP_INT_MAX,则会抛出 ValueError。在 PHP 8.0.0 之前,会发出 E_WARNING

从 PHP 8.0.0 开始,当传递的参数少于所需的参数时会抛出 ValueError。在 PHP 8.0.0 之前,返回 false 并发出 E_WARNING

更新日志

版本 说明
8.0.0 此函数失败时不再返回 false
8.0.0 如果参数个数为零则抛出 ValueError;以前该函数则会发出 E_WARNING
8.0.0 如果 [width] 小于零或大于 PHP_INT_MAX,则抛出 ValueError;以前该函数则会发出 E_WARNING
8.0.0 如果 [precision] 小于零或大于 PHP_INT_MAX,则抛出 ValueError;以前该函数则会发出 E_WARNING
8.0.0 当传递的参数少于所需的参数时抛出 ValueError;以前该函数则会发出 E_WARNING

示例

示例 #1 vprintf():补零整数

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

以上示例会输出:

 
1988-08-01

参见

add a note

User Contributed Notes 8 notes

up
10
steve at stevelockwood dot net
8 years ago
If, instead of an array, you pass an object PHP will automatically cast the object as an array so you can use it directly in vprintf.
<?php
$object
= new stdClass();
$object->Property1 = 'Value 1';
$object->Property2 = 'Value 2';
vprintf('%-20s %-20s', $object);

/* will output
Value 1 Value 2
*/
?>
up
1
phpcoder at gmail dot com
4 years ago
Using the ... operator, vprintf($format, $array) is basically just printf($format, ...$array).
up
1
tehjosh at gamingg dot net
16 years ago
To toolofthesystem at gmail dot com:

You don't need to use output buffering with vprintf() because you can use vsprintf(), which has the same functionality as vprintf(), except that it returns the resulting string instead of outputting it.
up
0
taken from &#34;Php Phrasebook&#34;
15 years ago
<?php
$string
= 'The site runs on PHP '.phpversion();
preg_match('/php ((\d)\.\d\.\d+)/i',$string,$matches);
print_r($matches);
vprintf('Match: %s<br /> Version %s; Major:%d.',$matches);
?>

output:
Array ( [0] => PHP 5.2.5 [1] => 5.2.5 [2] => 5 )
Match: PHP 5.2.5 Version 5.2.5; Major:5.

For preg_match:

If matches is provided, then it is filled with the results of search. $matches[0] will contain the text that matched the full pattern, $matches[1] will have the text that matched the first captured parenthesized subpattern, and so on.
up
-1
Chris
11 years ago
Another way to display arrays is use an array_walk(). This can be useful inline echo/print where a foreach wouldn't work, e.g.

<?php
echo "These errors: ", (unset)array_walk($msgs, function($a) { echo "<p>$a</p>"; } ), "must be corrected.";
?>
up
-1
toolofthesystem at gmail dot com
16 years ago
This function comes useful sometimes when trying to list information returned from MySQL:

function print_sql($query,$printf){
$sql_sql = mysql_query($query);
while($sql = mysql_fetch_row($sql_sql)){
vprintf($printf,$sql);
}
}

Unfortunately, this seems to sneak its way past output buffering when I tried creating an argument to allow it to be contained in a returned string... either that or I didn't do it right.
up
-2
badcop666 at hotmail dot com
15 years ago
For blocks of text, sprintf() is slow according to my tests.

Also, having the mapping between place-holders and the list of actual variables or datastructures often makes this code difficult to read. But the printf() family are widely supported and have a huge range of nice features. Performance is a cold mistress though!

From an ease-of-reading and maintenance, debugging point of view, I much prefer HEREDOC and "...{$variable}..." methods.

For a block of HTML markup with place holders, the fastest by far was:-

?>
<div> markup etc<?= $variable ?>more markup
<?

My tests comprised 20 runs of a loop of 1 million iterations with output buffering, ditching the buffer on each loop.

The timings ranged from average 2.1msec/million repetitions for the <?= $var ?> method up to 7.6msec/million using printf().

I'll try some benchmarking tools too, since I just wrote this myself and it could be introducing bias, but they've run on dev servers with low load.

Hopefully interesting.
up
-2
caleb at tekhawk dot com
16 years ago
i know that you can use %1$s or %3$s to select the first or third string but how can you or can you use array names to select it

something like %'user'$s $'email'$s

i tend to add things to my databases over time and this could save loads of recoding
To Top