reference/strings/functions/sprintf.xml
f134250210702ab6280ab303b846679177d39f14
...
...
@@ -1,6 +1,6 @@
1
1
<?xml version="1.0" encoding="utf-8"?>
2
2
<!-- $Revision$ -->
3
-
<refentry xmlns="http://docbook.org/ns/docbook" xml:id="function.sprintf">
3
+
<refentry xml:id="function.sprintf" xmlns="http://docbook.org/ns/docbook">
4
4
<refnamediv>
5
5
<refname>sprintf</refname>
6
6
<refpurpose>Return a formatted string</refpurpose>
...
...
@@ -11,8 +11,7 @@
11
11
<methodsynopsis>
12
12
<type>string</type><methodname>sprintf</methodname>
13
13
<methodparam><type>string</type><parameter>format</parameter></methodparam>
14
-
<methodparam choice="opt"><type>mixed</type><parameter>args</parameter></methodparam>
15
-
<methodparam choice="opt"><type>mixed</type><parameter>...</parameter></methodparam>
14
+
<methodparam rep="repeat"><type>mixed</type><parameter>values</parameter></methodparam>
16
15
</methodsynopsis>
17
16
<para>
18
17
Returns a string produced according to the formatting string
...
...
@@ -24,200 +23,45 @@
24
23
&reftitle.parameters;
25
24
<para>
26
25
<variablelist>
26
+
&strings.parameter.format;
27
27
<varlistentry>
28
-
<term><parameter>format</parameter></term>
28
+
<term><parameter>values</parameter></term>
29
29
<listitem>
30
30
<para>
31
-
The format string is composed of zero or more directives:
32
-
ordinary characters (excluding <literal>%</literal>) that are
33
-
copied directly to the result, and <emphasis>conversion
34
-
specifications</emphasis>, each of which results in fetching its
35
-
own parameter. This applies to both <function>sprintf</function>
36
-
and <function>printf</function>.
37
31
</para>
38
-
<para>
39
-
Each conversion specification consists of a percent sign
40
-
(<literal>%</literal>), followed by one or more of these
41
-
elements, in order:
42
-
<orderedlist>
43
-
<listitem>
44
-
<simpara>
45
-
An optional <emphasis>sign specifier</emphasis> that forces a sign
46
-
(- or +) to be used on a number. By default, only the - sign is used
47
-
on a number if it's negative. This specifier forces positive numbers
48
-
to have the + sign attached as well, and was added in PHP 4.3.0.
49
-
</simpara>
50
-
</listitem>
51
-
<listitem>
52
-
<simpara>
53
-
An optional <emphasis>padding specifier</emphasis> that says
54
-
what character will be used for padding the results to the
55
-
right string size. This may be a space character or a
56
-
<literal>0</literal> (zero character). The default is to pad
57
-
with spaces. An alternate padding character can be specified
58
-
by prefixing it with a single quote (<literal>'</literal>).
59
-
See the examples below.
60
-
</simpara>
61
-
</listitem>
62
-
<listitem>
63
-
<simpara>
64
-
An optional <emphasis>alignment specifier</emphasis> that says
65
-
if the result should be left-justified or right-justified.
66
-
The default is right-justified; a <literal>-</literal>
67
-
character here will make it left-justified.
68
-
</simpara>
69
-
</listitem>
70
-
<listitem>
71
-
<simpara>
72
-
An optional number, a <emphasis>width specifier</emphasis>
73
-
that says how many characters (minimum) this conversion should
74
-
result in.
75
-
</simpara>
76
-
</listitem>
77
-
<listitem>
78
-
<simpara>
79
-
An optional <emphasis>precision specifier</emphasis> in the form
80
-
of a period (<literal>.</literal>) followed by an optional decimal digit string
81
-
that says how many decimal digits should be displayed for
82
-
floating-point numbers. When using this specifier on a string,
83
-
it acts as a cutoff point, setting a maximum character limit to
84
-
the string. Additionally, the character to use when padding a
85
-
number may optionally be specified between the period and the
86
-
digit.
87
-
</simpara>
88
-
</listitem>
89
-
<listitem>
90
-
<para>
91
-
A <emphasis>type specifier</emphasis> that says what type the
92
-
argument data should be treated as. Possible types:
93
-
<simplelist>
94
-
<member>
95
-
<literal>%</literal> - a literal percent character. No
96
-
argument is required.
97
-
</member>
98
-
<member>
99
-
<literal>b</literal> - the argument is treated as an
100
-
integer, and presented as a binary number.
101
-
</member>
102
-
<member>
103
-
<literal>c</literal> - the argument is treated as an
104
-
integer, and presented as the character with that ASCII
105
-
value.
106
-
</member>
107
-
<member>
108
-
<literal>d</literal> - the argument is treated as an
109
-
integer, and presented as a (signed) decimal number.
110
-
</member>
111
-
<member>
112
-
<literal>e</literal> - the argument is treated as scientific
113
-
notation (e.g. 1.2e+2).
114
-
The precision specifier stands for the number of digits after the
115
-
decimal point since PHP 5.2.1. In earlier versions, it was taken as
116
-
number of significant digits (one less).
117
-
</member>
118
-
<member>
119
-
<literal>E</literal> - like <literal>%e</literal> but uses
120
-
uppercase letter (e.g. 1.2E+2).
121
-
</member>
122
-
<member>
123
-
<literal>f</literal> - the argument is treated as a
124
-
float, and presented as a floating-point number (locale aware).
125
-
</member>
126
-
<member>
127
-
<literal>F</literal> - the argument is treated as a
128
-
float, and presented as a floating-point number (non-locale aware).
129
-
Available since PHP 4.3.10 and PHP 5.0.3.
130
-
</member>
131
-
<member>
132
-
<literal>g</literal> - shorter of <literal>%e</literal> and
133
-
<literal>%f</literal>.
134
-
</member>
135
-
<member>
136
-
<literal>G</literal> - shorter of <literal>%E</literal> and
137
-
<literal>%f</literal>.
138
-
</member>
139
-
<member>
140
-
<literal>o</literal> - the argument is treated as an
141
-
integer, and presented as an octal number.
142
-
</member>
143
-
<member>
144
-
<literal>s</literal> - the argument is treated as and
145
-
presented as a string.
146
-
</member>
147
-
<member>
148
-
<literal>u</literal> - the argument is treated as an
149
-
integer, and presented as an unsigned decimal number.
150
-
</member>
151
-
<member>
152
-
<literal>x</literal> - the argument is treated as an integer
153
-
and presented as a hexadecimal number (with lowercase
154
-
letters).
155
-
</member>
156
-
<member>
157
-
<literal>X</literal> - the argument is treated as an integer
158
-
and presented as a hexadecimal number (with uppercase
159
-
letters).
160
-
</member>
161
-
</simplelist>
162
-
</para>
163
-
</listitem>
164
-
</orderedlist>
165
-
</para>
166
-
<para>
167
-
Variables will be co-erced to a suitable type for the specifier:
168
-
<table xml:id="sprintf.coercion">
169
-
<title>Type Handling</title>
170
-
<tgroup cols="2">
171
-
<thead>
172
-
<row>
173
-
<entry>Type</entry>
174
-
<entry>Specifiers</entry>
175
-
</row>
176
-
</thead>
177
-
<tbody>
178
-
<row>
179
-
<entry><literal>string</literal></entry>
180
-
<entry><literal>s</literal></entry>
181
-
</row>
182
-
<row>
183
-
<entry><literal>integer</literal></entry>
184
-
<entry>
185
-
<literal>d</literal>,
186
-
<literal>u</literal>,
187
-
<literal>c</literal>,
188
-
<literal>o</literal>,
189
-
<literal>x</literal>,
190
-
<literal>X</literal>,
191
-
<literal>b</literal>
192
-
</entry>
193
-
</row>
194
-
<row>
195
-
<entry><literal>double</literal></entry>
196
-
<entry>
197
-
<literal>g</literal>,
198
-
<literal>G</literal>,
199
-
<literal>e</literal>,
200
-
<literal>E</literal>,
201
-
<literal>f</literal>,
202
-
<literal>F</literal>
203
-
</entry>
204
-
</row>
205
-
</tbody>
206
-
</tgroup>
207
-
</table>
208
-
</para>
209
-
<warning>
210
-
<para>
211
-
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
212
-
</para>
213
-
</warning>
214
-
<para>
215
-
The format string supports argument numbering/swapping. Here is an
216
-
example:
217
-
<example>
218
-
<title>Argument swapping</title>
219
-
<programlisting role="php">
220
-
<![CDATA[
32
+
</listitem>
33
+
</varlistentry>
34
+
</variablelist>
35
+
</para>
36
+
</refsect1>
37
+

38
+
<refsect1 role="returnvalues">
39
+
&reftitle.returnvalues;
40
+
<para>
41
+
Returns a string produced according to the formatting string
42
+
<parameter>format</parameter>.
43
+
</para>
44
+
</refsect1>
45
+

46
+
<refsect1 role="errors">
47
+
&reftitle.errors;
48
+
&strings.errors.sprintf;
49
+
</refsect1>
50
+

51
+
<refsect1 role="changelog">
52
+
&reftitle.changelog;
53
+
&strings.changelog.sprintf;
54
+
</refsect1>
55
+

56
+
<refsect1 role="examples">
57
+
&reftitle.examples;
58
+
<example>
59
+
<title>Argument swapping</title>
60
+
<para>
61
+
The format string supports argument numbering/swapping.
62
+
</para>
63
+
<programlisting role="php">
64
+
<![CDATA[
221
65
<?php
222
66
$num = 5;
223
67
$location = 'tree';
...
...
@@ -226,207 +70,93 @@ $format = 'There are %d monkeys in the %s';
226
70
echo sprintf($format, $num, $location);
227
71
?>
228
72
]]>
229
-
</programlisting>
230
-
</example>
231
-
This will output "There are 5 monkeys in the tree". But
232
-
imagine we are creating a format string in a separate file,
233
-
commonly because we would like to internationalize it and we
234
-
rewrite it as:
235
-
<example>
236
-
<title>Argument swapping</title>
237
-
<programlisting role="php">
73
+
</programlisting>
74
+
&example.outputs;
75
+
<screen>
238
76
<![CDATA[
77
+
There are 5 monkeys in the tree
78
+
]]>
79
+
</screen>
80
+
<para>
81
+
However imagine we are creating a format string in a separate file,
82
+
commonly because we would like to internationalize it and we rewrite it as:
83
+
</para>
84
+
<programlisting role="php">
85
+
<![CDATA[
239
86
<?php
240
87
$format = 'The %s contains %d monkeys';
241
88
echo sprintf($format, $num, $location);
242
89
?>
243
90
]]>
244
-
</programlisting>
245
-
</example>
246
-
We now have a problem. The order of the placeholders in the
247
-
format string does not match the order of the arguments in the
248
-
code. We would like to leave the code as is and simply indicate
249
-
in the format string which arguments the placeholders refer to.
250
-
We would write the format string like this instead:
251
-
<example>
252
-
<title>Argument swapping</title>
253
-
<programlisting role="php">
254
-
<![CDATA[
91
+
</programlisting>
92
+
<para>
93
+
We now have a problem. The order of the placeholders in the
94
+
format string does not match the order of the arguments in the
95
+
code. We would like to leave the code as is and simply indicate
96
+
in the format string which arguments the placeholders refer to.
97
+
We would write the format string like this instead:
98
+
</para>
99
+
<programlisting role="php">
100
+
<![CDATA[
255
101
<?php
256
102
$format = 'The %2$s contains %1$d monkeys';
257
103
echo sprintf($format, $num, $location);
258
104
?>
259
105
]]>
260
-
</programlisting>
261
-
</example>
262
-
An added benefit here is that you can repeat the placeholders without
263
-
adding more arguments in the code. For example:
264
-
<example>
265
-
<title>Argument swapping</title>
266
-
<programlisting role="php">
267
-
<![CDATA[
106
+
</programlisting>
107
+
<para>
108
+
An added benefit is that placeholders can be repeated without adding
109
+
more arguments in the code.
110
+
</para>
111
+
<programlisting role="php">
112
+
<![CDATA[
268
113
<?php
269
114
$format = 'The %2$s contains %1$d monkeys.
270
115
That\'s a nice %2$s full of %1$d monkeys.';
271
116
echo sprintf($format, $num, $location);
272
117
?>
273
118
]]>
274
-
</programlisting>
275
-
</example>
276
-
When using argument swapping, the <literal>n$</literal>
277
-
<emphasis>position specifier</emphasis> must come immediately
278
-
after the percent sign (<literal>%</literal>), before any other
279
-
specifiers, as shown in the example below.
280
-
<example>
281
-
<title>Specifying padding character</title>
282
-
<programlisting role="php">
283
-
<![CDATA[
284
-
<?php
285
-
echo sprintf("%'.9d\n", 123);
286
-
echo sprintf("%'.09d\n", 123);
287
-
?>
288
-
]]>
289
-
</programlisting>
290
-
&example.outputs;
291
-
<screen>
292
-
<![CDATA[
293
-
......123
294
-
000000123
295
-
]]>
296
-
</screen>
297
-
</example>
298
-
<example>
299
-
<title>Position specifier with other specifiers</title>
300
-
<programlisting role="php">
301
-
<![CDATA[
302
-
<?php
303
-
$format = 'The %2$s contains %1$04d monkeys';
304
-
echo sprintf($format, $num, $location);
305
-
?>
306
-
]]>
307
-
</programlisting>
308
-
&example.outputs;
309
-
<screen>
310
-
<![CDATA[
311
-
The tree contains 0005 monkeys
312
-
]]>
313
-
</screen>
314
-
</example>
315
-
</para>
316
-
<note>
317
-
<para>
318
-
Attempting to use a position specifier greater than
319
-
<constant>PHP_INT_MAX</constant> will result in
320
-
<function>sprintf</function> generating warnings.
321
-
</para>
322
-
</note>
323
-
<warning>
324
-
<para>
325
-
The <literal>c</literal> type specifier ignores padding and width
326
-
</para>
327
-
</warning>
328
-
</listitem>
329
-
</varlistentry>
330
-
<varlistentry>
331
-
<term><parameter>args</parameter></term>
332
-
<listitem>
333
-
<para>
334
-
</para>
335
-
</listitem>
336
-
</varlistentry>
337
-
<varlistentry>
338
-
<term><parameter>...</parameter></term>
339
-
<listitem>
340
-
<para>
341
-
</para>
342
-
</listitem>
343
-
</varlistentry>
344
-
</variablelist>
345
-
</para>
346
-
</refsect1>
347
-

348
-
<refsect1 role="returnvalues">
349
-
&reftitle.returnvalues;
350
-
<para>
351
-
Returns a string produced according to the formatting string
352
-
<parameter>format</parameter>.
353
-
</para>
354
-
</refsect1>
119
+
</programlisting>
120
+
<para>
121
+
When using argument swapping, the <literal>n$</literal>
122
+
<emphasis>position specifier</emphasis> must come immediately
123
+
after the percent sign (<literal>%</literal>), before any other
124
+
specifiers, as shown below.
125
+
</para>
126
+
</example>
355
127

356
-
<refsect1 role="examples">
357
-
&reftitle.examples;
358
128
<example>
359
-
<title><function>printf</function>: various examples</title>
129
+
<title>Specifying padding character</title>
360
130
<programlisting role="php">
361
131
<![CDATA[
362
132
<?php
363
-
$n = 43951789;
364
-
$u = -43951789;
365
-
$c = 65; // ASCII 65 is 'A'
366
-

367
-
// notice the double %%, this prints a literal '%' character
368
-
printf("%%b = '%b'\n", $n); // binary representation
369
-
printf("%%c = '%c'\n", $c); // print the ascii character, same as chr() function
370
-
printf("%%d = '%d'\n", $n); // standard integer representation
371
-
printf("%%e = '%e'\n", $n); // scientific notation
372
-
printf("%%u = '%u'\n", $n); // unsigned integer representation of a positive integer
373
-
printf("%%u = '%u'\n", $u); // unsigned integer representation of a negative integer
374
-
printf("%%f = '%f'\n", $n); // floating point representation
375
-
printf("%%o = '%o'\n", $n); // octal representation
376
-
printf("%%s = '%s'\n", $n); // string representation
377
-
printf("%%x = '%x'\n", $n); // hexadecimal representation (lower-case)
378
-
printf("%%X = '%X'\n", $n); // hexadecimal representation (upper-case)
379
-

380
-
printf("%%+d = '%+d'\n", $n); // sign specifier on a positive integer
381
-
printf("%%+d = '%+d'\n", $u); // sign specifier on a negative integer
133
+
echo sprintf("%'.9d\n", 123);
134
+
echo sprintf("%'.09d\n", 123);
382
135
?>
383
136
]]>
384
137
</programlisting>
385
138
&example.outputs;
386
139
<screen>
387
140
<![CDATA[
388
-
%b = '10100111101010011010101101'
389
-
%c = 'A'
390
-
%d = '43951789'
391
-
%e = '4.39518e+7'
392
-
%u = '43951789'
393
-
%u = '4251015507'
394
-
%f = '43951789.000000'
395
-
%o = '247523255'
396
-
%s = '43951789'
397
-
%x = '29ea6ad'
398
-
%X = '29EA6AD'
399
-
%+d = '+43951789'
400
-
%+d = '-43951789'
141
+
......123
142
+
000000123
401
143
]]>
402
144
</screen>
403
145
</example>
404
146
<example>
405
-
<title><function>printf</function>: string specifiers</title>
147
+
<title>Position specifier with other specifiers</title>
406
148
<programlisting role="php">
407
149
<![CDATA[
408
150
<?php
409
-
$s = 'monkey';
410
-
$t = 'many monkeys';
411
-

412
-
printf("[%s]\n", $s); // standard string output
413
-
printf("[%10s]\n", $s); // right-justification with spaces
414
-
printf("[%-10s]\n", $s); // left-justification with spaces
415
-
printf("[%010s]\n", $s); // zero-padding works on strings too
416
-
printf("[%'#10s]\n", $s); // use the custom padding character '#'
417
-
printf("[%10.10s]\n", $t); // left-justification but with a cutoff of 10 characters
151
+
$format = 'The %2$s contains %1$04d monkeys';
152
+
echo sprintf($format, $num, $location);
418
153
?>
419
154
]]>
420
155
</programlisting>
421
156
&example.outputs;
422
157
<screen>
423
158
<![CDATA[
424
-
[monkey]
425
-
[ monkey]
426
-
[monkey ]
427
-
[0000monkey]
428
-
[####monkey]
429
-
[many monke]
159
+
The tree contains 0005 monkeys
430
160
]]>
431
161
</screen>
432
162
</example>
...
...
@@ -448,12 +178,20 @@ $isodate = sprintf("%04d-%02d-%02d", $year, $month, $day);
448
178
$money1 = 68.75;
449
179
$money2 = 54.35;
450
180
$money = $money1 + $money2;
451
-
// echo $money will output "123.1";
181
+
echo $money;
182
+
echo "\n";
452
183
$formatted = sprintf("%01.2f", $money);
453
-
// echo $formatted will output "123.10"
184
+
echo $formatted;
454
185
?>
455
186
]]>
456
187
</programlisting>
188
+
&example.outputs;
189
+
<screen>
190
+
<![CDATA[
191
+
123.1
192
+
123.10
193
+
]]>
194
+
</screen>
457
195
</example>
458
196
<example>
459
197
<title><function>sprintf</function>: scientific notation</title>
...
...
@@ -462,10 +200,16 @@ $formatted = sprintf("%01.2f", $money);
462
200
<?php
463
201
$number = 362525200;
464
202

465
-
echo sprintf("%.3e", $number); // outputs 3.625e+8
203
+
echo sprintf("%.3e", $number);
466
204
?>
467
205
]]>
468
206
</programlisting>
207
+
&example.outputs;
208
+
<screen>
209
+
<![CDATA[
210
+
3.625e+8
211
+
]]>
212
+
</screen>
469
213
</example>
470
214
</refsect1>
471
215

...
...
@@ -474,9 +218,12 @@ echo sprintf("%.3e", $number); // outputs 3.625e+8
474
218
<para>
475
219
<simplelist>
476
220
<member><function>printf</function></member>
221
+
<member><function>fprintf</function></member>
222
+
<member><function>vprintf</function></member>
223
+
<member><function>vsprintf</function></member>
224
+
<member><function>vfprintf</function></member>
477
225
<member><function>sscanf</function></member>
478
226
<member><function>fscanf</function></member>
479
-
<member><function>vsprintf</function></member>
480
227
<member><function>number_format</function></member>
481
228
<member><function>date</function></member>
482
229
</simplelist>
...
...
@@ -484,7 +231,6 @@ echo sprintf("%.3e", $number); // outputs 3.625e+8
484
231
</refsect1>
485
232

486
233
</refentry>
487
-

488
234
<!-- Keep this comment at the end of the file
489
235
Local variables:
490
236
mode: sgml
491
237



Tools (Spanish Manual)