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

<?xml version="1.0" encoding="utf-8"?>
<!-- EN-Revision: 45042fef652f1b4e904e809fcbfcf31f6c60670b 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>values</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>
  </example>
  <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>
  <example>
   <title>Mauvais ordre des 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 = 'tree';
$format = 'Le %s a %d singes';

echo sprintf($format, $num, $location);
?>
]]>
   </programlisting>
  </example>
  <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>
 
 <example>
  <title>Utilisation de l'espace réservé d'ordre</title>
  <programlisting role="php">
<![CDATA[
<?php
$num = 5;
$location = 'tree';

$format = 'Le %2$s a %1$d singes';
echo sprintf($format, $num, $location);
?>
]]>
  </programlisting>
 </example>
 <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>
 <example>
  <title>Répétition de l'espace réservé</title>
  <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>
  </example>
  <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>
   <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
$year = 2005;
$month = 5;
$day = 6;

$isodate = sprintf("%04d-%02d-%02d", $year, $month, $day);
echo $isodate;
?>
]]>
   </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, PHP_EOL;

$formatted = sprintf("%01.2f", $money);
echo $formatted, PHP_EOL;
?>
]]>
   </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), PHP_EOL;
?>
]]>
   </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
-->