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