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

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!-- EN-Revision: 96c9d88bad9a7d7d44bfb7f26c226df7ee9ddf26 Maintainer: dams Status: ready -->
<!-- Reviewed: yes -->

<refentry xmlns="http://docbook.org/ns/docbook" xml:id="function.sprintf">
 <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 choice="opt"><type>mixed</type><parameter>args</parameter></methodparam>
   <methodparam choice="opt"><type>mixed</type><parameter>...</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>
    <varlistentry>
     <term><parameter>format</parameter></term>
     <listitem>
      <para>
       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és après la chaîne de format.
       Ces formats s'appliquent à <function>sprintf</function>
       et <function>printf</function>.
      </para>
      <para>
      Chaque spécification de conversion est constituée d'un signe
      de pourcentage (<literal>%</literal>), suivi d'un ou plusieurs
      des éléments suivants, dans cet ordre :
       <orderedlist>
        <listitem>
         <simpara>
          Le <emphasis>signe</emphasis> optionnel ne force pas le nombre
          à être positif/négatif mais force à utiliser le signe - ou + sur
          un nombre. Par défaut, seul le signe - est utilisé
          sur un nombre s'il est négatif. Ce spécificateur force également
          les nombres positifs à avoir un signe + d'attaché, et a été ajouté
          en PHP 4.3.0.
         </simpara>
        </listitem>
        <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 sera justifié à gauche.
         </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> de la forme 
          d'un point (<literal>"."</literal>), suivi par un nombre 
          de décimales qui doivent être affichées pour les nombres
          décimaux. Lorsque vous utilisez ce spécificateur dans une
          chaîne, il agit comme un point de coupure, définissant une limite
          maximale de caractères de la chaîne.
         </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 litté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. <literal>1.2e+2</literal>).
            Le spécificateur de précision représente le nombre de chiffres après
            la virgule depuis PHP 5.2.1. Dans les versions antérieures, il a été
            pris comme nombre des chiffres significatifs (au moins un).
           </member>
           <member>
            <literal>E</literal> : comme <literal>%e</literal> mais utilise
            des lettres en majuscule (i.e. 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 (tenant compte de la locale utilisée).
           </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 (ne tenant pas compte de la locale
            utilisée). Disponible depuis PHP 4.3.10 et PHP 5.0.3.
           </member>
           <member>
            <literal>g</literal> : raccourci pour <literal>%e</literal> et
            <literal>%f</literal>.
           </member>
           <member>
            <literal>G</literal> : reccourci pour <literal>%E</literal> et
            <literal>%f</literal>.
           </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>
       La chaîne de format supporte le numérotage
       et l'échange d'arguments. Par exemple :
       <example>
        <title>Échange d'arguments</title>
        <programlisting role="php">
<![CDATA[
<?php
$format = 'Il y a %d singes dans le %s';
printf($format, $num, $location);
?>
]]>
        </programlisting>
       </example>
       Ainsi, cet exemple peut afficher : 
       <literal>"Il y a 5 singes dans le bananier"</literal>.
       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 :
       <example>
        <title>Échange d'arguments (2)</title>
        <programlisting role="php">
<![CDATA[
<?php
$format = 'Le %s a %d singes';
printf($format, $num, $location);
?>
]]>
        </programlisting>
       </example>
       Ici, nous voyons bien le 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 :
       <example>
        <title>Échange d'arguments (3)</title>
        <programlisting role="php">
<![CDATA[
<?php
$format = 'Le %2$s a %1$d singes';
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>Échange 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 singes.';
printf($format, $num, $location);
?>
]]>
        </programlisting>
       </example>
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>args</parameter></term>
     <listitem>
      <para>
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>...</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="changelog">
  &reftitle.changelog;
  <para>
   <informaltable>
    <tgroup cols="2">
     <thead>
      <row>
       <entry>&Version;</entry>
       <entry>&Description;</entry>
      </row>
     </thead>
     <tbody>
      <row>
       <entry>4.0.6</entry>
       <entry>
        Ajout du support de l'argument d'échange
       </entry>
      </row>
     </tbody>
    </tgroup>
   </informaltable>
  </para>
 </refsect1>

 <refsect1 role="examples">
  &reftitle.examples;
  <example>
   <title><function>printf</function> : divers exemples</title>
   <programlisting role="php">
<![CDATA[
<?php
$n =  43951789;
$u = -43951789;
$c = 65; // ASCII 65 is 'A'

// notez le double %%, cela affiche un caractère '%' littéral
printf("%%b = '%b'\n", $n); // représentation binaire
printf("%%c = '%c'\n", $c); // affiche le caractère ascii, comme la fonction chr()
printf("%%d = '%d'\n", $n); // représentation standard d'un entier
printf("%%e = '%e'\n", $n); // notation scientifique
printf("%%u = '%u'\n", $n); // représentation entière non signée d'un entier positif
printf("%%u = '%u'\n", $u); // représentation entière non signée d'un entier négatif
printf("%%f = '%f'\n", $n); // représentation en virgule flottante
printf("%%o = '%o'\n", $n); // représentation octale
printf("%%s = '%s'\n", $n); // représentation chaîne de caractères
printf("%%x = '%x'\n", $n); // représentation hexadécimal (minuscule)
printf("%%X = '%X'\n", $n); // représentation hexadécimal (majuscule)

printf("%%+d = '%+d'\n", $n); // indication du signe pour un entier positif
printf("%%+d = '%+d'\n", $u); // indication du signe pour un entier négatif
?>
]]>
   </programlisting>
   &example.outputs;
   <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'
%+d = '+43951789'
%+d = '-43951789'
]]>
   </screen>
  </example>
  <example>
   <title><function>printf</function> : spécificateurs chaînes de caractères</title>
   <programlisting role="php">
<![CDATA[
<?php
$s = 'monkey';
$t = 'many monkeys';

printf("[%s]\n",      $s); // affichage d'une chaîne standard
printf("[%10s]\n",    $s); // justification à droite avec des espaces
printf("[%-10s]\n",   $s); // justification à gauche avec des espaces
printf("[%010s]\n",   $s); // l'espacement nul fonctionne aussi sur les chaînes
printf("[%'#10s]\n",  $s); // utilisation du caractère personnalisé de séparation '#'
printf("[%10.10s]\n", $t); // justification à gauche mais avec une coupure à 10 caractères
?>
]]>
   </programlisting>
   &example.outputs;
   <screen>
<![CDATA[
[monkey]
[    monkey]
[monkey    ]
[0000monkey]
[####monkey]
[many monke]
]]>
   </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 affichera "123.1";
$formatted = sprintf("%01.2f", $money);
// echo $formatted affichera "123.10"
?>
]]>
   </programlisting>
  </example>
  <example>
   <title><function>sprintf</function>: notation scientifique</title>
   <programlisting role="php">
<![CDATA[
<?php
$number = 362525200;

echo sprintf("%.3e", $number); // affiche 3.625e+8
?>
]]>
   </programlisting>
  </example>
 </refsect1>

 <refsect1 role="seealso">
  &reftitle.seealso;
  <para>
   <simplelist>
    <member><function>printf</function></member>
    <member><function>sscanf</function></member>
    <member><function>fscanf</function></member>
    <member><function>vsprintf</function></member>
    <member><function>number_format</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
-->