local-lib5/man/man3/DateTime::TimeZone.3pm

   1 .\" Automatically generated by Pod::Man 2.22 (Pod::Simple 3.10)
   2 .\"
   3 .\" Standard preamble:
   4 .\" ========================================================================
   5 .de Sp \" Vertical space (when we can't use .PP)
   6 .if t .sp .5v
   7 .if n .sp
   8 ..
   9 .de Vb \" Begin verbatim text
  10 .ft CW
  11 .nf
  12 .ne \\$1
  13 ..
  14 .de Ve \" End verbatim text
  15 .ft R
  16 .fi
  17 ..
  18 .\" Set up some character translations and predefined strings.  \*(-- will
  19 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  20 .\" double quote, and \*(R" will give a right double quote.  \*(C+ will
  21 .\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
  22 .\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
  23 .\" nothing in troff, for use with C<>.
  24 .tr \(*W-
  25 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  26 .ie n \{\
  27 .    ds -- \(*W-
  28 .    ds PI pi
  29 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  30 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  31 .    ds L" ""
  32 .    ds R" ""
  33 .    ds C` ""
  34 .    ds C' ""
  35 'br\}
  36 .el\{\
  37 .    ds -- \|\(em\|
  38 .    ds PI \(*p
  39 .    ds L" ``
  40 .    ds R" ''
  41 'br\}
  42 .\"
  43 .\" Escape single quotes in literal strings from groff's Unicode transform.
  44 .ie \n(.g .ds Aq \(aq
  45 .el       .ds Aq '
  46 .\"
  47 .\" If the F register is turned on, we'll generate index entries on stderr for
  48 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
  49 .\" entries marked with X<> in POD.  Of course, you'll have to process the
  50 .\" output yourself in some meaningful fashion.
  51 .ie \nF \{\
  52 .    de IX
  53 .    tm Index:\\$1\t\\n%\t"\\$2"
  54 ..
  55 .    nr % 0
  56 .    rr F
  57 .\}
  58 .el \{\
  59 .    de IX
  60 ..
  61 .\}
  62 .\"
  63 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  64 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  65 .    \" fudge factors for nroff and troff
  66 .if n \{\
  67 .    ds #H 0
  68 .    ds #V .8m
  69 .    ds #F .3m
  70 .    ds #[ \f1
  71 .    ds #] \fP
  72 .\}
  73 .if t \{\
  74 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  75 .    ds #V .6m
  76 .    ds #F 0
  77 .    ds #[ \&
  78 .    ds #] \&
  79 .\}
  80 .    \" simple accents for nroff and troff
  81 .if n \{\
  82 .    ds ' \&
  83 .    ds ` \&
  84 .    ds ^ \&
  85 .    ds , \&
  86 .    ds ~ ~
  87 .    ds /
  88 .\}
  89 .if t \{\
  90 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
  91 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
  92 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
  93 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
  94 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
  95 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
  96 .\}
  97 .    \" troff and (daisy-wheel) nroff accents
  98 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
  99 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 100 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 101 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 102 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 103 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 104 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 105 .ds ae a\h'-(\w'a'u*4/10)'e
 106 .ds Ae A\h'-(\w'A'u*4/10)'E
 107 .    \" corrections for vroff
 108 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 109 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 110 .    \" for low resolution devices (crt and lpr)
 111 .if \n(.H>23 .if \n(.V>19 \
 112 \{\
 113 .    ds : e
 114 .    ds 8 ss
 115 .    ds o a
 116 .    ds d- d\h'-1'\(ga
 117 .    ds D- D\h'-1'\(hy
 118 .    ds th \o'bp'
 119 .    ds Th \o'LP'
 120 .    ds ae ae
 121 .    ds Ae AE
 122 .\}
 123 .rm #[ #] #H #V #F C
 124 .\" ========================================================================
 125 .\"
 126 .IX Title "DateTime::TimeZone 3"
 127 .TH DateTime::TimeZone 3 "2009-11-16" "perl v5.8.7" "User Contributed Perl Documentation"
 128 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
 129 .\" way too many mistakes in technical documents.
 130 .if n .ad l
 131 .nh
 132 .SH "NAME"
 133 DateTime::TimeZone \- Time zone object base class and factory
 134 .SH "SYNOPSIS"
 135 .IX Header "SYNOPSIS"
 136 .Vb 2
 137 \&  use DateTime;
 138 \&  use DateTime::TimeZone;
 139 \&
 140 \&  my $tz = DateTime::TimeZone\->new( name => \*(AqAmerica/Chicago\*(Aq );
 141 \&
 142 \&  my $dt = DateTime\->now();
 143 \&  my $offset = $tz\->offset_for_datetime($dt);
 144 .Ve
 145 .SH "DESCRIPTION"
 146 .IX Header "DESCRIPTION"
 147 This class is the base class for all time zone objects.  A time zone
 148 is represented internally as a set of observances, each of which
 149 describes the offset from \s-1GMT\s0 for a given time period.
 150 .PP
 151 Note that without the \f(CW\*(C`DateTime.pm\*(C'\fR module, this module does not do
 152 much.  It's primary interface is through a \f(CW\*(C`DateTime\*(C'\fR object, and
 153 most users will not need to directly use \f(CW\*(C`DateTime::TimeZone\*(C'\fR
 154 methods.
 155 .SH "USAGE"
 156 .IX Header "USAGE"
 157 This class has the following methods:
 158 .ie n .SS "DateTime::TimeZone\->new( name => $tz_name )"
 159 .el .SS "DateTime::TimeZone\->new( name => \f(CW$tz_name\fP )"
 160 .IX Subsection "DateTime::TimeZone->new( name => $tz_name )"
 161 Given a valid time zone name, this method returns a new time zone
 162 blessed into the appropriate subclass.  Subclasses are named for the
 163 given time zone, so that the time zone \*(L"America/Chicago\*(R" is the
 164 DateTime::TimeZone::America::Chicago class.
 165 .PP
 166 If the name given is a \*(L"link\*(R" name in the Olson database, the object
 167 created may have a different name.  For example, there is a link from
 168 the old \*(L"\s-1EST5EDT\s0\*(R" name to \*(L"America/New_York\*(R".
 169 .PP
 170 When loading a time zone from the Olson database, the constructor
 171 checks the version of the loaded class to make sure it matches the
 172 version of the current DateTime::TimeZone installation. If they do not
 173 match it will issue a warning. This is useful because time zone names
 174 may fall out of use, but you may have an old module file installed for
 175 that time zone.
 176 .PP
 177 There are also several special values that can be given as names.
 178 .PP
 179 If the \*(L"name\*(R" parameter is \*(L"floating\*(R", then a
 180 \&\f(CW\*(C`DateTime::TimeZone::Floating\*(C'\fR object is returned.  A floating time
 181 zone does have \fIany\fR offset, and is always the same time.  This is
 182 useful for calendaring applications, which may need to specify that a
 183 given event happens at the same \fIlocal\fR time, regardless of where it
 184 occurs.  See \s-1RFC\s0 2445 for more details.
 185 .PP
 186 If the \*(L"name\*(R" parameter is \*(L"\s-1UTC\s0\*(R", then a \f(CW\*(C`DateTime::TimeZone::UTC\*(C'\fR
 187 object is returned.
 188 .PP
 189 If the \*(L"name\*(R" is an offset string, it is converted to a number, and a
 190 \&\f(CW\*(C`DateTime::TimeZone::OffsetOnly\*(C'\fR object is returned.
 191 .PP
 192 \fIThe \*(L"local\*(R" time zone\fR
 193 .IX Subsection "The local time zone"
 194 .PP
 195 If the \*(L"name\*(R" parameter is \*(L"local\*(R", then the module attempts to
 196 determine the local time zone for the system.
 197 .PP
 198 The method for finding the local zone varies by operating system. See
 199 the appropriate module for details of how we check for the local time
 200 zone.
 201 .IP "\(bu" 4
 202 DateTime::TimeZone::Local::Unix
 203 .IP "\(bu" 4
 204 DateTime::TimeZone::Local::Win32
 205 .IP "\(bu" 4
 206 DateTime::TimeZone::Local::VMS
 207 .PP
 208 If a local time zone is not found, then an exception will be thrown.
 209 .ie n .SS "$tz\->offset_for_datetime( $dt )"
 210 .el .SS "\f(CW$tz\fP\->offset_for_datetime( \f(CW$dt\fP )"
 211 .IX Subsection "$tz->offset_for_datetime( $dt )"
 212 Given a \f(CW\*(C`DateTime\*(C'\fR object, this method returns the offset in seconds
 213 for the given datetime.  This takes into account historical time zone
 214 information, as well as Daylight Saving Time.  The offset is
 215 determined by looking at the object's \s-1UTC\s0 Rata Die days and seconds.
 216 .ie n .SS "$tz\->offset_for_local_datetime( $dt )"
 217 .el .SS "\f(CW$tz\fP\->offset_for_local_datetime( \f(CW$dt\fP )"
 218 .IX Subsection "$tz->offset_for_local_datetime( $dt )"
 219 Given a \f(CW\*(C`DateTime\*(C'\fR object, this method returns the offset in seconds
 220 for the given datetime.  Unlike the previous method, this method uses
 221 the local time's Rata Die days and seconds.  This should only be done
 222 when the corresponding \s-1UTC\s0 time is not yet known, because local times
 223 can be ambiguous due to Daylight Saving Time rules.
 224 .ie n .SS "$tz\->name"
 225 .el .SS "\f(CW$tz\fP\->name"
 226 .IX Subsection "$tz->name"
 227 Returns the name of the time zone.  If this value is passed to the
 228 \&\f(CW\*(C`new()\*(C'\fR method, it is guaranteed to create the same object.
 229 .ie n .SS "$tz\->short_name_for_datetime( $dt )"
 230 .el .SS "\f(CW$tz\fP\->short_name_for_datetime( \f(CW$dt\fP )"
 231 .IX Subsection "$tz->short_name_for_datetime( $dt )"
 232 Given a \f(CW\*(C`DateTime\*(C'\fR object, this method returns the \*(L"short name\*(R" for
 233 the current observance and rule this datetime is in.  These are names
 234 like \*(L"\s-1EST\s0\*(R", \*(L"\s-1GMT\s0\*(R", etc.
 235 .PP
 236 It is \fBstrongly\fR recommended that you do not rely on these names for
 237 anything other than display.  These names are not official, and many
 238 of them are simply the invention of the Olson database maintainers.
 239 Moreover, these names are not unique.  For example, there is an \*(L"\s-1EST\s0\*(R"
 240 at both \-0500 and +1000/+1100.
 241 .ie n .SS "$tz\->is_floating"
 242 .el .SS "\f(CW$tz\fP\->is_floating"
 243 .IX Subsection "$tz->is_floating"
 244 Returns a boolean indicating whether or not this object represents a
 245 floating time zone, as defined by \s-1RFC\s0 2445.
 246 .ie n .SS "$tz\->is_utc"
 247 .el .SS "\f(CW$tz\fP\->is_utc"
 248 .IX Subsection "$tz->is_utc"
 249 Indicates whether or not this object represents the \s-1UTC\s0 (\s-1GMT\s0) time
 250 zone.
 251 .ie n .SS "$tz\->has_dst_changes"
 252 .el .SS "\f(CW$tz\fP\->has_dst_changes"
 253 .IX Subsection "$tz->has_dst_changes"
 254 Indicates whether or not this zone has \fIever\fR had a change to and
 255 from \s-1DST\s0, either in the past or future.
 256 .ie n .SS "$tz\->is_olson"
 257 .el .SS "\f(CW$tz\fP\->is_olson"
 258 .IX Subsection "$tz->is_olson"
 259 Returns true if the time zone is a named time zone from the Olson
 260 database.
 261 .ie n .SS "$tz\->category"
 262 .el .SS "\f(CW$tz\fP\->category"
 263 .IX Subsection "$tz->category"
 264 Returns the part of the time zone name before the first slash.  For
 265 example, the \*(L"America/Chicago\*(R" time zone would return \*(L"America\*(R".
 266 .SS "DateTime::TimeZone\->is_valid_name($name)"
 267 .IX Subsection "DateTime::TimeZone->is_valid_name($name)"
 268 Given a string, this method returns a boolean value indicating whether
 269 or not the string is a valid time zone name.  If you are using
 270 \&\f(CW\*(C`DateTime::TimeZone::Alias\*(C'\fR, any aliases you've created will be valid.
 271 .SS "DateTime::TimeZone\->all_names"
 272 .IX Subsection "DateTime::TimeZone->all_names"
 273 This returns a pre-sorted list of all the time zone names.  This list
 274 does not include link names.  In scalar context, it returns an array
 275 reference, while in list context it returns an array.
 276 .SS "DateTime::TimeZone\->categories"
 277 .IX Subsection "DateTime::TimeZone->categories"
 278 This returns a list of all time zone categories.  In scalar context,
 279 it returns an array reference, while in list context it returns an
 280 array.
 281 .SS "DateTime::TimeZone\->links"
 282 .IX Subsection "DateTime::TimeZone->links"
 283 This returns a hash of all time zone links, where the keys are the
 284 old, deprecated names, and the values are the new names.  In scalar
 285 context, it returns a hash reference, while in list context it returns
 286 a hash.
 287 .ie n .SS "DateTime::TimeZone\->names_in_category( $category )"
 288 .el .SS "DateTime::TimeZone\->names_in_category( \f(CW$category\fP )"
 289 .IX Subsection "DateTime::TimeZone->names_in_category( $category )"
 290 Given a valid category, this method returns a list of the names in
 291 that category, without the category portion.  So the list for the
 292 \&\*(L"America\*(R" category would include the strings \*(L"Chicago\*(R",
 293 \&\*(L"Kentucky/Monticello\*(R", and \*(L"New_York\*(R". In scalar context, it returns
 294 an array reference, while in list context it returns an array.
 295 .PP
 296 The list is returned in order of population by zone, which should mean
 297 that this order will be the best to use for most UIs.
 298 .SS "DateTime::TimeZone\->\fIcountries()\fP"
 299 .IX Subsection "DateTime::TimeZone->countries()"
 300 Returns a sorted list of all the valid country codes (in lower-case)
 301 which can be passed to \f(CW\*(C`names_in_country()\*(C'\fR. In scalar context, it
 302 returns an array reference, while in list context it returns an array.
 303 .PP
 304 If you need to convert country codes to names or vice versa you can
 305 use \f(CW\*(C`Locale::Country\*(C'\fR to do so.
 306 .ie n .SS "DateTime::TimeZone\->names_in_country( $country_code )"
 307 .el .SS "DateTime::TimeZone\->names_in_country( \f(CW$country_code\fP )"
 308 .IX Subsection "DateTime::TimeZone->names_in_country( $country_code )"
 309 Given a two-letter \s-1ISO3166\s0 country code, this method returns a list of
 310 time zones used in that country. The country code may be of any
 311 case. In scalar context, it returns an array reference, while in list
 312 context it returns an array.
 313 .ie n .SS "DateTime::TimeZone\->offset_as_seconds( $offset )"
 314 .el .SS "DateTime::TimeZone\->offset_as_seconds( \f(CW$offset\fP )"
 315 .IX Subsection "DateTime::TimeZone->offset_as_seconds( $offset )"
 316 Given an offset as a string, this returns the number of seconds
 317 represented by the offset as a positive or negative number.  Returns
 318 \&\f(CW\*(C`undef\*(C'\fR if \f(CW$offset\fR is not in the range \f(CW\*(C`\-99:59:59\*(C'\fR to \f(CW\*(C`+99:59:59\*(C'\fR.
 319 .PP
 320 The offset is expected to match either
 321 \&\f(CW\*(C`/^([\e+\e\-])?(\ed\ed?):(\ed\ed)(?::(\ed\ed))?$/\*(C'\fR or
 322 \&\f(CW\*(C`/^([\e+\e\-])?(\ed\ed)(\ed\ed)(\ed\ed)?$/\*(C'\fR.  If it doesn't match either of
 323 these, \f(CW\*(C`undef\*(C'\fR will be returned.
 324 .PP
 325 This means that if you want to specify hours as a single digit, then
 326 each element of the offset must be separated by a colon (:).
 327 .ie n .SS "DateTime::TimeZone\->offset_as_string( $offset )"
 328 .el .SS "DateTime::TimeZone\->offset_as_string( \f(CW$offset\fP )"
 329 .IX Subsection "DateTime::TimeZone->offset_as_string( $offset )"
 330 Given an offset as a number, this returns the offset as a string.
 331 Returns \f(CW\*(C`undef\*(C'\fR if \f(CW$offset\fR is not in the range \f(CW\*(C`\-359999\*(C'\fR to \f(CW359999\fR.
 332 .SS "Storable Hooks"
 333 .IX Subsection "Storable Hooks"
 334 This module provides freeze and thaw hooks for \f(CW\*(C`Storable\*(C'\fR so that the
 335 huge data structures for Olson time zones are not actually stored in
 336 the serialized structure.
 337 .PP
 338 If you subclass \f(CW\*(C`DateTime::TimeZone\*(C'\fR, you will inherit its hooks,
 339 which may not work for your module, so please test the interaction of
 340 your module with Storable.
 341 .SH "SUPPORT"
 342 .IX Header "SUPPORT"
 343 Support for this module is provided via the datetime@perl.org email
 344 list. See http://datetime.perl.org/?MailingList for details.
 345 .PP
 346 Please submit bugs to the \s-1CPAN\s0 \s-1RT\s0 system at
 347 http://rt.cpan.org/NoAuth/ReportBug.html?Queue=datetime%3A%3Atimezone
 348 or via email at bug\-datetime\-timezone@rt.cpan.org.
 349 .SH "DONATIONS"
 350 .IX Header "DONATIONS"
 351 If you'd like to thank me for the work I've done on this module,
 352 please consider making a \*(L"donation\*(R" to me via PayPal. I spend a lot of
 353 free time creating free software, and would appreciate any support
 354 you'd care to offer.
 355 .PP
 356 Please note that \fBI am not suggesting that you must do this\fR in order
 357 for me to continue working on this particular software. I will
 358 continue to do so, inasmuch as I have in the past, for as long as it
 359 interests me.
 360 .PP
 361 Similarly, a donation made in this way will probably not make me work
 362 on this software much more, unless I get so many donations that I can
 363 consider working on free software full time, which seems unlikely at
 364 best.
 365 .PP
 366 To donate, log into PayPal and send money to autarch@urth.org or use
 367 the button on this page:
 368 <http://www.urth.org/~autarch/fs\-donation.html>
 369 .SH "AUTHOR"
 370 .IX Header "AUTHOR"
 371 Dave Rolsky <autarch@urth.org>
 372 .SH "CREDITS"
 373 .IX Header "CREDITS"
 374 This module was inspired by Jesse Vincent's work on
 375 Date::ICal::Timezone, and written with much help from the
 376 datetime@perl.org list.
 377 .SH "COPYRIGHT"
 378 .IX Header "COPYRIGHT"
 379 Copyright (c) 2003\-2008 David Rolsky.  All rights reserved.  This
 380 program is free software; you can redistribute it and/or modify it
 381 under the same terms as Perl itself.
 382 .PP
 383 The full text of the license can be found in the \s-1LICENSE\s0 file included
 384 with this module.
 385 .SH "SEE ALSO"
 386 .IX Header "SEE ALSO"
 387 datetime@perl.org mailing list
 388 .PP
 389 http://datetime.perl.org/
 390 .PP
 391 The tools directory of the DateTime::TimeZone distribution includes
 392 two scripts that may be of interest to some people.  They are
 393 parse_olson and tests_from_zdump.  Please run them with the \-\-help
 394 flag to see what they can be used for.