=head1 NOM

DateTime::SpanSet - Ensembles d'intervalles de temps C<DateTime::Span>

=head1 RÉSUMÉ

    $spanset = DateTime::SpanSet->from_spans( spans => [ $dt_span, $dt_span ] );

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

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

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

    $iter = $spanset->iterator;
    while ( $dt = $iter->next ) {
        # $dt is a DateTime::Span
        print $dt->start->ymd;   # début de l'intervalle
        print $dt->end->ymd;     # fin de l'intervalle
    };

=head1 DESCRIPTION

C<DateTime::SpanSet> est une classe représentant des intervalles de dates-heures.
Un exemple serait une réunion hebdomadaire planifiée tous les
vendredis de 13:00 à 15:00.

=head1 MÉTHODES

=over 4

=item * from_spans

Crée un nouvel ensemble d'intervalles à partir d'un ou de plusieurs
objets C<DateTime::Span>.

   $spanset = DateTime::SpanSet->from_spans( spans => [ $dt_span ] );

=item * from_set_and_duration

Crée un nouvel ensemble d'intervalles à partir d'un ou de plusieurs
objets C<DateTime::Set> et d'une durée.

La durée peut être un objet C<DateTime::Duration>, ou les paramètres
permettant de créer un nouvel objet C<DateTime::Duration>, tels
que C<days> pour les jours, C<months> pour les mois, etc.

   $spanset =
       DateTime::SpanSet->from_set_and_duration
           ( set => $dt_set, days => 1 );

=item * from_sets

Crée un nouvel ensemble d'intervalles à partir de deux objets C<DateTime::Set>.

Le premier ensemble énumère les I<dates de début> et l'autre
énumère les I<dates de fin>.

   $spanset =
       DateTime::SpanSet->from_sets
           ( start_set => $dt_set1, end_set => $dt_set2 );

Les intervalles sont I<fermés> au début et I<ouverts> à la fin,
ce qui donne un intervalle [C<$dt1>, C<$dt2>[ (en notation française)
ou [C<$dt1>, C<$dt2>) (en notation américaine).

If an end date comes without a starting date before it, then it
defines a span like C<(-inf, $dt)>.

If a starting date comes without an end date after it, then it defines
a span like C<[$dt, inf)>.

=item * empty_set

Crée un ensemble vide.

=item * clone

Cette méthode d'objet renvoie un nouvel objet, semblable en tous points
à l'objet d'origine.

=item * set_time_zone( $tz )

Cette méthode accepte un objet fuseau horaire ou une chaîne admissible
pour le paramètre C<name> du contructeur C<< DateTime::TimeZone->new() >>.
Si le décalage horaire du nouveau fuseau horaire diffère de l'ancien,
l'heure I<locale> est ajustée.

Si l'ancien fuseau horaire est le fuseau flottant, aucun ajustement de 
l'heure locale n'a lieu, sauf dans le cas des secondes intercalaires.
Si le nouveau fuseau horaire est le fuseau flottant, alors le temps
I<UTC> est ajusté de manière que l'heure locale ne soit pas modifiée.

=item * min

=item * max

La première et la dernière date 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 scalaire représentant l'infini positif ou l'infini
négatif.

=item * duration

La durée totale de l'ensemble, sous la forme d'un objet C<DateTime::Duration>.

La durée peut être infinie.

Disponible également en tant que C<size()>.

=item * span

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

=item * next 

  my $span = $set->next( $dt );

Cette méthode permet de chercher dans l'ensemble le premier intervalle
qui suit la date ou l'intervalle donné en paramètre.

La valeur retournée est un objet C<DateTime::Span>, ou bien C<undef> 
s'il n'existe aucun intervalle correspondant dans l'ensemble.

=item * previous 

  my $span = $set->previous( $dt );

Cette méthode permet de chercher dans l'ensemble l'intervalle le plus
récent qui précède la date ou l'intervalle donné en paramètre.

La valeur retournée est un objet C<DateTime::Span>, ou bien C<undef> 
s'il n'existe aucun intervalle correspondant dans l'ensemble.

=item * current 

  my $span = $set->current( $dt );

Cette méthode permet de chercher dans l'ensemble l'intervalle S<« courant »>,
qui chevauche la date ou l'intervalle donné en paramètre. S'il n'existe
pas d'intervalle contenant la date ou chevauchant l'intervalle,
la méthode renvoie l'intervalle précédent (méthode C<previous>).

La valeur retournée est un objet C<DateTime::SpanSet>, ou bien C<undef> 
s'il n'existe aucun intervalle correspondant dans l'ensemble.

Si le paramètre transmis est un intervalle, il se peut que la méthode
C<current> renvoie plusieurs intervalles.

Cf. la méthode C<intersected_spans()>.

=item * closest 

  my $span = $set->closest( $dt );

Cette méthode permet de trouver l'intervalle le plus proche
de la date ou de l'intervalle envoyé en paramètre.

La valeur retournée est un objet C<DateTime::SpanSet>, ou bien C<undef> 
s'il n'existe aucun intervalle correspondant dans l'ensemble.

Si le paramètre transmis est un intervalle, il se peut que la méthode
C<closest> renvoie plusieurs intervalles.

=item * as_list

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

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

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 * union

=item * intersection

=item * complement

Opérations ensemblistes qui peuvent traiter non seulement des objets
C<DateTime::SpanSet>, mais aussi des objets C<DateTime>,
C<DateTime::Set> et C<DateTime::Span> objects.  Ces opérations
renvoient toujours un objet C<DateTime::SpanSet>.

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

=item * intersected_spans

Cette méthode admet comme argument une liste de C<DateTime>,
un C<DateTime::Set>, un C<DateTime::Span> ou un C<DateTime::SpanSet>.

    $set = $set1->intersected_spans( $set2 );

La méthode renvoie toujours un objet C<DateTime::SpanSet>, contenant 
tous les intervalles ayant une intersection avec l'ensemble
donné en paramètre.

À l'inverse de la méthode C<intersection>, les intervalles ne
sont pas modifiés. Le diagramme ci-dessous montre la S<différence :>

               set1   [....]   [....]   [....]   [....]
               set2      [................]

       intersection      [.]   [....]   [.]

  intersected_spans   [....]   [....]   [....]

=item * intersects

=item * contains

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

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

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

=item * iterator / next / previous

Cette méthode permet d'effectuer un traitement itératif sur les
intervalles d'un ensemble.

    $iter = $spanset->iterator;
    while ( $dt = $iter->next ) {
        # $dt is a DateTime::Span
        print $dt->min->ymd;   # début de l'intervalle
        print $dt->max->ymd;     # fin de l'intervalle
    }

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
l'un des constructeurs 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 d'intervalle dans l'itérateur.

=item * start_set

=item * end_set

Ces méthodes font l'inverse de la méthode C<from_sets>.

C<start_set> renvoie un C<DateTime::Set> avec la date de début de chaque intervalle.

C<end_set> renvoie un C<DateTime::Set> avec la date de fin de chaque intervalle.

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

    # example: enlarge the spans
    $set = $set2->map( 
        sub {
            my $start = $_->start;
            my $end = $_->end;
            return DateTime::Span->from_datetimes(
                start => $start,
                before => $end,
            );
        }
    );

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 le C<DateTime::Span> à 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. 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.

The callback return value is expected to be within the span of the
C<previous> and the C<next> element in the original set.

For example: given the set C<[ 2001, 2010, 2015 ]>,
the callback result for the value C<2010> is expected to be
within the span C<[ 2001 .. 2015 ]>.

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

    # example: filter out all spans happening today
    my $today = DateTime->today;
    $set = $set2->grep( 
        sub {
            return ( ! $_->contains( $today ) );
        }
    );

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 C<DateTime::Span> à 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. 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

I<Méthode interne -- utilisez C<map> ou C<grep> à la place.>

Cette fonction applique une fonction de rappel à tous les éléments
d'un ensemble et renvoie l'ensemble des résultats.

Le paramètre C<$_[0]> de la routine de rappel est un objet C<DateTime::Span>.

Si la fonction de rappel renvoie C<undef>, la date-heure est enlevée de l'S<ensemble :>

    sub enleve_dimanches {
        $_[0] unless $_[0]->start->day_of_week == 7;
    }

The callback return value is expected to be within the span of the
C<previous> and the C<next> element in the original set.

For example: given the set C<[ 2001, 2010, 2015 ]>,
the callback result for the value C<2010> is expected to be
within the span C<[ 2001 .. 2015 ]>.

La fonction de rappel peut ne pas être appelée immédiatement. 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.

=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 suffisamment la langue anglaise,
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.1603 de C<DateTime::SpanSet>

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

=head1 COPYRIGHT

Copyright (c) 2003 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