Patch sprintf_related_functions_improvement for Strings related Bug #77451
Patch version 2019-03-20 17:50 UTC
Return to Bug #77451 |
Download this patch
Patch Revisions:
Developer: girgias@php.net
Index: en/reference/strings/functions/vprintf.xml
--- en/reference/strings/functions/vprintf.xml
+++ en/reference/strings/functions/vprintf.xml
@@ -28,15 +28,7 @@
&reftitle.parameters;
<para>
<variablelist>
- <varlistentry>
- <term><parameter>format</parameter></term>
- <listitem>
- <para>
- See <function>sprintf</function> for a description of
- <parameter>format</parameter>.
- </para>
- </listitem>
- </varlistentry>
+ &strings.parameter.format;
<varlistentry>
<term><parameter>args</parameter></term>
<listitem>
@@ -63,10 +55,16 @@
<programlisting role="php">
<![CDATA[
<?php
-vprintf("%04d-%02d-%02d", explode('-', '1988-8-1')); // 1988-08-01
+vprintf("%04d-%02d-%02d", explode('-', '1988-8-1'));
?>
]]>
</programlisting>
+ &example.outputs;
+ <screen>
+<![CDATA[
+1988-08-01
+]]>
+ </screen>
</example>
</para>
</refsect1>
@@ -77,7 +75,13 @@
<simplelist>
<member><function>printf</function></member>
<member><function>sprintf</function></member>
+ <member><function>fprintf</function></member>
<member><function>vsprintf</function></member>
+ <member><function>vfprintf</function></member>
+ <member><function>sscanf</function></member>
+ <member><function>fscanf</function></member>
+ <member><function>number_format</function></member>
+ <member><function>date</function></member>
</simplelist>
</para>
</refsect1>
Index: en/reference/strings/functions/printf.xml
--- en/reference/strings/functions/printf.xml
+++ en/reference/strings/functions/printf.xml
@@ -11,7 +11,6 @@
<methodsynopsis>
<type>int</type><methodname>printf</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>
<simpara>
@@ -23,22 +22,7 @@
&reftitle.parameters;
<para>
<variablelist>
- <varlistentry>
- <term><parameter>format</parameter></term>
- <listitem>
- <para>
- See <function>sprintf</function> for a description of
- <parameter>format</parameter>.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>args</parameter></term>
- <listitem>
- <para>
- </para>
- </listitem>
- </varlistentry>
+ &strings.parameter.format;
<varlistentry>
<term><parameter>...</parameter></term>
<listitem>
@@ -57,15 +41,103 @@
</para>
</refsect1>
+ <refsect1 role="examples">
+ &reftitle.examples;
+ <para>
+ <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>
+ </para>
+ </refsect1>
+
<refsect1 role="seealso">
&reftitle.seealso;
<para>
<simplelist>
<member><function>print</function></member>
+ <member><function>printf</function></member>
<member><function>sprintf</function></member>
+ <member><function>fprintf</function></member>
<member><function>vprintf</function></member>
+ <member><function>vsprintf</function></member>
+ <member><function>vfprintf</function></member>
<member><function>sscanf</function></member>
<member><function>fscanf</function></member>
+ <member><function>number_format</function></member>
+ <member><function>date</function></member>
<member><function>flush</function></member>
</simplelist>
</para>
Index: en/reference/strings/functions/sprintf.xml
--- en/reference/strings/functions/sprintf.xml
+++ en/reference/strings/functions/sprintf.xml
@@ -5,7 +5,7 @@
<refname>sprintf</refname>
<refpurpose>Return a formatted string</refpurpose>
</refnamediv>
-
+
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
@@ -23,200 +23,35 @@
&reftitle.parameters;
<para>
<variablelist>
+ &strings.parameter.format;
<varlistentry>
- <term><parameter>format</parameter></term>
+ <term><parameter>...</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.
- </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 (<literal>.</literal>) 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. Additionally, the character to use when padding a
- number may optionally be specified between the period and the
- digit.
- </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>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 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>u</literal> - the argument is treated as an
- integer and presented as an unsigned decimal number.
- </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>
- Variables will be co-erced to a suitable type for the specifier:
- <table xml:id="sprintf.coercion">
- <title>Type Handling</title>
- <tgroup cols="2">
- <thead>
- <row>
- <entry>Type</entry>
- <entry>Specifiers</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry><literal>string</literal></entry>
- <entry><literal>s</literal></entry>
- </row>
- <row>
- <entry><literal>integer</literal></entry>
- <entry>
- <literal>d</literal>,
- <literal>u</literal>,
- <literal>c</literal>,
- <literal>o</literal>,
- <literal>x</literal>,
- <literal>X</literal>,
- <literal>b</literal>
- </entry>
- </row>
- <row>
- <entry><literal>double</literal></entry>
- <entry>
- <literal>g</literal>,
- <literal>G</literal>,
- <literal>e</literal>,
- <literal>E</literal>,
- <literal>f</literal>,
- <literal>F</literal>
- </entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- </para>
- <warning>
- <para>
- 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
- </para>
- </warning>
- <para>
- The format string supports argument numbering/swapping. Here is an
- example:
- <example>
- <title>Argument swapping</title>
- <programlisting role="php">
-<![CDATA[
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+ </refsect1>
+
+ <refsect1 role="returnvalues">
+ &reftitle.returnvalues;
+ <para>
+ Returns a string produced according to the formatting string
+ <parameter>format</parameter>, &return.falseforfailure;.
+ </para>
+ </refsect1>
+
+ <refsect1 role="examples">
+ &reftitle.examples;
+ <example>
+ <title>Argument swapping</title>
+ <para>
+ The format string supports argument numbering/swapping.
+ </para>
+ <programlisting role="php">
+ <![CDATA[
<?php
$num = 5;
$location = 'tree';
@@ -225,200 +60,93 @@
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">
+ </programlisting>
+ &example.outputs;
+ <screen>
<![CDATA[
+There are 5 monkeys in the tree
+]]>
+ </screen>
+ <para>
+ However imagine we are creating a format string in a separate file,
+ commonly because we would like to internationalize it and we rewrite it as:
+ </para>
+ <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[
+ </programlisting>
+ <para>
+ 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:
+ </para>
+ <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[
+ </programlisting>
+ <para>
+ An added benefit is that placeholders can be repeated without adding
+ more arguments in the code.
+ </para>
+ <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>Specifying padding character</title>
- <programlisting role="php">
- <![CDATA[
-<?php
-echo sprintf("%'.9d\n", 123);
-echo sprintf("%'.09d\n", 123);
-?>
-]]>
- </programlisting>
- &example.outputs;
- <screen>
- <![CDATA[
-......123
-000000123
-]]>
- </screen>
- </example>
- <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>
- <warning>
- <para>
- The <literal>c</literal> type specifier ignores padding and width
- </para>
- </warning>
- </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>, &return.falseforfailure;.
- </para>
- </refsect1>
+ </programlisting>
+ <para>
+ 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 below.
+ </para>
+ </example>
- <refsect1 role="examples">
- &reftitle.examples;
<example>
- <title><function>printf</function>: various examples</title>
+ <title>Specifying padding character</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
+echo sprintf("%'.9d\n", 123);
+echo sprintf("%'.09d\n", 123);
?>
]]>
</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'
+......123
+000000123
]]>
</screen>
</example>
<example>
- <title><function>printf</function>: string specifiers</title>
+ <title>Position specifier with other 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
+$format = 'The %2$s contains %1$04d monkeys';
+echo sprintf($format, $num, $location);
?>
]]>
</programlisting>
&example.outputs;
<screen>
<![CDATA[
-[monkey]
-[ monkey]
-[monkey ]
-[0000monkey]
-[####monkey]
-[many monke]
+The tree contains 0005 monkeys
]]>
</screen>
</example>
@@ -440,12 +168,20 @@
$money1 = 68.75;
$money2 = 54.35;
$money = $money1 + $money2;
-// echo $money will output "123.1";
+echo $money;
+echo "\n";
$formatted = sprintf("%01.2f", $money);
-// echo $formatted will output "123.10"
+echo $formatted;
?>
]]>
</programlisting>
+ &example.outputs;
+ <screen>
+<![CDATA[
+123.1
+123.10
+]]>
+ </screen>
</example>
<example>
<title><function>sprintf</function>: scientific notation</title>
@@ -454,10 +190,16 @@
<?php
$number = 362525200;
-echo sprintf("%.3e", $number); // outputs 3.625e+8
+echo sprintf("%.3e", $number);
?>
]]>
</programlisting>
+ &example.outputs;
+ <screen>
+<![CDATA[
+3.625e+8
+]]>
+ </screen>
</example>
</refsect1>
@@ -466,9 +208,12 @@
<para>
<simplelist>
<member><function>printf</function></member>
+ <member><function>fprintf</function></member>
+ <member><function>vprintf</function></member>
+ <member><function>vsprintf</function></member>
+ <member><function>vfprintf</function></member>
<member><function>sscanf</function></member>
<member><function>fscanf</function></member>
- <member><function>vsprintf</function></member>
<member><function>number_format</function></member>
<member><function>date</function></member>
</simplelist>
Index: en/reference/strings/functions/vsprintf.xml
--- en/reference/strings/functions/vsprintf.xml
+++ en/reference/strings/functions/vsprintf.xml
@@ -23,15 +23,7 @@
&reftitle.parameters;
<para>
<variablelist>
- <varlistentry>
- <term><parameter>format</parameter></term>
- <listitem>
- <para>
- See <function>sprintf</function> for a description of
- <parameter>format</parameter>.
- </para>
- </listitem>
- </varlistentry>
+ &strings.parameter.format;
<varlistentry>
<term><parameter>args</parameter></term>
<listitem>
@@ -47,8 +39,7 @@
&reftitle.returnvalues;
<para>
Return array values as a formatted string according to
- <parameter>format</parameter> (which is described in the documentation
- for <function>sprintf</function>).
+ <parameter>format</parameter>, &return.falseforfailure;.
</para>
</refsect1>
@@ -60,10 +51,16 @@
<programlisting role="php">
<![CDATA[
<?php
-print vsprintf("%04d-%02d-%02d", explode('-', '1988-8-1')); // 1988-08-01
+print vsprintf("%04d-%02d-%02d", explode('-', '1988-8-1'));
?>
]]>
</programlisting>
+ &example.outputs;
+ <screen>
+<![CDATA[
+1988-08-01
+]]>
+ </screen>
</example>
</para>
</refsect1>
@@ -72,8 +69,15 @@
&reftitle.seealso;
<para>
<simplelist>
+ <member><function>printf</function></member>
<member><function>sprintf</function></member>
+ <member><function>fprintf</function></member>
<member><function>vprintf</function></member>
+ <member><function>vfprintf</function></member>
+ <member><function>sscanf</function></member>
+ <member><function>fscanf</function></member>
+ <member><function>number_format</function></member>
+ <member><function>date</function></member>
</simplelist>
</para>
</refsect1>
Index: en/reference/filesystem/functions/fscanf.xml
--- en/reference/filesystem/functions/fscanf.xml
+++ en/reference/filesystem/functions/fscanf.xml
@@ -41,15 +41,7 @@
&fs.file.pointer;
</listitem>
</varlistentry>
- <varlistentry>
- <term><parameter>format</parameter></term>
- <listitem>
- <para>
- The specified format as described in the
- <function>sprintf</function> documentation.
- </para>
- </listitem>
- </varlistentry>
+ &strings.parameter.format;
<varlistentry>
<term><parameter>...</parameter></term>
<listitem>
Index: en/reference/strings/functions/vfprintf.xml
--- en/reference/strings/functions/vfprintf.xml
+++ en/reference/strings/functions/vfprintf.xml
@@ -35,15 +35,7 @@
</para>
</listitem>
</varlistentry>
- <varlistentry>
- <term><parameter>format</parameter></term>
- <listitem>
- <para>
- See <function>sprintf</function> for a description of
- <parameter>format</parameter>.
- </para>
- </listitem>
- </varlistentry>
+ &strings.parameter.format;
<varlistentry>
<term><parameter>args</parameter></term>
<listitem>
@@ -88,10 +80,13 @@
<simplelist>
<member><function>printf</function></member>
<member><function>sprintf</function></member>
+ <member><function>fprintf</function></member>
+ <member><function>vprintf</function></member>
+ <member><function>vsprintf</function></member>
<member><function>sscanf</function></member>
<member><function>fscanf</function></member>
- <member><function>vsprintf</function></member>
<member><function>number_format</function></member>
+ <member><function>date</function></member>
</simplelist>
</para>
</refsect1>
Index: en/reference/strings/functions/sscanf.xml
--- en/reference/strings/functions/sscanf.xml
+++ en/reference/strings/functions/sscanf.xml
@@ -145,9 +145,15 @@
&reftitle.seealso;
<para>
<simplelist>
- <member><function>fscanf</function></member>
<member><function>printf</function></member>
<member><function>sprintf</function></member>
+ <member><function>fprintf</function></member>
+ <member><function>vprintf</function></member>
+ <member><function>vsprintf</function></member>
+ <member><function>vfprintf</function></member>
+ <member><function>fscanf</function></member>
+ <member><function>number_format</function></member>
+ <member><function>date</function></member>
</simplelist>
</para>
</refsect1>
Index: en/reference/strings/functions/fprintf.xml
--- en/reference/strings/functions/fprintf.xml
+++ en/reference/strings/functions/fprintf.xml
@@ -30,15 +30,7 @@
&fs.file.pointer;
</listitem>
</varlistentry>
- <varlistentry>
- <term><parameter>format</parameter></term>
- <listitem>
- <para>
- See <function>sprintf</function> for a description of
- <parameter>format</parameter>.
- </para>
- </listitem>
- </varlistentry>
+ &strings.parameter.format;
<varlistentry>
<term><parameter>...</parameter></term>
<listitem>
@@ -106,10 +98,13 @@
<simplelist>
<member><function>printf</function></member>
<member><function>sprintf</function></member>
+ <member><function>vprintf</function></member>
+ <member><function>vsprintf</function></member>
+ <member><function>vfprintf</function></member>
<member><function>sscanf</function></member>
<member><function>fscanf</function></member>
- <member><function>vsprintf</function></member>
<member><function>number_format</function></member>
+ <member><function>date</function></member>
</simplelist>
</para>
</refsect1>
Index: en/language-snippets.ent
--- en/language-snippets.ent
+++ en/language-snippets.ent
@@ -2443,6 +2443,311 @@
</para>
'>
+<!ENTITY strings.parameter.format '
+<varlistentry xmlns="http://docbook.org/ns/docbook">
+ <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.
+ </para>
+
+ <para>
+ A conversion specification follows this prototype:
+ <literal>%[flags][width][.precision]specifier</literal>.
+ </para>
+
+ <para>
+ <table>
+ <title>Flags</title>
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>Flag</entry>
+ <entry>&Description;</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry><literal>-</literal></entry>
+ <entry>
+ Left-justify within the given field width;
+ Right justification is the default
+ </entry>
+ </row>
+ <row>
+ <entry><literal>+</literal></entry>
+ <entry>
+ Prefix positive numbers with a plus sign
+ <literal>+</literal>; Default only negative
+ are prefixed with a negative sign.
+ </entry>
+ </row>
+ <row>
+ <entry><literal> </literal>(space)</entry>
+ <entry>
+ Pads the result with spaces.
+ This is the default.
+ </entry>
+ </row>
+ <row>
+ <entry><literal>0</literal></entry>
+ <entry>
+ Only left-pads numbers with zeros.
+ With <literal>s</literal> specifiers this can
+ also right-pad with zeros.
+ </entry>
+ </row>
+ <row>
+ <entry><literal>'</literal>(char)</entry>
+ <entry>
+ Pads the result with the character (char).
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ </para>
+
+ <formalpara>
+ <title>Width</title>
+ <para>
+ An integer that says how many characters (minimum)
+ this conversion should result in.
+ </para>
+ </formalpara>
+
+ <formalpara>
+ <title>Precision</title>
+ <para>
+ A period <literal>.</literal> followed by an integer
+ who's meaning depends on the specifier:
+ <itemizedlist>
+ <listitem>
+ <simpara>
+ For <literal>e</literal>, <literal>E</literal>,
+ <literal>f</literal> and <literal>F</literal>
+ specifiers: this is the number of digits to be printed
+ after the decimal point (by default, this is 6).
+ </simpara>
+ </listitem>
+ <listitem>
+ <simpara>
+ For <literal>g</literal> and <literal>G</literal>
+ specifiers: this is the maximum number of significant
+ digits to be printed.
+ </simpara>
+ </listitem>
+ <listitem>
+ <simpara>
+ For <literal>s</literal> specifier: it acts as a cutoff point,
+ setting a maximum character limit to the string.
+ </simpara>
+ </listitem>
+ </itemizedlist>
+ <note>
+ <simpara>
+ If the period is specified without an explicit value for precision,
+ 0 is assumed.
+ </simpara>
+ </note>
+ </para>
+ </formalpara>
+
+ <note>
+ <simpara>
+ Attempting to use a position specifier greater than
+ <constant>PHP_INT_MAX</constant> will generate warnings.
+ </simpara>
+ </note>
+
+ <para>
+ <table>
+ <title>Specifiers</title>
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>Specifier</entry>
+ <entry>&Description;</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry><literal>%</literal></entry>
+ <entry>
+ A literal percent character. No argument is required.
+ </entry>
+ </row>
+ <row>
+ <entry><literal>b</literal></entry>
+ <entry>
+ The argument is treated as an integer and presented
+ as a binary number.
+ </entry>
+ </row>
+ <row>
+ <entry><literal>c</literal></entry>
+ <entry>
+ The argument is treated as an integer and presented
+ as the character with that ASCII.
+ </entry>
+ </row>
+ <row>
+ <entry><literal>d</literal></entry>
+ <entry>
+ The argument is treated as an integer and presented
+ as a (signed) decimal number.
+ </entry>
+ </row>
+ <row>
+ <entry><literal>e</literal></entry>
+ <entry>
+ 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).
+ </entry>
+ </row>
+ <row>
+ <entry><literal>E</literal></entry>
+ <entry>
+ Like the <literal>e</literal> specifier but uses
+ uppercase letter (e.g. 1.2E+2).
+ </entry>
+ </row>
+ <row>
+ <entry><literal>f</literal></entry>
+ <entry>
+ The argument is treated as a float and presented
+ as a floating-point number (locale aware).
+ </entry>
+ </row>
+ <row>
+ <entry><literal>F</literal></entry>
+ <entry>
+ The argument is treated as a float and presented
+ as a floating-point number (non-locale aware).
+ Available as of PHP 5.0.3.
+ </entry>
+ </row>
+ <row>
+ <entry><literal>g</literal></entry>
+ <entry>
+ <para>
+ General format.
+ </para>
+ <para>
+ 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:
+ </para>
+ <para>
+ 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.
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry><literal>G</literal></entry>
+ <entry>
+ Like the <literal>g</literal> specifier but uses
+ <literal>E</literal> and <literal>F</literal>.
+ </entry>
+ </row>
+ <row>
+ <entry><literal>o</literal></entry>
+ <entry>
+ The argument is treated as an integer and presented
+ as an octal number.
+ </entry>
+ </row>
+ <row>
+ <entry><literal>s</literal></entry>
+ <entry>
+ the argument is treated and presented as a string.
+ </entry>
+ </row>
+ <row>
+ <entry><literal>x</literal></entry>
+ <entry>
+ The argument is treated as an integer and presented
+ as a hexadecimal number (with lowercase letters).
+ </entry>
+ </row>
+ <row>
+ <entry><literal>X</literal></entry>
+ <entry>
+ The argument is treated as an integer and presented
+ as a hexadecimal number (with uppercase letters).
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ </para>
+
+ <warning>
+ <para>
+ The <literal>c</literal> type specifier ignores padding and width
+ </para>
+ </warning>
+
+ <warning>
+ <para>
+ 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
+ </para>
+ </warning>
+
+ <para>
+ Variables will be co-erced to a suitable type for the specifier:
+ <table>
+ <title>Type Handling</title>
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>Type</entry>
+ <entry>Specifiers</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry><literal>string</literal></entry>
+ <entry><literal>s</literal></entry>
+ </row>
+ <row>
+ <entry><literal>integer</literal></entry>
+ <entry>
+ <literal>d</literal>,
+ <literal>u</literal>,
+ <literal>c</literal>,
+ <literal>o</literal>,
+ <literal>x</literal>,
+ <literal>X</literal>,
+ <literal>b</literal>
+ </entry>
+ </row>
+ <row>
+ <entry><literal>double</literal></entry>
+ <entry>
+ <literal>g</literal>,
+ <literal>G</literal>,
+ <literal>e</literal>,
+ <literal>E</literal>,
+ <literal>f</literal>,
+ <literal>F</literal>
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ </para>
+ </listitem>
+</varlistentry>
+'>
+
<!ENTITY strings.parameter.needle.non-string '
<para xmlns="http://docbook.org/ns/docbook">
If <parameter>needle</parameter> is not a string, it is converted
Index: en/reference/spl/splfileobject/fscanf.xml
--- en/reference/spl/splfileobject/fscanf.xml
+++ en/reference/spl/splfileobject/fscanf.xml
@@ -28,14 +28,7 @@
&reftitle.parameters;
<para>
<variablelist>
- <varlistentry>
- <term><parameter>format</parameter></term>
- <listitem>
- <para>
- The specified format as described in the <function>sprintf</function> documentation.
- </para>
- </listitem>
- </varlistentry>
+ &strings.parameter.format;
<varlistentry>
<term><parameter>...</parameter></term>
<listitem>
@@ -92,6 +85,9 @@
<para>
<simplelist>
<member><function>fscanf</function></member>
+ <member><function>sscanf</function></member>
+ <member><function>printf</function></member>
+ <member><function>sprintf</function></member>
</simplelist>
</para>
</refsect1>
|
Copyright © 2001-2024 The PHP Group