<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<refentry xml:id="function.sprintf" xmlns="http://docbook.org/ns/docbook">
 <refnamediv>
  <refname>sprintf</refname>
  <refpurpose>Return a formatted string</refpurpose>
 </refnamediv>

 <refsect1 role="description">
  &reftitle.description;
  <methodsynopsis>
   <type>string</type><methodname>sprintf</methodname>
   <methodparam><type>string</type><parameter>format</parameter></methodparam>
   <methodparam rep="repeat"><type>mixed</type><parameter>values</parameter></methodparam>
  </methodsynopsis>
  <para>
   Returns a string produced according to the formatting string
   <parameter>format</parameter>.
  </para>
 </refsect1>

 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <variablelist>
    &strings.parameter.format;
    <varlistentry>
     <term><parameter>values</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>.
  </para>
 </refsect1>

 <refsect1 role="errors">
  &reftitle.errors;
  &strings.errors.sprintf;
 </refsect1>

 <refsect1 role="changelog">
  &reftitle.changelog;
  &strings.changelog.sprintf;
 </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';

$format = 'There are %d monkeys in the %s';
echo sprintf($format, $num, $location);
?>
]]>
   </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>
   <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>
   <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>
   <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>

  <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>
  <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">
<![CDATA[
<?php
$money1 = 68.75;
$money2 = 54.35;
$money = $money1 + $money2;
echo $money;
echo "\n";
$formatted = sprintf("%01.2f", $money);
echo $formatted;
?>
]]>
   </programlisting>
   &example.outputs;
   <screen>
<![CDATA[
123.1
123.10
]]>
   </screen>
  </example>
  <example>
   <title><function>sprintf</function>: scientific notation</title>
   <programlisting role="php">
<![CDATA[
<?php
$number = 362525200;

echo sprintf("%.3e", $number);
?>
]]>
   </programlisting>
   &example.outputs;
   <screen>
<![CDATA[
3.625e+8
]]>
   </screen>
  </example>
 </refsect1>

 <refsect1 role="seealso">
  &reftitle.seealso;
  <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>number_format</function></member>
    <member><function>date</function></member>
   </simplelist>
  </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:"~/.phpdoc/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
-->