doc-fr/reference/datetime/functions/strftime.xml

<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.28 $ -->
<!-- EN-Revision: 1.25 Maintainer: yannick Status: ready -->
<!-- Reviewed: no -->

<refentry xml:id="function.strftime" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
 <refnamediv>
  <refname>strftime</refname>
  <refpurpose>Formate une date/heure locale avec la configuration locale</refpurpose>
 </refnamediv>

 <refsect1 role="description">
  &reftitle.description;
  <methodsynopsis>
   <type>string</type><methodname>strftime</methodname>
   <methodparam><type>string</type><parameter>format</parameter></methodparam>
   <methodparam choice="opt"><type>int</type><parameter>timestamp</parameter></methodparam>
  </methodsynopsis>
  <para>
   Formate une date/heure locale suivant la localisation locale. Les noms
   des mois, des jours de la semaine mais aussi d'autres chaînes dépendant
   de la location, respecteront la localisation courante définie par la fonction
   <function>setlocale</function>.
  </para>
  <para>
   Tous les caractères modificateurs ne sont pas toujours supportés par
   toutes les bibliothèques C. Dans ce cas, ils ne seront pas supportés
   par PHP non plus. De plus, toutes les plates-formes ne supportent pas
   les timestamps négatifs, et vos dates pourraient être limitées par le
   début de l'époque Unix. Cela signifie que 
   %e, %T, %R et %D (et peut être d'autres) et les dates antérieures au
   <literal>1er Janvier 1970</literal> ne fonctionneront pas sous Windows,
   sur certaines distributions de Linux, et sur certains systèmes d'exploitation.
   Pour Windows, une liste complète des options de conversion est disponible
   sur le <link xlink:href="&url.strftime.win32;">site de <acronym>MSDN</acronym></link>.
  </para>
 </refsect1>

 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <variablelist>
    <varlistentry>
     <term><parameter>format</parameter></term>
     <listitem>
      <para>
       Les caractères suivants sont utilisés pour spécifier
       le format de la date :
       <itemizedlist>
        <listitem>
         <simpara>
          %a - nom abrégé du jour de la semaine (local)
         </simpara>
        </listitem>
        <listitem>
         <simpara>
          %A - nom complet du jour de la semaine (local)
         </simpara>
        </listitem>
        <listitem>
         <simpara>
          %b - nom abrégé du mois (local)
         </simpara>
        </listitem>
        <listitem>
         <simpara>
          %B - nom complet du mois (local)
         </simpara>
        </listitem>
        <listitem>
         <simpara>
          %c - représentation préférée pour les dates et heures, en local
         </simpara>
        </listitem>
        <listitem>
         <simpara>
          %C - numéro de siècle (l'année, divisée par 100
          et arrondie entre 00 et 99)
         </simpara>
        </listitem>
        <listitem>
         <simpara>
          %d - jour du mois en numérique (intervalle 01 à 31)
         </simpara>
        </listitem>
        <listitem>
         <simpara>
          %D - identique à  %m/%d/%y
         </simpara>
        </listitem>
        <listitem>
         <simpara>
          %e - numéro du jour du mois. Les chiffres sont précédés
          d'un espace (de ' 1' à '31')
         </simpara>
        </listitem>
        <listitem>
         <simpara>
          %g - identique à %G, sur 2 chiffres
         </simpara>
        </listitem>
        <listitem>
         <simpara>
          %G - L'année sur 4 chiffres correspondant au numéro de semaine (voir %V).
          Même format et valeur que %Y, excepté que si le numéro de la semaine
          appartient à l'année précédente ou suivante, l'année courante sera utilisé à la place
         </simpara>
        </listitem>
        <listitem>
         <simpara>
          %h - identique à %b
         </simpara>
        </listitem>
        <listitem>
         <simpara>
          %H - heure de la journée en numérique, et sur 24-heures
          (intervalle de 00 à 23)
         </simpara>
        </listitem>
        <listitem>
         <simpara>
          %I - heure de la journée en numérique, et sur 12- heures
          (intervalle 01 à 12)
         </simpara>
        </listitem>
        <listitem>
         <simpara>
          %j - jour de l'année, en numérique (intervalle 001 à 366)
         </simpara>
        </listitem>
        <listitem>
         <simpara>
          %m - mois en numérique (intervalle 1 à 12)
         </simpara>
        </listitem>
        <listitem>
         <simpara>
          %M - minute en numérique
         </simpara>
        </listitem>
        <listitem>
         <simpara>
          %n - caractère de nouvelle ligne
         </simpara>
        </listitem>
        <listitem>
         <simpara>
          %p - `AM' ou `PM', en majuscule, suivant la valeur donnée, ou la chaîne
          correspondante pour la locale courante
         </simpara>
        </listitem>
        <listitem>
         <simpara>
          %P - `am' ou `pm', en majuscule, suivant la valeur donnée, ou la chaîne
          correspondante à la locale courante
         </simpara>
        </listitem>
        <listitem>
         <simpara>
          %r - l'heure au format a.m. et p.m
         </simpara>
        </listitem>
        <listitem>
         <simpara>
          %R - l'heure au format 24h
         </simpara>
        </listitem>
        <listitem>
         <simpara>
          %S - secondes en numérique
         </simpara>
        </listitem>
        <listitem>
         <simpara>
          %t - tabulation
         </simpara>
        </listitem>
        <listitem>
         <simpara>
          %T - l'heure actuelle (égal à  %H:%M:%S)
         </simpara>
        </listitem>
        <listitem>
         <simpara>
          %u - le numéro de jour dans la semaine, de 1 à 7. (1 représente
          Lundi)
         </simpara>
         <warning>
          <simpara>
           Les systèmes Sun Solaris semblent commencer le Dimanche à 1 malgré
           le fait que le standard ISO 9889:1999 (actuellement le standard C) spécifie 
           clairement le début de la semaine à Lundi.
          </simpara>
         </warning>
        </listitem>
        <listitem>
         <simpara>
          %U - numéro de semaine dans l'année, en considérant
          le premier dimanche de l'année comme le premier jour de la
          première semaine
         </simpara>
        </listitem>
        <listitem>
         <simpara>
          %V - le numéro de semaine comme défini dans l'ISO 8601:1988,
          sous forme décimale, de 01 à 53. La semaine 1 est la première
          semaine qui a plus de 4 jours dans l'année courante, et dont
          Lundi est le premier jour. (Utilisez %G ou %g pour les éléments de l'année
          qui correspondent au numéro de la semaine pour le timestamp donné.)
         </simpara>
        </listitem>
        <listitem>
         <simpara>
          %W - numéro de semaine dans l'année, en considérant
          le premier lundi de l'année comme le premier jour de la
          première semaine
         </simpara>
        </listitem>
        <listitem>
         <simpara>
          %w - jour de la semaine, numérique, avec Dimanche = 0
         </simpara>
        </listitem>
        <listitem>
         <simpara>
          %x - format préféré de représentation de la date sans l'heure
         </simpara>
        </listitem>
        <listitem>
         <simpara>
          %X - format préféré de représentation de l'heure sans la date
         </simpara>
        </listitem>
        <listitem>
         <simpara>
          %y - l'année, numérique, sur deux chiffres (de 00 à 99)
         </simpara>
        </listitem>
        <listitem>
         <simpara>
          %Y - l'année, numérique, sur quatre chiffres
         </simpara>
        </listitem>
        <listitem>
         <simpara>
          %Z ou %z - fuseau horaire, ou nom ou abréviation (suivant le système
          d'exploitation)
         </simpara>
        </listitem>
        <listitem>
         <simpara>
          %% - un caractère `%' littéral
         </simpara>
        </listitem>
       </itemizedlist>
      </para>
      <para>
       La longueur maximale de ce paramètre est de 1023 caractères.
      </para>
     </listitem>
    </varlistentry>

    &date.timestamp.description;

   </variablelist>
  </para>
 </refsect1>

 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   Retourne une &string; formatée suivant le format donné, en utilisant
   le paramètre <parameter>timestamp</parameter> ou la date locale courante
   si aucun timestamp n'est fourni. Les noms des mois, des jours de la
   semaine mais aussi d'autres chaînes dépendant de la location, respecteront
   la localisation courante définie par la fonction <function>setlocale</function>.
  </para>
 </refsect1>

 <refsect1 role="errors">
  &reftitle.errors;
  &date.timezone.errors.description;
 </refsect1>

 <refsect1 role="changelog">
  &reftitle.changelog;
  <para>
   <informaltable>
    <tgroup cols="2">
     <thead>
      <row>
       <entry>&Version;</entry>
       <entry>&Description;</entry>
      </row>
     </thead>
     <tbody>
      &date.timezone.errors.changelog;
     </tbody>
    </tgroup>
   </informaltable>
  </para>
 </refsect1>

 <refsect1 role="examples">
  &reftitle.examples;
  <para>
   Cet exemple ne fonctionnera que si vous avez les locales respectives
   installées sur votre système.
   <example>
    <title>Exemple avec <function>strftime</function></title>
    <programlisting role="php">
<![CDATA[
<?php
setlocale(LC_TIME, "C");
echo strftime("%A");
setlocale(LC_TIME, "fi_FI");
echo strftime(" in Finnish is %A,");
setlocale(LC_TIME, "fr_FR");
echo strftime(" in French %A and");
setlocale(LC_TIME, "de_DE");
echo strftime(" in German %A.\n");
?>
]]>
    </programlisting>
   </example>
   <example>
    <title>Exemple au format de date ISO 8601:1988</title>
    <programlisting role="php">
<![CDATA[
<?php
/*     December 2002 / January 2003
ISOWk  M   Tu  W   Thu F   Sa  Su
----- ----------------------------
51     16  17  18  19  20  21  22
52     23  24  25  26  27  28  29
1      30  31   1   2   3   4   5
2       6   7   8   9  10  11  12
3      13  14  15  16  17  18  19   */

// Affiche : 12/28/2002 - %V,%G,%Y = 52,2002,2002
echo "12/28/2002 - %V,%G,%Y = " . strftime("%V,%G,%Y", strtotime("12/28/2002")) . "\n";

// Affiche : 12/30/2002 - %V,%G,%Y = 1,2003,2002
echo "12/30/2002 - %V,%G,%Y = " . strftime("%V,%G,%Y", strtotime("12/30/2002")) . "\n";

// Affiche : 1/3/2003 - %V,%G,%Y = 1,2003,2003
echo "1/3/2003 - %V,%G,%Y = " . strftime("%V,%G,%Y",strtotime("1/3/2003")) . "\n";

// Affiche : 1/10/2003 - %V,%G,%Y = 2,2003,2003
echo "1/10/2003 - %V,%G,%Y = " . strftime("%V,%G,%Y",strtotime("1/10/2003")) . "\n";

/*     December 2004 / January 2005
ISOWk  M   Tu  W   Thu F   Sa  Su
----- ----------------------------
51     13  14  15  16  17  18  19
52     20  21  22  23  24  25  26
53     27  28  29  30  31   1   2
1       3   4   5   6   7   8   9
2      10  11  12  13  14  15  16   */

// Affiche : 12/23/2004 - %V,%G,%Y = 52,2004,2004
echo "12/23/2004 - %V,%G,%Y = " . strftime("%V,%G,%Y",strtotime("12/23/2004")) . "\n";

// Affiche : 12/31/2004 - %V,%G,%Y = 53,2004,2004
echo "12/31/2004 - %V,%G,%Y = " . strftime("%V,%G,%Y",strtotime("12/31/2004")) . "\n";

// Affiche : 1/2/2005 - %V,%G,%Y = 53,2004,2005
echo "1/2/2005 - %V,%G,%Y = " . strftime("%V,%G,%Y",strtotime("1/2/2005")) . "\n";

// Affiche : 1/3/2005 - %V,%G,%Y = 1,2005,2005
echo "1/3/2005 - %V,%G,%Y = " . strftime("%V,%G,%Y",strtotime("1/3/2005")) . "\n";

?>
]]>
    </programlisting>
   </example>
  </para>
 </refsect1>

 <refsect1 role="notes">
  &reftitle.notes;
  <note>
   <simpara>
    %G et %V, qui sont basées sur la semaine ISO 8601:1988, peut
    conduire à des résultat inattendus (bien que corrects) si le
    système de numérotation n'est pas connu. Voir l'exemple 
    %V de cette page.
   </simpara>
  </note>
 </refsect1>

 <refsect1 role="seealso">
  &reftitle.seealso;
  <para>
   <simplelist>
    <member><function>setlocale</function></member>
    <member><function>mktime</function></member>
    <member><function>strptime</function></member>
    <member><function>gmstrftime</function></member>
    <member><link xlink:href="&spec.strftime;">groupe de spécifications de <function>strftime</function></link></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:"../../../../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
-->