1Date::Manip::TZ(3) User Contributed Perl Documentation Date::Manip::TZ(3)
2
6 Date::Manip::TZ - an interface to the time zone data
7
9 use Date::Manip::TZ;
10 $tz = new Date::Manip::TZ;
11 Data for most (and hopefully all) time zones used around the world have
13 been gathered and is publicly available in the zoneinfo (or Olson)
14 database.
15 This module uses the data from the zoneinfo database to perform various
17 time zone operations.
18
20 Every time zone has some of the following characteristics:
21 name
23 Every time zone has a unique name. In the zoneinfo database, these
24 are something similar to:
25 America/New_York
27 aliases
29 Time zones may have (but are not required to have) one or more
30 aliases. Each alias is unique, and is not the same as any time
31 zone name. An alias can be used in exactly the same way as a name.
32 periods
34 Every time zone is broken up into periods. Each period describes
35 how a portion of time relates to GMT, and how it might be
36 expressed.
37 Each period includes the following information:
39 start time, end time
41 The period begin and ends at certain times. The times are included
42 both as an absolute GMT time, and as a wallclock time. The
43 wallclock start time is the time that will be on a clock just as
44 the period starts (i.e. after a time change). The wallclock end
45 time is the time on a clock immediately before the period ends.
46 offset
48 The entire period has an offset which is how much the wallclock
49 time differs from GMT.
50 abbreviation
52 When expressing the time period, an abbreviation (such as EST) is
53 typically used.
54 daylight saving time flag
56 Every period is categorized as a standard time or a daylight saving
57 time. The flag will be 1 if it is a daylight saving time, or 0 if
58 it is a standard time.
59 Date::Manip includes all of the data for all of the time zones from the
61 zoneinfo database. This data is available from:
62 ftp://elsie.nci.nih.gov/pub/
64 Additional data from other standards are also used.
66 The zoneinfo database is not necessary in order to use Date::Manip.
68 Instead, all of that data has been extracted and stored in a series of
69 other modules which are used to handle each time zone. In that way,
70 Date::Manip has no dependency on any other source of data.
71 The Date::Manip::Zones document contains detailed information on the
73 data available.
74
76 In all methods, the following variables are used:
77 $zone
79 This is a string which contains a valid time zone name. For
80 example:
81 America/New_York
83 $alias
85 This is a strings which contains a valid time zone name, or a valid
86 time zone alias. For example:
87 America/New_York
89 US/Eastern
90 EST5EDT
91 $abbrev
93 This is a string which contains a valid time zone abbreviation. For
94 example:
95 EST
97 $offset
99 This is a time zone entered as an offset. An offset is either a
100 string of one of the formats:
101 +HH
103 +HHMM
104 +HHMMSS
105 +HH:MM
106 +HH:MM:SS
107 or it can be a list reference:
109 [HH,MM,SS]
111 If a list reference is used, the sign must be included with all
113 values. So, the offset "-05:30" would be the list reference:
114 [-5,-30,0]
116 $dstflag
118 This is always one of the values: std, stdonly, dst, dstonly
119 It defaults to stdonly if it is not present. When determining a
121 time zone, it is usually necessary to check a number of different
122 time zone and DST combinations.
123 If $dstflag is "std", it will check both standard and daylight
125 saving times, but will give preference to standard times. If
126 $dstflag is "stdonly", only standard times will be checked.
127 The "dst" and "dstonly" values are similar but will check daylight
129 saving times in preference.
130 $date
132 A date is always a string containing a date in one of the formats:
133 YYYYMMDDHH:MN:SS
135 YYYY-MM-DD-HH:MN:SS
136 YYYYMMDDHHMNSS
137 or a list reference:
139 [Y,M,D,H,MN,S]
141 $isdst
143 This is 0 if a date is in standard time, 1 if it is in daylight
144 saving time.
145 $period
147 A period is a list reference currently containing the following
148 items:
149 [ $dateUT, $dateLT, $offsetstr, $offset, $abbrev, $isdst,
151 $endUT, $endLT, $begUTs, $begLTs, $endUTs, $endLTs ]
152 $dateUT and $dateLT are the starting date of the period (i.e. the
154 first second in a period) in universal (GMT) time and local
155 (wallclock) time. $endUT and $endLT are the end date of the period
156 (i.e. the last second in a period) in universal and local time.
157 These are all stored as list references.
158 $offsetstr is the string representation of the offset ("+05:00:00")
160 and $offset is the corresponding list reference form ([5,0,0]).
161 $abbrev is the abbreviation that applies during this period, and
163 $isdst is 0 or 1 if it is standard or daylight saving time.
164 When accessing the elements in a period, use ONLY positive indices.
166 In other words, to get $endUT, access it as $$period[6], NOT as
167 $$period[-2], since I am looking at adding more information to the
168 period description that may speed up performance.
169 $begUTs is the string representation (YYYYMMDDHH:MN:SS) of $begUT.
171 Similar for $begLTs, $endUTs, and $endLTs.
172 The following methods are available:
174 base
176 config
177 err
178 new
179 new_config
180 Please refer to the Date::Manip::Obj documentation for these
181 methods.
182 all_periods
184 @periods = $tz->all_periods($zone,$year);
185 This returns the description of all time zone periods that occur
187 (in full or in part) during the given year.
188 convert
190 convert_to_gmt
191 convert_from_gmt
192 convert_to_local
193 convert_from_local
194 These functions convert a date from one time zone to another.
195 ($err,$date,$offset,$isdst,$abbrev) =
197 $tz->convert($date,$from,$to [,$isdst]);
198 This converts a date in the time zone given by $from to the time
200 zone given by $to.
201 ($err,$date,$offset,$isdst,$abbrev) =
203 $tz->convert_to_gmt($date [,$from] [,$isdst]);
204 This converts a date to GMT. If $from is given, it is the current
206 time zone of the date. If $from is omitted, it defaults to the
207 local time zone.
208 The value of $isdst returned is always 0.
210 ($err,$date,$offset,$isdst,$abbrev) =
212 $tz->convert_from_gmt($date [,$to]);
213 This converts a date from GMT to another time zone. If $to is
215 given, the date is converted to that time zone. Otherwise, it is
216 converted to the local time zone.
217 ($err,$date,$offset,$isdst,$abbrev) =
219 $tz->convert_to_local($date [,$from] [,$isdst]);
220 ($err,$date,$offset,$isdst,$abbrev) =
221 $tz->convert_from_local($date [,$to] [,$isdst]);
222 Similar to the convert_to_gmt and convert_from_gmt functions. If
224 $from or $to are omitted, they default to GMT.
225 If there is any ambiguity about whether $date is in DST or not
227 (i.e. if it is a date that is repeated during a time change due to
228 the clock being moved back), the $isdst option can be passed in as
229 an argument (it should be 0 or 1) to say which time to use. It is
230 ignored in all cases where $date can be determined without that
231 information.
232 The $isdst value passed back is 1 if the converted date is in DST.
234 The $offset value passed back is a list reference containing the
235 offset from GMT. $abbrev passed back is the time zone abbreviation.
236 Error codes are:
238 0 No error
240 1 Invalid arguments
241 2 Invalid FROM zone
242 3 Invalid TO zone
243 4 Invalid date
244 curr_zone
246 $tz->curr_zone();
247 This returns the system time zone. The system time zone is
249 determined using the methods described below in the DETERMINING THE
250 SYSTEM TIME ZONE section.
251 This is the time zone that is used by default unless the SetDate or
253 ForceDate config variable is set to a different zone.
254 $tz->curr_zone(1);
256 This clears the system time zone and re-determines it using the
258 methods described below.
259 The main reason to do this is if the curr_zone_methods method is
261 used to change how the time zone is determined.
262 curr_zone_methods
264 $tz->curr_zone_methods(@methods);
265 This sets the list and order of methods to use in determining the
267 local time zone. The various methods available are listed below in
268 the section DETERMINING THE SYSTEM TIME ZONE.
269 Some methods may require one or more arguments. For example, the
271 method named "mainvar" takes an option that is the name of a
272 variable. The arguments must be included in the @methods list
273 immediately after the method name (so @methods is actually a
274 mixture of method names and arguments).
275 This method may not be used in any environment where taint checking
277 is enabled. If it is, it will issue a warning, but will NOT change
278 the method list.
279 date_period
281 $period = $tz->date_period($date,$zone,$wallclock [,$isdst]);
282 This returns the period information for the given date. $date
284 defaults to GMT, but may be given as local (i.e. wallclock) time if
285 $wallclock is non-zero. The period information is described in the
286 periods method below.
287 If a wallclock time is given, no period is returned if the
289 wallclock time doesn't ever appear (such as when a time change
290 results in the clock moving forward "skipping" a period of time).
291 If the wallclock time appears twice (i.e. when a time change
292 results in the clock being set back), the $isdst variable is used.
293 The standard time is used unless $isdst is non-zero. $isdst is
294 ignored except in the case where there are two possible periods.
295 define_abbrev
297 ($err,$val) = $tz->define_abbrev($abbrev,@zone);
298 When encountering an abbreviation, by default, all time zones which
300 ever include the abbreviation will be examine in the order given in
301 the Date::Manip::Zones manual.
302 Occasionally, it may be necessary to change the order. This is true
304 if you are parsing dates in a time zone which uses an abbreviation
305 which is also used in another time zone, and where the other time
306 zone is given preference. As an example, the abbreviation "ADT"
307 will default to the "Atlantic/Bermuda" time zone. If you are in the
308 "America/Halifax" time zone (which also uses that abbreviation),
309 you may want to change the order of time zones.
310 This will take an abbreviation (which must be a known
312 abbreviation... there is no means of defining a totally new
313 abbreviation) and a list of zones. This will set the list of zones
314 that will be checked, and the order in which they are checked, when
315 a date is encountered with the given abbreviation. It is not
316 necessary that the list include every zone that has ever used the
317 abbreviation, but it may not include a zone that has never used it.
318 If $abbrev is "reset", all abbreviations are reset to the standard
320 values. If @zone includes only the element 'reset', the default
321 list for $abbrev is restored.
322 The following error codes are returned:
324 0 No error
326 1 $abbrev is not a valid abbreviation in any time zone
327 2 A zone (returned as $val) is not a valid time zone
328 3 A zone (returned as $val) does not use the abbreviation
329 For more information about the different zones which may correspond
331 to each abbreviation, and the order in which they will be examined
332 by default, refer to the Date::Manip::Zones manual.
333 define_alias
335 $err = $tz->define_alias($alias,$zone);
336 This will define a new alias (or override an existing alias). $zone
338 must be a valid zone or an error is returned.
339 For more information about the different aliases which are set by
341 default, refer to the Date::Manip::Zones manual.
342 If $alias is "reset", all aliases will be reset to the standard
344 values. If $zone is "reset", $alias will be reset to the standard
345 value.
346 define_offset
348 ($err,$val) = $tz->define_offset($offset, [$dstflag,] @zone);
349 This is similar to the define_abbrev method. When an offset is
351 encountered, all time zones which have ever included that offset
352 are checked. This will defined which time zones, and in what order,
353 they should be checked.
354 The zones to both standard and daylight saving times which include
356 the offset (if $dstflag is "std" or "dst") or to only one or the
357 other.
358 If $offset is "reset", all lists are reset to the default values.
360 If @zone includes only the element 'reset', the default list and
361 order is restored for $offset ($dstflag must not be given).
362 The following error codes are returned:
364 0 No error
366 1 $offset is not a valid offset in any time zone
367 2 $offset is not a valid offset in the selected
368 time (if doing "dstonly" or "stdonly")
369 3 A zone (returned as $val) is not a valid time zone
370 4 A zone (returned as $val) does not use the offset
371 5 A zone (returned as $val) does not include the
372 offset in the selected time (if doing "dstonly"
373 or "stdonly")
374 9 Offset is not a valid offset
376 periods
378 @periods = $tz->periods($zone,$year);
379 This returns the description of all time zone periods that begin
381 during the year given. The year is measured in universal (GMT)
382 time.
383 If no time zone period starts in the given year, nothing is
385 returned.
386 @periods = $tz->periods($zone,undef,$year);
388 This returns all periods that begin in any year from 0001 to $year.
390 @periods = $tz->periods($zone,$year0,$year1);
392 This returns all periods that begin in any year from 0001 to $year.
394 tzdata
396 tzcode
397 $vers = $tz->tzdata();
398 $vers = $tz->tzcode();
399 These return the versions of the tzdata and tzcode packages used to
401 generate the modules.
402 zone
404 $zone = $tz->zone(@args);
405 @zone = $tz->zone(@args);
406 This function will return a list of all zones, or the default zone,
408 which matches all of the supplied information. In scalar context,
409 it will return only the default zone. In list context, it will
410 return all zones.
411 @args may include any of the following items, and the order is not
413 important.
414 A zone name or alias ($alias)
416 A zone abbreviation ($abbrev)
418 An offset ($offset)
420 A dstflag ($dstflag)
422 A date ($date)
424 It is NOT valid to include two of any of the items. Any time zone
426 returned will match all of the data supplied.
427 If an error occurs, undef is returned. If no zone matches, an empty
429 string, or an empty list is returned.
430 The order of the zones will be determined in the following way:
432 If $abbrev is given, the order of time zones will be determined by
434 it (and $dstflag). If $dstflag is "std", all zones which match
435 $abbrev in standard time are included, followed by all that match
436 $abbrev in saving time (but no duplication is allowed). The reverse
437 is true if $dstflag is "dst".
438 If $abbrev is not given, but $offset is, $offset (and $dstflag)
440 will determine the order given. If $dstflag is "std", all zones
441 which match $offset in standard time are included, followed by all
442 that match $offset in saving time (but no duplication is allowed).
443 The reverse is true if $dstflag is "dst".
444 If $date is given, only zones in which $date will appear in a zone
446 that matches all other information are given. $date is a wallclock
447 time.
448 If no $zone, $abbrev, or $offset are entered, the local time zone
450 may be returned (unless $date is entered, and it doesn't exist in
451 the local time zone).
452
454 Date::Manip makes use of three potentially different time zones when
455 working with a date.
456 The first time zone that may be used is the actual local time zone.
458 This is the time zone that the computer is actually running in.
459 The second time zone is the working time zone. Usually, you will want
461 the default time zone to be the local time zone, but occasionally, you
462 may want the default time zone to be different.
463 The third time zone is the actual time zone that was parsed, or set,
465 for a date. If a date contains no time zone information, it will
466 default to the working time zone.
467 The local time zone is determined using the methods described in the
469 following section. The preferred way is to locate the time zone in some
470 system file, or using some system command, or (in the case of a Windows
471 operating system) to look it up in the registry. If all of these
472 methods fail, the local time zone may be set using either the $::TZ or
473 $ENV{TZ} variables. Please note that these should ONLY be used to set
474 the actual local time zone.
475 If you are running in one time zone, but you want to force dates to be
477 specified in an alternate time zone by default, you need to set the
478 working time zone. The working time zone defaults to the local time
479 zone, but this can be changed using either the SetDate or ForceDate
480 config variables. Refer to the Date::Manip::Config manual for more
481 information.
482 Finally, when a date is actually parsed, if it contains any time zone
484 information, the date is stored in that time zone.
485
487 There are a large number of ways available for determining the time
488 zone. Some or all of them may be checked. A list of methods to use is
489 provided by default, and may be overridden by the curr_zone_methods
490 function described above. To override the default order and/or list of
491 methods, just pass in a list of method names (with arguments where
492 necessary), and only those methods will be done, and in the order
493 given.
494 The following methods are available:
496 Method Argument(s) Procedure
498 ====== =========== =========
499 main VAR The main variable named VAR is
501 checked. E.g. "main TZ" checks
502 the variable $::TZ .
503 env VAR The named environment variable
505 is checked.
506 file FILE Look in the given file for any
508 one of the following case
509 insensitive lines:
510 ZONE
511 tz = ZONE
512 zone = ZONE
513 timezone = ZONE
514 ZONE may be quoted (single or
515 double) and whitespace is
516 ignored. If the entire line
517 is a zone, it must be the first
518 non-blank non-comment line in
519 the file.
520 command COMMAND Runs a command which produces
522 a time zone as the output.
523 cmdfield COMMAND N Runs a command which produces
525 whitespace separated fields,
526 the Nth one containing the
527 time zone (fields are numbered
528 starting at 0, or from the
529 end starting at -1).
530 gmtoff Uses the current offset from
532 GMT to come up with a best guess.
533 registry Look up the value in the
535 Windows registry. This is only
536 available to hosts running a
537 Windows operating system.
538 Note that the "main" and "env" methods should only be used to specify
540 the actual time zone the system is running in. Use the SetDate and
541 ForceDate config variables to specify an alternate time zone that you
542 want to work in.
543 By default, the following methods are checked (in the order given) on
545 Unix systems:
546 main TZ
548 env TZ
549 file /etc/TIMEZONE
550 file /etc/timezone
551 file /etc/sysconfig/clock
552 file /etc/default/init
553 command "/bin/date +%Z"
554 command "/usr/bin/date +%Z"
555 command "/usr/local/bin/date +%Z"
556 cmdfield /bin/date -2
557 cmdfield /usr/bin/date -2
558 cmdfield /usr/local/bin/date -2
559 gmtoff
560 The default methods for Windows systems are:
562 main TZ
564 env TZ
565 registry
566 gmtoff
567 The default methods for VMS systems are:
569 main TZ
571 env TZ
572 env SYS$TIMEZONE_RULE
573 env SYS$TIMEZONE_NAME
574 env UCX$TZ
575 env TCPIP$TZ
576 env MULTINET_TIMEZONE
577 env SYS$TIMEZONE_DIFFERENTIAL
578 gmtoff
579 The default methods for all other systems are:
581 main TZ
583 env TZ
584 gmtoff
585 If anyone wants better support for a specific OS, please contact me and
587 we'll coordinate adding it.
588 In all cases, the value returned from the method may be any of the
590 following:
591 the full name of a time zone (e.g. America/New_York)
593 or an alias
594 an abbreviation (e.g. EDT) which will be used to
596 determine the zone if possible
597 an offset (+hh, +hhmn, +hh:mm, +hh:mm:ss) from GMT
599 The Date::Manip::Zones module contains information about the time zones
601 and aliases available, and what time zones contain the abbreviations.
602
604 The design decisions made in writing this module may cause some
605 questions (and probably complaints). The time zone modules are all
606 generated using scripts (included in the Date::Manip distribution)
607 which use the standard tzdata tools to parse the tzdata files and store
608 that information in perl modules.
609 I'd like to address some of them, to avoid answering some of the "why
611 did you do it that way" remarks. I do welcome discussion about these
612 decisions... but preferably after you understand why those decisions
613 were made so that that we have an informed basis to begin a discussion.
614 Why not use existing zoneinfo files
616 Some people will probably think that I should have written an
617 interface to the zoneinfo files which are distributed with most
618 operating systems. Although I considered doing that, I rejected
619 the idea for two reasons.
620 First, not all operating systems come with the zoneinfo databases
622 in a user accessible state (Micro$oft for example). Even those
623 that do include them store the information in various formats and
624 locations. In order to bypass all that, I have included the data
625 directly in these modules.
626 Second, as I was doing my initial investigations into this, I ran
628 into a bug in the Solaris zoneinfo tools (long since fixed I'm
629 sure). I decided then that I didn't want to depend on an
630 implementation where I could not control and fix the bugs.
631 Why not use the native tzdata files
633 Another decision people may question is that I parse the tzdata
634 files and store the data from them in a large number of perl
635 modules instead of creating an interface to the tzdata files
636 directly. This was done solely for the sake of speed. Date::Manip
637 is already a slow module. I didn't want to slow it down further by
638 doing the complex parsing required to interpret the tzdata files
639 while manipulating dates. By storing the data in these modules,
640 there is little or no parsing done while using Date::Manip modules.
641 It costs a little disk space to store this information... but very
642 little of it is actually loaded at runtime (time zone data is only
643 loaded when the time zone is actually referred to), so I feel it's
644 a good tradeoff.
645 Why store the information in so many files
647 The data from the native tzdata files are parsed and stored in two
648 sets of modules. These include almost 500 Date::Manip::Offset::*
649 modules and almost 450 Date::Manip::TZ::* modules.
650 I note that on my linux box, /usr/share/zoneinfo (which contains
652 data files generated from the tzdata files) contains over 1700
653 files, so I'm not doing anything "new" by breaking up the
654 information into separate files. And doing so has a huge impact on
655 performance... it is not necessary to load and/or manipulate data
656 from time zones which are not in use.
657 The minute I made the decision to distribute the timezone
659 information myself, as opposed to using the system version, it was
660 a given that there would be a lot of files.
661 These modules are loaded only when the time zone or offset is
663 actually used, so, unless dates from around the world are being
664 parsed, only a very small number of these modules will actually be
665 loaded. In many applications, only a single TZ module will be
666 loaded. If parsing dates which have timezone information stored as
667 offsets, one or two Offset modules will also be loaded.
668 The disk space seems excessive
670 Currently, the disk usage of the perl files is around 9 MB. Total
671 disk usage for /usr/share/zoneinfo on my computer is around 4 MB.
672 There are a couple of differences.
673 The primary difference is that the zoneinfo files are stored in a
675 binary (and hence, more compressed) version, where the perl modules
676 have all the data in pure text.
677 Since these are all automatically generated and used, it may be
679 beneficial to store the data in some packed binary format instead
680 of the fully expanded text form that is currently in use. This
681 would decrease the disk space usage, and might improve performance.
682 However, the performance improvement would happen only once per
683 timezone, and would make for more complicated code, so I'm not very
684 interested in pursuing this.
685 Another aspect of the current modules is that they all include pod
687 documentation. Although not necessary, this allows users to easily
688 see what modules handle which time zones, and that's nice. It also
689 allows me to use pod_coverage tests for the module which is a nice
690 check to make sure that the documentation is accurate.
691 All told, I don't consider the disk usage excessive at all.
693
695 Unable to determine Time Zone
696 When using Date::Manip, when the module is initialized, it must be
697 able to determine the local time zone. If it fails to do so, an
698 error will occur:
699 Unable to determine Time Zone
701 and the script will exit.
703 In the past, this was the most common problem with using
705 Date::Manip . With the release of 6.00, this problem should be
706 significantly less common. If you do get this error, please refer
707 to the section above DETERMINING THE SYSTEM TIME ZONE for
708 information about determining the local time zone. I am also
709 interested in hearing about this so that I can update the default
710 list of methods to be able to determine the local time zone better.
711 Asia/Jerusalem time zone
713 The Asia/Jerusalem time zone has a non-standard way of specifying
714 the start and end of Daylight Savings Time based on the Hebrew
715 calendar.
716 As a result, there is no way to specify a simple rule to define
718 time zone changes for all years in the future. As such, this module
719 supports all time zone changes currently specified in the zoneinfo
720 database (which currently goes to the year 2037) but does not
721 attempt to correctly handle zone changes beyond that date. As a
722 result, Date::Manip should not be used to parse dates in the
723 Jerusalem time zone that are far enough in the future that
724 information is not included in the current version of the zoneinfo
725 database.
726 LMT and zzz abbreviations
728 Both the LMT and zzz abbreviations are used in the zoneinfo
729 databases. LMT is use for most time zones for the times before the
730 Gregorian calendar was adopted, and zzz is used for a few where the
731 time zone was created and no description of dates prior to that are
732 supported. Both LMT and zzz are basically ignored in parsing dates
733 (because there is no reasonable way to determine which zone they
734 are referring to), and will be treated as the local time zone
735 regardless.
736
738 None known.
739
741 Please refer to the Date::Manip::Problems documentation for information
742 on submitting bug reports or questions to the author.
743
745 Date::Manip - main module documentation
746
748 This script is free software; you can redistribute it and/or modify it
749 under the same terms as Perl itself.
750
752 Sullivan Beck (sbeck@cpan.org)
753perl v5.12.0 2010-04-27 Date::Manip::TZ(3)