archived-doc-fr/reference/strings/functions/sprintf.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!-- EN-Revision: f134250210702ab6280ab303b846679177d39f14 Maintainer: yannick Status: ready -->
<!-- Reviewed: no -->
<refentry xml:id="function.sprintf" xmlns="http://docbook.org/ns/docbook">
<refnamediv>
  <refname>sprintf</refname>
  <refpurpose>Retourne une chaîne formatée</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>
   Retourne une chaîne formatée, avec le format
   <parameter>format</parameter>, en utilisant les arguments
   <parameter>args</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>
   Retourne une &string; créée suivant le format
   <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>Échange d'arguments</title>
   <para>
    La chaîne de format supporte le numérotage et l'échange d'arguments.
   </para>
   <programlisting role="php">
<![CDATA[
<?php
$num = 5;
$location = 'bananier';

$format = 'Il y a %d singes dans le %s';
echo sprintf($format, $num, $location);
?>
]]>
   </programlisting>
   &example.outputs;
   <screen>
<![CDATA[
Il y a 5 singes dans le bananier
]]>
   </screen>
   <para>
    Mais imaginez que la chaîne de format soit créée dans un script séparé,
    comme une bibliothèque : cela arrive lorsqu'il faut internationaliser une
    application. Suivant la langue, il faudra peut-être écrire :
   </para>
   <programlisting role="php">
<![CDATA[
<?php
$format = 'Le %s a %d singes';
echo sprintf($format, $num, $location);
?>
]]>
   </programlisting>
   <para>
    Nous avons désormais un problème. L'ordre des arguments a été changé,
    et ne correspond plus à l'ordre des arguments dans le script PHP.
    Nous souhaitons laisser le code PHP intact, mais simplement indiquer
    dans la chaîne de formatage l'ordre dans lequel les arguments doivent
    être utilisés. La chaîne de format peut être réécrite ainsi :
   </para>
   <programlisting role="php">
<![CDATA[
<?php
$format = 'Le %2$s a %1$d singes';
echo sprintf($format, $num, $location);
?>
]]>
  </programlisting>
  <para>
   Un des avantages est que les paramètres fictifs peuvent être répétés sans
   ajouter plus d'arguments dans le code.
  </para>
  <programlisting role="php">
<![CDATA[
<?php
$format = 'Le %2$s a %1$d singes.
           C\'est un beau %2$s avec %1$d singes.';
echo sprintf($format, $num, $location);
?>
]]>
   </programlisting>
   <para>
    Lors de l'utilisation du mécanisme de l'échange d'arguments,
    le <emphasis>spécificateur de position</emphasis>
    <literal>n$</literal> doit survenir immédiatement après le
    signe de pourcentage(<literal>%</literal>), avant tout autre
    spécificateur, tel que dans l'exemple suivant.
   </para>
  </example>
  <example>
   <title>Spécification du caractère de remplissage</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>Spécificateur de position avec d'autres spécificateurs</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> : entier sans espace</title>
   <programlisting role="php">
<![CDATA[
<?php
$isodate = sprintf("%04d-%02d-%02d", $year, $month, $day);
?>
]]>
   </programlisting>
  </example>
  <example>
   <title><function>sprintf</function> : formatage de devises</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> : notation scientifique</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
-->