dave Fri Jul 30 01:04:21 2004 EDT
Modified files:
/phpdoc/en/reference/strings/functions fprintf.xml sprintf.xml
Log:
- 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.
http://cvs.php.net/diff.php/phpdoc/en/reference/strings/functions/fprintf.xml?r1=1.3&r2=1.4&ty=u
Index: phpdoc/en/reference/strings/functions/fprintf.xml
diff -u phpdoc/en/reference/strings/functions/fprintf.xml:1.3
phpdoc/en/reference/strings/functions/fprintf.xml:1.4
--- phpdoc/en/reference/strings/functions/fprintf.xml:1.3 Fri Jul 30 00:20:42
2004
+++ phpdoc/en/reference/strings/functions/fprintf.xml Fri Jul 30 01:04:21 2004
@@ -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,112 +14,12 @@
<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>
<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>
http://cvs.php.net/diff.php/phpdoc/en/reference/strings/functions/sprintf.xml?r1=1.9&r2=1.10&ty=u
Index: phpdoc/en/reference/strings/functions/sprintf.xml
diff -u phpdoc/en/reference/strings/functions/sprintf.xml:1.9
phpdoc/en/reference/strings/functions/sprintf.xml:1.10
--- phpdoc/en/reference/strings/functions/sprintf.xml:1.9 Fri May 28 17:45:59
2004
+++ phpdoc/en/reference/strings/functions/sprintf.xml Fri Jul 30 01:04:21 2004
@@ -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 @@
</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 @@
// 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 @@
echo sprintf("%.3e", $number); // outputs 3.63e+8
?>
]]>
- </programlisting>
- </example>
- </para>
+ </programlisting>
+ </example>
</refsect1>
</refentry>
