mirror of
https://github.com/sigmasternchen/php-doc-en
synced 2025-03-16 00:48:54 +00:00
- 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
parent
ea09e1e3fc
commit
284476507c
2 changed files with 110 additions and 131 deletions
|
|
@ -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>
|
||||
|
|
|
|||
|
|
@ -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>
|
||||
|
||||
|
|
|
|||
Loading…
Reference in a new issue