=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 de Perl. Tout comme la méthode C, cette méthode accepte les paramètres C et C. =item * today( ... ) L'utilisation de cette méthode équivaut S<à :> DateTime->now->truncate( to => 'day' ); =item * from_object( object => $object, ... ) Cette méthode de classe permet de construire un objet C à partir de n'importe quel objet qui possède une méthode C. C'est le cas des modules C, qui doivent implémenter cette méthode pour fournir un mode de conversion de calendrier à calendrier. Cette méthode accepte un paramètre C. Si l'objet passé en paramètre possède également une méthode C, cette méthode est utilisée pour le nouvel objet C et l'associer au même fuseau horaire que l'objet source. =item * last_day_of_month( ... ) Ce contructeur admet les mêmes arguments que la méthode C sauf le jour C. D'autre part, il y a maintenant deux paramètres obligatoires, C et C. =item * from_day_of_year( ... ) Ce constructeur reçoit les mêmes arguments que C, sauf les arguments C et C qui sont interdits. En revanche, il y a deux paramètres obligatoires, C pour l'année et C qui donne le numéro du jour dans l'année, numéro compris entre 1 et 366. La valeur 366 n'est autorisée que pour les années bissextiles. =item * clone Il s'agit d'une méthode d'instance, qui renvoie une nouvelle instance, réplique de l'objet origine. =back =head3 Méthodes "Get" La classe C possède de nombreuses méthodes pour fournir de l'information sur un objet. =over 4 =item * year Renvoie l'année. =item * ce_year Renvoie l'année conformément à la numérotation av. J.-C. / ap. J.-C. (ou BCE/CE en anglais). L'année qui précède l'an 1 dans ce système est l'année S<« -1 »>, c'est-à-dire S<« 1> avant S. =item * era Renvoie une chaîne S<« BCE »> ou S<« CE »> (en anglais), ou S<« av. J.-C. »> ou S<« ap. J.-C. »> en français. =item * year_with_era Renvoie une chaîne comportant l'année et l'ère correspondante. La valeur numérique de l'année est la valeur absolue de C, donc l'année 1 est S<« 1 ap. J.-C. »> et l'année 0 est S<« 1 av. J.-C. »>. =item * month Renvoie le mois de l'année, dans l'intervalle 1..12. =item * month_name Renvoie le nom du mois. Cf. la section L pour les détails. =item * month_abbr Renvoie l'abréviation du mois. Cf. la section L pour les détails. =item * day_of_month, day, mday Renvoie le jour du mois, dans l'intervalle 1..31. =item * day_of_week, wday, dow Renvoie le jour de la semaine sous forme numérique, dans l'intervalle 1..7, 1 représentant le lundi et 7 représentant le dimanche. =item * day_name Renvoie le jour de la semaine. Cf. la section L pour les détails. =item * day_abbr Renvoie l'abréviation du jour de la semaine. Cf. la section L pour les détails. =item * day_of_year, doy Renvoie le jour relativement à l'année. =item * quarter Renvoie le numéro du trimestre, intervalle 1..4. =item * day_of_quarter, doq Renvoie le numéro du jour dans le trimestre. =item * weekday_of_month Renvoie un nombre dans l'intervalle 1..5, indiquant le numéro de la semaine relativement au mois. Par exemple, pour le 9 juin 2003, qui est le deuxième lundi de ce mois, la méthode renvoie 2. =item * ymd( $separateur_facultatif ), date =item * mdy( $separateur_facultatif ) =item * dmy( $separateur_facultatif ) Ces trois méthodes renvoient une chaîne comportant l'année (y), le mois (m) et le jour (d) dans l'ordre indiqué par le nom de la méthode. L'année comporte 4 chiffres, en complétant si nécessaire par des zéros à gauche. De même, le mois et le jour comportent deux chiffres chacun, avec si nécessaire un zéro à gauche. Par défaut, les trois valeurs sont séparées par un tiret S<« - »>, mais vous pouvez spécifier le séparateur de votre choix en le transmettant comme paramètre à l'appel de la méthode. =item * hour Renvoie l'heure du jour, dans l'intervalle 0..23. =item * hour_1 Renvoie l'heure du jour, dans l'intervalle 1..24. =item * hour_12 Renvoie l'heure du jour, dans l'intervalle 1..12. =item * hour_12_0 Renvoie l'heure du jour, dans l'intervalle 0..11. =item * minute, min Renvoie les minutes, dans l'intervalle 0..59. =item * second, sec Renvoie les secondes, dans l'intervalle 0..61. Les valeurs 60 et 61 sont utilisées pour les secondes intercalaires. =item * fractional_second Renvoie les secondes, sous forme d'un nombre réel dans l'intervalle 0.0 jusqu'à 61.999999999 Les valeurs à partir de 60 correspondent aux secondes intervalaires. =item * millisecond Renvoie la partie décimale de la seconde, convertie en millisecondes (1E-3 secondes). Une demi-seconde vaut 500 millisecondes. =item * microsecond Renvoie la partie décimale de la seconde, convertie en microsecondes (1E-6 secondes). Cette valeur est arrondie pour obtenir un entier. Une demi-seconde vaut 500_000 microsecondes. Cette valeur est arrondie pour obtenir un entier. =item * nanosecond Renvoie la partie décimale de la seconde, convertie en nanosecondes (1E-9 secondes). Une demi-seconde vaut 500_000_000 nanosecondes. =item * hms( $optional_separator ), time Renvoie les heures, minutes et secondes, chacune sur deux chiffres. Si le séparateur n'est pas renseigné, la méthode utilise par défaut le deux-points S<« : »>. =item * datetime, iso8601 Cette méthode équivaut S<à :> $dt->ymd('-') . 'T' . $dt->hms(':') =item * is_leap_year Cette méthode renvoie une valeur vraie ou fausse selon que l'année de l'objet C est une année bissextile ou une année normale. =item * week ($week_year, $week_number) = $dt->week; Renvoie les informations concernant la semaine qui contient l'objet C. Les valeurs sont disponibles séparément avec les méthode C et C. Le standard ISO définit la première semaine de l'année comme étant celle qui contient le 4 janvier. Une définition équivalente est de dire que c'est la première semaine dont au moins quatre jours sont contenus dans l'année demandée. Généralement, l'année de la semaine (C) coïncide avec l'année du jour, mais au tout début de l'année, une date peut appartenir à la dernière semaine de l'année précédente. De même, en fin d'année, une date peut appartenir à la première semaine de l'année suivante. =item * week_year Renvoie l'année de la seamine. =item * week_number Renvoie le numéro de la semaine dans l'année, dans l'intervalle 1..53. =item * week_of_month Le numéro de la semaine dans le mois, intervalle 0..5. La première semaine du mois est la première semaine comportant un jeudi dans ce mois. Cela se base sur la définition ICU de la semaine et cela correspond à la définition ISO8601 de la semaine dans l'année. Si un jour est antérieur à la première semaine du mois (un vendredi premier ou un samedi 2, par exemple), la méthode renvoie 0. =item * jd, mjd Ces méthodes renvoient le S<« jour julien »> et le S<« jour> julien S (I et I), respectivement. La valeur est un nombre flottant, la partie décimale représentant la portion heures-minutes-secondes de l'objet. =item * time_zone Renvoie l'objet C représentant le fuseau horaire. =item * offset Renvoie le décalage du fuseau horaire par rapport au temps UTC, en secondes. =item * is_dst Renvoie un booléen indicant si l'objet C correspond à l'heure d'été (vrai) ou à l'heure d'hiver (faux). =item * time_zone_long_name C'est un raccourci pour C<< $dt->time_zone->name >>. Cette méthode est fournie pour permettre l'utilisation d'une spécification C<%{time_zone_long_name}> dans une chaîne de format pour C. =item * time_zone_short_name Cette méthode renvoie l'abréviation du fuseau horaire courant, comme S<« PST »> ou S<« GMT »>. Ces abréviations peuvent prêter à confusion et B être utilisées pour une application permettant de faire référence au monde entier. =item * strftime( $format, ... ) Cette méthode apporte une fonctionnalité équivalente à la fonction C du langage C. Toutefois, si plusieurs chaînes de format sont transmises en paramètre, la méthode renverra une liste de scalaires, un par chaîne de format. Cf. le paragraphe L pour avoir la liste de toutes les spécifications possibles. Si vous envoyez une spécification de format inexistante, alors elle sera traitée comme une sous-chaîne de caractères fixes. =item * epoch Renvoie la valeur I UTC de l'objet C. En interne, cette méthode utilise C, qui se base sur la date origine Unix, même sur les machines qui utilisent une autre date origine (comme Mac OS). Pour un objet C antérieur à cette date origine, la valeur renvoyée est négative. La valeur renvoyée est toujours un entier. Étant donné que la valeur I ne tient pas compte des secondes intercalaires, la valeur pour 1971-12-31T23:59:60 (UTC) est strictement égale à celle pour 1972-01-01T00:00:00. Sur la plupart des plateformes, les valeurs I sont dans l'incapacité de représenter de nombreuses dates. La méthode renvoie donc C dans certains cas. L'utilisation de la date origine de votre système est sujette à erreur, étant donné que la plage de valeurs est très limitée sur les machines à 32 bits. De plus, le fait que des systèmes d'exploitation différents ont des dates origines différentes est une autre source d'erreurs. =item * hires_epoch Renvoie la valeur I sous la forme d'un nombre flottant. La partie décimale correspond aux nanosecondes de l'objet C. Cette méthode est fournie pour assurer la compatibilité avec le module C. =item * is_finite, is_infinite Ces méthodes permettent de déterminer si un objet C est fini ou infini. Les objets infinis sont documentés dans le module L. =item * utc_rd_values Renvoie une liste de trois éléments, avec le nombre de jours I, les secondes et les nanosecondes, le tout pour le temps UTC. Cette méthode a pour principal but d'assurer la conversion vers d'autres calendriers, les modules correspondants créant des objets se basant sur ces trois valeurs. =item * leap_seconds Renvoie le nombre de secondes intercalaires précédant la date représentée par l'objet. Pour les dates dans le fuseau flottant, la méthode renvoie toujours 0. =item * utc_rd_as_seconds Renvoie les valeurs UTC I des jours et des secondes combinées en un seul nombre. Ce nombre ne tient pas compte des fractions de secondes ni des secondes intercalaires. =item * local_rd_as_seconds -- déprécié Renvoie les valeurs locales I des jours et des secondes combinées en un seul nombre. Ce nombre ne tient pas compte des fractions de secondes ni des secondes intercalaires. À ne plus utiliser. =item * locale Renvoie l'objet C associé à l'objet date. =back =head3 Méthodes "Set" Les méthodes restantes du module C, sauf exception dûment signalée, renvoient l'objet lui-même, ce qui permet l'appel en cascade des méthodes. S my $dt = DateTime->now->set_time_zone( 'Australia/Sydney' ); my $first = DateTime ->last_day_of_month( year => 2003, month => 3 ) ->add( days => 1 ) ->subtract( seconds => 1 ); =over 4 =item * set( .. ) Cette méthode permet de changer les composants de la date et de l'heure, ou bien la localisation. Cette méthode accepte les mêmes paramètres que la méthode C, à l'exception du paramètre C. Pour modifier le fuseau horaire, il faut utiliser la méthode dédiée C. Cette méthode contrôle la valeur des paramètres exactement comme la méthode C. =item * truncate( to => ... ) Cette méthode permet de réinitialiser certains composants de l'heure et éventuellement de la date à leur valeur S<« zéro »>. Le paramètre C permet de spécifier à quel niveau il faut tronquer, à savoir C pour l'année, C pour le mois, C pour la semaine, C pour le jour, C pour les heures, C pour les minutes ou C pour les secondes. Par exemple, si vous demandez à tronquer au mois près (C), le jour est reinitialisé à 1, tandis que les heures, minutes, secondes et nanosecondes sont remises à zéro. Si vous spécifiez C pour la semaine, alors la date est ramenée au premier jour de la semaine où elle apparaît et les composantes de l'heure sont remises à zéro. =item * set_time_zone( $tz ) Cette méthode accepte soit un objet C, soit une chaîne de caractères pouvant être transmise en tant que paramètre C à C<< DateTime::TimeZone->new() >>. Si le décalage horaire du nouveau fuseau horaire diffère de celui de l'ancien, alors l'heure I est ajustée en conséquence. Par S my $dt = DateTime->new( year => 2000, month => 5, day => 10, hour => 15, minute => 15, time_zone => 'America/Los_Angeles', ); print $dt->hour; # affiche 15 $dt->set_time_zone( 'America/Chicago' ); print $dt->hour; # affiche 17 Si l'ancien fuseau horaire est le fuseau flottant, aucun ajustement n'est effectué, mis à part l'ajustement des secondes intercalaires. Si le nouveau fuseau horaire est le fuseau flottant, alors l'heure I est ajustée de façon à ce que l'heure locale ne soit pas modifiée. Les amateurs des films de Tsai Ming-Liang seront heureux de savoir que ceci S my $dt = DateTime::TimeZone->now( time_zone => 'Asia/Taipei' ); $dt->set_time_zone( 'Europe/Paris' ); Oui, nous pouvons maintenant I. =item * add_duration( $objet_durée ) Cette méthode additionne un objet C à l'objet date-heure. Cf. la documentation du module L pour plus de détails. =item * add( paramètres pour DateTime::Duration->new ) Cette méthode n'est rien de plus que du sucre syntaxique pour la méthode C. Elle se contente de créer un nouvel objet C avec les paramètres transmis et d'appeler ensuite la méthode C. =item * subtract_duration( $objet_durée ) Avec un objet C, cette méthode appelle la méthode C et transmet le nouvel objet durée à la méthode C. =item * subtract( paramètres pour DateTime::Duration->new ) Tout comme C, c'est simplement du sucre syntactique pour la méthode C. =item * subtract_datetime( $datetime ) Cette méthode crée un objet C représentant la différence entre les deux dates. La durée est B à l'objet auquel C<$datetime> est soustrait. 2003-03-15 00:00:00.00000000 - 2003-02-15 00:00:00.00000000 ------------------------------- = 1 mois Notez que cette durée n'est pas une mesure absolue de la durée entre les deux dates, étant donné que la durée d'un mois dépend de ce mois et qu'il peut y avoir également des secondes intercalaires. La durée renvoyée peut avoir des valeurs de delta pour les mois, les jours, les minutes, les secondes et les nanosecondes. =item * subtract_datetime_absolute( $datetime ) Cette méthode renvoie un objet durée (C) représentant la différence des deux dates. L'objet durée n'aura de valeur delta que pour les secondes et les nanosecondes. C'est la seule façon de mesurer précisément la durée absolue entre deux dates-heures, compte tenu du fait que toute unité de mesure supérieure à la seconde ne représente pas un nombre constant de secondes. =item * delta_md( $datetime ) =item * delta_days( $datetime ) =item * delta_ms( $datetime ) Chacune de ces méthodes crée un objet C représentant une portion de la différence entre les deux dates. La méthode C renvoie une durée ne comportant que des mois et des jours. La méthode C renvoie une durée ne contenant que des jours et la méthode C renvoie une durée ne comportant que des minutes et des secondes. Les méthodes C et C tronquent la durée de sorte que les fractions de jours sont perdues. La méthode C convertit les différences de jours et de mois en minutes. À l'inverse des méthodes de soustraction, B. =back =head3 Méthodes de classe =over 4 =item * DefaultLocale( $locale ) Cette méthode permet de spécifier la valeur par défaut à utiliser lors de la création des objets dates-heures. Si la localisation n'est pas définie, la valeur sera C. =item * compare =item * compare_ignore_floating $cmp = DateTime->compare( $dta, $dtb ); $cmp = DateTime->compare_ignore_floating( $dta, $dtb ); Compare deux objets dates-heures. La sémantique est compatible avec la fonction C de Perl. Les méthodes renvoient -1 si $dta < $dtb, 0 si $dta == $dtb, 1 si $dta > $dtb. Si l'un des objets dates-heures est associé au fuseau flottant, il sera d'abord converti au fuseau horaire de l'autre objet. La plupart du temps, c'est le comportement auquel vous vous attendez, mais il peut se produire des cas où les résultats seront incohérents, si vous avez à comparer plusieurs objets, dont certains sont flottants et les autres dans divers fuseaux horaires fixes. Si vous souhaitez avoir des résultats cohérents (parce que vous devez trier un tableau de dates, par exemple), vous pouvez utiliser la méthode S :> @dates = sort { DateTime->compare_ignore_floating($a, $b) } @dates; Dans ce cas, tout se passe comme si les dates-heures flottantes étaient associées au fuseau horaire UTC. Étant donné que le module C surcharge les opérateurs de comparaison, cette S @dates = sort @dates; équivaut à S @dates = sort { DateTime->compare($a, $b) } @dates; Les objets C peuvent être comparés à des objets de tout autre calendrier qui connaisse la méthode C. =back =head2 Mécanismes de calcul Pour pouvoir utiliser convenablement ce module et C, il est important d'avoir quelques notions sur les mécanismes de calcul sur les dates et les durées. Les éléments d'un objet durée sont découpés en quatre parties. Il y a les mois, les jours, les minutes et les secondes. Ajouter un mois n'est pas la même chose qu'ajouter 4 semaines, ou 28, 29, 30 ou 31 jours. De même, avec l'heure d'été et les secondes intercalaires, ajouter un jour n'est pas la même chose qu'ajouter S<86 400 secondes>, ajouter une minute n'est pas la même chose qu'ajouter 60 secondes. C procède toujours en additionnant (ou soustrayant) les jours, puis les mois, les minutes et enfin les secondes. Si un débordement se produit à une étape, la valeur est normalisée avant de passer à l'étape suivante. Cela signifie que si l'on part du 28 février 2003, l'ajout d'une durée de 1 mois et 1 jour donnera le premier avril 2003, pas le 29 mars. my $dt = DateTime->new( year => 2003, month => 2, day => 28 ); $dt->add( months => 1, days => 1 ); # 2003-04-01 - résultat D'un autre côté, si nous scindons les additions pour ajouter d'abord un mois et seulement ensuite ajouter un jour, nous obtiendrons le 29 mars S<2003 :> $dt->add( months => 1 )->add( days => 1 ); # 2003-03-29 =head3 Calcul et secondes intercalaires La présence de secondes intercalaires peut occasionner un comportement curieux des calculs sur les dates. Par exemple, voici une date S my $dt = DateTime->new( year => 1971, month => 12, day => 31, hour => 23, minute => 59, second => 60, time_zone => 'UTC' ); Si nous exécutons cette S $dt->add( months => 1 ); Alors le résultat sera "1972-02-01 00:00:00", parce que le 31 janvier 1972 n'est pas allé au-delà de 23:59:59, donc 23:59:60 n'existait pas ce jour-là. À cause des secondes intercalaires, nous sommes également obligés de faire la distinction entre les minutes et les secondes pendant les calculs. Si nous partons de la date-heure S my $dt = DateTime->new( year => 1971, month => 12, day => 31, hour => 23, minute => 59, second => 30, time_zone => 'UTC' ); nous obtiendrons des résultats différents selon que nous additionnons 1 minute ou 60 secondes. La raison est que la dernière minute de ce jour, celle qui commence à 23:59:00, contient 61 secondes. Voici les S # 1971-12-31 23:59:30 - date-heure initiale $dt->clone->add( minutes => 1 ); # 1972-01-01 00:00:30 - une minute plus tard $dt->clone->add( seconds => 60 ); # 1972-01-01 00:00:29 - 60 secondes plus tard =head3 Heure locale ou heure UTC et 24 heures ou 1 jour Lorsque vous effectuez un calcul sur dates, vous modifiez la date et l'heure I. C'est généralement la même chose que de modifier la date et l'heure UTC, sauf si le calcul traverse un changement d'heure. La conséquence est qu'un jour peut comporter plus ou moins de 24 heures. En particulier, si vous effectuez une opération du S my $dt = DateTime->new( year => 2004, month => 3, day => 27, hour => 2, time_zone => 'Europe/Paris', ); $dt->add( days => 1 ); alors le résultat est une heure locale I et le module s'interrompt en erreur. Toutefois, cette opération S my $dt = DateTime->new( year => 2004, month => 3, day => 27, hour => 2, time_zone => 'Europe/Paris', ); $dt->add( hours => 24 ); et le résultat est une date avec l'heure locale à S<« 03:00 »>. Une autre façon de se représenter les opérations est que lors d'un calcul sur des dates et des heures, chaque élément, secondes, minutes, jours et mois, est ajouté séparément à la date-heure locale. En d'autres termes, ajouter un jour à "2003-02-22 12:00:00" revient à incrémenter l'élément jour, 22, ce qui donne le jour 23. Ajouter 24 heures, en revanche, revient à ajouter 1440 minutes (24 x 60), et à normaliser le résultat (car il n'y a pas d'heure "12:1440:00", ni "36:00:00"). Si ces explications vous donnent mal au crâne, il existe une échappatoire. Il vous suffit de convertir vos dates en UTC avant les calculs, puis de convertir en sens inverse après les calculs. En agissant ainsi, vous n'avez plus à craindre que le module s'arrête en erreur et vous êtes sûr qu'un jour durera exactement 24 heures. Cela dit, cela ne correspond pas forcément à ce que vous voulez calculer. C'est vous qui voyez. =head3 Résultat des calculs sur dates et heures Étant donné que les calculs sur dates et heures se font séparément pour les différentes unités, le résultat du calcul peut différer légèrement de ce que vous attendez. En interne, un objet durée est constitué de quelques unités, mois, jours, minutes, secondes et nanosecondes. De toutes ces unités, la conversion et la normalisation ne peuvent s'effectuer de manière simple qu'entre les secondes et les nanosecondes. Pour toutes les autres unités, il est impossible de définir un facteur de conversion à cause des secondes intercalaires, des changements d'heure, etc. Voici un exemple, à partir d'une question de Mark Fowler envoyée à la liste datetime (arobase) perl (point) org. Si vous voulez savoir combien de secondes un objet durée représente réellement, vous devez l'additionner à une date pour le savoir, en faisant S my $maintenant = DateTime->now( time_zone => 'UTC' ); my $ensuite = $maintenant->clone->add_duration($duree); my $duree_secondes = $ensuite->subtract_datetime_absolute($maintenant); Cela renvoie un nouvel objet durée qui ne comporte que des secondes et des nanosecondes. Il existe d'autres méthodes de soustraction et de différence dans C pour générer différents types de durées. Ces méthodes sont C, C, C, C, et C. =head2 Surcharge Ce module surcharge explicitement l'addition (+), la soustraction (-), la comparaison de chaîne et la comparaison numérique. Cela signifie que les lignes suivantes font effectivement quelque chose de S my $dt_nouv = $dt + $obj_duree; my $dt_nouv = $dt - $obj_duree; my $obj_duree = $dt - $dt_nouv; foreach my $dt ( sort @dates ) { ... } De plus, le paramètre C est positionné à S<« vrai »>, ce qui fait que les opérateurs dérivés (C<+=>, C<-=>, etc.) fonctionneront correctement eux aussi. Cela dit, n'espérez pas que l'incrément (C<++>) et le décrément (C<-->) donneront un résultat utile. Le module surcharge également la conversion en chaîne pour qu'elle appelle la méthode C. =head2 Spécifications pour strftime La chaîne de format transmise à la méthode C autorise les spécifications S =over 4 =item * %a L'abréviation du jour de la semaine. =item * %A Le nom complet du jour de la semaine. =item * %b L'abréviation du mois. =item * %B Le nom complet du mois. =item * %c Le format date-heure par défaut pour la localisation de l'objet. =item * %C Les deux premiers chiffres de l'année, correspondant plus ou moins au siècle. =item * %d Le jour du mois sous forme numérique (de 01 à 31). =item * %D Équivalent à %m/%d/%y. Peut-être pas la meilleure façon de se faire comprendre en Europe... =item * %e Comme C<%d>, le jour du mois sous forme numérique, mais le zéro de gauche est remplacé par un blanc. =item * %F Équivalent à %Y-%m-%d (le format ISO 8601) =item * %G L'année ISO 8601 sur 4 chiffres. Il s'agit de l'année correspondant à la semaine (cf. C<%V>), pas nécessairement l'année du jour. Le format est le même que pour C<%Y>, mais si l'année de la semaine ISO n'est pas la même que l'année du jour, c'est l'année de la semaine ISO qui est utilisée. =item * %g Comme %G, mais sur deux chiffres, sans indication du siècle (00-99). =item * %h Équivalent à %b. =item * %H L'heure sous la forme d'un nombre décimal, en utilisant une horloge sur 24 heures (donc de 00 à 23). =item * %I L'heure sous forme décimale, en utilisant une horloge sur 12 heures (donc de 01 à 12). =item * %j Le jour de l'année, sous forme décimale (de 001 à 366). =item * %k L'heure sous forme décimale, utilisant une horloge sur S<24 heures ;> le zéro de gauche est remplacé par un espace (de 0 à 23). =item * %l L'heure sous forme décimale, utilisant une horloge sur S<12 heures ;> le zéro de gauche est remplacé par un espace (de 1 à 12). =item * %m Le mois sous forme décimale (de 01 à 12). =item * %M Les minutes, sous forme décimale (de 00 à 59). =item * %n Un caractère de saut de ligne. =item * %N La partie fractionnaire des secondes. Par défaut, 9 chiffres (pour les nanosecondes). %3N millisecondes (3 chiffres) %6N microsecondes (6 chiffres) %9N nanosecondes (9 chiffres) =item * %p La chaîne C ou C correspondant à l'heure donnée, ou leur équivalent local. En particulier, midi donne C et minuit donne C. =item * %P Comme C<%p>, mais en S C ou C ou les chaînes correspondantes en local. =item * %r L'heure dans la notation AM/PM. Avec la localisation POSIX, c'est équivalent à `%I:%M:%S %p'. =item * %R L'heure avec une notation sur 24 heures (%H:%M). Voir C<%T> ci-dessous si vous voulez les secondes. =item * %s Le nombre de secondes depuis la date origine du système. =item * %S Les secondes sous forme numérique (de 00 à 61). =item * %t Un caractère de tabulation. =item * %T L'heure avec une notation sur 24 heures (%H:%M:%S). =item * %u Le jour de la semaine sous la forme d'un numéro de 1 à 7, 1 représentant le lundi. Cf. C<%w>. =item * %U Le numéro de la semaine dans l'année sous forme d'un numéro de 00 à 53. Le premier dimanche de l'année est le premier jour de la semaine 01. Cf. C<%V> et C<%W>. =item * %V Le numéro ISO 8601:1988 de la semaine dans l'année, sous la forme d'un numéro de 01 à 53. La semaine 1 est la première semaine comportant 4 jours au moins dans l'année. Les semaines commencent le lundi. Cf. C<%U> et C<%W>. =item * %w Le jour de la semaine sous la forme d'un numéro de 0 à 6, 0 représentant le dimanche. Cf. C<%u>. =item * %W Le numéro de la semaine dans l'année sous forme d'un numéro de 00 à 53. Le premier lundi de l'année est le premier jour de la semaine 01. =item * %x Le format de date par défaut pour la localisation de l'objet. =item * %X Le format d'heure par défaut pour la localisation de l'objet. =item * %y L'année sur deux chiffres, sans indication du siècle (de 00 à 99). =item * %Y L'année sur 4 chiffres. =item * %z Le fuseau horaire exprimé par le décalage vis-à-vis du fuseau UTC. Indispensable pour obtenir des dates conformes à la RFC-822 (avec le format C<%a, %d %b %Y %H:%M:%S %z>). =item * %Z Le nom ou l'abréviation du fuseau horaire. =item * %% Un caractère C<%>. =item * %{méthode} Vous pouvez spécifier n'importe quel nom de méthode avec le format C<%{méthode}>, dans lequel C est un nom de méthode d'instance valide pour C. =back =head1 DateTime.pm et Storable Depuis la version 0.13, DateTime prévoir des points d'entrée (I) pour le module Storable, ce qui permet de réduire la taille d'un objet DateTime après sérialisation. =head1 SUPPORT Le support de ce module est assuré par la liste de diffusion C. Cf. http://lists.perl.org/ pour les détails. Merci de communiquer vos rapports de bugs au système RT de CPAN à l'adresse http://rt.cpan.org/NoAuth/ReportBug.html?Queue=datetime ou par messagerie électronique à l'adresse C sur le serveur C. Si vous ne pensez pas maîtriser suffisamment la langue anglaise, faites-vous aider par l'un de vos proches ou éventuellement par le traducteur. =head1 AUTEUR Dave Rolsky . Toutefois, veuillez consulter le fichier CREDITS pour savoir plus précisément à qui j'ai volé tout le code. =head1 TRADUCTION Cette traduction concerne la version 0.21 de C. La traduction a été réalisée par Jean Forget () le 2004-06-16. =head1 COPYRIGHT Copyright (c) 2003 David Rolsky pour la version originale. Tous droits réservés. Ce logiciel est un logiciel S vous pouvez le redistribuer et le modifier aux mêmes conditions que Perl lui-même. Certaines portions du code de la distribution sont dérivées de travaux antérieurs. Voir le fichier CREDITS pour plus de détails. Vous pouvez trouver le texte complet de la licence (en anglais) dans le fichier LICENSE inclus avec le module. Copyright (c) 2004 Jean Forget et les Mongueurs de Perl pour la traduction française. Tous droits réservés. =head1 VOIR ÉGALEMENT La liste de distribution C http://datetime.perl.org/ http://datetime.mongueurs.net/ =cut