- Remove the format documentation from fprintf and link to the

documentation in sprintf. Keeping it in one place is better and the
  fprintf version was outdated anyway.

- The precision specifier works on strings too. Document this and add
  examples.

- Add some basic examples of each type specifier.


git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@164698 c90b9560-bf6c-de11-be94-00142212c4b1
This commit is contained in:
Dave Barr 2004-07-30 05:04:21 +00:00
parent ea09e1e3fc
commit 284476507c
2 changed files with 110 additions and 131 deletions

View file

@ -1,5 +1,5 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.3 $ -->
<!-- $Revision: 1.4 $ -->
<refentry id="function.fprintf">
<refnamediv>
<refname>fprintf</refname>
@ -14,111 +14,11 @@
<methodparam choice="opt"><type>mixed</type><parameter>args</parameter></methodparam>
</methodsynopsis>
<simpara>
Write a string produced according to the formatting string
<parameter>format</parameter> to the stream resource specified
by <parameter>handle</parameter>..
Write a string produced according to <parameter>format</parameter>
to the stream resource specified by <parameter>handle</parameter>.
<parameter>format</parameter> is described in the documentation for
<function>sprintf</function>.
</simpara>
<simpara>
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 <function>fprintf</function>,
<function>sprintf</function>, and <function>printf</function>.
</simpara>
<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>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> that says
how many decimal digits should be displayed for floating-point
numbers. This option has no effect for other types than
<type>float</type>. (Another function useful for formatting numbers is
<function>number_format</function>.)
</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>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
<type>float</type>, and presented as a floating-point number.
</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>
<simpara>
Returns the length of the outputted string.
</simpara>
@ -134,26 +34,36 @@
<title>Examples</title>
<para>
<example>
<title><function>sprintf</function>: zero-padded integers</title>
<title><function>fprintf</function>: zero-padded integers</title>
<programlisting role="php">
<![CDATA[
<?php
$isodate = sprintf("%04d-%02d-%02d", $year, $month, $day);
if (!($fp = fopen('date.txt', 'w')))
return;
fprintf($fp, "%04d-%02d-%02d", $year, $month, $day);
// will write the formatted ISO date to date.txt
?>
]]>
</programlisting>
</example>
<example>
<title><function>sprintf</function>: formatting currency</title>
<title><function>fprintf</function>: formatting currency</title>
<programlisting role="php">
<![CDATA[
<?php
if (!($fp = fopen('currency.txt', 'w')))
return;
$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"
$len = fprintf($fp, '%01.2f', $money);
// will write "123.10" to currency.txt
echo "wrote $len bytes to currency.txt";
// use the return value of fprintf to determine how many bytes we wrote
?>
]]>
</programlisting>

View file

@ -1,5 +1,5 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.9 $ -->
<!-- $Revision: 1.10 $ -->
<!-- splitted from ./en/functions/strings.xml, last change in rev 1.2 -->
<refentry id="function.sprintf">
<refnamediv>
@ -60,9 +60,8 @@
<simpara>
An optional <emphasis>precision specifier</emphasis> that says
how many decimal digits should be displayed for floating-point
numbers. This option has no effect for other types than
<type>float</type>. (Another function useful for formatting numbers is
<function>number_format</function>.)
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>
@ -191,20 +190,91 @@ printf($format, $num, $location);
</refsect1>
<refsect1>
<title>Examples</title>
<para>
<example>
<title><function>sprintf</function>: zero-padded integers</title>
<programlisting role="php">
<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)
?>
]]>
</programlisting>
<para>
The printout of this program would be:
</para>
<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'
]]>
</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("[%10.10s]\n", $t); // left-justification but with a cutoff of 10 characters
?>
]]>
</programlisting>
<para>
The printout of this program would be:
</para>
<screen>
<![CDATA[
[monkey]
[ monkey]
[monkey ]
[0000monkey]
[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">
</programlisting>
</example>
<example>
<title><function>sprintf</function>: formatting currency</title>
<programlisting role="php">
<![CDATA[
<?php
$money1 = 68.75;
@ -215,11 +285,11 @@ $formatted = sprintf("%01.2f", $money);
// echo $formatted will output "123.10"
?>
]]>
</programlisting>
</example>
<example>
<title><function>sprintf</function>: scientific notation</title>
<programlisting role="php">
</programlisting>
</example>
<example>
<title><function>sprintf</function>: scientific notation</title>
<programlisting role="php">
<![CDATA[
<?php
$number = 362525200;
@ -227,9 +297,8 @@ $number = 362525200;
echo sprintf("%.3e", $number); // outputs 3.63e+8
?>
]]>
</programlisting>
</example>
</para>
</programlisting>
</example>
</refsect1>
</refentry>