php.net |  support |  documentation |  report a bug |  advanced search |  search howto |  statistics |  random bug |  login

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>&#37;</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>&#37;[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>&apos;</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&apos;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>&#37;</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>
 
PHP Copyright © 2001-2024 The PHP Group
All rights reserved.
Last updated: Fri Mar 29 07:01:28 2024 UTC