DateTime::TimeZone(3pm)

1DateTime::TimeZone(3) User Contributed Perl DocumentationDateTime::TimeZone(3)
2
3
4

NAME

6       DateTime::TimeZone - Time zone object base class and factory
7

SYNOPSIS

9         use DateTime;
10         use DateTime::TimeZone;
11
12         my $tz = DateTime::TimeZone->new( name => 'America/Chicago' );
13
14         my $dt = DateTime->now();
15         my $offset = $tz->offset_for_datetime($dt);
16

DESCRIPTION

18       This class is the base class for all time zone objects.  A time zone is
19       represented internally as a set of observances, each of which describes
20       the offset from GMT for a given time period.
21
22       Note that without the "DateTime.pm" module, this module does not do
23       much.  It's primary interface is through a "DateTime" object, and most
24       users will not need to directly use "DateTime::TimeZone" methods.
25

USAGE

27       This class has the following methods:
28
29       DateTime::TimeZone->new( name => $tz_name )
30
31       Given a valid time zone name, this method returns a new time zone
32       blessed into the appropriate subclass.  Subclasses are named for the
33       given time zone, so that the time zone "America/Chicago" is the Date‐
34       Time::TimeZone::America::Chicago class.
35
36       If the name given is a "link" name in the Olson database, the object
37       created may have a different name.  For example, there is a link from
38       the old "EST5EDT" name to "America/New_York".
39
40       There are also several special values that can be given as names.
41
42       If the "name" parameter is "floating", then a "DateTime::Time‐
43       Zone::Floating" object is returned.  A floating time zone does have any
44       offset, and is always the same time.  This is useful for calendaring
45       applications, which may need to specify that a given event happens at
46       the same local time, regardless of where it occurs.  See RFC 2445 for
47       more details.
48
49       If the "name" parameter is "UTC", then a "DateTime::TimeZone::UTC"
50       object is returned.
51
52       If the "name" is an offset string, it is converted to a number, and a
53       "DateTime::TimeZone::OffsetOnly" object is returned.
54
55       The "local" time zone
56
57       If the "name" parameter is "local", then the module attempts to deter‐
58       mine the local time zone for the system.
59
60       First it checks $ENV for keys named "TZ", "SYS$TIMEZONE_RULE",
61       "SYS$TIMEZONE_NAME", "UCX$TZ", or "TCPIP$TZC" (the last 4 are for VMS).
62       If this is defined, and it is not the string "local", then it is
63       treated as any other valid name (including "floating"), and the con‐
64       structor tries to create a time zone based on that name.
65
66       Next, it checks for the existence of a symlink at /etc/localtime.  It
67       follows this link to the real file and figures out what the file's name
68       is.  It then tries to turn this name into a valid time zone.  For exam‐
69       ple, if this file is linked to /usr/share/zoneinfo/US/Central, it will
70       end up trying "US/Central", which will then be converted to "Amer‐
71       ica/Chicago" internally.
72
73       Some systems just copy the relevant file to /etc/localtime instead of
74       making a symlink.  In this case, we look in /usr/share/zoneinfo for a
75       file that has the same size and content as /etc/localtime to determine
76       the local time zone.
77
78       Then it checks for a file called /etc/timezone or /etc/TIMEZONE.  If
79       one of these exists, it is read and it tries to create a time zone with
80       the name contained in the file.
81
82       Finally, it checks for a file called /etc/sysconfig/clock.  If this
83       file exists, it looks for a line inside the file matching
84       "/^(?:TIME)?ZONE="([^"]+)"/".  If this line exists, it tries the value
85       as a time zone name.
86
87       If none of these methods work, it gives up and dies.
88
89       $tz->offset_for_datetime( $dt )
90
91       Given a "DateTime" object, this method returns the offset in seconds
92       for the given datetime.  This takes into account historical time zone
93       information, as well as Daylight Saving Time.  The offset is determined
94       by looking at the object's UTC Rata Die days and seconds.
95
96       $tz->offset_for_local_datetime( $dt )
97
98       Given a "DateTime" object, this method returns the offset in seconds
99       for the given datetime.  Unlike the previous method, this method uses
100       the local time's Rata Die days and seconds.  This should only be done
101       when the corresponding UTC time is not yet known, because local times
102       can be ambiguous due to Daylight Saving Time rules.
103
104       $tz->name
105
106       Returns the name of the time zone.  If this value is passed to the
107       "new()" method, it is guaranteed to create the same object.
108
109       $tz->short_name_for_datetime( $dt )
110
111       Given a "DateTime" object, this method returns the "short name" for the
112       current observance and rule this datetime is in.  These are names like
113       "EST", "GMT", etc.
114
115       It is strongly recommended that you do not rely on these names for any‐
116       thing other than display.  These names are not official, and many of
117       them are simply the invention of the Olson database maintainers.  More‐
118       over, these names are not unique.  For example, there is an "EST" at
119       both -0500 and +1000/+1100.
120
121       $tz->is_floating
122
123       Returns a boolean indicating whether or not this object represents a
124       floating time zone, as defined by RFC 2445.
125
126       $tz->is_utc
127
128       Indicates whether or not this object represents the UTC (GMT) time
129       zone.
130
131       $tz->has_dst_changes
132
133       Indicates whether or not this zone has ever had a change to and from
134       DST, either in the past or future.
135
136       $tz->is_olson
137
138       Returns true if the time zone is a named time zone from the Olson data‐
139       base.
140
141       $tz->category
142
143       Returns the part of the time zone name before the first slash.  For
144       example, the "America/Chicago" time zone would return "America".
145
146       DateTime::TimeZone->is_valid_name($name)
147
148       Given a string, this method returns a boolean value indicating whether
149       or not the string is a valid time zone name.  If you are using "Date‐
150       Time::TimeZone::Alias", any aliases you've created will be valid.
151
152       DateTime::TimeZone->all_names
153
154       This returns a pre-sorted list of all the time zone names.  This list
155       does not include link names.  In scalar context, it returns an array
156       reference, while in list context it returns an array.
157
158       DateTime::TimeZone->categories
159
160       This returns a list of all time zone categories.  In scalar context, it
161       returns an array reference, while in list context it returns an array.
162
163       DateTime::TimeZone->links
164
165       This returns a hash of all time zone links, where the keys are the old,
166       deprecated names, and the values are the new names.  In scalar context,
167       it returns a hash reference, while in list context it returns a hash.
168
169       DateTime::TimeZone->names_in_category( $category )
170
171       Given a valid category, this method returns a list of the names in that
172       category, without the category portion.  So the list for the "America"
173       category would include the strings "Chicago", "Kentucky/Monticello",
174       and "New_York". In scalar context, it returns an array reference, while
175       in list context it returns an array.
176
177       The list is returned in order of population by zone, which should mean
178       that this order will be the best to use for most UIs.
179
180       DateTime::TimeZone->countries()
181
182       Returns a sorted list of all the valid country codes (in lower-case)
183       which can be passed to "names_in_country()". In scalar context, it
184       returns an array reference, while in list context it returns an array.
185
186       If you need to convert country codes to names or vice versa you can use
187       "Locale::Country" to do so.
188
189       DateTime::TimeZone->names_in_country( $country_code )
190
191       Given a two-letter ISO3066 country code, this method returns a list of
192       time zones used in that country. The country code may be of any case.
193       In scalar context, it returns an array reference, while in list context
194       it returns an array.
195
196       DateTime::TimeZone->offset_as_seconds( $offset )
197
198       Given an offset as a string, this returns the number of seconds repre‐
199       sented by the offset as a positive or negative number.  Returns "undef"
200       if $offset is not in the range "-99:59:59" to "+99:59:59".
201
202       The offset is expected to match either
203       "/^([\+\-])?(\d\d?):(\d\d)(?::(\d\d))?$/" or
204       "/^([\+\-])?(\d\d)(\d\d)(\d\d)?$/".  If it doesn't match either of
205       these, "undef" will be returned.
206
207       This means that if you want to specify hours as a single digit, then
208       each element of the offset must be separated by a colon (:).
209
210       DateTime::TimeZone->offset_as_string( $offset )
211
212       Given an offset as a number, this returns the offset as a string.
213       Returns "undef" if $offset is not in the range "-359999" to 359999.
214
215       Storable Hooks
216
217       This module provides freeze and thaw hooks for "Storable" so that the
218       huge data structures for Olson time zones are not actually stored in
219       the serialized structure.
220
221       If you subclass "DateTime::TimeZone", you will inherit its hooks, which
222       may not work for your module, so please test the interaction of your
223       module with Storable.
224

SUPPORT

226       Support for this module is provided via the datetime@perl.org email
227       list.  See http://lists.perl.org/ for more details.
228
229       Please submit bugs to the CPAN RT system at
230       http://rt.cpan.org/NoAuth/ReportBug.html?Queue=datetime%3A%3Atimezone
231       or via email at bug-datetime-timezone@rt.cpan.org.
232

AUTHOR

234       Dave Rolsky <autarch@urth.org>
235

CREDITS

237       This module was inspired by Jesse Vincent's work on Date::ICal::Time‐
238       zone, and written with much help from the datetime@perl.org list.
239

COPYRIGHT

241       Copyright (c) 2003-2007 David Rolsky.  All rights reserved.  This pro‐
242       gram is free software; you can redistribute it and/or modify it under
243       the same terms as Perl itself.
244
245       The full text of the license can be found in the LICENSE file included
246       with this module.
247