|
Packit |
95306a |
# Copyright (c) 2008-2017 Sullivan Beck. All rights reserved.
|
|
Packit |
95306a |
# This program is free software; you can redistribute it and/or modify it
|
|
Packit |
95306a |
# under the same terms as Perl itself.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
=pod
|
|
Packit |
95306a |
|
|
Packit |
95306a |
=head1 NAME
|
|
Packit |
95306a |
|
|
Packit |
95306a |
Date::Manip::TZ - an interface to the time zone data
|
|
Packit |
95306a |
|
|
Packit |
95306a |
=head1 SYNOPSIS
|
|
Packit |
95306a |
|
|
Packit |
95306a |
use Date::Manip::TZ;
|
|
Packit |
95306a |
$tz = new Date::Manip::TZ;
|
|
Packit |
95306a |
|
|
Packit |
95306a |
Data for most (and hopefully all) time zones used around the world have
|
|
Packit |
95306a |
been gathered and is publicly available in the zoneinfo (or Olson)
|
|
Packit |
95306a |
database.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
This module uses the data from the zoneinfo database to perform various
|
|
Packit |
95306a |
time zone operations.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
=head1 DESCRIPTION
|
|
Packit |
95306a |
|
|
Packit |
95306a |
Every time zone has some of the following characteristics:
|
|
Packit |
95306a |
|
|
Packit |
95306a |
=over 4
|
|
Packit |
95306a |
|
|
Packit |
95306a |
=item B<name>
|
|
Packit |
95306a |
|
|
Packit |
95306a |
Every time zone has a unique name. In the zoneinfo database, these
|
|
Packit |
95306a |
are something similar to:
|
|
Packit |
95306a |
|
|
Packit |
95306a |
America/New_York
|
|
Packit |
95306a |
|
|
Packit |
95306a |
=item B<aliases>
|
|
Packit |
95306a |
|
|
Packit |
95306a |
Time zones may have (but are not required to have) one or more aliases.
|
|
Packit |
95306a |
Each alias is unique, and is not the same as any time zone name. An
|
|
Packit |
95306a |
alias can be used in exactly the same way as a name.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
=item B<periods>
|
|
Packit |
95306a |
|
|
Packit |
95306a |
Every time zone is broken up into periods. Each period describes how
|
|
Packit |
95306a |
a portion of time relates to GMT, and how it might be expressed.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
=back
|
|
Packit |
95306a |
|
|
Packit |
95306a |
Each period includes the following information:
|
|
Packit |
95306a |
|
|
Packit |
95306a |
=over 4
|
|
Packit |
95306a |
|
|
Packit |
95306a |
=item B<start time, end time>
|
|
Packit |
95306a |
|
|
Packit |
95306a |
The period begin and ends at certain times. The times are
|
|
Packit |
95306a |
included both as an absolute GMT time, and as a wall clock time.
|
|
Packit |
95306a |
The wall clock start time is the time that will be on a clock
|
|
Packit |
95306a |
just as the period starts (i.e. after a time change). The wall clock
|
|
Packit |
95306a |
end time is the time on a clock immediately before the period ends.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
=item B<offset>
|
|
Packit |
95306a |
|
|
Packit |
95306a |
The entire period has an offset which is how much the wall clock
|
|
Packit |
95306a |
time differs from GMT.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
=item B<abbreviation>
|
|
Packit |
95306a |
|
|
Packit |
95306a |
When expressing the time period, an abbreviation (such as EST) is
|
|
Packit |
95306a |
typically used.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
=item B<daylight saving time flag>
|
|
Packit |
95306a |
|
|
Packit |
95306a |
Every period is categorized as a standard time or a daylight
|
|
Packit |
95306a |
saving time. The flag will be 1 if it is a daylight saving time,
|
|
Packit |
95306a |
or 0 if it is a standard time.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
=back
|
|
Packit |
95306a |
|
|
Packit |
95306a |
Date::Manip includes all of the data for all of the time zones from
|
|
Packit |
95306a |
the zoneinfo database. This data is available from:
|
|
Packit |
95306a |
|
|
Packit |
95306a |
L<ftp://ftp.iana.org/tz/>
|
|
Packit |
95306a |
|
|
Packit |
95306a |
Additional data from other standards are also used.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
The zoneinfo database is not necessary in order to use Date::Manip.
|
|
Packit |
95306a |
Instead, all of that data has been extracted and stored in a
|
|
Packit |
95306a |
series of other modules which are used to handle each time zone.
|
|
Packit |
95306a |
In that way, Date::Manip has no dependency on any other source
|
|
Packit |
95306a |
of data.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
The L<Date::Manip::Zones> document contains detailed information
|
|
Packit |
95306a |
on the data available.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
=head1 METHODS
|
|
Packit |
95306a |
|
|
Packit |
95306a |
In all methods, the following variables are used:
|
|
Packit |
95306a |
|
|
Packit |
95306a |
=over 4
|
|
Packit |
95306a |
|
|
Packit |
95306a |
=item B<$zone>
|
|
Packit |
95306a |
|
|
Packit |
95306a |
This is a string which contains a valid time zone name. For
|
|
Packit |
95306a |
example:
|
|
Packit |
95306a |
|
|
Packit |
95306a |
America/New_York
|
|
Packit |
95306a |
|
|
Packit |
95306a |
=item B<$alias>
|
|
Packit |
95306a |
|
|
Packit |
95306a |
This is a strings which contains a valid time zone name, or a valid
|
|
Packit |
95306a |
time zone alias. For example:
|
|
Packit |
95306a |
|
|
Packit |
95306a |
America/New_York
|
|
Packit |
95306a |
US/Eastern
|
|
Packit |
95306a |
EST5EDT
|
|
Packit |
95306a |
|
|
Packit |
95306a |
=item B<$abbrev>
|
|
Packit |
95306a |
|
|
Packit |
95306a |
This is a string which contains a valid time zone abbreviation. For
|
|
Packit |
95306a |
example:
|
|
Packit |
95306a |
|
|
Packit |
95306a |
EST
|
|
Packit |
95306a |
|
|
Packit |
95306a |
=item B<$offset>
|
|
Packit |
95306a |
|
|
Packit |
95306a |
This is a time zone entered as an offset. An offset is either a string
|
|
Packit |
95306a |
of one of the formats:
|
|
Packit |
95306a |
|
|
Packit |
95306a |
+HH
|
|
Packit |
95306a |
+HHMM
|
|
Packit |
95306a |
+HHMMSS
|
|
Packit |
95306a |
+HH:MM
|
|
Packit |
95306a |
+HH:MM:SS
|
|
Packit |
95306a |
|
|
Packit |
95306a |
or it can be a list reference:
|
|
Packit |
95306a |
|
|
Packit |
95306a |
[HH,MM,SS]
|
|
Packit |
95306a |
|
|
Packit |
95306a |
If a list reference is used, the sign must be included with all values.
|
|
Packit |
95306a |
So, the offset "-05:30" would be the list reference:
|
|
Packit |
95306a |
|
|
Packit |
95306a |
[-5,-30,0]
|
|
Packit |
95306a |
|
|
Packit |
95306a |
=item B<$dstflag>
|
|
Packit |
95306a |
|
|
Packit |
95306a |
This is always one of the values: std, stdonly, dst, dstonly
|
|
Packit |
95306a |
|
|
Packit |
95306a |
It defaults to "std" if it is not present. When determining a time zone,
|
|
Packit |
95306a |
it is usually necessary to check a number of different time zone and
|
|
Packit |
95306a |
DST combinations.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
If C<$dstflag> is "std", it will check both standard and daylight saving
|
|
Packit |
95306a |
times, but will give preference to standard times. If C<$dstflag> is
|
|
Packit |
95306a |
"stdonly", only standard times will be checked.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
The "dst" flag will search both, but give preference to daylight saving
|
|
Packit |
95306a |
times. The "dstonly" values will only use daylight saving times.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
=item B<$date>
|
|
Packit |
95306a |
|
|
Packit |
95306a |
A date is always a string containing a date in one of the formats:
|
|
Packit |
95306a |
|
|
Packit |
95306a |
YYYYMMDDHH:MN:SS
|
|
Packit |
95306a |
YYYY-MM-DD-HH:MN:SS
|
|
Packit |
95306a |
YYYYMMDDHHMNSS
|
|
Packit |
95306a |
|
|
Packit |
95306a |
or a list reference:
|
|
Packit |
95306a |
|
|
Packit |
95306a |
[Y,M,D,H,MN,S]
|
|
Packit |
95306a |
|
|
Packit |
95306a |
=item B<$isdst>
|
|
Packit |
95306a |
|
|
Packit |
95306a |
This is 0 if a date is in standard time, 1 if it is in daylight saving
|
|
Packit |
95306a |
time.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
=item B<$period>
|
|
Packit |
95306a |
|
|
Packit |
95306a |
A period is a list reference currently containing the following
|
|
Packit |
95306a |
items:
|
|
Packit |
95306a |
|
|
Packit |
95306a |
[ $dateUT, $dateLT, $offsetstr, $offset, $abbrev, $isdst,
|
|
Packit |
95306a |
$endUT, $endLT, $begUTs, $begLTs, $endUTs, $endLTs ]
|
|
Packit |
95306a |
|
|
Packit |
95306a |
C<$dateUT> and C<$dateLT> are the starting date of the period (i.e. the
|
|
Packit |
95306a |
first second in a period) in universal (GMT) time and local
|
|
Packit |
95306a |
(wall clock) time. C<$endUT> and C<$endLT> are the end date of the period
|
|
Packit |
95306a |
(i.e. the last second in a period) in universal and local time.
|
|
Packit |
95306a |
These are all stored as list references.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
C<$offsetstr> is the string representation of the offset ("+05:00:00")
|
|
Packit |
95306a |
and C<$offset> is the corresponding list reference form ([5,0,0]).
|
|
Packit |
95306a |
|
|
Packit |
95306a |
C<$abbrev> is the abbreviation that applies during this period, and C<$isdst>
|
|
Packit |
95306a |
is 0 or 1 if it is standard or daylight saving time.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
When accessing the elements in a period, use ONLY positive indices.
|
|
Packit |
95306a |
In other words, to get C<$endUT>, access it as C<$$period[6]>, NOT as
|
|
Packit |
95306a |
C<$$period[-2]>, since I am considering adding more information to the
|
|
Packit |
95306a |
period description that may speed up performance.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
C<$begUTs> is the string representation (YYYYMMDDHH:MN:SS) of C<$begUT>.
|
|
Packit |
95306a |
Similar for C<$begLTs>, C<$endUTs>, and C<$endLTs>.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
=back
|
|
Packit |
95306a |
|
|
Packit |
95306a |
The following methods are available:
|
|
Packit |
95306a |
|
|
Packit |
95306a |
=over 4
|
|
Packit |
95306a |
|
|
Packit |
95306a |
=item B<base>
|
|
Packit |
95306a |
|
|
Packit |
95306a |
=item B<config>
|
|
Packit |
95306a |
|
|
Packit |
95306a |
=item B<err>
|
|
Packit |
95306a |
|
|
Packit |
95306a |
=item B<new>
|
|
Packit |
95306a |
|
|
Packit |
95306a |
=item B<new_config>
|
|
Packit |
95306a |
|
|
Packit |
95306a |
Please refer to the L<Date::Manip::Obj> documentation for these methods.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
=item B<all_periods>
|
|
Packit |
95306a |
|
|
Packit |
95306a |
@periods = $tz->all_periods($zone,$year);
|
|
Packit |
95306a |
|
|
Packit |
95306a |
This returns the description of all time zone periods that occur (in
|
|
Packit |
95306a |
full or in part) during the given year. The year is measured in universal
|
|
Packit |
95306a |
(GMT) time.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
=item B<convert>
|
|
Packit |
95306a |
|
|
Packit |
95306a |
=item B<convert_to_gmt>
|
|
Packit |
95306a |
|
|
Packit |
95306a |
=item B<convert_from_gmt>
|
|
Packit |
95306a |
|
|
Packit |
95306a |
=item B<convert_to_local>
|
|
Packit |
95306a |
|
|
Packit |
95306a |
=item B<convert_from_local>
|
|
Packit |
95306a |
|
|
Packit |
95306a |
These functions convert a date from one time zone to another.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
($err,$date,$offset,$isdst,$abbrev) =
|
|
Packit |
95306a |
$tz->convert($date,$from,$to [,$isdst]);
|
|
Packit |
95306a |
|
|
Packit |
95306a |
This converts a date in the time zone given by C<$from> to the time zone
|
|
Packit |
95306a |
given by C<$to>.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
($err,$date,$offset,$isdst,$abbrev) =
|
|
Packit |
95306a |
$tz->convert_to_gmt($date [,$from] [,$isdst]);
|
|
Packit |
95306a |
|
|
Packit |
95306a |
This converts a date to GMT. If C<$from> is given, it is the current
|
|
Packit |
95306a |
time zone of the date. If C<$from> is omitted, it defaults to the local
|
|
Packit |
95306a |
time zone.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
The value of C<$isdst> returned is always 0.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
($err,$date,$offset,$isdst,$abbrev) =
|
|
Packit |
95306a |
$tz->convert_from_gmt($date [,$to]);
|
|
Packit |
95306a |
|
|
Packit |
95306a |
This converts a date from GMT to another time zone. If C<$to> is given,
|
|
Packit |
95306a |
the date is converted to that time zone. Otherwise, it is converted
|
|
Packit |
95306a |
to the local time zone.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
($err,$date,$offset,$isdst,$abbrev) =
|
|
Packit |
95306a |
$tz->convert_to_local($date [,$from] [,$isdst]);
|
|
Packit |
95306a |
($err,$date,$offset,$isdst,$abbrev) =
|
|
Packit |
95306a |
$tz->convert_from_local($date [,$to] [,$isdst]);
|
|
Packit |
95306a |
|
|
Packit |
95306a |
Similar to the B<convert_to_gmt> and B<convert_from_gmt> functions. If C<$from>
|
|
Packit |
95306a |
or C<$to> are omitted, they default to GMT.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
If there is any ambiguity about whether C<$date> is in DST or not (i.e.
|
|
Packit |
95306a |
if it is a date that is repeated during a time change due to the clock
|
|
Packit |
95306a |
being moved back), the C<$isdst> option can be passed in as an argument
|
|
Packit |
95306a |
(it should be 0 or 1) to say which time to use. It is ignored in all
|
|
Packit |
95306a |
cases where C<$date> can be determined without that information.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
The C<$isdst> value passed back is 1 if the converted date is in DST. The
|
|
Packit |
95306a |
C<$offset> value passed back is a list reference containing the offset from
|
|
Packit |
95306a |
GMT. C<$abbrev> passed back is the time zone abbreviation.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
Error codes are:
|
|
Packit |
95306a |
|
|
Packit |
95306a |
0 No error
|
|
Packit |
95306a |
1 Invalid arguments
|
|
Packit |
95306a |
2 Invalid FROM zone
|
|
Packit |
95306a |
3 Invalid TO zone
|
|
Packit |
95306a |
4 Invalid date
|
|
Packit |
95306a |
|
|
Packit |
95306a |
=item B<curr_zone>
|
|
Packit |
95306a |
|
|
Packit |
95306a |
$tz->curr_zone();
|
|
Packit |
95306a |
|
|
Packit |
95306a |
This returns the system time zone. The system time zone is determined
|
|
Packit |
95306a |
using the methods described below in the
|
|
Packit |
95306a |
L</"DETERMINING THE SYSTEM TIME ZONE"> section.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
This is the time zone that is used by default unless the SetDate
|
|
Packit |
95306a |
or ForceDate config variable is set to a different zone.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
$tz->curr_zone(1);
|
|
Packit |
95306a |
|
|
Packit |
95306a |
This clears the system time zone and re-determines it using the
|
|
Packit |
95306a |
methods described below.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
The main reason to do this is if the curr_zone_methods method is
|
|
Packit |
95306a |
used to change how the time zone is determined.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
=item B<curr_zone_methods>
|
|
Packit |
95306a |
|
|
Packit |
95306a |
$tz->curr_zone_methods(@methods);
|
|
Packit |
95306a |
|
|
Packit |
95306a |
This sets the list and order of methods to use in determining the
|
|
Packit |
95306a |
local time zone. The various methods available are listed below in
|
|
Packit |
95306a |
the section L</"DETERMINING THE SYSTEM TIME ZONE">.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
Some methods may require one or more arguments. For example, the
|
|
Packit |
95306a |
method named "mainvar" takes an option that is the name of a
|
|
Packit |
95306a |
variable. The arguments must be included in the @methods list
|
|
Packit |
95306a |
immediately after the method name (so @methods is actually a
|
|
Packit |
95306a |
mixture of method names and arguments).
|
|
Packit |
95306a |
|
|
Packit |
95306a |
This method may not be used in any environment where taint
|
|
Packit |
95306a |
checking is enabled. If it is, it will issue a warning, but
|
|
Packit |
95306a |
will NOT change the method list.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
=item B<date_period>
|
|
Packit |
95306a |
|
|
Packit |
95306a |
$period = $tz->date_period($date,$zone,$wall_clock [,$isdst]);
|
|
Packit |
95306a |
|
|
Packit |
95306a |
This returns the period information for the given date. $date defaults
|
|
Packit |
95306a |
to GMT, but may be given as local (i.e. wall clock) time if $wall_clock
|
|
Packit |
95306a |
is non-zero. The period information is described in the periods method
|
|
Packit |
95306a |
below.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
If a wall clock time is given, no period is returned if the wall clock
|
|
Packit |
95306a |
time doesn't ever appear (such as when a time change results in the
|
|
Packit |
95306a |
clock moving forward "skipping" a period of time). If the wall clock
|
|
Packit |
95306a |
time appears twice (i.e. when a time change results in the clock
|
|
Packit |
95306a |
being set back), the $isdst variable is used. The standard time
|
|
Packit |
95306a |
is used unless $isdst is non-zero. $isdst is ignored except in the
|
|
Packit |
95306a |
case where there are two possible periods.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
=item B<define_abbrev>
|
|
Packit |
95306a |
|
|
Packit |
95306a |
($err,$val) = $tz->define_abbrev($abbrev,@zone);
|
|
Packit |
95306a |
|
|
Packit |
95306a |
When encountering an abbreviation, by default, all time zones which ever
|
|
Packit |
95306a |
include the abbreviation will be examine in the order given in the
|
|
Packit |
95306a |
Date::Manip::Zones manual.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
Occasionally, it may be necessary to change the order. This is
|
|
Packit |
95306a |
true if you are parsing dates in a time zone which uses an abbreviation which
|
|
Packit |
95306a |
is also used in another time zone, and where the other time zone is given
|
|
Packit |
95306a |
preference. As an example, the abbreviation "ADT" will default to the
|
|
Packit |
95306a |
"Atlantic/Bermuda" time zone. If you are in the "America/Halifax" time zone
|
|
Packit |
95306a |
(which also uses that abbreviation), you may want to change the order
|
|
Packit |
95306a |
of time zones.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
This will take an abbreviation (which must be a known
|
|
Packit |
95306a |
abbreviation... there is no means of defining a totally new
|
|
Packit |
95306a |
abbreviation) and a list of zones. This will set the list of zones
|
|
Packit |
95306a |
that will be checked, and the order in which they are checked, when a
|
|
Packit |
95306a |
date is encountered with the given abbreviation. It is not necessary
|
|
Packit |
95306a |
that the list include every zone that has ever used the abbreviation,
|
|
Packit |
95306a |
but it may not include a zone that has never used it.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
If $abbrev is "reset", all abbreviations are reset to the standard
|
|
Packit |
95306a |
values. If @zone includes only the element 'reset', the default list
|
|
Packit |
95306a |
for $abbrev is restored.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
The following error codes are returned:
|
|
Packit |
95306a |
|
|
Packit |
95306a |
0 No error
|
|
Packit |
95306a |
1 $abbrev is not a valid abbreviation in any time zone
|
|
Packit |
95306a |
2 A zone (returned as $val) is not a valid time zone
|
|
Packit |
95306a |
3 A zone (returned as $val) does not use the abbreviation
|
|
Packit |
95306a |
|
|
Packit |
95306a |
For more information about the different zones which may correspond
|
|
Packit |
95306a |
to each abbreviation, and the order in which they will be examined
|
|
Packit |
95306a |
by default, refer to the Date::Manip::Zones manual.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
=item B<define_alias>
|
|
Packit |
95306a |
|
|
Packit |
95306a |
$err = $tz->define_alias($alias,$zone);
|
|
Packit |
95306a |
|
|
Packit |
95306a |
This will define a new alias (or override an existing alias). $zone must
|
|
Packit |
95306a |
be a valid zone or an error is returned.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
For more information about the different aliases which are set by
|
|
Packit |
95306a |
default, refer to the Date::Manip::Zones manual.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
If $alias is "reset", all aliases will be reset to the standard values.
|
|
Packit |
95306a |
If $zone is "reset", $alias will be reset to the standard value.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
=item B<define_offset>
|
|
Packit |
95306a |
|
|
Packit |
95306a |
($err,$val) = $tz->define_offset($offset, [$dstflag,] @zone);
|
|
Packit |
95306a |
|
|
Packit |
95306a |
This is similar to the define_abbrev method. When an offset is encountered,
|
|
Packit |
95306a |
all time zones which have ever included that offset are checked. This will
|
|
Packit |
95306a |
defined which time zones, and in what order, they should be checked.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
The zones to both standard and daylight saving times which include the
|
|
Packit |
95306a |
offset (if $dstflag is "std" or "dst") or to only one or the other.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
If $offset is "reset", all lists are reset to the default values. If
|
|
Packit |
95306a |
@zone includes only the element 'reset', the default list and order is
|
|
Packit |
95306a |
restored for $offset ($dstflag must not be given).
|
|
Packit |
95306a |
|
|
Packit |
95306a |
The following error codes are returned:
|
|
Packit |
95306a |
|
|
Packit |
95306a |
0 No error
|
|
Packit |
95306a |
1 $offset is not a valid offset in any time zone
|
|
Packit |
95306a |
2 $offset is not a valid offset in the selected
|
|
Packit |
95306a |
time (if doing "dstonly" or "stdonly")
|
|
Packit |
95306a |
3 A zone (returned as $val) is not a valid time zone
|
|
Packit |
95306a |
4 A zone (returned as $val) does not use the offset
|
|
Packit |
95306a |
5 A zone (returned as $val) does not include the
|
|
Packit |
95306a |
offset in the selected time (if doing "dstonly"
|
|
Packit |
95306a |
or "stdonly")
|
|
Packit |
95306a |
|
|
Packit |
95306a |
9 Offset is not a valid offset
|
|
Packit |
95306a |
|
|
Packit |
95306a |
=item B<periods>
|
|
Packit |
95306a |
|
|
Packit |
95306a |
@periods = $tz->periods($zone,$year);
|
|
Packit |
95306a |
|
|
Packit |
95306a |
This returns the description of all time zone periods that begin during the
|
|
Packit |
95306a |
year given. The year is measured in universal (GMT) time.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
If no time zone period starts in the given year, nothing is returned.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
@periods = $tz->periods($zone,undef,$year);
|
|
Packit |
95306a |
|
|
Packit |
95306a |
This returns all periods that begin in any year from 0001 to $year.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
@periods = $tz->periods($zone,$year0,$year1);
|
|
Packit |
95306a |
|
|
Packit |
95306a |
This returns all periods that begin in any year from $year0 to $year1.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
=item B<tzdata>
|
|
Packit |
95306a |
|
|
Packit |
95306a |
=item B<tzcode>
|
|
Packit |
95306a |
|
|
Packit |
95306a |
$vers = $tz->tzdata();
|
|
Packit |
95306a |
$vers = $tz->tzcode();
|
|
Packit |
95306a |
|
|
Packit |
95306a |
These return the versions of the tzdata and tzcode packages used to
|
|
Packit |
95306a |
generate the modules.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
=item B<zone>
|
|
Packit |
95306a |
|
|
Packit |
95306a |
$zone = $tz->zone(@args);
|
|
Packit |
95306a |
@zone = $tz->zone(@args);
|
|
Packit |
95306a |
|
|
Packit |
95306a |
This function will return a list of all zones, or the default zone,
|
|
Packit |
95306a |
which matches all of the supplied information. In scalar context,
|
|
Packit |
95306a |
it will return only the default zone. In list context, it will return
|
|
Packit |
95306a |
all zones.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
@args may include any of the following items, and the order is not
|
|
Packit |
95306a |
important.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
A zone name or alias ($alias)
|
|
Packit |
95306a |
|
|
Packit |
95306a |
A zone abbreviation ($abbrev)
|
|
Packit |
95306a |
|
|
Packit |
95306a |
An offset ($offset)
|
|
Packit |
95306a |
|
|
Packit |
95306a |
A dstflag ($dstflag)
|
|
Packit |
95306a |
|
|
Packit |
95306a |
A date ($date)
|
|
Packit |
95306a |
|
|
Packit |
95306a |
It is NOT valid to include two of any of the items. Any time zone
|
|
Packit |
95306a |
returned will match all of the data supplied.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
If an error occurs, undef is returned. If no zone matches, an empty
|
|
Packit |
95306a |
string, or an empty list is returned.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
The order of the zones will be determined in the following way:
|
|
Packit |
95306a |
|
|
Packit |
95306a |
If $abbrev is given, the order of time zones will be determined by it
|
|
Packit |
95306a |
(and $dstflag). If $dstflag is "std", all zones which match $abbrev in
|
|
Packit |
95306a |
standard time are included, followed by all that match $abbrev in
|
|
Packit |
95306a |
saving time (but no duplication is allowed). The reverse is true if
|
|
Packit |
95306a |
$dstflag is "dst".
|
|
Packit |
95306a |
|
|
Packit |
95306a |
If $abbrev is not given, but $offset is, $offset (and $dstflag)
|
|
Packit |
95306a |
will determine the order given. If $dstflag is "std", all zones
|
|
Packit |
95306a |
which match $offset in standard time are included, followed by
|
|
Packit |
95306a |
all that match $offset in saving time (but no duplication is
|
|
Packit |
95306a |
allowed). The reverse is true if $dstflag is "dst".
|
|
Packit |
95306a |
|
|
Packit |
95306a |
If $date is given, only zones in which $date will appear in a
|
|
Packit |
95306a |
zone that matches all other information are given. $date is a
|
|
Packit |
95306a |
wall clock time.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
If no $zone, $abbrev, or $offset are entered, the local time zone
|
|
Packit |
95306a |
may be returned (unless $date is entered, and it doesn't exist in
|
|
Packit |
95306a |
the local time zone).
|
|
Packit |
95306a |
|
|
Packit |
95306a |
NOTE: there is one important thing to note with respect to $dstflag
|
|
Packit |
95306a |
when you are working with a timezone expressed as an offset and a date
|
|
Packit |
95306a |
is passed in. In this case, the default value of $dstflag is "dst"
|
|
Packit |
95306a |
(NOT "stdonly"), and you probably never want to pass in a value of
|
|
Packit |
95306a |
"std" (though passing in "stdonly" is okay).
|
|
Packit |
95306a |
|
|
Packit |
95306a |
For standard offsets (with no minute component), there is always
|
|
Packit |
95306a |
a standard timezone which matches that offset. For example,
|
|
Packit |
95306a |
the timezone "+0100" matches the timezone "Etc/GMT+01", so you
|
|
Packit |
95306a |
will never get a timezone in daylight saving time if $dstflag
|
|
Packit |
95306a |
is "std".
|
|
Packit |
95306a |
|
|
Packit |
95306a |
If you want to pass in a date of 2001-07-01-00:00:00 and an timezone
|
|
Packit |
95306a |
of "+0100" and you want to get a timezone that refers to that date
|
|
Packit |
95306a |
as a daylight saving time date, you must use the $dstflag of "dst"
|
|
Packit |
95306a |
(or "dstonly").
|
|
Packit |
95306a |
|
|
Packit |
95306a |
Because this is almost always the behavior desired, when a zone
|
|
Packit |
95306a |
is passed in as an offset, and a date is passed in, the default
|
|
Packit |
95306a |
$dstflag is "dst" instead of "std". In all other situations,
|
|
Packit |
95306a |
the default is still "std".
|
|
Packit |
95306a |
|
|
Packit |
95306a |
If the timezone is expressed as an abbreviation, this problem
|
|
Packit |
95306a |
does not occur.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
=back
|
|
Packit |
95306a |
|
|
Packit |
95306a |
=head1 TIME ZONE INFORMATION IN DATE::MANIP
|
|
Packit |
95306a |
|
|
Packit |
95306a |
Date::Manip makes use of three potentially different time zones when
|
|
Packit |
95306a |
working with a date.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
The first time zone that may be used is the actual local time zone.
|
|
Packit |
95306a |
This is the time zone that the computer is actually running in.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
The second time zone is the working time zone. Usually, you will want
|
|
Packit |
95306a |
the default time zone to be the local time zone, but occasionally, you
|
|
Packit |
95306a |
may want the default time zone to be different.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
The third time zone is the actual time zone that was parsed, or set,
|
|
Packit |
95306a |
for a date. If a date contains no time zone information, it will
|
|
Packit |
95306a |
default to the working time zone.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
The local time zone is determined using the methods described in the
|
|
Packit |
95306a |
following section. The preferred way is to locate the time zone in
|
|
Packit |
95306a |
some system file, or using some system command, or (in the case of
|
|
Packit |
95306a |
a Windows operating system) to look it up in the registry. If all
|
|
Packit |
95306a |
of these methods fail, the local time zone may be set using either
|
|
Packit |
95306a |
the $::TZ or $ENV{TZ} variables. Please note that these should ONLY
|
|
Packit |
95306a |
be used to set the actual local time zone.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
If you are running in one time zone, but you want to force dates to be
|
|
Packit |
95306a |
specified in an alternate time zone by default, you need to set the
|
|
Packit |
95306a |
working time zone. The working time zone defaults to the local time zone,
|
|
Packit |
95306a |
but this can be changed using either the SetDate or ForceDate
|
|
Packit |
95306a |
config variables. Refer to the Date::Manip::Config manual for more
|
|
Packit |
95306a |
information.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
Finally, when a date is actually parsed, if it contains any time zone
|
|
Packit |
95306a |
information, the date is stored in that time zone.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
=head1 DETERMINING THE SYSTEM TIME ZONE
|
|
Packit |
95306a |
|
|
Packit |
95306a |
There are a large number of ways available for determining the
|
|
Packit |
95306a |
time zone. Some or all of them may be checked. A list of methods to use
|
|
Packit |
95306a |
is provided by default, and may be overridden by the curr_zone_methods
|
|
Packit |
95306a |
function described above. To override the default order and/or list of
|
|
Packit |
95306a |
methods, just pass in a list of method names (with arguments where
|
|
Packit |
95306a |
necessary), and only those methods will be done, and in the order
|
|
Packit |
95306a |
given.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
The following methods are available:
|
|
Packit |
95306a |
|
|
Packit |
95306a |
Method Argument(s) Procedure
|
|
Packit |
95306a |
====== =========== =========
|
|
Packit |
95306a |
|
|
Packit |
95306a |
main VAR The main variable named VAR is
|
|
Packit |
95306a |
checked. E.g. "main TZ" checks
|
|
Packit |
95306a |
the variable $::TZ .
|
|
Packit |
95306a |
|
|
Packit |
95306a |
env TYPE VAR The named environment variable
|
|
Packit |
95306a |
is checked and the type of
|
|
Packit |
95306a |
data stored there (TYPE can
|
|
Packit |
95306a |
be 'zone' or 'offset' which
|
|
Packit |
95306a |
is the number of seconds from
|
|
Packit |
95306a |
UTC).
|
|
Packit |
95306a |
|
|
Packit |
95306a |
file FILE Look in the given file for any
|
|
Packit |
95306a |
one of the following case
|
|
Packit |
95306a |
insensitive lines:
|
|
Packit |
95306a |
ZONE
|
|
Packit |
95306a |
tz = ZONE
|
|
Packit |
95306a |
zone = ZONE
|
|
Packit |
95306a |
timezone = ZONE
|
|
Packit |
95306a |
ZONE may be quoted (single or
|
|
Packit |
95306a |
double) and whitespace is
|
|
Packit |
95306a |
ignored (except that underscores
|
|
Packit |
95306a |
in the zone name may be replaced
|
|
Packit |
95306a |
by whitespace on some OSes). If
|
|
Packit |
95306a |
the entire line is a zone, it must
|
|
Packit |
95306a |
be the first non-blank non-comment
|
|
Packit |
95306a |
line in the file.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
command COMMAND Runs a command which produces
|
|
Packit |
95306a |
a time zone as the output.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
cmdfield COMMAND N Runs a command which produces
|
|
Packit |
95306a |
whitespace separated fields,
|
|
Packit |
95306a |
the Nth one containing the
|
|
Packit |
95306a |
time zone (fields are numbered
|
|
Packit |
95306a |
starting at 0, or from the
|
|
Packit |
95306a |
end starting at -1).
|
|
Packit |
95306a |
|
|
Packit |
95306a |
gmtoff Uses the current offset from
|
|
Packit |
95306a |
GMT to come up with a best guess.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
tzdata FILE DIR This uses a system config file that
|
|
Packit |
95306a |
contains a pointer to the local tzdata
|
|
Packit |
95306a |
files to determine the timezone. On
|
|
Packit |
95306a |
many operating systems, use:
|
|
Packit |
95306a |
|
|
Packit |
95306a |
tzdata /etc/localtime /usr/share/zoneinfo
|
|
Packit |
95306a |
|
|
Packit |
95306a |
FILE is the system file. DIR is the
|
|
Packit |
95306a |
directory where the tzdata files are stored.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
The config file is either a link to a file
|
|
Packit |
95306a |
in the tzdata directory or a copy of one
|
|
Packit |
95306a |
of the files.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
registry Look up the value in the
|
|
Packit |
95306a |
Windows registry. This is only
|
|
Packit |
95306a |
available to hosts running a
|
|
Packit |
95306a |
Windows operating system.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
Note that the "main" and "env" methods should only be used to
|
|
Packit |
95306a |
specify the actual time zone the system is running in. Use the
|
|
Packit |
95306a |
SetDate and ForceDate config variables to specify an alternate
|
|
Packit |
95306a |
time zone that you want to work in.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
By default, the following methods are checked (in the order given) on
|
|
Packit |
95306a |
Unix systems:
|
|
Packit |
95306a |
|
|
Packit |
95306a |
main TZ
|
|
Packit |
95306a |
env zone TZ
|
|
Packit |
95306a |
file /etc/TIMEZONE
|
|
Packit |
95306a |
file /etc/timezone
|
|
Packit |
95306a |
file /etc/sysconfig/clock
|
|
Packit |
95306a |
file /etc/default/init
|
|
Packit |
95306a |
tzdata /etc/localtime /usr/share/zoneinfo
|
|
Packit |
95306a |
command "/bin/date +%Z"
|
|
Packit |
95306a |
command "/usr/bin/date +%Z"
|
|
Packit |
95306a |
command "/usr/local/bin/date +%Z"
|
|
Packit |
95306a |
cmdfield /bin/date -2
|
|
Packit |
95306a |
cmdfield /usr/bin/date -2
|
|
Packit |
95306a |
cmdfield /usr/local/bin/date -2
|
|
Packit |
95306a |
gmtoff
|
|
Packit |
95306a |
|
|
Packit |
95306a |
The default methods for Windows systems are:
|
|
Packit |
95306a |
|
|
Packit |
95306a |
main TZ
|
|
Packit |
95306a |
env zone TZ
|
|
Packit |
95306a |
registry
|
|
Packit |
95306a |
gmtoff
|
|
Packit |
95306a |
|
|
Packit |
95306a |
The default methods for VMS systems are:
|
|
Packit |
95306a |
|
|
Packit |
95306a |
main TZ
|
|
Packit |
95306a |
env zone TZ
|
|
Packit |
95306a |
env zone SYS$TIMEZONE_NAME
|
|
Packit |
95306a |
env zone UCX$TZ
|
|
Packit |
95306a |
env zone TCPIP$TZ
|
|
Packit |
95306a |
env zone MULTINET_TIMEZONE
|
|
Packit |
95306a |
env offset SYS$TIMEZONE_DIFFERENTIAL
|
|
Packit |
95306a |
gmtoff
|
|
Packit |
95306a |
|
|
Packit |
95306a |
The default methods for all other systems are:
|
|
Packit |
95306a |
|
|
Packit |
95306a |
main TZ
|
|
Packit |
95306a |
env zone TZ
|
|
Packit |
95306a |
gmtoff
|
|
Packit |
95306a |
|
|
Packit |
95306a |
If anyone wants better support for a specific OS, please contact me and
|
|
Packit |
95306a |
we'll coordinate adding it.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
In all cases, the value returned from the method may be any of the
|
|
Packit |
95306a |
following:
|
|
Packit |
95306a |
|
|
Packit |
95306a |
the full name of a time zone (e.g. America/New_York)
|
|
Packit |
95306a |
or an alias
|
|
Packit |
95306a |
|
|
Packit |
95306a |
an abbreviation (e.g. EDT) which will be used to
|
|
Packit |
95306a |
determine the zone if possible
|
|
Packit |
95306a |
|
|
Packit |
95306a |
an offset (+hh, +hhmn, +hh:mm, +hh:mm:ss) from GMT
|
|
Packit |
95306a |
|
|
Packit |
95306a |
The Date::Manip::Zones module contains information about the time zones
|
|
Packit |
95306a |
and aliases available, and what time zones contain the abbreviations.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
=head1 DESIGN ISSUES
|
|
Packit |
95306a |
|
|
Packit |
95306a |
The design decisions made in writing this module may cause some
|
|
Packit |
95306a |
questions (and probably complaints). The time zone modules are all
|
|
Packit |
95306a |
generated using scripts (included in the Date::Manip distribution)
|
|
Packit |
95306a |
which use the standard tzdata tools to parse the tzdata files and
|
|
Packit |
95306a |
store that information in perl modules.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
I'd like to address some of them, to avoid answering some of the
|
|
Packit |
95306a |
"why did you do it that way" remarks. I do welcome discussion about
|
|
Packit |
95306a |
these decisions... but preferably after you understand why those
|
|
Packit |
95306a |
decisions were made so that that we have an informed basis to begin
|
|
Packit |
95306a |
a discussion.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
=over 4
|
|
Packit |
95306a |
|
|
Packit |
95306a |
=item B<Why not use existing zoneinfo files>
|
|
Packit |
95306a |
|
|
Packit |
95306a |
Some people will probably think that I should have written an interface to
|
|
Packit |
95306a |
the zoneinfo files which are distributed with most operating systems.
|
|
Packit |
95306a |
Although I considered doing that, I rejected the idea for two reasons.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
First, not all operating systems come with the zoneinfo databases in a
|
|
Packit |
95306a |
user accessible state (Microsoft for example). Even those that do
|
|
Packit |
95306a |
include them store the information in various formats and locations.
|
|
Packit |
95306a |
In order to bypass all that, I have included the data directly in
|
|
Packit |
95306a |
these modules.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
Second, as I was doing my initial investigations into this, I ran into
|
|
Packit |
95306a |
a bug in the Solaris zoneinfo tools (long since fixed I'm sure). I
|
|
Packit |
95306a |
decided then that I didn't want to depend on an implementation where I
|
|
Packit |
95306a |
could not control and fix the bugs.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
=item B<Why not use the native tzdata files>
|
|
Packit |
95306a |
|
|
Packit |
95306a |
Another decision people may question is that I parse the tzdata
|
|
Packit |
95306a |
files and store the data from them in a large number of perl modules
|
|
Packit |
95306a |
instead of creating an interface to the tzdata files directly. This
|
|
Packit |
95306a |
was done solely for the sake of speed. Date::Manip is already a slow
|
|
Packit |
95306a |
module. I didn't want to slow it down further by doing the complex
|
|
Packit |
95306a |
parsing required to interpret the tzdata files while manipulating
|
|
Packit |
95306a |
dates. By storing the data in these modules, there is little or no
|
|
Packit |
95306a |
parsing done while using Date::Manip modules. It costs a little disk
|
|
Packit |
95306a |
space to store this information... but very little of it is actually
|
|
Packit |
95306a |
loaded at runtime (time zone data is only loaded when the time zone
|
|
Packit |
95306a |
is actually referred to), so I feel it's a good tradeoff.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
=item B<Why store the information in so many files>
|
|
Packit |
95306a |
|
|
Packit |
95306a |
The data from the native tzdata files are parsed and stored in two
|
|
Packit |
95306a |
sets of modules. These include almost 500 Date::Manip::Offset::*
|
|
Packit |
95306a |
modules and almost 450 Date::Manip::TZ::* modules.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
I note that on my linux box, /usr/share/zoneinfo (which contains data
|
|
Packit |
95306a |
files generated from the tzdata files) contains over 1700 files, so
|
|
Packit |
95306a |
I'm not doing anything "new" by breaking up the information into
|
|
Packit |
95306a |
separate files. And doing so has a huge impact on performance... it
|
|
Packit |
95306a |
is not necessary to load and/or manipulate data from time zones which
|
|
Packit |
95306a |
are not in use.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
The minute I made the decision to distribute the timezone information
|
|
Packit |
95306a |
myself, as opposed to using the system version, it was a given that
|
|
Packit |
95306a |
there would be a lot of files.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
These modules are loaded only when the time zone or offset is actually
|
|
Packit |
95306a |
used, so, unless dates from around the world are being parsed, only a
|
|
Packit |
95306a |
very small number of these modules will actually be loaded. In many
|
|
Packit |
95306a |
applications, only a single TZ module will be loaded. If parsing
|
|
Packit |
95306a |
dates which have timezone information stored as offsets, one or two
|
|
Packit |
95306a |
Offset modules will also be loaded.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
=item B<The disk space seems excessive>
|
|
Packit |
95306a |
|
|
Packit |
95306a |
Currently, the disk usage of the perl files is around 9 MB. Total disk
|
|
Packit |
95306a |
usage for /usr/share/zoneinfo on my computer is around 4 MB. There are
|
|
Packit |
95306a |
a couple of differences.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
The primary difference is that the zoneinfo files are stored in a binary
|
|
Packit |
95306a |
(and hence, more compressed) version, where the perl modules have all
|
|
Packit |
95306a |
the data in pure text.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
Since these are all automatically generated and used, it may be
|
|
Packit |
95306a |
beneficial to store the data in some packed binary format instead of
|
|
Packit |
95306a |
the fully expanded text form that is currently in use. This would
|
|
Packit |
95306a |
decrease the disk space usage, and might improve performance. However,
|
|
Packit |
95306a |
the performance improvement would happen only once per timezone, and
|
|
Packit |
95306a |
would make for more complicated code, so I'm not very interested in
|
|
Packit |
95306a |
pursuing this.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
Another aspect of the current modules is that they all include pod
|
|
Packit |
95306a |
documentation. Although not necessary, this allows users to easily
|
|
Packit |
95306a |
see what modules handle which time zones, and that's nice. It also
|
|
Packit |
95306a |
allows me to use pod_coverage tests for the module which is a nice
|
|
Packit |
95306a |
check to make sure that the documentation is accurate.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
All told, I don't consider the disk usage excessive at all.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
=back
|
|
Packit |
95306a |
|
|
Packit |
95306a |
=head1 KNOWN PROBLEMS OR ISSUES
|
|
Packit |
95306a |
|
|
Packit |
95306a |
=over 4
|
|
Packit |
95306a |
|
|
Packit |
95306a |
=item B<Unable to determine Time Zone>
|
|
Packit |
95306a |
|
|
Packit |
95306a |
When using Date::Manip, when the module is initialized, it must be
|
|
Packit |
95306a |
able to determine the local time zone. If it fails to do so, an
|
|
Packit |
95306a |
error will occur:
|
|
Packit |
95306a |
|
|
Packit |
95306a |
Unable to determine Time Zone
|
|
Packit |
95306a |
|
|
Packit |
95306a |
and the script will exit.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
In the past, this was the most common problem with using Date::Manip .
|
|
Packit |
95306a |
With the release of 6.00, this problem should be significantly less
|
|
Packit |
95306a |
common. If you do get this error, please refer to the section above
|
|
Packit |
95306a |
DETERMINING THE SYSTEM TIME ZONE for information about determining the
|
|
Packit |
95306a |
local time zone. I am also interested in hearing about this so that I
|
|
Packit |
95306a |
can update the default list of methods to be able to determine the
|
|
Packit |
95306a |
local time zone better.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
=item B<Asia/Jerusalem time zone>
|
|
Packit |
95306a |
|
|
Packit |
95306a |
The Asia/Jerusalem time zone has a non-standard way of specifying
|
|
Packit |
95306a |
the start and end of Daylight Saving Time based on the Hebrew
|
|
Packit |
95306a |
calendar.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
As a result, there is no way to specify a simple rule to define
|
|
Packit |
95306a |
time zone changes for all years in the future. As such, this module
|
|
Packit |
95306a |
supports all time zone changes currently specified in the zoneinfo
|
|
Packit |
95306a |
database (which currently goes to the year 2037) but does not attempt
|
|
Packit |
95306a |
to correctly handle zone changes beyond that date. As a result,
|
|
Packit |
95306a |
Date::Manip should not be used to parse dates in the Jerusalem
|
|
Packit |
95306a |
time zone that are far enough in the future that information is not
|
|
Packit |
95306a |
included in the current version of the zoneinfo database.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
=item B<LMT and zzz abbreviations>
|
|
Packit |
95306a |
|
|
Packit |
95306a |
Both the LMT and zzz abbreviations are used in the zoneinfo databases.
|
|
Packit |
95306a |
LMT is use for most time zones for the times before the Gregorian
|
|
Packit |
95306a |
calendar was adopted, and zzz is used for a few where the time zone was
|
|
Packit |
95306a |
created and no description of dates prior to that are supported. Both
|
|
Packit |
95306a |
LMT and zzz are basically ignored in parsing dates (because there is
|
|
Packit |
95306a |
no reasonable way to determine which zone they are referring to), and
|
|
Packit |
95306a |
will be treated as the local time zone regardless.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
=back
|
|
Packit |
95306a |
|
|
Packit |
95306a |
=head1 KNOWN BUGS
|
|
Packit |
95306a |
|
|
Packit |
95306a |
None known.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
=head1 BUGS AND QUESTIONS
|
|
Packit |
95306a |
|
|
Packit |
95306a |
Please refer to the Date::Manip::Problems documentation for
|
|
Packit |
95306a |
information on submitting bug reports or questions to the author.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
=head1 SEE ALSO
|
|
Packit |
95306a |
|
|
Packit |
95306a |
Date::Manip - main module documentation
|
|
Packit |
95306a |
|
|
Packit |
95306a |
=head1 LICENSE
|
|
Packit |
95306a |
|
|
Packit |
95306a |
This script is free software; you can redistribute it and/or
|
|
Packit |
95306a |
modify it under the same terms as Perl itself.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
=head1 AUTHOR
|
|
Packit |
95306a |
|
|
Packit |
95306a |
Sullivan Beck (sbeck@cpan.org)
|
|
Packit |
95306a |
|
|
Packit |
95306a |
=cut
|