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

NAME

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

VERSION

9       version 2.39
10

SYNOPSIS

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

DESCRIPTION

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
25       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
29   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
34       If you are on HPUX, install DateTime::TimeZone::HPUX. This provides
35       support for HPUX style time zones like 'MET-1METDST'.
36

USAGE

38       This class has the following methods:
39
40   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
46       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
50       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
57       There are also several special values that can be given as names.
58
59       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
67       If the "name" parameter is "UTC", then a "DateTime::TimeZone::UTC"
68       object is returned.
69
70       If the "name" is an offset string, it is converted to a number, and a
71       "DateTime::TimeZone::OffsetOnly" object is returned.
72
73       The "local" time zone
74
75       If the "name" parameter is "local", then the module attempts to
76       determine the local time zone for the system.
77
78       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
82       ·   DateTime::TimeZone::Local::Unix
83
84       ·   DateTime::TimeZone::Local::Android
85
86       ·   DateTime::TimeZone::Local::hpux
87
88       ·   DateTime::TimeZone::Local::Win32
89
90       ·   DateTime::TimeZone::Local::VMS
91
92       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
96       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
100       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
105   $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
111   $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
118   $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
122   $tz->name
123       Returns the name of the time zone.
124
125   $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
130       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
136   $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
141   $tz->is_utc
142       Indicates whether or not this object represents the UTC (GMT) time
143       zone.
144
145   $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
149   $tz->is_olson
150       Returns true if the time zone is a named time zone from the Olson
151       database.
152
153   $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
157   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
162   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
167   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
171   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
176   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
183   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
188       If you need to convert country codes to names or vice versa you can use
189       "Locale::Country" to do so. Note that one of the codes returned is
190       "uk", which is an alias for the country code "gb", and is not a valid
191       ISO country code.
192
193   DateTime::TimeZone->names_in_country( $country_code )
194       Given a two-letter ISO3166 country code, this method returns a list of
195       time zones used in that country. The country code may be of any case.
196       In scalar context, it returns an array reference, while in list context
197       it returns an array.
198
199       This list is returned in an order vaguely based on geography and
200       population. In general, the least used zones come last, but there are
201       not guarantees of a specific order from one release to the next. This
202       order is probably the best option for presenting zones names to end
203       users.
204
205   DateTime::TimeZone->offset_as_seconds( $offset )
206       Given an offset as a string, this returns the number of seconds
207       represented by the offset as a positive or negative number.  Returns
208       "undef" if $offset is not in the range "-99:59:59" to "+99:59:59".
209
210       The offset is expected to match either
211       "/^([\+\-])?(\d\d?):(\d\d)(?::(\d\d))?$/" or
212       "/^([\+\-])?(\d\d)(\d\d)(\d\d)?$/".  If it doesn't match either of
213       these, "undef" will be returned.
214
215       This means that if you want to specify hours as a single digit, then
216       each element of the offset must be separated by a colon (:).
217
218   DateTime::TimeZone->offset_as_string( $offset )
219       Given an offset as a number, this returns the offset as a string.
220       Returns "undef" if $offset is not in the range "-359999" to 359999.
221
222   Storable Hooks
223       This module provides freeze and thaw hooks for "Storable" so that the
224       huge data structures for Olson time zones are not actually stored in
225       the serialized structure.
226
227       If you subclass "DateTime::TimeZone", you will inherit its hooks, which
228       may not work for your module, so please test the interaction of your
229       module with Storable.
230

LOADING TIME ZONES IN A PRE-FORKING SYSTEM

232       If you are running an application that does pre-forking (for example
233       with Starman), then you should try to load all the time zones that
234       you'll need in the parent process. Time zones are loaded on-demand, so
235       loading them once in each child will waste memory that could otherwise
236       be shared.
237

CREDITS

239       This module was inspired by Jesse Vincent's work on
240       Date::ICal::Timezone, and written with much help from the
241       datetime@perl.org list.
242

SEE ALSO

244       datetime@perl.org mailing list
245
246       http://datetime.perl.org/
247
248       The tools directory of the DateTime::TimeZone distribution includes two
249       scripts that may be of interest to some people.  They are parse_olson
250       and tests_from_zdump.  Please run them with the --help flag to see what
251       they can be used for.
252

SUPPORT

254       Support for this module is provided via the datetime@perl.org email
255       list. See http://datetime.perl.org/wiki/datetime/page/Mailing_List for
256       details.
257
258       Please submit bugs to the CPAN RT system at
259       http://rt.cpan.org/NoAuth/ReportBug.html?Queue=datetime%3A%3Atimezone
260       or via email at bug-datetime-timezone@rt.cpan.org.
261
262       Bugs may be submitted at
263       <https://github.com/houseabsolute/DateTime-TimeZone/issues>.
264
265       I am also usually active on IRC as 'autarch' on "irc://irc.perl.org".
266

SOURCE

268       The source code repository for DateTime-TimeZone can be found at
269       <https://github.com/houseabsolute/DateTime-TimeZone>.
270

DONATIONS

272       If you'd like to thank me for the work I've done on this module, please
273       consider making a "donation" to me via PayPal. I spend a lot of free
274       time creating free software, and would appreciate any support you'd
275       care to offer.
276
277       Please note that I am not suggesting that you must do this in order for
278       me to continue working on this particular software. I will continue to
279       do so, inasmuch as I have in the past, for as long as it interests me.
280
281       Similarly, a donation made in this way will probably not make me work
282       on this software much more, unless I get so many donations that I can
283       consider working on free software full time (let's all have a chuckle
284       at that together).
285
286       To donate, log into PayPal and send money to autarch@urth.org, or use
287       the button at <https://www.urth.org/fs-donation.html>.
288

AUTHOR

290       Dave Rolsky <autarch@urth.org>
291

CONTRIBUTORS

293       ·   Alexey Molchanov <alexey.molchanov@gmail.com>
294
295       ·   Alfie John <alfiej@fastmail.fm>
296
297       ·   Andrew Paprocki <apaprocki@bloomberg.net>
298
299       ·   Bron Gondwana <brong@fastmail.fm>
300
301       ·   Daisuke Maki <dmaki@cpan.org>
302
303       ·   David Pinkowitz <dave@pinkowitz.com>
304
305       ·   Iain Truskett <deceased>
306
307       ·   Jakub Wilk <jwilk@jwilk.net>
308
309       ·   James E Keenan <jkeenan@cpan.org>
310
311       ·   Joshua Hoblitt <jhoblitt@cpan.org>
312
313       ·   Karen Etheridge <ether@cpan.org>
314
315       ·   karupanerura <karupa@cpan.org>
316
317       ·   kclaggett <kclaggett@proofpoint.com>
318
319       ·   Mohammad S Anwar <mohammad.anwar@yahoo.com>
320
321       ·   Olaf Alders <olaf@wundersolutions.com>
322
323       ·   Peter Rabbitson <ribasushi@cpan.org>
324
325       ·   Tom Wyant <wyant@cpan.org>
326
328       This software is copyright (c) 2020 by Dave Rolsky.
329
330       This is free software; you can redistribute it and/or modify it under
331       the same terms as the Perl 5 programming language system itself.
332
333       The full text of the license can be found in the LICENSE file included
334       with this distribution.
335
336
337
338perl v5.30.2                      2020-04-27             DateTime::TimeZone(3)
Impressum