<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.1 $ -->
  <refentry id="function.fprintf">
   <refnamediv>
    <refname>fprintf</refname>
    <refpurpose>Write a formatted string to a stream</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>int</type><methodname>fprintf</methodname>
      <methodparam><type>resource</type><parameter>handle</parameter></methodparam>
      <methodparam><type>string</type><parameter>format</parameter></methodparam>
      <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>..
    </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>
     See also: <function>printf</function>,
     <function>sprintf</function>,
     <function>sscanf</function>, <function>fscanf</function>, 
     <function>vsprintf</function>, and
     <function>number_format</function>.
    </simpara>
   </refsect1>
   <refsect1>
    <title>Examples</title>
    <para>
     <example>
      <title><function>sprintf</function>: zero-padded integers</title>
      <programlisting role="php">
<![CDATA[
$isodate = sprintf("%04d-%02d-%02d", $year, $month, $day);
]]>
      </programlisting>
     </example>
     <example>
      <title><function>sprintf</function>: formatting currency</title>
      <programlisting role="php">
<![CDATA[
$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"
]]>
      </programlisting>
     </example>
    </para>
   </refsect1>
  </refentry>

<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"../../../../manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->