mirror of
https://github.com/sigmasternchen/php-doc-en
synced 2025-03-19 10:28:54 +00:00
87455002a7
Fixes doc bug #61531 (Integer Overflow in all printf functions). git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@328312 c90b9560-bf6c-de11-be94-00142212c4b1
457 lines
14 KiB
XML
457 lines
14 KiB
XML
<?xml version="1.0" encoding="utf-8"?>
|
|
<!-- $Revision$ -->
|
|
<refentry xmlns="http://docbook.org/ns/docbook" xml:id="function.sprintf">
|
|
<refnamediv>
|
|
<refname>sprintf</refname>
|
|
<refpurpose>Return a formatted string</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsect1 role="description">
|
|
&reftitle.description;
|
|
<methodsynopsis>
|
|
<type>string</type><methodname>sprintf</methodname>
|
|
<methodparam><type>string</type><parameter>format</parameter></methodparam>
|
|
<methodparam choice="opt"><type>mixed</type><parameter>args</parameter></methodparam>
|
|
<methodparam choice="opt"><type>mixed</type><parameter>...</parameter></methodparam>
|
|
</methodsynopsis>
|
|
<para>
|
|
Returns a string produced according to the formatting string
|
|
<parameter>format</parameter>.
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1 role="parameters">
|
|
&reftitle.parameters;
|
|
<para>
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><parameter>format</parameter></term>
|
|
<listitem>
|
|
<para>
|
|
The format string is composed of zero or more directives:
|
|
ordinary characters (excluding <literal>%</literal>) that are
|
|
copied directly to the result, and <emphasis>conversion
|
|
specifications</emphasis>, each of which results in fetching its
|
|
own parameter. This applies to both <function>sprintf</function>
|
|
and <function>printf</function>.
|
|
</para>
|
|
<para>
|
|
Each conversion specification consists of a percent sign
|
|
(<literal>%</literal>), followed by one or more of these
|
|
elements, in order:
|
|
<orderedlist>
|
|
<listitem>
|
|
<simpara>
|
|
An optional <emphasis>sign specifier</emphasis> that forces a sign
|
|
(- or +) to be used on a number. By default, only the - sign is used
|
|
on a number if it's negative. This specifier forces positive numbers
|
|
to have the + sign attached as well, and was added in PHP 4.3.0.
|
|
</simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara>
|
|
An optional <emphasis>padding specifier</emphasis> that says
|
|
what character will be used for padding the results to the
|
|
right string size. This may be a space character or a
|
|
<literal>0</literal> (zero character). The default is to pad
|
|
with spaces. An alternate padding character can be specified
|
|
by prefixing it with a single quote (<literal>'</literal>).
|
|
See the examples below.
|
|
</simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara>
|
|
An optional <emphasis>alignment specifier</emphasis> that says
|
|
if the result should be left-justified or right-justified.
|
|
The default is right-justified; a <literal>-</literal>
|
|
character here will make it left-justified.
|
|
</simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara>
|
|
An optional number, a <emphasis>width specifier</emphasis>
|
|
that says how many characters (minimum) this conversion should
|
|
result in.
|
|
</simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara>
|
|
An optional <emphasis>precision specifier</emphasis> in the form
|
|
of a period (`.') followed by an optional decimal digit string
|
|
that says how many decimal digits should be displayed for
|
|
floating-point numbers. When using this specifier on a string,
|
|
it acts as a cutoff point, setting a maximum character limit to
|
|
the string.
|
|
</simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
A <emphasis>type specifier</emphasis> that says what type the
|
|
argument data should be treated as. Possible types:
|
|
<simplelist>
|
|
<member>
|
|
<literal>%</literal> - a literal percent character. No
|
|
argument is required.
|
|
</member>
|
|
<member>
|
|
<literal>b</literal> - the argument is treated as an
|
|
integer, and presented as a binary number.
|
|
</member>
|
|
<member>
|
|
<literal>c</literal> - the argument is treated as an
|
|
integer, and presented as the character with that ASCII
|
|
value.
|
|
</member>
|
|
<member>
|
|
<literal>d</literal> - the argument is treated as an
|
|
integer, and presented as a (signed) decimal number.
|
|
</member>
|
|
<member>
|
|
<literal>e</literal> - the argument is treated as scientific
|
|
notation (e.g. 1.2e+2).
|
|
The precision specifier stands for the number of digits after the
|
|
decimal point since PHP 5.2.1. In earlier versions, it was taken as
|
|
number of significant digits (one less).
|
|
</member>
|
|
<member>
|
|
<literal>E</literal> - like <literal>%e</literal> but uses
|
|
uppercase letter (e.g. 1.2E+2).
|
|
</member>
|
|
<member>
|
|
<literal>u</literal> - the argument is treated as an
|
|
integer, and presented as an unsigned decimal number.
|
|
</member>
|
|
<member>
|
|
<literal>f</literal> - the argument is treated as a
|
|
float, and presented as a floating-point number (locale aware).
|
|
</member>
|
|
<member>
|
|
<literal>F</literal> - the argument is treated as a
|
|
float, and presented as a floating-point number (non-locale aware).
|
|
Available since PHP 4.3.10 and PHP 5.0.3.
|
|
</member>
|
|
<member>
|
|
<literal>g</literal> - shorter of <literal>%e</literal> and
|
|
<literal>%f</literal>.
|
|
</member>
|
|
<member>
|
|
<literal>G</literal> - shorter of <literal>%E</literal> and
|
|
<literal>%f</literal>.
|
|
</member>
|
|
<member>
|
|
<literal>o</literal> - the argument is treated as an
|
|
integer, and presented as an octal number.
|
|
</member>
|
|
<member>
|
|
<literal>s</literal> - the argument is treated as and
|
|
presented as a string.
|
|
</member>
|
|
<member>
|
|
<literal>x</literal> - the argument is treated as an integer
|
|
and presented as a hexadecimal number (with lowercase
|
|
letters).
|
|
</member>
|
|
<member>
|
|
<literal>X</literal> - the argument is treated as an integer
|
|
and presented as a hexadecimal number (with uppercase
|
|
letters).
|
|
</member>
|
|
</simplelist>
|
|
</para>
|
|
</listitem>
|
|
</orderedlist>
|
|
</para>
|
|
<para>
|
|
The format string supports argument numbering/swapping. Here is an
|
|
example:
|
|
<example>
|
|
<title>Argument swapping</title>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
$num = 5;
|
|
$location = 'tree';
|
|
|
|
$format = 'There are %d monkeys in the %s';
|
|
echo sprintf($format, $num, $location);
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
</example>
|
|
This will output "There are 5 monkeys in the tree". But
|
|
imagine we are creating a format string in a separate file,
|
|
commonly because we would like to internationalize it and we
|
|
rewrite it as:
|
|
<example>
|
|
<title>Argument swapping</title>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
$format = 'The %s contains %d monkeys';
|
|
echo sprintf($format, $num, $location);
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
</example>
|
|
We now have a problem. The order of the placeholders in the
|
|
format string does not match the order of the arguments in the
|
|
code. We would like to leave the code as is and simply indicate
|
|
in the format string which arguments the placeholders refer to.
|
|
We would write the format string like this instead:
|
|
<example>
|
|
<title>Argument swapping</title>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
$format = 'The %2$s contains %1$d monkeys';
|
|
echo sprintf($format, $num, $location);
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
</example>
|
|
An added benefit here is that you can repeat the placeholders without
|
|
adding more arguments in the code. For example:
|
|
<example>
|
|
<title>Argument swapping</title>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
$format = 'The %2$s contains %1$d monkeys.
|
|
That\'s a nice %2$s full of %1$d monkeys.';
|
|
echo sprintf($format, $num, $location);
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
</example>
|
|
When using argument swapping, the <literal>n$</literal>
|
|
<emphasis>position specifier</emphasis> must come immediately
|
|
after the percent sign (<literal>%</literal>), before any other
|
|
specifiers, as shown in the example below.
|
|
<example>
|
|
<title>Position specifier with other specifiers</title>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
$format = 'The %2$s contains %1$04d monkeys';
|
|
echo sprintf($format, $num, $location);
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
&example.outputs;
|
|
<screen>
|
|
<![CDATA[
|
|
The tree contains 0005 monkeys
|
|
]]>
|
|
</screen>
|
|
</example>
|
|
</para>
|
|
<note>
|
|
<para>
|
|
Attempting to use a position specifier greater than
|
|
<constant>PHP_INT_MAX</constant> will result in
|
|
<function>sprintf</function> generating warnings.
|
|
</para>
|
|
</note>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><parameter>args</parameter></term>
|
|
<listitem>
|
|
<para>
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><parameter>...</parameter></term>
|
|
<listitem>
|
|
<para>
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1 role="returnvalues">
|
|
&reftitle.returnvalues;
|
|
<para>
|
|
Returns a string produced according to the formatting string
|
|
<parameter>format</parameter>.
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1 role="changelog">
|
|
&reftitle.changelog;
|
|
<para>
|
|
<informaltable>
|
|
<tgroup cols="2">
|
|
<thead>
|
|
<row>
|
|
<entry>&Version;</entry>
|
|
<entry>&Description;</entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row>
|
|
<entry>4.0.6</entry>
|
|
<entry>
|
|
Support for argument numbering/swapping was added
|
|
</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</informaltable>
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1 role="examples">
|
|
&reftitle.examples;
|
|
<example>
|
|
<title><function>printf</function>: various examples</title>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
$n = 43951789;
|
|
$u = -43951789;
|
|
$c = 65; // ASCII 65 is 'A'
|
|
|
|
// notice the double %%, this prints a literal '%' character
|
|
printf("%%b = '%b'\n", $n); // binary representation
|
|
printf("%%c = '%c'\n", $c); // print the ascii character, same as chr() function
|
|
printf("%%d = '%d'\n", $n); // standard integer representation
|
|
printf("%%e = '%e'\n", $n); // scientific notation
|
|
printf("%%u = '%u'\n", $n); // unsigned integer representation of a positive integer
|
|
printf("%%u = '%u'\n", $u); // unsigned integer representation of a negative integer
|
|
printf("%%f = '%f'\n", $n); // floating point representation
|
|
printf("%%o = '%o'\n", $n); // octal representation
|
|
printf("%%s = '%s'\n", $n); // string representation
|
|
printf("%%x = '%x'\n", $n); // hexadecimal representation (lower-case)
|
|
printf("%%X = '%X'\n", $n); // hexadecimal representation (upper-case)
|
|
|
|
printf("%%+d = '%+d'\n", $n); // sign specifier on a positive integer
|
|
printf("%%+d = '%+d'\n", $u); // sign specifier on a negative integer
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
&example.outputs;
|
|
<screen>
|
|
<![CDATA[
|
|
%b = '10100111101010011010101101'
|
|
%c = 'A'
|
|
%d = '43951789'
|
|
%e = '4.39518e+7'
|
|
%u = '43951789'
|
|
%u = '4251015507'
|
|
%f = '43951789.000000'
|
|
%o = '247523255'
|
|
%s = '43951789'
|
|
%x = '29ea6ad'
|
|
%X = '29EA6AD'
|
|
%+d = '+43951789'
|
|
%+d = '-43951789'
|
|
]]>
|
|
</screen>
|
|
</example>
|
|
<example>
|
|
<title><function>printf</function>: string specifiers</title>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
$s = 'monkey';
|
|
$t = 'many monkeys';
|
|
|
|
printf("[%s]\n", $s); // standard string output
|
|
printf("[%10s]\n", $s); // right-justification with spaces
|
|
printf("[%-10s]\n", $s); // left-justification with spaces
|
|
printf("[%010s]\n", $s); // zero-padding works on strings too
|
|
printf("[%'#10s]\n", $s); // use the custom padding character '#'
|
|
printf("[%10.10s]\n", $t); // left-justification but with a cutoff of 10 characters
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
&example.outputs;
|
|
<screen>
|
|
<![CDATA[
|
|
[monkey]
|
|
[ monkey]
|
|
[monkey ]
|
|
[0000monkey]
|
|
[####monkey]
|
|
[many monke]
|
|
]]>
|
|
</screen>
|
|
</example>
|
|
<example>
|
|
<title><function>sprintf</function>: zero-padded integers</title>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
$isodate = sprintf("%04d-%02d-%02d", $year, $month, $day);
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
</example>
|
|
<example>
|
|
<title><function>sprintf</function>: formatting currency</title>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
$money1 = 68.75;
|
|
$money2 = 54.35;
|
|
$money = $money1 + $money2;
|
|
// echo $money will output "123.1";
|
|
$formatted = sprintf("%01.2f", $money);
|
|
// echo $formatted will output "123.10"
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
</example>
|
|
<example>
|
|
<title><function>sprintf</function>: scientific notation</title>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
$number = 362525200;
|
|
|
|
echo sprintf("%.3e", $number); // outputs 3.625e+8
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
</example>
|
|
</refsect1>
|
|
|
|
<refsect1 role="seealso">
|
|
&reftitle.seealso;
|
|
<para>
|
|
<simplelist>
|
|
<member><function>printf</function></member>
|
|
<member><function>sscanf</function></member>
|
|
<member><function>fscanf</function></member>
|
|
<member><function>vsprintf</function></member>
|
|
<member><function>number_format</function></member>
|
|
</simplelist>
|
|
</para>
|
|
</refsect1>
|
|
|
|
</refentry>
|
|
|
|
<!-- Keep this comment at the end of the file
|
|
Local variables:
|
|
mode: sgml
|
|
sgml-omittag:t
|
|
sgml-shorttag:t
|
|
sgml-minimize-attributes:nil
|
|
sgml-always-quote-attributes:t
|
|
sgml-indent-step:1
|
|
sgml-indent-data:t
|
|
indent-tabs-mode:nil
|
|
sgml-parent-document:nil
|
|
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
|
|
sgml-exposed-tags:nil
|
|
sgml-local-catalogs:nil
|
|
sgml-local-ecat-files:nil
|
|
End:
|
|
vim600: syn=xml fen fdm=syntax fdl=2 si
|
|
vim: et tw=78 syn=sgml
|
|
vi: ts=1 sw=1
|
|
-->
|