1DateTime::TimeZone(3) User Contributed Perl DocumentationDateTime::TimeZone(3)
2
6 DateTime::TimeZone - Time zone object base class and factory
7
9 version 2.38
10
12 use DateTime;
13 use DateTime::TimeZone;
14 my $tz = DateTime::TimeZone->new( name => 'America/Chicago' );
16 my $dt = DateTime->now();
18 my $offset = $tz->offset_for_datetime($dt);
19
21 This class is the base class for all time zone objects. A time zone is
22 represented internally as a set of observances, each of which describes
23 the offset from GMT for a given time period.
24 Note that without the DateTime module, this module does not do much.
26 It's primary interface is through a DateTime object, and most users
27 will not need to directly use "DateTime::TimeZone" methods.
28 Special Case Platforms
30 If you are on the Win32 platform, you will want to also install
31 DateTime::TimeZone::Local::Win32. This will enable you to specify a
32 time zone of 'local' when creating a DateTime object.
33 If you are on HPUX, install DateTime::TimeZone::HPUX. This provides
35 support for HPUX style time zones like 'MET-1METDST'.
36
38 This class has the following methods:
39 DateTime::TimeZone->new( name => $tz_name )
41 Given a valid time zone name, this method returns a new time zone
42 blessed into the appropriate subclass. Subclasses are named for the
43 given time zone, so that the time zone "America/Chicago" is the
44 DateTime::TimeZone::America::Chicago class.
45 If the name given is a "link" name in the Olson database, the object
47 created may have a different name. For example, there is a link from
48 the old "EST5EDT" name to "America/New_York".
49 When loading a time zone from the Olson database, the constructor
51 checks the version of the loaded class to make sure it matches the
52 version of the current DateTime::TimeZone installation. If they do not
53 match it will issue a warning. This is useful because time zone names
54 may fall out of use, but you may have an old module file installed for
55 that time zone.
56 There are also several special values that can be given as names.
58 If the "name" parameter is "floating", then a
60 "DateTime::TimeZone::Floating" object is returned. A floating time
61 zone does not have any offset, and is always the same time. This is
62 useful for calendaring applications, which may need to specify that a
63 given event happens at the same local time, regardless of where it
64 occurs. See RFC 2445 <https://www.ietf.org/rfc/rfc2445.txt> for more
65 details.
66 If the "name" parameter is "UTC", then a "DateTime::TimeZone::UTC"
68 object is returned.
69 If the "name" is an offset string, it is converted to a number, and a
71 "DateTime::TimeZone::OffsetOnly" object is returned.
72 The "local" time zone
74 If the "name" parameter is "local", then the module attempts to
76 determine the local time zone for the system.
77 The method for finding the local zone varies by operating system. See
79 the appropriate module for details of how we check for the local time
80 zone.
81 · DateTime::TimeZone::Local::Unix
83 · DateTime::TimeZone::Local::Android
85 · DateTime::TimeZone::Local::hpux
87 · DateTime::TimeZone::Local::Win32
89 · DateTime::TimeZone::Local::VMS
91 If a local time zone is not found, then an exception will be thrown.
93 This exception will always stringify to something containing the text
94 "Cannot determine local time zone".
95 If you are writing code for users to run on systems you do not control,
97 you should try to account for the possibility that this exception may
98 be thrown. Falling back to UTC might be a reasonable alternative.
99 When writing tests for your modules that might be run on others'
101 systems, you are strongly encouraged to either not use "local" when
102 creating DateTime objects or to set $ENV{TZ} to a known value in your
103 test code. All of the per-OS classes check this environment variable.
104 $tz->offset_for_datetime( $dt )
106 Given a "DateTime" object, this method returns the offset in seconds
107 for the given datetime. This takes into account historical time zone
108 information, as well as Daylight Saving Time. The offset is determined
109 by looking at the object's UTC Rata Die days and seconds.
110 $tz->offset_for_local_datetime( $dt )
112 Given a "DateTime" object, this method returns the offset in seconds
113 for the given datetime. Unlike the previous method, this method uses
114 the local time's Rata Die days and seconds. This should only be done
115 when the corresponding UTC time is not yet known, because local times
116 can be ambiguous due to Daylight Saving Time rules.
117 $tz->is_dst_for_datetime( $dt )
119 Given a "DateTime" object, this method returns true if the DateTime is
120 currently in Daylight Saving Time.
121 $tz->name
123 Returns the name of the time zone.
124 $tz->short_name_for_datetime( $dt )
126 Given a "DateTime" object, this method returns the "short name" for the
127 current observance and rule this datetime is in. These are names like
128 "EST", "GMT", etc.
129 It is strongly recommended that you do not rely on these names for
131 anything other than display. These names are not official, and many of
132 them are simply the invention of the Olson database maintainers.
133 Moreover, these names are not unique. For example, there is an "EST"
134 at both -0500 and +1000/+1100.
135 $tz->is_floating
137 Returns a boolean indicating whether or not this object represents a
138 floating time zone, as defined by RFC 2445
139 <https://www.ietf.org/rfc/rfc2445.txt>.
140 $tz->is_utc
142 Indicates whether or not this object represents the UTC (GMT) time
143 zone.
144 $tz->has_dst_changes
146 Indicates whether or not this zone has ever had a change to and from
147 DST, either in the past or future.
148 $tz->is_olson
150 Returns true if the time zone is a named time zone from the Olson
151 database.
152 $tz->category
154 Returns the part of the time zone name before the first slash. For
155 example, the "America/Chicago" time zone would return "America".
156 DateTime::TimeZone->is_valid_name($name)
158 Given a string, this method returns a boolean value indicating whether
159 or not the string is a valid time zone name. If you are using
160 "DateTime::TimeZone::Alias", any aliases you've created will be valid.
161 DateTime::TimeZone->all_names
163 This returns a pre-sorted list of all the time zone names. This list
164 does not include link names. In scalar context, it returns an array
165 reference, while in list context it returns an array.
166 DateTime::TimeZone->categories
168 This returns a list of all time zone categories. In scalar context, it
169 returns an array reference, while in list context it returns an array.
170 DateTime::TimeZone->links
172 This returns a hash of all time zone links, where the keys are the old,
173 deprecated names, and the values are the new names. In scalar context,
174 it returns a hash reference, while in list context it returns a hash.
175 DateTime::TimeZone->names_in_category( $category )
177 Given a valid category, this method returns a list of the names in that
178 category, without the category portion. So the list for the "America"
179 category would include the strings "Chicago", "Kentucky/Monticello",
180 and "New_York". In scalar context, it returns an array reference, while
181 in list context it returns an array.
182 DateTime::TimeZone->countries()
184 Returns a sorted list of all the valid country codes (in lower-case)
185 which can be passed to "names_in_country()". In scalar context, it
186 returns an array reference, while in list context it returns an array.
187 If you need to convert country codes to names or vice versa you can use
189 "Locale::Country" to do so.
190 DateTime::TimeZone->names_in_country( $country_code )
192 Given a two-letter ISO3166 country code, this method returns a list of
193 time zones used in that country. The country code may be of any case.
194 In scalar context, it returns an array reference, while in list context
195 it returns an array.
196 This list is returned in an order vaguely based on geography and
198 population. In general, the least used zones come last, but there are
199 not guarantees of a specific order from one release to the next. This
200 order is probably the best option for presenting zones names to end
201 users.
202 DateTime::TimeZone->offset_as_seconds( $offset )
204 Given an offset as a string, this returns the number of seconds
205 represented by the offset as a positive or negative number. Returns
206 "undef" if $offset is not in the range "-99:59:59" to "+99:59:59".
207 The offset is expected to match either
209 "/^([\+\-])?(\d\d?):(\d\d)(?::(\d\d))?$/" or
210 "/^([\+\-])?(\d\d)(\d\d)(\d\d)?$/". If it doesn't match either of
211 these, "undef" will be returned.
212 This means that if you want to specify hours as a single digit, then
214 each element of the offset must be separated by a colon (:).
215 DateTime::TimeZone->offset_as_string( $offset )
217 Given an offset as a number, this returns the offset as a string.
218 Returns "undef" if $offset is not in the range "-359999" to 359999.
219 Storable Hooks
221 This module provides freeze and thaw hooks for "Storable" so that the
222 huge data structures for Olson time zones are not actually stored in
223 the serialized structure.
224 If you subclass "DateTime::TimeZone", you will inherit its hooks, which
226 may not work for your module, so please test the interaction of your
227 module with Storable.
228
230 If you are running an application that does pre-forking (for example
231 with Starman), then you should try to load all the time zones that
232 you'll need in the parent process. Time zones are loaded on-demand, so
233 loading them once in each child will waste memory that could otherwise
234 be shared.
235
237 This module was inspired by Jesse Vincent's work on
238 Date::ICal::Timezone, and written with much help from the
239 datetime@perl.org list.
240
242 datetime@perl.org mailing list
243 http://datetime.perl.org/
245 The tools directory of the DateTime::TimeZone distribution includes two
247 scripts that may be of interest to some people. They are parse_olson
248 and tests_from_zdump. Please run them with the --help flag to see what
249 they can be used for.
250
252 Support for this module is provided via the datetime@perl.org email
253 list. See http://datetime.perl.org/wiki/datetime/page/Mailing_List for
254 details.
255 Please submit bugs to the CPAN RT system at
257 http://rt.cpan.org/NoAuth/ReportBug.html?Queue=datetime%3A%3Atimezone
258 or via email at bug-datetime-timezone@rt.cpan.org.
259 Bugs may be submitted at
261 <https://github.com/houseabsolute/DateTime-TimeZone/issues>.
262 I am also usually active on IRC as 'autarch' on "irc://irc.perl.org".
264
266 The source code repository for DateTime-TimeZone can be found at
267 <https://github.com/houseabsolute/DateTime-TimeZone>.
268
270 If you'd like to thank me for the work I've done on this module, please
271 consider making a "donation" to me via PayPal. I spend a lot of free
272 time creating free software, and would appreciate any support you'd
273 care to offer.
274 Please note that I am not suggesting that you must do this in order for
276 me to continue working on this particular software. I will continue to
277 do so, inasmuch as I have in the past, for as long as it interests me.
278 Similarly, a donation made in this way will probably not make me work
280 on this software much more, unless I get so many donations that I can
281 consider working on free software full time (let's all have a chuckle
282 at that together).
283 To donate, log into PayPal and send money to autarch@urth.org, or use
285 the button at <http://www.urth.org/~autarch/fs-donation.html>.
286
288 Dave Rolsky <autarch@urth.org>
289
291 · Alexey Molchanov <alexey.molchanov@gmail.com>
292 · Alfie John <alfiej@fastmail.fm>
294 · Andrew Paprocki <apaprocki@bloomberg.net>
296 · Bron Gondwana <brong@fastmail.fm>
298 · Daisuke Maki <dmaki@cpan.org>
300 · David Pinkowitz <dave@pinkowitz.com>
302 · Iain Truskett <deceased>
304 · Jakub Wilk <jwilk@jwilk.net>
306 · James E Keenan <jkeenan@cpan.org>
308 · Joshua Hoblitt <jhoblitt@cpan.org>
310 · Karen Etheridge <ether@cpan.org>
312 · karupanerura <karupa@cpan.org>
314 · kclaggett <kclaggett@proofpoint.com>
316 · Mohammad S Anwar <mohammad.anwar@yahoo.com>
318 · Olaf Alders <olaf@wundersolutions.com>
320 · Peter Rabbitson <ribasushi@cpan.org>
322 · Tom Wyant <wyant@cpan.org>
324
326 This software is copyright (c) 2019 by Dave Rolsky.
327 This is free software; you can redistribute it and/or modify it under
329 the same terms as the Perl 5 programming language system itself.
330 The full text of the license can be found in the LICENSE file included
332 with this distribution.
333perl v5.30.1 2019-11-18 DateTime::TimeZone(3)