1DateTime::TimeZone(3) User Contributed Perl DocumentationDateTime::TimeZone(3)
2
3
4
6 DateTime::TimeZone - Time zone object base class and factory
7
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
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
27 This class has the following methods:
28
29 DateTime::TimeZone->new( name => $tz_name )
30 Given a valid time zone name, this method returns a new time zone
31 blessed into the appropriate subclass. Subclasses are named for the
32 given time zone, so that the time zone "America/Chicago" is the
33 DateTime::TimeZone::America::Chicago class.
34
35 If the name given is a "link" name in the Olson database, the object
36 created may have a different name. For example, there is a link from
37 the old "EST5EDT" name to "America/New_York".
38
39 When loading a time zone from the Olson database, the constructor
40 checks the version of the loaded class to make sure it matches the
41 version of the current DateTime::TimeZone installation. If they do not
42 match it will issue a warning. This is useful because time zone names
43 may fall out of use, but you may have an old module file installed for
44 that time zone.
45
46 There are also several special values that can be given as names.
47
48 If the "name" parameter is "floating", then a
49 "DateTime::TimeZone::Floating" object is returned. A floating time
50 zone does have any offset, and is always the same time. This is useful
51 for calendaring applications, which may need to specify that a given
52 event happens at the same local time, regardless of where it occurs.
53 See RFC 2445 for more details.
54
55 If the "name" parameter is "UTC", then a "DateTime::TimeZone::UTC"
56 object is returned.
57
58 If the "name" is an offset string, it is converted to a number, and a
59 "DateTime::TimeZone::OffsetOnly" object is returned.
60
61 The "local" time zone
62
63 If the "name" parameter is "local", then the module attempts to
64 determine the local time zone for the system.
65
66 The method for finding the local zone varies by operating system. See
67 the appropriate module for details of how we check for the local time
68 zone.
69
70 · DateTime::TimeZone::Local::Unix
71
72 · DateTime::TimeZone::Local::Win32
73
74 · DateTime::TimeZone::Local::VMS
75
76 If a local time zone is not found, then an exception will be thrown.
77
78 $tz->offset_for_datetime( $dt )
79 Given a "DateTime" object, this method returns the offset in seconds
80 for the given datetime. This takes into account historical time zone
81 information, as well as Daylight Saving Time. The offset is determined
82 by looking at the object's UTC Rata Die days and seconds.
83
84 $tz->offset_for_local_datetime( $dt )
85 Given a "DateTime" object, this method returns the offset in seconds
86 for the given datetime. Unlike the previous method, this method uses
87 the local time's Rata Die days and seconds. This should only be done
88 when the corresponding UTC time is not yet known, because local times
89 can be ambiguous due to Daylight Saving Time rules.
90
91 $tz->name
92 Returns the name of the time zone. If this value is passed to the
93 "new()" method, it is guaranteed to create the same object.
94
95 $tz->short_name_for_datetime( $dt )
96 Given a "DateTime" object, this method returns the "short name" for the
97 current observance and rule this datetime is in. These are names like
98 "EST", "GMT", etc.
99
100 It is strongly recommended that you do not rely on these names for
101 anything other than display. These names are not official, and many of
102 them are simply the invention of the Olson database maintainers.
103 Moreover, these names are not unique. For example, there is an "EST"
104 at both -0500 and +1000/+1100.
105
106 $tz->is_floating
107 Returns a boolean indicating whether or not this object represents a
108 floating time zone, as defined by RFC 2445.
109
110 $tz->is_utc
111 Indicates whether or not this object represents the UTC (GMT) time
112 zone.
113
114 $tz->has_dst_changes
115 Indicates whether or not this zone has ever had a change to and from
116 DST, either in the past or future.
117
118 $tz->is_olson
119 Returns true if the time zone is a named time zone from the Olson
120 database.
121
122 $tz->category
123 Returns the part of the time zone name before the first slash. For
124 example, the "America/Chicago" time zone would return "America".
125
126 DateTime::TimeZone->is_valid_name($name)
127 Given a string, this method returns a boolean value indicating whether
128 or not the string is a valid time zone name. If you are using
129 "DateTime::TimeZone::Alias", any aliases you've created will be valid.
130
131 DateTime::TimeZone->all_names
132 This returns a pre-sorted list of all the time zone names. This list
133 does not include link names. In scalar context, it returns an array
134 reference, while in list context it returns an array.
135
136 DateTime::TimeZone->categories
137 This returns a list of all time zone categories. In scalar context, it
138 returns an array reference, while in list context it returns an array.
139
140 DateTime::TimeZone->links
141 This returns a hash of all time zone links, where the keys are the old,
142 deprecated names, and the values are the new names. In scalar context,
143 it returns a hash reference, while in list context it returns a hash.
144
145 DateTime::TimeZone->names_in_category( $category )
146 Given a valid category, this method returns a list of the names in that
147 category, without the category portion. So the list for the "America"
148 category would include the strings "Chicago", "Kentucky/Monticello",
149 and "New_York". In scalar context, it returns an array reference, while
150 in list context it returns an array.
151
152 The list is returned in order of population by zone, which should mean
153 that this order will be the best to use for most UIs.
154
155 DateTime::TimeZone->countries()
156 Returns a sorted list of all the valid country codes (in lower-case)
157 which can be passed to "names_in_country()". In scalar context, it
158 returns an array reference, while in list context it returns an array.
159
160 If you need to convert country codes to names or vice versa you can use
161 "Locale::Country" to do so.
162
163 DateTime::TimeZone->names_in_country( $country_code )
164 Given a two-letter ISO3166 country code, this method returns a list of
165 time zones used in that country. The country code may be of any case.
166 In scalar context, it returns an array reference, while in list context
167 it returns an array.
168
169 DateTime::TimeZone->offset_as_seconds( $offset )
170 Given an offset as a string, this returns the number of seconds
171 represented by the offset as a positive or negative number. Returns
172 "undef" if $offset is not in the range "-99:59:59" to "+99:59:59".
173
174 The offset is expected to match either
175 "/^([\+\-])?(\d\d?):(\d\d)(?::(\d\d))?$/" or
176 "/^([\+\-])?(\d\d)(\d\d)(\d\d)?$/". If it doesn't match either of
177 these, "undef" will be returned.
178
179 This means that if you want to specify hours as a single digit, then
180 each element of the offset must be separated by a colon (:).
181
182 DateTime::TimeZone->offset_as_string( $offset )
183 Given an offset as a number, this returns the offset as a string.
184 Returns "undef" if $offset is not in the range "-359999" to 359999.
185
186 Storable Hooks
187 This module provides freeze and thaw hooks for "Storable" so that the
188 huge data structures for Olson time zones are not actually stored in
189 the serialized structure.
190
191 If you subclass "DateTime::TimeZone", you will inherit its hooks, which
192 may not work for your module, so please test the interaction of your
193 module with Storable.
194
196 Support for this module is provided via the datetime@perl.org email
197 list. See http://datetime.perl.org/?MailingList for details.
198
199 Please submit bugs to the CPAN RT system at
200 http://rt.cpan.org/NoAuth/ReportBug.html?Queue=datetime%3A%3Atimezone
201 or via email at bug-datetime-timezone@rt.cpan.org.
202
204 If you'd like to thank me for the work I've done on this module, please
205 consider making a "donation" to me via PayPal. I spend a lot of free
206 time creating free software, and would appreciate any support you'd
207 care to offer.
208
209 Please note that I am not suggesting that you must do this in order for
210 me to continue working on this particular software. I will continue to
211 do so, inasmuch as I have in the past, for as long as it interests me.
212
213 Similarly, a donation made in this way will probably not make me work
214 on this software much more, unless I get so many donations that I can
215 consider working on free software full time, which seems unlikely at
216 best.
217
218 To donate, log into PayPal and send money to autarch@urth.org or use
219 the button on this page:
220 <http://www.urth.org/~autarch/fs-donation.html>
221
223 Dave Rolsky <autarch@urth.org>
224
226 This module was inspired by Jesse Vincent's work on
227 Date::ICal::Timezone, and written with much help from the
228 datetime@perl.org list.
229
231 Copyright (c) 2003-2008 David Rolsky. All rights reserved. This
232 program is free software; you can redistribute it and/or modify it
233 under the same terms as Perl itself.
234
235 The full text of the license can be found in the LICENSE file included
236 with this module.
237
239 datetime@perl.org mailing list
240
241 http://datetime.perl.org/
242
243 The tools directory of the DateTime::TimeZone distribution includes two
244 scripts that may be of interest to some people. They are parse_olson
245 and tests_from_zdump. Please run them with the --help flag to see what
246 they can be used for.
247
248
249
250perl v5.10.1 2017-03-21 DateTime::TimeZone(3)