=head1 NOM

DateTime::Duration - objets durées pour les calculs de date et d'heure

=head1 RÉSUMÉ

  use DateTime::Duration;

  $d = DateTime::Duration->new( years   => 3,
                                months  => 5,
                                weeks   => 1,
                                days    => 1,
                                hours   => 6,
                                minutes => 15,
                                seconds => 45, 
                                nanoseconds => 12000 );

  # Conversion vers des unités différentes
  $d->in_units('days', 'hours', 'seconds');

  # Accesseurs lisibles par un être humain, toujours positifs
  $d->years;
  $d->months;
  $d->weeks;
  $d->days;
  $d->hours;
  $d->minutes;
  $d->seconds;
  $d->nanoseconds;

  if ( $d->is_positive ) { ... }
  if ( $d->is_zero )     { ... }
  if ( $d->is_negative ) { ... }

  # La partie importante pour les calculs
  $d->delta_months
  $d->delta_days
  $d->delta_minutes
  $d->delta_seconds
  $d->delta_nanoseconds

  my %deltas = $d->deltas

  $d->is_wrap_mode
  $d->is_limit_mode
  $d->is_preserve_mode

  # Multiplie tous les deltas par -1
  my $opposite = $d->inverse;

  my $bigger  = $dur1 + $dur2;
  my $smaller = $dur1 - $dur2; # the result could be negative
  my $bigger  = $dur1 * 3;

  my $base_dt = DateTime->new( year => 2000 );
  my @sorted =
      sort { DateTime::Duration->compare( $a, $b, $base_dt ) } @durations;

=head1 DESCRIPTION

Ce module est une classe simple pour représenter des objets durées.
Chaque fois que vous faites de l'arithmétique sur des dates-heures
C<DateTime>, vous utilisez également des objets C<DateTime::Duration>.

Cf. la section L<Mécanismes de calcul|DateTime/"Mécanismes de calcul">
dans la documentation de C<DateTime.pm> pour des explications
détaillées. En bref, il est impossible de convertir des durées
entre les unités telles que secondes, minutes, jours et mois,
donc cette classe ne tente jamais de telles conversions.
À la place, la durée est créée avec les différentes unuités, par exemple
en appelant la méthode de soustraction de C<DateTime.pm>.

=head1 MÉTHODES

Tout comme  C<DateTime>, les méthodes de mise à jour de C<DateTime::Duration> 
renvoient l'objet, ce qui permet d'enchaîner les appeles de méthode.

C<DateTime::Duration> fournit les méthodes S<suivantes :>

=over 4

=item * new( ... )

Cette méthode crée une durée à partir des paramètres C<years>
(années), C<months> (mois), C<weeks> (semaines), C<days> (jours),
C<hours> (heures), C<minutes> (devinez), C<seconds> (...),
C<nanoseconds> (...) et C<end_of_month> (fin de mois).
Tous les paramètres sauf C<end_of_month> requièrent une valeur
numérique. Si l'une de ces valeurs est négative, l'objet créé
sera une durée négative.

En interne, les années font 12 mois. De même, les semaines font 7 jours
et les heures sont converties en minutes. Les secondes et les nanosecondes
sont néanmoins traitées séparément.

Le paramètre C<end_of_month> est C<wrap> (report), C<limit>
(troncature) ou C<preserve> (conserver). Il permet de spécifier
comment un changement de mois se produit par rapport à la fin du mois.

En mode S<« report »> (C<wrap>), si l'ajout de mois ou d'années provoque un
débordement, les jours excédentaires sont reportés dans le mois suivant.
Par exemple, additionner une année à un 29 février donne le 1er mars de
l'année suivante.

Si vous spécifiez S<« troncature »> (C<limit>), la fin du mois n'est
jamais franchie par l'addition de mois ou d'années. Par exemple, 
additionner une année à un 29 février donnera le 28 février suivant.
Ajouter de nouveau trois années donnera le 28 février de l'année bissextile
suivante, pas le 29.

Si vous spécifiez S<« conserver »> (C<preserve>), les calculs se produisent
comme avec S<« troncature »>, mis à part que si la date initiale
se trouve à la fin du mois, alors la nouvelle date le sera aussi.
Par exemple, additionner un mois au 29 février 2000 donnera le
31 mars 2000.

Pour les durées positives, le paramètres C<end_of_month> vaut
C<wrap> par défaut. Pour les durées négatives, la valeur par
défaut est C<limit>. Cela devrait correspondre à ce que la plupart
des gens attendent intuitivement de calculs sur dates.

=item * clone

Renvoie un nouvel objet avec les mêmes propriétés que l'objet sur
lequel cette méthode a été invoquée.

=item * in_units( ... )

Renvoie la longueur de la durée dans l'unité ou les unités demandées
(vous pouvez choisir toute unité autorisée pour C<new()>).
Les valeurs obtenues sont entières, éventuellement négatives.
Les valeurs pour les petites unités sont calculées après le calcul
des unités plus grandes. S<Exemple :>

  my $dur = DateTime::Duration->new( years => 1, months => 15 );

  $dur->in_units( 'years' );            # 2
  $dur->in_units( 'months' );           # 27
  $dur->in_units( 'years', 'months' );  # (2, 3)

Notez bien que les nombres renvoyés ne correspondent pas nécessairement
aux valeurs soumises au constructeur.

En contexte de liste, C<in_units> renvoie les longueurs dans l'ordre
des unités données. En contexte scalaire, la méthode renvoie la valeur
de la première unité (mais effectue quand même le calcul avec toutes les
unités transmises).

Si vous voulez plus de souplesse pour présenter l'information sur une
durée, jetez un coup d'oeil au module C<DateTime::Format::Duration>.

=item * years, months, weeks, days, hours, minutes, seconds, nanoseconds

Ces méthodes renvoient des nombres indiquant combien d'unités de ce type
la durée comporte, après avoir retranché les unités supérieures.
Ces nombres sont toujours positifs. Demander les jours (C<days>)
équivaut à demander C<abs( in_units( 'days', 'weeks' ) )>.

=item * delta_months, delta_days, delta_minutes, delta_seconds, delta_nanoseconds

Ces méthodes renvoient les mêmes informations que ci-dessus, mais
sous une forme adéquate pour les calculs sur dates. Les nombres renvoyés
peuvent être positifs ou négatifs. L'appel de C<delta_days> équivaut à 
C<in_units('days')>.

=item * deltas

Renvoie un hachage avec les clés C<months>, C<days>, C<minutes>,
C<seconds> et C<nanoseconds>, contenant toute les informations 
disponibles par l'intermédiaire des méthodes C<delta_xxx>.

=item * is_positive, is_zero, is_negative

Indique si la durée est positive, négative ou nulle.

Si la durée comporte à la fois des unités positives et des unités
négatives, B<les trois> méthodes renvoient S<« faux »>.

=item * is_wrap_mode, is_limit_mode, is_preserve_mode

Permet de savoir comment la durée se comporte à la fin d'un mois.

=item * inverse

Renvoie un nouvel objet durée avec les mêmes deltas que l'objet
origine, multipliés par -1. Le comportement de fin de mois sera
le comportement par défaut, dépendant du signe de la durée.

=item * add_duration( $duration_object ), subtract_duration( $duration_object )

Additionne ou soustrait deux durées.

=item * add( ... ), subtract( ... )

Sucre syntaxique pour l'addition et la soustraction. Les paramètres
transmis à ces deux méthodes sont utilisés pour créer une nouvelle
durée, laquelle est additionnée à l'ancienne durée ou soustraite, par
C<add_duration()> ou C<subtract_duration()>, selon le cas.

=item * multiply( $number )

Multiplie chaque élément de la durée par le nombre spécifié.

=item * DateTime::Duration->compare( $duration1, $duration2, $base_datetime )

Cette méthode de classe permet de comparer deux durées ou de trier
une liste de durées. La comparaison s'effectue en additionnant
chaque durée à la date-heure de base, puis en comparant les dates-heures
résultantes. Il est indispensable de procéder de la sorte, car
de nombreuses durées ne peuvent pas être comparées directement.
Par exemple, une durée d'un mois peut être plus longue ou plus courte
qu'une durée de 29 jours, tout dépend de la date-heure à laquelle 
les durées sont additionnées.

Si la méthode est appelée sans date-heure de base, elle utilisera
par défaut le résultat de C<< DateTime->now >>. L'utilisation de
cette valeur par défaut conduit à des résultats qui ne seront
pas toujours reproductibles d'une exécution à l'autre, si les durées 
ont des unités différentes et incompatibles. Les résultats ne seront pas non plus
reproductibles si certaines durées comportent plusieurs unités,
comme un mélange de mois et d'années.

Toutefois, si vous savez que les deux objets contiennent une seule
unité et que c'est la même (ou bien s'ils contiennent plusieurs unités
mais que celles-ci sont compatibles, comme des heures et des minutes),
alors les résultats seront reproductibles.

=back

=head2 Surcharge

Cette classe surcharge l'addition, la soustraction et la multiplication.

Il n'y a B<pas> de surcharge de la comparaison. Si vous essayez
de comparer des durées avec
C<< <=> >> ou C<cmp>, le programme s'arrêtera en S<erreur !>
Utilisez plutôt la méthode de classe
C<compare()>.

=head1 SUPPORT

Le support de ce module est assuré par la liste de diffusion
C<datetime@perl.org>. Cf. http://lists.perl.org/ pour les détails.
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 (C<autarch> chez C<urth> point C<org>).

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 de C<DateTime::Duration> fournie
avec la version 0.21 de C<DateTime>.

Traduit le 2004-06-14 par Jean Forget.

=head1 COPYRIGHT

Copyright (c) 2003 David Rolsky pour la version originale.  Tous 
droits réservés. Ce logiciel est un logiciel S<libre ;>
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 F<CREDITS> pour plus de détails.

Vous pouvez trouver le texte complet de la licence (en anglais)
dans le fichier F<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<datetime arobase perl point org>

http://datetime.perl.org/

http://datetime.mongueurs.net/

=cut