=head1 NOM

DateTime::Set - Ensembles d'objets DateTime et opérations ensemblistes

=head1 RÉSUMÉ

    use DateTime;
    use DateTime::Set;

    $date1 = DateTime->new( year => 2002, month => 3, day => 11 );
    $ens1 = DateTime::Set->from_datetimes( dates => [ $date1 ] );
    #  ens1 = 2002-03-11

    $date2 = DateTime->new( year => 2003, month => 4, day => 12 );
    $ens2 = DateTime::Set->from_datetimes( dates => [ $date1, $date2 ] );
    #  ens2 = 2002-03-11, et 2003-04-12

    $date3 = DateTime->new( year => 2003, month => 4, day => 1 );
    print $ens2->next( $date3 )->ymd;      # 2003-04-12
    print $ens2->previous( $date3 )->ymd;  # 2002-03-11
    print $ens2->current( $date3 )->ymd;   # 2002-03-11
    print $ens2->closest( $date3 )->ymd;   # 2003-04-12

    # une récurrence mensuelle :
    $ens = DateTime::Set->from_recurrence( 
        recurrence => sub {
            return $_[0] if $_[0]->is_infinite;
            return $_[0]->truncate( to => 'month' )->add( months => 1 )
        },
        span => $date_span1,    # plage de temps facultative
    );

    $ens = $ens1->union( $ens2 );         # like "OR", "insert", "both"
    $ens = $ens1->complement( $ens2 );    # like "delete", "remove"
    $ens = $ens1->intersection( $ens2 );  # like "AND", "while"
    $ens = $ens1->complement;             # like "NOT", "negate", "invert"

    if ( $ens1->intersects( $ens2 ) ) { ...  # like "touches", "interferes"
    if ( $ens1->contains( $ens2 ) ) { ...    # like "is-fully-inside"

    # extraction de données 
    $date = $ens1->min;           # première date-heure de l'ensemble
    $date = $ens1->max;           # dernière date-heure de l'ensemble

    $iter = $ens1->iterator;
    while ( $dt = $iter->next ) {
        print $dt->ymd;
    };

=head1 DESCRIPTION

DateTime::Set est un module pour des ensembles de dates-heures. Il peut
être utilisé pour manipuler deux types d'ensembles.

Le premier type est un ensemble fixé d'objets DateTime prédéfinis. Par
exemple, nous pouvons créer l'ensemble des anniversaires des personnes
de notre famille.

Le second type d'ensemble est basé sur l'idée de récurrence, comme 
S<« tous> les S<mercredis »>, ou bien S<« à> midi, le 15 de chaque
S<mois »>. Les ensembles de ce type peuvent avoir une date de début et
une date de fin, mais ce n'est pas indispensable. Notre ensemble 
S<« tous> les S<mercredis »> peut très bien représenter S<« tous> les
mercredis, de l'origine des temps à la fin des S<temps »>, ou bien 
S<« tous> les mercredis, après le 5 mars 2003 jusqu'à la fin des
S<temps »>, ou encore S<« tous> les mercredis, entre le 5 mars 2003 et
le 7 janvier S<2004 »>.

=head1 MÉTHODES

=over 4

=item * from_datetimes

Crée un ensemble à partir d'une liste de dates-heures.

   $dates = DateTime::Set->from_datetimes( dates => [ $dt1, $dt2, $dt3 ] );

Les dates-heure peuvent être des objets de la classe C<DateTime> ou d'une classe
C<DateTime::Calendar::*>.

Les objets C<DateTime::Infinite::*> ne sont pas valides en tant qu'éléments
d'un ensemble. Ils peuvent toutefois servir comme borne supérieure ou
inférieure d'un ensemble.

=item * from_recurrence

Crée un nouvel ensemble en le spécifiant par une fonction de rappel
S<« récurrence »>.

    $months = DateTime::Set->from_recurrence( 
        span => $dt_span_this_year,    # plage de temps facultative
        recurrence => sub { 
            return $_[0]->truncate( to => 'month' )->add( months => 1 ) 
        }, 
    );

Le paramètre C<span> est facultatif. Ce doit être un objet C<DateTime::Span>.

La plage de dates peut également être spécifiée par un paramètre
C<begin> / C<after> et un paramètre C<before> / C<end> comme dans le
constructeur de C<DateTime::Span>. Dans ce cas, s'il y a un paramètre
C<span>, il sera ignoré.

    $months = DateTime::Set->from_recurrence(
        after => $dt_now,
        recurrence => sub {
            return $_[0]->truncate( to => 'month' )->add( months => 1 );
        },
    );

La fonction de rappel de récurrence reçoit un paramètre et
un seul, un objet C<DateTime.pm> ou un objet d'une classe
C<DateTime::Calendar::*>. Cela peut être également un objet
C<DateTime::Infinite::Future> ou C<DateTime::Infinite::Past>. 

La récurrence doit renvoyer l'événement I<suivant> postérieur à cet
objet. Il n'y a aucune garantie sur la valeur de cet objet, mis à
part que la date-heure renvoyée doit être postérieure à celle reçue
par la fonction. S'il ne reste plus de dates-heures après le paramètre
fourni, la fonction de récurrence doit renvoyer
C<DateTime::Infinite::Future>.

Vous pouvez modifier C<$_[0]> dans la fonction de récurrence, il n'y a
pas d'effet de bord.

Par exemple, si vous voulez une récurrence qui génère des dates-heures
par intervalle de 30 secondes, utilisez une routine dans ce S<genre :>

  sub toutes_les_30_secondes {
      my $dt = shift;
      if ( $dt->second < 30 ) {
          return $dt->truncate( to => 'minute' )->add( seconds => 30 );
      } else {
          return $dt->truncate( to => 'minute' )->add( minutes => 1 );
      }
  }

Notez bien que cette récurrence tient compte des secondes intercalaires.
Vous avez intérêt à utiliser autant que possible les méthodes des
modules C<DateTime> pour éviter les problèmes compliqués S<d'arithmétique !>

Il est possible également de créer une récurrence en spécifiant une fonction
de rappel C<next> (suivant), une fonction de rappel C<previous> (précédent)
ou les deux à la fois.

Les fonctions de rappel peuvent renvoyer des dates infinies 
C<DateTime::Infinite::Future> ou
C<DateTime::Infinite::Past> pour définir une I<récurrence bornée>.
Dans ce cas, il faut définir les deux fonctions de rappel
C<next> et C<previous>.

    # tous les mois en commençant à $dt et jusqu'à la fin des temps

    my $months = DateTime::Set->from_recurrence(
        next => sub {
            return $dt if $_[0] < $dt;
            $_[0]->truncate( to => 'month' );
            $_[0]->add( months => 1 );
            return $_[0];
        },
        previous => sub {
            my $param = $_[0]->clone;
            $_[0]->truncate( to => 'month' );
            $_[0]->subtract( months => 1 ) if $_[0] == $param;
            return $_[0] if $_[0] >= $dt;
            return DateTime::Infinite::Past->new;
        },
    );

Les récurrences bornées sont plus faciles à créer avec
les paramètres pour les plages de dates. Cf. ci-dessus.

Cf. C<DateTime::Event::Recurrence> et les autres modules C<DateTime::Event::*>
pour générer des récurrences spécifiques, comme le lever et le coucher
du soleil, ou bien les fêtes et jours fériés.

=item * empty_set

Crée un ensemble vide.

    $ens = DateTime::Set->empty_set;
    print "ensemble vide" unless defined $ens->max;

=item * clone

Cette méthode d'objet renvoie un nouvel objet, réplique de l'objet de départ.

C<clone> est utile si vous voulez appliquer une transformation à un 
ensemble, tout en conservant l'ancienne valeur de cet S<ensemble :>

    $ens2 = $ens1->clone;
    $ens2->add_duration( year => 1 );  # $ens1 reste intouché

=item * add_duration( $duree )

Cette méthode ajoute la durée spécifiée à chaque élément de l'ensemble.

    $dt_dur = new DateTime::Duration( year => 1 );
    $ens->add_duration( $dt_dur );

L'ensemble original est modifié. Si vous voulez conserver les anciennes
valeurs, S<codez :>

    $nouv_ens = $ens->clone->add_duration( $dt_dur );

=item * add

Cette méthode est du sucre syntaxique pour la méthode C<add_duration()>.

    $meetings_2004 = $meetings_2003->clone->add( years => 1 );

=item * subtract_duration( $objet_duree )

Cette méthode reçoit un objet C<DateTime::Duration>, lui applique
C<invert()> et passe la durée résultante à la méthode
C<add_duration>.

=item * subtract( paramètres pour DateTime::Duration->new )

Comme C<add()>, c'est du sucre syntaxique pour la méthode C<subtract_duration()>.

=item * set_time_zone( $tz )

Cette méthode essaie d'appliquer la méthode C<set_time_zone> à chaque
date-heure de l'ensemble.

=item * set( locale => .. )

Cette méthode permet de changer les informations de localisation d'un
ensemble de dates-heures.

=item * min

=item * max

La première et la dernière dates-heures de l'ensemble. Ces méthodes
peuvent renvoyer C<undef> dans le cas d'un ensemble vide. Il se peut
également que ces méthodes renvoient un objet
C<DateTime::Infinite::Past> ou C<DateTime::Infinite::Future>.

=item * span

Renvoie un objet C<DateTime::Span> correspondant à la plage de dates-heures
qui couvre la totalité de l'ensemble.

=item * iterator / next / previous

Ces méthodes peuvent servir à parcourir itérativement les dates-heures
d'un ensemble.

    $iter = $ens1->iterator;
    while ( $dt = $iter->next ) {
        print $dt->ymd;
    }

    # parcours à reculons
    $iter = $ens1->iterator;
    while ( $dt = $iter->previous ) {
        print $dt->ymd;
    }

Les bornes de l'itérateur peuvent être spécifiées grâce à un
paramètre C<span>. Ce paramètre doit être un objet C<DateTime::Span> 
pour délimiter les bornes de l'itérateur. Une autre façon de
procéder consiste à transmettre des paramètres admissibles pour
le constructeur de la classe
C<DateTime::Span> et cela créera un objet pour votre bénéfice.

De toute évidence, si la plage que vous spécifiez s'étend à l'infini
dans une direction ou dans l'autre, votre itérateur peut conduire
à une boucle sans fin, selon la nature de votre ensemble.
S<Méfiance !>

Les méthodes C<next()> et C<previous()> renvoient C<undef> s'il
ne reste plus de date-heure dans l'itérateur.

=item * as_list

Renvoie les éléments de l'ensemble sous la forme d'une liste d'objets
C<DateTime>.

  my @dt = $ens->as_list( span => $plage_facultative );

Tout comme pour la méthode C<iterator()>, la méthode C<as_list()> 
peut être bornée par une plage de dates C<DateTime::Span>.

Si un ensemble est spécifié avec une récurrence mais sans date-heure
de début ou sans date-heure de fin, alors C<as_list> renverra C<undef>
si vous ne spécifiez pas de plage de dates. Notez bien que c'est
différent d'une liste vide, étant donné qu'une liste vide est
la valeur, parfaitement valide, renvoyée pour l'ensemble S<vide !>

=item * count

Renvoie le nombre d'objets C<DateTime> dans l'ensemble.

  my $n = $ens->count( span => $plage_facultative );

Tout comme pour la méthode C<iterator()>, la méthode C<count()> 
peut être bornée par une plage de dates C<DateTime::Span>.

Si un ensemble est spécifié avec une récurrence mais sans date-heure
de début ou sans date-heure de fin, alors C<count> renverra C<undef>
si vous ne spécifiez pas de plage de dates. Notez bien que c'est
différent d'un compte à zéro, étant donné que zéro est
la valeur, parfaitement valide, renvoyée pour l'ensemble S<vide !>

=item * union

=item * intersection 

=item * complement

Ces opérations ensemblistes peuvent recevoir une liste d'objets  C<DateTime>, 
un objet C<DateTime::Set>, C<DateTime::Span>, ou C<DateTime::SpanSet> 
comme argument.

    $ens = $ens1->union( $ens2 );         # like "OR", "insert", "both"
    $ens = $ens1->complement( $ens2 );    # like "delete", "remove"
    $ens = $ens1->intersection( $ens2 );  # like "AND", "while"
    $ens = $ens1->complement;             # like "NOT", "negate", "invert"

L'C<union> d'un C<DateTime::Set> avec un C<DateTime::Span> ou un
C<DateTime::SpanSet> renvoie un objet C<DateTime::SpanSet>.

Si C<complement> est appelé sans aucun argument, le résultat est un objet
C<DateTime::SpanSet> représentant les plages entre deux éléments
de l'ensemble de départ. Si C<complement> est appelé avec un argument,
la valeur retournée est un objet
C<DateTime::Set> représentant la I<différence ensembliste> des ensembles
de départ.

Toutes les autres opérations renvoient un C<DateTime::Set>.

=item * intersects

=item * contains

Ces opérations ensemblistes renvoient une valeur booléenne.

    if ( $ens1->intersects( $ens2 ) ) { ...  # like "touches", "interferes"
    if ( $ens1->contains( $dt ) ) { ...    # like "is-fully-inside"

Ces méthodes peuvent recevoir en argument une liste d'objets  C<DateTime>, 
un objet C<DateTime::Set>, C<DateTime::Span> ou C<DateTime::SpanSet>.

=item * previous

=item * next

=item * current

=item * closest

  my $dt = $ens->next( $dt );
  my $dt = $ens->previous( $dt );
  my $dt = $ens->current( $dt );
  my $dt = $ens->closest( $dt );

Ces méthodes permettent de trouver un élément de l'ensemble relativement
à une date-heure.

La méthode C<current()> renvoie C<$dt> si cette date-heure appartient à l'ensemble, ou
la précédente valeur sinon.

La méthode C<closest()> renvoie C<$dt> si cette date-heure appartient à l'ensemble, sinon
elle renvoie l'élément chronologiquement le plus proche (antérieur ou postérieur).

Toutes ces méthodes sont susceptibles de renvoyer C<undef> s'il n'existe
pas d'élément convenable dans l'ensemble.

Ces méthodes essaient d'affecter à la valeur renvoyée le même fuseau horaire
que celui de l'argument, sauf si le fuseau horaire de l'argument est
le fuseau horaire flottant.

=item * map ( sub { ... } )

    # exemple : supprime les informations hh:mm:ss
    $ens = $ens2->map( 
        sub {
            return $_->truncate( to => day );
        }
    );

    # exemple : diffère ou avance les dates-heures qui figurent dans un autre ensemble
    $ens = $ens2->map(
        sub {
            return $_->add( days => 1 ) while $vacances->contains( $_ );
        }
    );

Cette méthode est l'équivalent ensembliste de la fonction C<map> des listes Perl.

La méthode évalue la routine pour chaque élément de l'ensemble (en affectant
localement la date-heure à C<$_>) et renvoie l'ensemble composé des
résultats de chaque évaluation.

Comme avec le C<map> du standard Perl, chaque élément de l'ensemble peut
produire zéro, un ou plusieurs éléments dans la valeur renvoyée.

À l'inverse du C<map> standard, la modification de C<$_> n'entraîne
pas de modification de l'ensemble d'origine. Cela signifie que l'utilisation
de la méthode C<map> en contexte vide n'a pas d'effet.

La fonction de rappel peut ne pas être appelée immédiatement à cause de 
l'S<« évaluation> S<paresseuse »> (I<lazy evaluation>). Inutile donc
de s'appuyer sur les effets de bord de la routine. Par exemple, un C<print>
à l'intérieur de cette routine peut se déclencher beaucoup plus tard que
ce que vous avez prévu.

Il est indispensable que la valeur modifiée et renvoyée par la routine 
appartienne à l'intervalle des dates-heures obtenues par
C<previous> et C<next> sur l'ensemble d'origine. Cette contrainte
est imposée par l'algorithme de retour arrière (I<backtracking>) utilisé
dans le module C<Set::Infinite>.

Par exemple, si l'ensemble de départ est C<[ 2001, 2010, 2015 ]>,
l'appel de la routine pour la valeur C<2010> doit renvoyer une
valeur comprise dans l'intervalle C<[ 2001 .. 2015 ]>.

=item * grep ( sub { ... } )

    # exemple : enlever les dimanches
    $ens = $ens2->grep( 
        sub {
            return ( $_->day_of_week != 7 );
        }
    );

Cette méthode est l'équivalent ensembliste du C<grep> pour les listes Perl.

Elle évalue une routine pour chaque élément de l'ensemble (en affectant
localement chaque date-heure à C<$_>) et renvoie un ensemble contenant
tous les éléments pour lesquels l'évaluation a donné un résultat vrai.

À l'inverse du C<grep> de Perl, la modification de C<$_> n'entraîne pas
de modification de l'ensemble de départ. Cela veut dire que l'appel
de la méthode C<grep> en contexte vide n'a aucun effet.

En revanche, les modifications de C<$_> se retrouvent dans 
l'ensemble résultat.

La fonction de rappel peut ne pas être appelée immédiatement à cause de
l'S<« évaluation> S<paresseuse »> (I<lazy evaluation>). Inutile donc
de s'appuyer sur les effets de bord de la routine. Par exemple, un C<print>
à l'intérieur de cette routine peut se déclencher beaucoup plus tard que
ce que vous avez prévu.

=item * iterate ( sub { ... } )

I<Cette méthode est maintenue uniquement pour la compatibilité ascendante
et elle disparaîtra dans une prochaine version
-- utilisez C<map> ou C<grep> à la place.>

=back

=head1 SUPPORT

Le support de ce module est assuré par la liste de diffusion
C<datetime@perl.org>.

Merci de signaler les bugs en utilisant rt.cpan.org

Si vous ne pensez pas maîtriser la langue anglaise suffisamment,
faites-vous aider par l'un de vos proches ou éventuellement
par le traducteur.

=head1 AUTEUR

Flavio Soibelmann Glock <fglock arobase pucrs point br>

L'API a été développée en collaboration avec Dave Rolsky et
la communaute DateTime.

=head1 TRADUCTION

La traduction concerne la version 0.17 de C<DateTime::Set>

Traduit le 2004-08-26 par Jean Forget <JFORGET arobase cpan point org>.

=head1 COPYRIGHT

Copyright (c) 2003, 2004 Flavio Soibelmann Glock. 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.

Copyright (c) 2004 Jean Forget et les Mongueurs de Perl pour la
traduction française. Tous droits réservés.

Vous pouvez trouver le texte intégral de la licence en anglais
dans le fichier F<LICENSE> inclus dans la distribution de ce module.

=head1 VOIR ÉGALEMENT

Set::Infinite

Pour plus de détail sur le projet Perl DateTime, cf. 
L<http://datetime.perl.org>.

Une version partiellement traduite en français est disponible à l'adresse 
L<http://datetime.mongueurs.net/>.

=cut