=head1 NOM

DateTime::Span - intervalles de temps, plages de valeurs pour Datetime

=head1 RÉSUMÉ

    use DateTime;
    use DateTime::Span;

    $date1 = DateTime->new( year => 2002, month => 3, day => 11 );
    $date2 = DateTime->new( year => 2003, month => 4, day => 12 );
    $ens2 = DateTime::Span->from_datetimes( start => $date1, end => $date2 );
    #  ens2 = 2002-03-11 jusqu'à 2003-04-12

    $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->start;           # début de l'intervalle
    $date = $ens1->end;             # fin de l'intervalle

=head1 DESCRIPTION

DateTime::Span est un module pour les intervalles de temps ou les plages
de valeurs de dates-heures.

=head1 MÉTHODES

=over 4

=item * from_datetimes

Crée un nouvel intervalle en fonction d'une date-heure de début et d'une
date-heure de fin.

Un intervalle I<fermé> inclut ses S<bornes :>

   $span = DateTime::Span->from_datetimes( start => $dt1, end => $dt2 );

Un intervalle I<ouvert> n'inclut pas ses S<bornes :>

   $span = DateTime::Span->from_datetimes( after => $dt1, before => $dt2 );

Un intervalle I<semi-ouvert> inclut l'un de ses S<bornes :>

   $span = DateTime::Span->from_datetimes( start => $dt1, before => $dt2 );
   $span = DateTime::Span->from_datetimes( after => $dt1, end => $dt2 );

Un intervalle peut avoir une date de début mais pas de date de fin,
ou bien une date de fin sans date de début. Ces intervalles s'étendent
donc jusqu'à une date imaginaire S<« nuit> des S<temps » :>

   $span = DateTime::Span->from_datetimes( start => $dt1 );
   $span = DateTime::Span->from_datetimes( end => $dt2 );
   $span = DateTime::Span->from_datetimes( after => $dt1 );
   $span = DateTime::Span->from_datetimes( before => $dt2 );

Vous ne pouvez pas spécifier à la fois un paramètre C<start> et un
paramètre C<after>. De même, il est impossible de spécifier
simultanément un paramètre C<end> et un paramètre C<before>.
Dans un cas comme dans l'autre, la méthode 
C<from_datetimes()> s'arrête par un C<die>.

=item * from_datetime_and_duration

Crée un nouvel intervalle en fonction de la date de début ou
de fin et de la durée.

   $span = DateTime::Span->from_datetime_and_duration( 
       start => $dt1, duration => $dt_dur1 );
   $span = DateTime::Span->from_datetime_and_duration( 
       after => $dt1, hours => 12 );

Par défaut, l'extrémité implicite de l'intervalle est I<ouverte>.

=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 * duration

La durée totale de l'intervalle, sous la forme d'un objet C<DateTime::Duration>,
ou bien un scalaire représentant l'infini.

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

=item * start

=item * end

Début et fin de l'intervalle.

Il se peut que ces méthodes renvoient un objet
C<DateTime::Infinite::Past> ou C<DateTime::Infinite::Future>.

Si l'objet a été créé avec le paramètre C<before> ou C<after>, 
la méthode C<start> ou C<end> respectivement renvoie la date
correspondante. Notez que dans ce cas, la date renvoyée n'appartient
pas à l'intervalle, mais c'est néanmoins la borne inférieure ou supérieure.

=cut

# scalar containing either negative infinity
# or positive infinity.

=item * start_is_closed

=item * end_is_closed

Renvoie vrai si la borne inférieure ou supérieure appartient 
à l'intervalle (début E<lt>= x E<lt>= fin).

=item * start_is_open

=item * end_is_open

Renvoie vrai si la borne inférieure ou supérieure n'appartient 
pas à l'intervalle (début E<lt> x E<lt> fin).

=item * union

=item * intersection

=item * complement

Les opérations ensemblistes peuvent faire intervenir non seulement des objets
C<DateTime::Span>, mais aussi des C<DateTime::Set> et des C<DateTime::SpanSet>.
Dans tous les cas, le résultat est un objet C<DateTime::SpanSet>.

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

=item * intersects

=item * contains

Ces fonctions ensemblistes renvoient une valeur booléenne.

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

Ces méthodes acceptent un argument C<DateTime>, C<DateTime::Set>,
C<DateTime::Span> ou C<DateTime::SpanSet>.

=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::Span>

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