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

<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.9 $ -->
<!-- EN-Revision: 1.9 Maintainer: yannick Status: ready -->
  <refentry id="function.sprintf">
   <refnamediv>
    <refname>sprintf</refname>
    <refpurpose>Retourne une chaîne formatée</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>string</type><methodname>sprintf</methodname>
      <methodparam><type>string</type><parameter>format</parameter></methodparam>
      <methodparam choice="opt"><type>mixed</type><parameter>args</parameter></methodparam>
     </methodsynopsis>
    <simpara>
     <methodname>sprintf</methodname> retourne une chaîne formatée, avec
     le format <parameter>format</parameter> et en utilisant les arguments 
     <parameter>args</parameter>.
    </simpara>
    <simpara>
     La chaîne de format est composée de zéro, une ou plusieurs directives :
     les caractères ordinaires (à l'exception de <literal>%</literal>) 
     qui sont copiés directement dans le résultat, et des 
     <emphasis>spécifications de conversion</emphasis>, qui exploitent
     chacune un des arguments passé après la chaîne de format.
     Ces formats s'appliquent à <function>sprintf</function>
     et <function>printf</function>.
    </simpara>
    <para>
     Chaque spécification de conversion est consistituée d'un signe
     de pourcentage (<literal>%</literal>), suivi d'un ou plusieurs
     des éléments suivants, dans cet ordre : 
     <orderedlist>
      <listitem>
       <simpara>
        Un <emphasis>remplisseur</emphasis> optionnel qui indique
        quel caractère sera utilisé pour compléter le résultat
        jusqu'à la longueur requise. Ce peut être le caractère d'espace,
        ou le caractère &zero;. Par défaut, le remplissage
        se fait avec des espaces. Un autre caractère de remplissage peut
        être spécifié en le préfixant avec un guillemet simple 
        (<literal>'</literal>) : voir les exemples ci-dessous.
       </simpara>
      </listitem>
      <listitem>
       <simpara>
        Un <emphasis>spécificateur d'alignement</emphasis> qui indique
        si le résultat doit être aligné à gauche ou à droite. Par
        défaut, le résultat est aligné à gauche. Le caractère
        <literal>-</literal> fera que le résultat est aligné à droite.
       </simpara>
      </listitem>
      <listitem>
       <simpara>
        Un nombre optionnel, <emphasis>spécificateur de taille</emphasis>
        indique le nombre minimum de caractères que cette conversion doit
        fournir en résultat.
       </simpara>
      </listitem>
      <listitem>
       <simpara>
        Un <emphasis>spécificateur de précision</emphasis> qui indique
        le nombre de décimales qui doivent être affichées pour les nombres
        à virgule flottante. Cette option n'a pas d'effet pour les autres
        types que &float;. Une autre fonction pratique pour
        formatter les nombres à virgule flottante est <function>number_format</function>.
       </simpara>
      </listitem>
      <listitem>
       <para>
        Un <emphasis>spécificateur de type</emphasis> qui indique le type
        avec lequel l'argument sera traité. Plusieurs types possibles :
        <simplelist>
         <member>
          <literal>%</literal> - un caractère de pourcentage litéral.
          Aucun argument n'est nécessaire.
         </member>
         <member>
          <literal>b</literal> - l'argument est traité comme un entier,
          et présenté comme un nombre binaire.
         </member>
         <member>
          <literal>c</literal> - l'argument est traité comme un entier,
          et présenté comme le caractère de code ASCII correspondant.
         </member>
         <member>
          <literal>d</literal> - l'argument est traité comme un entier,
          et présenté comme un nombre décimal signé.
         </member>
         <member>
          <literal>e</literal> - l'argument est traité comme une notation scientifique
          (e.g. 1.2e+2).
         </member>
         <member>
          <literal>u</literal> - l'argument est traité comme un entier,
          et présenté comme un nombre décimal non signé.
         </member>
         <member>
          <literal>f</literal> - l'argument est traité comme un nombre à 
          virgule flottante (type <type>float</type>), et présenté comme un nombre à 
          virgule flottante.
         </member>
         <member>
          <literal>o</literal> - l'argument est traité comme un entier,
          et présenté comme un nombre octal.
         </member>
         <member>
          <literal>s</literal> - l'argument est traité et 
          présenté comme une chaîne de caractères.
         </member>
         <member>
          <literal>x</literal> - l'argument est traité comme un entier,
          et présenté comme un nombre hexadécimal (les lettres en minuscules).
         </member>
         <member>
          <literal>X</literal> - l'argument est traité comme un entier,
          et présenté comme un nombre hexadécimal (les lettres en majuscules).
         </member>
        </simplelist>
       </para>
      </listitem>
     </orderedlist>
    </para>
    <para>
     Depuis &php; 4.0.6, la chaîne de format supporte le numérotage
     et l'échange d'arguments. Par exemple : 
     <example>
      <title>Echange d'arguments</title>
      <programlisting role="php">
<![CDATA[
<?php
$format = "Il y a %d singes dans le %s";
printf($format, $num, $location);
?>
]]>
      </programlisting>
     </example>
     Cet exemple peut afficher par exemple : "Il y a 5 singes dans le bananier". 
     Mais imaginez que la chaîne de format soit créée dans un script
     séparé (une librairie), ca nous devons internationaliser cet
     affichage. Nous aurons peut être à écrire : 
     <example>
      <title>Echange d'arguments (2)</title>
      <programlisting role="php">
<![CDATA[
<?php
$format = "Le %s a %d singes";
printf($format, $num, $location);
?>
]]>
      </programlisting>
     </example>
     Maintenant, nous avons un problème. L'ordre des arguments a été changé,
     et ne correspond pas à l'ordre des arguments dans le script &php;.
     Nous souhaitons laisser le code &php; tel quel, et simplement indiquer
     dans la chaîne de formattage l'ordre dans lequel les arguments doivent
     être repris. La chaîne de format peut être réécrite ainsi : 
     <example>
      <title>Echange d'arguments (3)</title>
      <programlisting role="php">
<![CDATA[
<?php
$format = "Le %2\$s a %1\$d signes";
printf($format, $num, $location);
?>
]]>
      </programlisting>
     </example>
     Un des avantages est que vous pouvez désormais exploiter plusieurs fois les 
     arguments sans les répéter. Ainsi :
     <example>
      <title>Echange d'arguments (4)</title>
      <programlisting role="php">
<![CDATA[
<?php
$format = "Le %2\$s a %1\$d singes.
           C'est un beau %2\$s, avec %1\$d signes.";
printf($format, $num, $location);
?>
]]>
      </programlisting>
     </example>
    </para>
    <simpara>
     Voir aussi
     <function>printf</function>,
     <function>sscanf</function>, 
     <function>fscanf</function>,
     <function>vsprintf</function> et
     <function>number_format</function>.
    </simpara>
   </refsect1>
   <refsect1>
    <title>Exemples avec <function>printf</function> et <function>sprintf</function></title>
    <para>
     <example>
      <title><function>sprintf</function>: entiers complétés de zéros</title>
      <programlisting role="php">
<![CDATA[
<?php
$isodate = sprintf("%04d-%02d-%02d", $year, $month, $day);
?>
]]>
      </programlisting>
     </example>
     <example>
      <title><function>sprintf</function>: format monétaire</title>
      <programlisting role="php">
<![CDATA[
<?php
$money1 = 68.75;
$money2 = 54.35;
$money = $money1 + $money2;
// echo $money va afficher "123.1";
$formatted = sprintf("%01.2f", $money);
// echo $formatted va afficher "123.10"
?>
]]>
      </programlisting>
     </example>
     <example>
      <title><function>sprintf</function>: notation scientifique</title>
      <programlisting role="php">
<![CDATA[
<?php
$number = 362525200;

echo sprintf("%.3e", $number); // affichera 3.63e+8
?>
]]>
      </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
-->