=head1 NOM

DateTime::TimeZone - Classe de base et générateur de classe pour les fuseaux horaires

=head1 RÉSUMÉ

  use DateTime;
  use DateTime::TimeZone

  my $tz = DateTime::TimeZone->new( name => 'America/Chicago' );

  my $dt = DateTime->now();
  my $offset = $tz->offset_for_datetime($dt);

=head1 DESCRIPTION

Cette classe est la classe de base pour tous les objets fuseaux horaires.
Le terme S<« fuseau horaire »> ne décrit pas ici simplement une zone
géographique située entre deux longitudes, mais plutôt une liste 
de périodes au cours desquelles tel ou tel décalage par rapport au
temps GMT a été suivi.

Notez que, si vous n'utilisez pas C<DateTime>, ce module ne vous sera
pas très utile. Son interface utilisateur est en grande partie
contenue implicitement dans celle de C<DateTime> et la plupart
des utilisateurs n'auront pas besoin d'invoquer directement les
méthodes de C<DateTime::TimeZone>.

=head1 UTILISATION

Cette classe possède les méthodes S<suivantes :>

=over 4

=item * new( name => $tz_name )

Cette méthode, qui reçoit un nom de fuseau horaire valide, renvoie
un objet fuseau horaire S<« béni »> dans la sous-classe appropriée.
Les sous-classes sont nommées en fonction du fuseau horaire, ce qui
fait que le fuseau horaire S<« America/Chicago »> est représenté par
la sous-classe C<DateTime::TimeZone::America::Chicago>.

Si le nom fourni est un S<« lien »> vers la base de données Olson,
l'objet peut porter un nom différent. Par exemple, il existe un lien
de l'ancien nom S<« EST5EDT »> vers le nom S<« America/New_York »>.

Il existe également quelques valeurs spéciales permettant de nommer
des fuseaux horaires particuliers.

Si le paramètre C<name> est C<floating>, alors le constructeur renvoie
un objet C<DateTime::TimeZone::Floating>. Un fuseau horaire flottant
n'a I<aucun> décalage horaire et ne change pas d'heure. Cela peut être
utile pour des applications d'agenda électronique, lorsqu'il faut
spécifier qu'un événement se produit toujours à la même heure I<locale>,
quels que soient le fuseau horaire et la saison où il se produit. 
Cf. la RFC 2445 pour de plus amples détails.

Si le paramètre C<name> est C<UTC>, le constructeur renvoie un objet
C<DateTime::TimeZone::UTC>.

Si le paramètre C<name> est une chaîne comportant uniquement un décalage
horaire, alors le constructeur renvoie un objet
C<DateTime::TimeZone::OffsetOnly>.

=back

=head3 Le fuseau horaire S<« local »>

Si le paramètre C<name> est C<local>, alors le module tente de déterminer
quel est le fuseau horaire local pour le système.

Tout d'abord, le module examine le hachage C<%ENV>
XXXXXX pas le scalaire  C<$ENV>.
pour y chercher une clé  "TZ", "SYS$TIMEZONE_RULE",
"SYS$TIMEZONE_NAME", "UCX$TZ", ou "TCPIP$TZC" (les quatre derniers
étant spécifiques à VMS). Si la variable d'environnement est définie
et s'il ne s'agit pas de la chaîne S<« local »>, alors le module
considère que c'est le nom d'un fuseau horaire (éventuellement 
S<« floating »>) et le constructeur tente de créer un objet 
C<DateTime::TimeZone> basé sur ce nom.

Sinon, le module teste l'existence d'un lien symbolique pour F</etc/localtime>.
Il suit ce lien pour trouver le fichier réel et détermine quel est
le nom de ce fichier. Il essaie alors de convertir le nom du
fichier en un nom valide de fuseau horaire. Par exemple,
si ce fichier est lié à F</usr/share/zoneinfo/US/Central>,
le module essaiera S<« US/Central »>", qui sera converti en interne en
S<« America/Chicago »>.

Certains systèmes ne procèdent pas par un lien symbolique vers le bon
fichier, mais par une copie pure et simple vers F</etc/localtime>.
Dans ce cas, le module cherche dans F</usr/share/zoneinfo> un fichier
dont la taille et le contenu sont les mêmes que pour F</etc/localtime>
et détermine ainsi le fuseau horaire local.

Puis le module vérifie l'existence d'un fichier nommé F</etc/timezone> 
ou F</etc/TIMEZONE>. Si un fichier existe avec l'un de ces deux noms,
le module le lit et tente de créer un objet C<DateTime::TimeZone>
avec le nom contenu dans ce fichier.

Finalement, le module cherche un fichier nommé F</etc/sysconfig/clock>.  
si ce fichier existe, le module cherche une ligne vérifiant l'expression
rationnelle C</^(?:TIME)?ZONE="([^"]+)"/>. Si une telle ligne existe,
le module tente de créer un fuseau horaire portant ce nom.

Si le module n'a toujours pas réussi à obtenir un objet C<DateTime::TimeZone>
valide à ce point, il s'arrête par un C<die>.

=head2 Méthodes d'objet

Les objets C<DateTime::TimeZone> possèdent les méthodes S<suivantes :>

=over 4

=item * offset_for_datetime( $dt )

Pour un objet C<DateTime>, cette méthode renvoie le décalage horaire
en secondes en vigueur à cette date et à cette heure. La méthode tient
compte de l'historique du fuseau horaire ainsi que de l'heure d'été.
Le décalage horaire est déterminé en consultant les informations
S<« Rata Die »> UTC de l'objet (jours RD et secondes RD).

=item * offset_for_local_datetime( $dt )

Pour un objet C<DateTime>, cette méthode renvoie le décalage horaire
en secondes en vigueur à cette date et à cette heure. À l'inverse de la méthode 
précédente, cette méthode utilise  les informations
S<« Rata Die »> locales de l'objet. Cette méthode ne doit être
utilisée que dans les cas où le temps UTC correspondant n'est pas
connu, étant donné que les dates-heures locales peuvent présenter
une ambiguïté à l'approche d'un changement d'heure.

=item * name

Renvoie le nom du fuseau horaire. Si cette valeur est ensuite transmise
à la méthode C<new()>, il est garanti que le module renverra le même objet.

=item * short_name_for_datetime( $dt )

Pour un objet C<DateTime>, cette méthode renvoie le nom abrégé
de la règle que suit cette date-heure. Il s'agit de noms du
type S<« EST »>, S<« GMT »>, etc.

Il est B<vivement> recommandé de ne pas se fier à ces noms
pour autre chose qu'un simple affichage. Ces noms n'ont rien
d'officiel et la plupart d'entre eux ne sont rien de plus que
des noms attribués par les mainteneurs de la base de données
Olson. De plus, ces noms ne sont pas discriminants. Par exemple,
il existe une règle S<« EST »> pour le décalage -0500 et une autre
pour le décalage +1000/+1100.

=item * is_floating

Renvoie un booléen indiquant si l'objet représente un fuseau horaire
flottant, ainsi qu'il est défini par la RFC 2445.

=item * is_utc

Indique si cet objet représent le fuseau horaire UTC (ou GMT).

=item * is_olson

Renvoie une valeur S<« vraie »> si le nom du fuseau horaire est un
nom figurant dans la base de données Olson.

=item * category

Renvoie la partie du nom figurant avant le premier slash. Par exemple,
pour S<« Europe/Paris »>, la méthode renvoie S<« Europe »>.

=back

=head2 Méthodes de classe

Cette classe fournit une méthode de S<classe :>

=over 4

=item * is_valid_name ($name)

Pour la chaîne envoyée en paramètre, la méthode renvoie une valeur
booléenne indiquant si la chaîne est un nom de fuseau horaire valide.
Si vous utilisez C<DateTime::TimeZone::Alias>, tout alias que vous
avez créé sera considéré comme valide.

=back

=head2 Points d'entrée pour Storable

Ce module propose des points d'entrée pour C<freeze> et C<thaw> de C<Storable>, de
sorte que les grosses structures de données des fuseaux horaires de
la base de données Olson ne sont pas stockées dans la structure
sérialisée.

Si vous créez une sous-classe héritant de C<DateTime::TimeZone>, 
cette sous-classe héritera de ces points d'entrée, mais cela risque
de ne pas fonctionner avec votre module. Donc, il est indispensable
de tester les interactions entre votre module et C<Storable>.

=head2 Fonctions

Cette classe contient également quelques fonctions, dont quelques-unes
sont exportées.

=over 4

=item * all_names

Cette fonction renvoie une liste triée des noms de fuseaux horaires.
Cette liste ne comporte cependant pas de liens. En contexte scalaire,
la fonction renvoie la référence à un tableau, tandis qu'en contexte
de liste, elle renvoie le tableau des noms.

=item * categories

Cette fonction renvoie la liste des catégories de fuseaux horaires.
En contexte scalaire, la fonction renvoie la référence à un tableau,
tandis qu'en contexte de liste, elle renvoie le tableau des
catégories.

=item * links

Cette fonction renvoie un hachage de tous les liens de fuseaux
horaires, dans lequel les clés sont les anciens noms, dépréciés,
tandis que les valeurs sont les nouveaux noms.  En contexte scalaire,
la fonction renvoie la référence à un hachage, tandis qu'en contexte
de liste, elle renvoie le hachage des liens.

=item * names_in_category( $category )

Pour une catégorie valide en paramètre, cette méthode renvoie
la liste des noms de fuseau appartenant à cette catégorie,
toutefois sans la catégorie. Par exemple, pour la catégorie
S<« America »>, cette fonction renvoie les chaînes S<« Chicago »>,
S<« Kentucky/Monticello »> et S<« New_York »> et ainsi de suite.  
En contexte scalaire, la fonction renvoie la référence à un tableau,
tandis qu'en contexte de liste, elle renvoie le tableau des noms.

=item * offset_as_seconds( $offset )

Cette méthode reçoit une chaîne de caractères représentant un décalage
horaire et renvoie la valeur de ce décalage horaire en secondes.
Renvoie C<undef> si le décalage C<$offset> ne figure pas dans la plage
C<-99:59:59> à C<+99:59:59>.

Le décalage doit correspondre à l'une des deux expressions rationnelles
C</^([\+\-])?(\d\d?):(\d\d)(?::(\d\d))?$/> ou
C</^([\+\-])?(\d\d)(\d\d)(\d\d)?$/>.  S'il ne correspond ni à l'une
ni à l'autre, la méthode renvoie C<undef>.

Cela signifie que si vous voulez spécifier l'heure avec un seul
chiffre, alors vous devez spécifier également les minutes en les séparant 
des heures par un deux-points (S<« : »>).

=item * offset_as_string( $offset )

Pour un décalage sous forme numérique, renvoie la chaîne de caractères
représentant ce décalage. Renvoie C<undef> si le décalage C<$offset>
n'appartient pas à la plage de valeurs de C<-359999> à C<359999>.

=back

=head1 SUPPORT

Le support de ce module est assuré par la liste de diffusion
C<datetime arobase perl point org>. 
Cf. http://lists.perl.org/ pour les détails.

Merci de communiquer vos rapporte de bugs au système RT de
CPAN à l'adresse
http://rt.cpan.org/NoAuth/ReportBug.html?Queue=datetime 
ou par messagerie électronique à 
C<bug-datetime> arobase C<rt> point C<cpan> point C<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

Dave Rolsky (adresse C<autarch> chez C<urth> point C<org>), 
qui s'est inspiré de Jesse Vincent et de son travail pour 
C<Date::ICal::Timezone>, avec également l'aide de la liste 
C<datetime> du site C<perl> point C<org>.

=head1 TRADUCTION

La traduction a été réalisée le 2004-06-20, en fonction de la version
0.2601 de C<DateTime::TimeZone>.

Traduit par Jean Forget (adresse C<JFORGET> sur le site C<cpan> point C<org>).

=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.

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<datetime@perl.org>

http://datetime.perl.org/

http://datetime.mongueurs.net/

Le répertoire C<tools> de la distribution C<DateTime::TimeZone>
inclut deux scripts qui peuvent intéresser certaines personnes.
Il s'agit de C<parse_olson> et de C<tests_from_zdump>. Vous pouvez
les lancer avec l'option B<--help> pour savoir à quoi ils servent.

=cut