=head1 NOM
DateTime - Un objet pour les dates et les heures
=head1 RÉSUMÉ
use DateTime;
$dt = DateTime->new( year => 1964,
month => 10,
day => 16,
hour => 16,
minute => 12,
second => 47,
nanosecond => 500000000,
time_zone => 'Asia/Taipei',
);
$dt = DateTime->from_epoch( epoch => $epoch );
$dt = DateTime->now; # la même chose que ( epoch => time() )
$year = $dt->year;
$month = $dt->month; # 1-12 - ou bien mon
$day = $dt->day; # 1-31 - ou bien day_of_month, mday
$dow = $dt->day_of_week; # 1-7 (lundi = 1) - également dow, wday
$hour = $dt->hour; # 0-23
$minute = $dt->minute; # 0-59 - également min
$second = $dt->second; # 0-61 (secondes intercalaires !) - ou bien sec
$doy = $dt->day_of_year; # 1-366 (années bissextiles) - également doy
$doq = $dt->day_of_quarter; # 1.. - également doq
$qtr = $dt->quarter; # 1-4
# la plupart des méthodes ci-dessus comptent de 1 à n
# chacune d'entre elles a une méthode correspondante qui compte
# de 0 à n-1, par exemple $dt->day_of_month_0, $dt->month_0 etc.
$ymd = $dt->ymd; # 2002-12-06
$ymd = $dt->ymd('/'); # 2002/12/06 - également date
$mdy = $dt->mdy; # 12-06-2002
$mdy = $dt->mdy('/'); # 12/06/2002
$dmy = $dt->dmy; # 06-12-2002
$dmy = $dt->dmy('/'); # 06/12/2002
$hms = $dt->hms; # 14:02:29
$hms = $dt->hms('!'); # 14!02!29 - également time
$bissextile = $dt->is_leap_year;
# ces méthodes peuvent s'adapter en fonction de la localisation
$mois = $dt->month_name; # January, February... ou bien janvier, février...
$mois_abr = $dt->month_abbr; # Jan, Feb... ou bien jan, fév...
$jour = $dt->day_name; # Monday, Tuesday... ou bien lundi, mardi...
$jour_abr = $dt->day_abbr; # Mon, Tue... ou bien lun, mar...
$epoch_time = $dt->epoch;
# susceptible de renvoyer undef si la date-heure est en dehore de la plage
# supportée par votre système d'exploitation
$dt2 = $dt + $objet_duree;
$dt3 = $dt - $objet_duree;
$objet_duree = $dt - $dt2;
$dt->set( year => 1882 );
$dt->set_time_zone( 'America/Chicago' );
=head1 DESCRIPTION
DateTime est une classe qui permet de représenter les combinaisons
d'une date et d'une heure. Ce module fait partie du projet Perl DateTime.
Pour plus de détails sur ce projet, voir L
(en anglais) ou L (en français, mais
incomplet). Il existe une FAQ, traduite, qui peut vous aider
à répondre à vos questions du type S<« Comment> dois-je faire pour S
La version originale se trouve en L
et la traduction en L.
La classe représente le calendrier grégorien, extrapolé dans le
passé, antérieurement à sa création (en 1582). On l'appelle
parfois S<« calendrier> grégorien S. Dans ce calendrier,
la date origine est fixée au premier jour de l'an 1, qui correspond
à la date de naissance estimée du Christ (même si l'on s'est aperçu
ultérieurement que l'estimation était erronée).
Le calendrier possède une année 0 et diffère en cela de la façon habituelle
d'écriture des dates s<« avant> S.
Pour des dates-heures infinies, voir le module
L.
=head1 UTILISATION
=head2 Compter à partir de 0 ou à partir de 1
Le module DateTime.pm obéit à quelques règles simples et
cohérentes pour savoir si l'on doit compter à partir
de 0 ou à partir de 1.
Le mois, le jour du mois, le jour de la semaine et le jour de l'année
sont numérotés à partir de 1. Toutefois, pour chaque méthode
qui compte à partir de 1, il existe une méthode équivalente
comptant à partir de 0. Le nom de cette méthode est le nom
de la première avec le suffixe C<_0>. Par exemple, pour le
jour de la semaine, la classe propose deux méthodes, C et
C.
Toutefois, la méthode C continue à considérer que la
semaine commence le lundi.
Tous les nombres relatifs à l'heure, comme les méthodes C,
C et C, comptent à partir de 0.
La question ne se pose pas pour les années, puisqu'il existe des
années négatives en plus des années positives. Il n'y a donc pas
d'origine. Notons qu'il I une année 0.
Il n'existe pas de méthode C.
=head2 Traitement d'erreur
Certaines erreurs dans ce module arrêtent le traitement par un
C avec un message d'explication. Cela ne se produit que lors
de l'appel des constructeurs, des méthodes qui altèrent un objet
(typiquement C) ou des méthodes qui reçoivent des paramètres.
Les méthodes qui renvoient simplement une information, comme C
ou C, n'utilisent jamais C.
=head2 Localisation
Certaines méthodes peuvent s'adapter en fonction de la localisation.
Cela s'obtient en alimentant la propriété C lors de la
création d'un objet DateTime. Il existe une méthode de classe
C qui sera utilisée pour les objets DateTime
créés sans préciser de localisation. Si cette méthode ne renvoie
pas de localisation, le module utilise S<« English »> (anglais).
Certaines localisations renvoient des données en Unicode. Si vous
utilisez Perl 5.6.0 ou ultérieur, il s'agit de chaînes natives Unicode.
Avec une version antérieure de Perl, vous obtenez une séquence
d'octets représentant des caractères Unicode.
=head2 Objets DateTime flottants
Par défaut, le fuseau horaire d'un objet C est
le fuseau horaire S<« flottant»>. Ce concept est repris du
standard ICal. Un objet C flottant n'est pas
attaché à un fuseau horaire déterminé. De plus, il ne tient
pas compte des secondes intercalaires, puisqu'il est impossible
de savoir quand ces secondes apparaissent si l'on ne connaît pas
le fuseau horaire.
Les calculs et les comparaisons faisant intervenir un C
flottant et un C associé à un véritable fuseau horaire
ne sont pas réellement valides, car l'un tient compte des secondes
intercalaire et pas l'autre. De même, il est impossible de comparer
le résultat d'un calcul sur des C flottants avec le résultat
du même calcul sur des C dépendant d'un fuseau horaire.
Si vous avez l'intention d'utiliser des objets associés à un véritable
fuseau horaire, nous vous recommandons vivement de B les
mélanger avec des C flottants.
=head2 Méthodes
=head3 Constructeurs
Tous les constructeurs s'arrêtent par C s'ils reçoivent des
paramètres invalides.
=over 4
=item * new( ... )
Cette méthode de classe attend un paramètre pour chaque composant
de date et d'S
C pour l'année, C pour le mois, C pour le jour,
C pour les heures, C pour les minutes,
C pour les secondes et C pour les nanosecondes.
Il est possible de transmettre également un paramètre C
pour la langue et les autres informations de localisation et un
paramètre C pour le fuseau horaire.
my $dt = DateTime->new( year => 1066,
month => 10,
day => 25,
hour => 7,
minute => 15,
second => 47,
nanosecond => 500000000,
time_zone => 'America/Chicago',
);
C contrôle les paramètres "month", "day", "hour", "minute", "second"
et "nanosecond". Les valeurs autorisées S
=over 8
=item * month
1-12
=item * day
1-31, sachant que cette plage de valeurs peut se réduire à 1-30, 1-29
ou 1-28 selon le mois.
=item * hour
0-23
=item * minute
0-59
=item * second
0-61 (61 à cause des secondes intercalaires). Les valeurs 60 et 61
ne sont autorisées que si elle correspondent réellement à des
secondes intercalaires.
=item * nanosecond
>= 0
=back
=back
Un type de paramètre invalide (une référence de tableau, par exemple),
provoquera la mort (C) du constructeur.
Tous les paramètres sont facultatifs, à part C pour l'année.
la valeur par défaut du mois et du jour est 1. La valeur par défaut
des heures, minutes, secondes et nanosecondes est 0.
Le paramètre C est soit une chaîne correspondant aux locales
valides, soit un objet C object. Cf. la documentation de
L pour des détails complémentaires.
Le paramètre C peut être un scalaire (XXXX une chaîne) ou un objet
C. S'il s'agit d'une chaîne, elle sera passée telle
quelle en tant que paramètre C à la méthode
C<< DateTime::TimeZone->new >>. Cette chaîne peut être le nom d'un
fuseau horaire tel qu'il apparaît dans la base de données Olson
("America/Chicago"), une chaîne donnant un décalage ("+0630"),
ou les mots "floating" ou "local". Cf. la documentation de
C pour les détails.
Le fuseau horaire par défaut est C.
=head4 Heures locales ambiguës
En raison des transitions avec l'heure d'été, il est possible
de spécifier une heure ambiguë. Par exemple, en France, le
retour à l'heure d'hiver a eu lieu le 26 octobre, à 3h00, heure
locale. Une pendule à l'heure locale passe alors de
02:59:59 (heure d'été) à 02:00:00 (heure standard). Cela signifie
que l'heure entre 02:00:00 et 02:59:59 se produit deux fois,
alors que le temps UTC continue à progresser.
Si vous spécifiez une heure ambiguë, c'est le temps UTC le plus
tardif qui sera utilisé, c'est-à-dire que l'on choisira l'heure
d'hiver. Dans ce cas, vous pouvez tout simplement
retrancher une heure pour revenir à l'heure d'été. Par S
# Cet objet représente 02:30:00 heure d'hiver
my $dt = DateTime->new( year => 2003,
month => 10,
day => 26,
hour => 2,
minute => 30,
second => 0,
time_zone => 'Europe/Paris',
);
print $dt->hms; # imprime 02:30:00
# Maintenant, l'objet représente 02:30:00 heure d'été
$dt->subtract( hours => 1 );
print $dt->hms; # continue à imprimer 02:30:00
Une autre façon de procéder consiste à créer l'objet en l'associant
au fuseau UTC, puis à appeler la méthode C
pour passer au fuseau horaire local. Il n'y a ainsi plus d'ambiguïté
à craindre.
=head4 Heure locale invalide
Un autre problème induit par l'heure d'été est que certaines
heures locales n'existent tout simplement pas. Par exemple,
en France en 2004, le passage à l'heure d'été a eu lieu
le 28 mars à 02:00:00 heure locale. L'heure locale
est donc passée de 01:59:59 (heure d'hiver) à 03:00:00
(heure d'été). Cela signifie qu'il n'y a rien de 02:00:00
à 02:59:59 le 28 S
Si vous essayez de créer un objet avec une heure invalide,
il se produit une erreur fatale. Ce comportement est
susceptible de changer dans une version future du module.
=over 4
=item * from_epoch( epoch => $epoch, ... )
Cette méthode de classe permet de construire un objet C
à partir d'une valeur I au lieu de spécifier chacun des
composants. Tout comme C, ce constructeur
accepte les paramètres C et C.
Si le paramètre C n'est pas un entier, la partie décimale
sera convertie en nanosecondes pour créer l'objet. Le module
procède ainsi pour être compatible avec C. Si
la partie décimale comporte plus de 9 chiffres, elle sera tronquée
à cette longueur, de sorte que 1.1234567891 correspondra à
1 seconde et S<123 456 789 nanosecondes>.
=item * now( ... )
Cette méthode équivaut à appeler C avec la valeur
renvoyée par la fonction standard C