1Date::Manip::TZ(3)    User Contributed Perl Documentation   Date::Manip::TZ(3)
2
3
4

NAME

6       Date::Manip::TZ - an interface to the time zone data
7

SYNOPSIS

9          use Date::Manip::TZ;
10          $tz = new Date::Manip::TZ;
11
12       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
16       This module uses the data from the zoneinfo database to perform various
17       time zone operations.
18

DESCRIPTION

20       Every time zone has some of the following characteristics:
21
22       name
23           Every time zone has a unique name. In the zoneinfo database, these
24           are something similar to:
25
26              America/New_York
27
28       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
33       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
38       Each period includes the following information:
39
40       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 wall clock time.  The wall
43           clock start time is the time that will be on a clock just as the
44           period starts (i.e. after a time change). The wall clock end time
45           is the time on a clock immediately before the period ends.
46
47       offset
48           The entire period has an offset which is how much the wall clock
49           time differs from GMT.
50
51       abbreviation
52           When expressing the time period, an abbreviation (such as EST) is
53           typically used.
54
55       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
60       Date::Manip includes all of the data for all of the time zones from the
61       zoneinfo database. This data is available from:
62
63       <ftp://ftp.iana.org/tz/>
64
65       Additional data from other standards are also used.
66
67       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
72       The Date::Manip::Zones document contains detailed information on the
73       data available.
74

METHODS

76       In all methods, the following variables are used:
77
78       $zone
79           This is a string which contains a valid time zone name.  For
80           example:
81
82             America/New_York
83
84       $alias
85           This is a strings which contains a valid time zone name, or a valid
86           time zone alias. For example:
87
88             America/New_York
89             US/Eastern
90             EST5EDT
91
92       $abbrev
93           This is a string which contains a valid time zone abbreviation. For
94           example:
95
96             EST
97
98       $offset
99           This is a time zone entered as an offset. An offset is either a
100           string of one of the formats:
101
102             +HH
103             +HHMM
104             +HHMMSS
105             +HH:MM
106             +HH:MM:SS
107
108           or it can be a list reference:
109
110             [HH,MM,SS]
111
112           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
115             [-5,-30,0]
116
117       $dstflag
118           This is always one of the values: std, stdonly, dst, dstonly
119
120           It defaults to "std" if it is not present. When determining a time
121           zone, it is usually necessary to check a number of different time
122           zone and DST combinations.
123
124           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
128           The "dst" flag will search both, but give preference to daylight
129           saving times.  The "dstonly" values will only use daylight saving
130           times.
131
132       $date
133           A date is always a string containing a date in one of the formats:
134
135              YYYYMMDDHH:MN:SS
136              YYYY-MM-DD-HH:MN:SS
137              YYYYMMDDHHMNSS
138
139           or a list reference:
140
141              [Y,M,D,H,MN,S]
142
143       $isdst
144           This is 0 if a date is in standard time, 1 if it is in daylight
145           saving time.
146
147       $period
148           A period is a list reference currently containing the following
149           items:
150
151              [ $dateUT, $dateLT, $offsetstr, $offset, $abbrev, $isdst,
152                $endUT, $endLT, $begUTs, $begLTs, $endUTs, $endLTs ]
153
154           $dateUT and $dateLT are the starting date of the period (i.e. the
155           first second in a period) in universal (GMT) time and local (wall
156           clock) time. $endUT and $endLT are the end date of the period (i.e.
157           the last second in a period) in universal and local time.  These
158           are all stored as list references.
159
160           $offsetstr is the string representation of the offset ("+05:00:00")
161           and $offset is the corresponding list reference form ([5,0,0]).
162
163           $abbrev is the abbreviation that applies during this period, and
164           $isdst is 0 or 1 if it is standard or daylight saving time.
165
166           When accessing the elements in a period, use ONLY positive indices.
167           In other words, to get $endUT, access it as $$period[6], NOT as
168           $$period[-2], since I am considering adding more information to the
169           period description that may speed up performance.
170
171           $begUTs is the string representation (YYYYMMDDHH:MN:SS) of $begUT.
172           Similar for $begLTs, $endUTs, and $endLTs.
173
174       The following methods are available:
175
176       base
177       config
178       err
179       new
180       new_config
181           Please refer to the Date::Manip::Obj documentation for these
182           methods.
183
184       all_periods
185              @periods = $tz->all_periods($zone,$year);
186
187           This returns the description of all time zone periods that occur
188           (in full or in part) during the given year.  The year is measured
189           in universal (GMT) time.
190
191       convert
192       convert_to_gmt
193       convert_from_gmt
194       convert_to_local
195       convert_from_local
196           These functions convert a date from one time zone to another.
197
198              ($err,$date,$offset,$isdst,$abbrev) =
199                 $tz->convert($date,$from,$to [,$isdst]);
200
201           This converts a date in the time zone given by $from to the time
202           zone given by $to.
203
204              ($err,$date,$offset,$isdst,$abbrev) =
205                 $tz->convert_to_gmt($date [,$from] [,$isdst]);
206
207           This converts a date to GMT. If $from is given, it is the current
208           time zone of the date. If $from is omitted, it defaults to the
209           local time zone.
210
211           The value of $isdst returned is always 0.
212
213              ($err,$date,$offset,$isdst,$abbrev) =
214                 $tz->convert_from_gmt($date [,$to]);
215
216           This converts a date from GMT to another time zone. If $to is
217           given, the date is converted to that time zone. Otherwise, it is
218           converted to the local time zone.
219
220              ($err,$date,$offset,$isdst,$abbrev) =
221                 $tz->convert_to_local($date [,$from] [,$isdst]);
222              ($err,$date,$offset,$isdst,$abbrev) =
223                 $tz->convert_from_local($date [,$to] [,$isdst]);
224
225           Similar to the convert_to_gmt and convert_from_gmt functions. If
226           $from or $to are omitted, they default to GMT.
227
228           If there is any ambiguity about whether $date is in DST or not
229           (i.e.  if it is a date that is repeated during a time change due to
230           the clock being moved back), the $isdst option can be passed in as
231           an argument (it should be 0 or 1) to say which time to use. It is
232           ignored in all cases where $date can be determined without that
233           information.
234
235           The $isdst value passed back is 1 if the converted date is in DST.
236           The $offset value passed back is a list reference containing the
237           offset from GMT. $abbrev passed back is the time zone abbreviation.
238
239           Error codes are:
240
241              0  No error
242              1  Invalid arguments
243              2  Invalid FROM zone
244              3  Invalid TO zone
245              4  Invalid date
246
247       curr_zone
248              $tz->curr_zone();
249
250           This returns the system time zone. The system time zone is
251           determined using the methods described below in the "DETERMINING
252           THE SYSTEM TIME ZONE" section.
253
254           This is the time zone that is used by default unless the SetDate or
255           ForceDate config variable is set to a different zone.
256
257              $tz->curr_zone(1);
258
259           This clears the system time zone and re-determines it using the
260           methods described below.
261
262           The main reason to do this is if the curr_zone_methods method is
263           used to change how the time zone is determined.
264
265       curr_zone_methods
266              $tz->curr_zone_methods(@methods);
267
268           This sets the list and order of methods to use in determining the
269           local time zone. The various methods available are listed below in
270           the section "DETERMINING THE SYSTEM TIME ZONE".
271
272           Some methods may require one or more arguments. For example, the
273           method named "mainvar" takes an option that is the name of a
274           variable. The arguments must be included in the @methods list
275           immediately after the method name (so @methods is actually a
276           mixture of method names and arguments).
277
278           This method may not be used in any environment where taint checking
279           is enabled. If it is, it will issue a warning, but will NOT change
280           the method list.
281
282       date_period
283              $period = $tz->date_period($date,$zone,$wall_clock [,$isdst]);
284
285           This returns the period information for the given date. $date
286           defaults to GMT, but may be given as local (i.e. wall clock) time
287           if $wall_clock is non-zero. The period information is described in
288           the periods method below.
289
290           If a wall clock time is given, no period is returned if the wall
291           clock time doesn't ever appear (such as when a time change results
292           in the clock moving forward "skipping" a period of time). If the
293           wall clock time appears twice (i.e. when a time change results in
294           the clock being set back), the $isdst variable is used. The
295           standard time is used unless $isdst is non-zero.  $isdst is ignored
296           except in the case where there are two possible periods.
297
298       define_abbrev
299              ($err,$val) = $tz->define_abbrev($abbrev,@zone);
300
301           When encountering an abbreviation, by default, all time zones which
302           ever include the abbreviation will be examine in the order given in
303           the Date::Manip::Zones manual.
304
305           Occasionally, it may be necessary to change the order. This is true
306           if you are parsing dates in a time zone which uses an abbreviation
307           which is also used in another time zone, and where the other time
308           zone is given preference. As an example, the abbreviation "ADT"
309           will default to the "Atlantic/Bermuda" time zone. If you are in the
310           "America/Halifax" time zone (which also uses that abbreviation),
311           you may want to change the order of time zones.
312
313           This will take an abbreviation (which must be a known
314           abbreviation... there is no means of defining a totally new
315           abbreviation) and a list of zones.  This will set the list of zones
316           that will be checked, and the order in which they are checked, when
317           a date is encountered with the given abbreviation. It is not
318           necessary that the list include every zone that has ever used the
319           abbreviation, but it may not include a zone that has never used it.
320
321           If $abbrev is "reset", all abbreviations are reset to the standard
322           values.  If @zone includes only the element 'reset', the default
323           list for $abbrev is restored.
324
325           The following error codes are returned:
326
327              0  No error
328              1  $abbrev is not a valid abbreviation in any time zone
329              2  A zone (returned as $val) is not a valid time zone
330              3  A zone (returned as $val) does not use the abbreviation
331
332           For more information about the different zones which may correspond
333           to each abbreviation, and the order in which they will be examined
334           by default, refer to the Date::Manip::Zones manual.
335
336       define_alias
337              $err = $tz->define_alias($alias,$zone);
338
339           This will define a new alias (or override an existing alias). $zone
340           must be a valid zone or an error is returned.
341
342           For more information about the different aliases which are set by
343           default, refer to the Date::Manip::Zones manual.
344
345           If $alias is "reset", all aliases will be reset to the standard
346           values.  If $zone is "reset", $alias will be reset to the standard
347           value.
348
349       define_offset
350              ($err,$val) = $tz->define_offset($offset, [$dstflag,] @zone);
351
352           This is similar to the define_abbrev method. When an offset is
353           encountered, all time zones which have ever included that offset
354           are checked. This will defined which time zones, and in what order,
355           they should be checked.
356
357           The zones to both standard and daylight saving times which include
358           the offset (if $dstflag is "std" or "dst") or to only one or the
359           other.
360
361           If $offset is "reset", all lists are reset to the default values.
362           If @zone includes only the element 'reset', the default list and
363           order is restored for $offset ($dstflag must not be given).
364
365           The following error codes are returned:
366
367              0  No error
368              1  $offset is not a valid offset in any time zone
369              2  $offset is not a valid offset in the selected
370                 time (if doing "dstonly" or "stdonly")
371              3  A zone (returned as $val) is not a valid time zone
372              4  A zone (returned as $val) does not use the offset
373              5  A zone (returned as $val) does not include the
374                 offset in the selected time (if doing "dstonly"
375                 or "stdonly")
376
377              9  Offset is not a valid offset
378
379       periods
380              @periods = $tz->periods($zone,$year);
381
382           This returns the description of all time zone periods that begin
383           during the year given. The year is measured in universal (GMT)
384           time.
385
386           If no time zone period starts in the given year, nothing is
387           returned.
388
389              @periods = $tz->periods($zone,undef,$year);
390
391           This returns all periods that begin in any year from 0001 to $year.
392
393              @periods = $tz->periods($zone,$year0,$year1);
394
395           This returns all periods that begin in any year from $year0 to
396           $year1.
397
398       tzdata
399       tzcode
400              $vers = $tz->tzdata();
401              $vers = $tz->tzcode();
402
403           These return the versions of the tzdata and tzcode packages used to
404           generate the modules.
405
406       zone
407              $zone = $tz->zone(@args);
408              @zone = $tz->zone(@args);
409
410           This function will return a list of all zones, or the default zone,
411           which matches all of the supplied information. In scalar context,
412           it will return only the default zone. In list context, it will
413           return all zones.
414
415           @args may include any of the following items, and the order is not
416           important.
417
418              A zone name or alias ($alias)
419
420              A zone abbreviation ($abbrev)
421
422              An offset ($offset)
423
424              A dstflag ($dstflag)
425
426              A date ($date)
427
428           It is NOT valid to include two of any of the items. Any time zone
429           returned will match all of the data supplied.
430
431           If an error occurs, undef is returned. If no zone matches, an empty
432           string, or an empty list is returned.
433
434           The order of the zones will be determined in the following way:
435
436           If $abbrev is given, the order of time zones will be determined by
437           it (and $dstflag). If $dstflag is "std", all zones which match
438           $abbrev in standard time are included, followed by all that match
439           $abbrev in saving time (but no duplication is allowed). The reverse
440           is true if $dstflag is "dst".
441
442           If $abbrev is not given, but $offset is, $offset (and $dstflag)
443           will determine the order given. If $dstflag is "std", all zones
444           which match $offset in standard time are included, followed by all
445           that match $offset in saving time (but no duplication is allowed).
446           The reverse is true if $dstflag is "dst".
447
448           If $date is given, only zones in which $date will appear in a zone
449           that matches all other information are given. $date is a wall clock
450           time.
451
452           If no $zone, $abbrev, or $offset are entered, the local time zone
453           may be returned (unless $date is entered, and it doesn't exist in
454           the local time zone).
455
456           NOTE: there is one important thing to note with respect to $dstflag
457           when you are working with a timezone expressed as an offset and a
458           date is passed in. In this case, the default value of $dstflag is
459           "dst" (NOT "stdonly"), and you probably never want to pass in a
460           value of "std" (though passing in "stdonly" is okay).
461
462           For standard offsets (with no minute component), there is always a
463           standard timezone which matches that offset. For example, the
464           timezone "+0100" matches the timezone "Etc/GMT+01", so you will
465           never get a timezone in daylight saving time if $dstflag is "std".
466
467           If you want to pass in a date of 2001-07-01-00:00:00 and an
468           timezone of "+0100" and you want to get a timezone that refers to
469           that date as a daylight saving time date, you must use the $dstflag
470           of "dst" (or "dstonly").
471
472           Because this is almost always the behavior desired, when a zone is
473           passed in as an offset, and a date is passed in, the default
474           $dstflag is "dst" instead of "std". In all other situations, the
475           default is still "std".
476
477           If the timezone is expressed as an abbreviation, this problem does
478           not occur.
479

TIME ZONE INFORMATION IN DATE::MANIP

481       Date::Manip makes use of three potentially different time zones when
482       working with a date.
483
484       The first time zone that may be used is the actual local time zone.
485       This is the time zone that the computer is actually running in.
486
487       The second time zone is the working time zone. Usually, you will want
488       the default time zone to be the local time zone, but occasionally, you
489       may want the default time zone to be different.
490
491       The third time zone is the actual time zone that was parsed, or set,
492       for a date. If a date contains no time zone information, it will
493       default to the working time zone.
494
495       The local time zone is determined using the methods described in the
496       following section. Methods exist for locating the zone in one of the
497       system configuration files, determining it by running a system command,
498       or by looking it up in the registry (for Windows operating systems).
499       If all of these methods fail, the local time zone may be set using
500       either the $::TZ or $ENV{TZ} variables. Please note that these should
501       ONLY be used to set the actual local time zone.
502
503       If you are running in one time zone, but you want to force dates to be
504       specified in an alternate time zone by default, you need to set the
505       working time zone. The working time zone defaults to the local time
506       zone, but this can be changed using either the SetDate or ForceDate
507       config variables. Refer to the Date::Manip::Config manual for more
508       information.
509
510       Finally, when a date is actually parsed, if it contains any time zone
511       information, the date is stored in that time zone.
512

DETERMINING THE SYSTEM TIME ZONE

514       There are a large number of ways available for determining the time
515       zone. Some or all of them may be checked. A list of methods to use is
516       provided by default, and may be overridden by the curr_zone_methods
517       function described above. To override the default order and/or list of
518       methods, just pass in a list of method names (with arguments where
519       necessary), and only those methods will be done, and in the order
520       given.
521
522       The following methods are available:
523
524          Method     Argument(s)    Procedure
525          ======     ===========    =========
526
527          main       VAR            The main variable named VAR is
528                                    checked. E.g. "main TZ" checks
529                                    the variable $::TZ .
530
531          env        TYPE VAR       The named environment variable
532                                    is checked and the type of
533                                    data stored there (TYPE can
534                                    be 'zone' or 'offset' which
535                                    is the number of seconds from
536                                    UTC).
537
538          file       FILE           Look in the given file for any
539                                    one of the following case
540                                    insensitive lines:
541                                       ZONE
542                                       tz = ZONE
543                                       zone = ZONE
544                                       timezone = ZONE
545                                    ZONE may be quoted (single or
546                                    double) and whitespace is
547                                    ignored (except that underscores
548                                    in the zone name may be replaced
549                                    by whitespace on some OSes). If
550                                    the entire line is a zone, it must
551                                    be the first non-blank non-comment
552                                    line in the file.
553
554          command    COMMAND        Runs a command which produces
555                                    a time zone as the output.
556
557          cmdfield   COMMAND N      Runs a command which produces
558                                    whitespace separated fields,
559                                    the Nth one containing the
560                                    time zone (fields are numbered
561                                    starting at 0, or from the
562                                    end starting at -1).
563
564          gmtoff                    Uses the current offset from
565                                    GMT to come up with a best guess.
566
567          tzdata     FILE DIR       This uses a system config file that
568                                    contains a pointer to the local tzdata
569                                    files to  determine the timezone.  On
570                                    many operating systems, use:
571
572                                    tzdata /etc/localtime /usr/share/zoneinfo
573
574                                    FILE is the system file.  DIR is the
575                                    directory where the tzdata files are stored.
576
577                                    The config file is either a link to a file
578                                    in the tzdata directory or a copy of one
579                                    of the files.
580
581          registry                  Look up the value in the
582                                    Windows registry. This is only
583                                    available to hosts running a
584                                    Windows operating system.
585
586       Note that the "main" and "env" methods should only be used to specify
587       the actual time zone the system is running in. Use the SetDate and
588       ForceDate config variables to specify an alternate time zone that you
589       want to work in.
590
591       By default, the following methods are checked (in the order given) on
592       Unix systems:
593
594          main     TZ
595          env      zone TZ
596          file     /etc/TIMEZONE
597          file     /etc/timezone
598          file     /etc/sysconfig/clock
599          file     /etc/default/init
600          command  "/bin/date +%Z"
601          command  "/usr/bin/date +%Z"
602          command  "/usr/local/bin/date +%Z"
603          cmdfield /bin/date             -2
604          cmdfield /usr/bin/date         -2
605          cmdfield /usr/local/bin/date   -2
606          command  "/bin/date +%z"
607          command  "/usr/bin/date +%z"
608          command  "/usr/local/bin/date +%z"
609          tzdata   /etc/localtime /usr/share/zoneinfo
610          gmtoff
611
612       The default methods for Windows systems are:
613
614          main     TZ
615          env      zone TZ
616          registry
617          gmtoff
618
619       The default methods for VMS systems are:
620
621          main     TZ
622          env      zone TZ
623          env      zone SYS$TIMEZONE_NAME
624          env      zone UCX$TZ
625          env      zone TCPIP$TZ
626          env      zone MULTINET_TIMEZONE
627          env      offset SYS$TIMEZONE_DIFFERENTIAL
628          gmtoff
629
630       The default methods for all other systems are:
631
632          main     TZ
633          env      zone TZ
634          gmtoff
635
636       If anyone wants better support for a specific OS, please contact me and
637       we'll coordinate adding it.
638
639       In all cases, the value returned from the method may be any of the
640       following:
641
642          the full name of a time zone (e.g. America/New_York)
643          or an alias
644
645          an abbreviation (e.g. EDT) which will be used to
646          determine the zone if possible
647
648          an offset (+hh, +hhmn, +hh:mm, +hh:mm:ss) from GMT
649
650       The Date::Manip::Zones module contains information about the time zones
651       and aliases available, and what time zones contain the abbreviations.
652

DESIGN ISSUES

654       The design decisions made in writing this module may cause some
655       questions (and probably complaints).  The time zone modules are all
656       generated using scripts (included in the Date::Manip distribution)
657       which use the standard tzdata tools to parse the tzdata files and store
658       that information in perl modules.
659
660       I'd like to address some of them, to avoid answering some of the "why
661       did you do it that way" remarks. I do welcome discussion about these
662       decisions... but preferably after you understand why those decisions
663       were made so that that we have an informed basis to begin a discussion.
664
665       Why not use existing zoneinfo files
666           Some people will probably think that I should have written an
667           interface to the zoneinfo files which are distributed with most
668           operating systems.  Although I considered doing that, I rejected
669           the idea for two reasons.
670
671           First, not all operating systems come with the zoneinfo databases
672           in a user accessible state (Microsoft for example).  Even those
673           that do include them store the information in various formats and
674           locations.  In order to bypass all that, I have included the data
675           directly in these modules.
676
677           Second, as I was doing my initial investigations into this, I ran
678           into a bug in the Solaris zoneinfo tools (long since fixed I'm
679           sure).  I decided then that I didn't want to depend on an
680           implementation where I could not control and fix the bugs.
681
682       Why not use the native tzdata files
683           Another decision people may question is that I parse the tzdata
684           files and store the data from them in a large number of perl
685           modules instead of creating an interface to the tzdata files
686           directly. This was done solely for the sake of speed.  Date::Manip
687           is already a slow module.  I didn't want to slow it down further by
688           doing the complex parsing required to interpret the tzdata files
689           while manipulating dates.  By storing the data in these modules,
690           there is little or no parsing done while using Date::Manip modules.
691           It costs a little disk space to store this information... but very
692           little of it is actually loaded at runtime (time zone data is only
693           loaded when the time zone is actually referred to), so I feel it's
694           a good tradeoff.
695
696       Why store the information in so many files
697           The data from the native tzdata files are parsed and stored in two
698           sets of modules. These include almost 500 Date::Manip::Offset::*
699           modules and almost 450 Date::Manip::TZ::* modules.
700
701           I note that on my linux box, /usr/share/zoneinfo (which contains
702           data files generated from the tzdata files) contains over 1700
703           files, so I'm not doing anything "new" by breaking up the
704           information into separate files. And doing so has a huge impact on
705           performance... it is not necessary to load and/or manipulate data
706           from time zones which are not in use.
707
708           The minute I made the decision to distribute the timezone
709           information myself, as opposed to using the system version, it was
710           a given that there would be a lot of files.
711
712           These modules are loaded only when the time zone or offset is
713           actually used, so, unless dates from around the world are being
714           parsed, only a very small number of these modules will actually be
715           loaded. In many applications, only a single TZ module will be
716           loaded. If parsing dates which have timezone information stored as
717           offsets, one or two Offset modules will also be loaded.
718
719       The disk space seems excessive
720           Currently, the disk usage of the perl files is around 9 MB. Total
721           disk usage for /usr/share/zoneinfo on my computer is around 4 MB.
722           There are a couple of differences.
723
724           The primary difference is that the zoneinfo files are stored in a
725           binary (and hence, more compressed) version, where the perl modules
726           have all the data in pure text.
727
728           Since these are all automatically generated and used, it may be
729           beneficial to store the data in some packed binary format instead
730           of the fully expanded text form that is currently in use. This
731           would decrease the disk space usage, and might improve performance.
732           However, the performance improvement would happen only once per
733           timezone, and would make for more complicated code, so I'm not very
734           interested in pursuing this.
735
736           Another aspect of the current modules is that they all include pod
737           documentation. Although not necessary, this allows users to easily
738           see what modules handle which time zones, and that's nice. It also
739           allows me to use pod_coverage tests for the module which is a nice
740           check to make sure that the documentation is accurate.
741
742           All told, I don't consider the disk usage excessive at all.
743

KNOWN PROBLEMS OR ISSUES

745       Unable to determine Time Zone
746           When using Date::Manip, when the module is initialized, it must be
747           able to determine the local time zone. If it fails to do so, an
748           error will occur:
749
750              Unable to determine Time Zone
751
752           and the script will exit.
753
754           In the past, this was the most common problem with using
755           Date::Manip .  With the release of 6.00, this problem should be
756           significantly less common. If you do get this error, please refer
757           to the section above DETERMINING THE SYSTEM TIME ZONE for
758           information about determining the local time zone. I am also
759           interested in hearing about this so that I can update the default
760           list of methods to be able to determine the local time zone better.
761
762       Asia/Jerusalem time zone
763           The Asia/Jerusalem time zone has a non-standard way of specifying
764           the start and end of Daylight Saving Time based on the Hebrew
765           calendar.
766
767           As a result, there is no way to specify a simple rule to define
768           time zone changes for all years in the future. As such, this module
769           supports all time zone changes currently specified in the zoneinfo
770           database (which currently goes to the year 2037) but does not
771           attempt to correctly handle zone changes beyond that date. As a
772           result, Date::Manip should not be used to parse dates in the
773           Jerusalem time zone that are far enough in the future that
774           information is not included in the current version of the zoneinfo
775           database.
776
777       LMT and zzz abbreviations
778           Both the LMT and zzz abbreviations are used in the zoneinfo
779           databases.  LMT is use for most time zones for the times before the
780           Gregorian calendar was adopted, and zzz is used for a few where the
781           time zone was created and no description of dates prior to that are
782           supported. Both LMT and zzz are basically ignored in parsing dates
783           (because there is no reasonable way to determine which zone they
784           are referring to), and will be treated as the local time zone
785           regardless.
786

KNOWN BUGS

788       None known.
789

BUGS AND QUESTIONS

791       Please refer to the Date::Manip::Problems documentation for information
792       on submitting bug reports or questions to the author.
793

SEE ALSO

795       Date::Manip        - main module documentation
796

LICENSE

798       This script is free software; you can redistribute it and/or modify it
799       under the same terms as Perl itself.
800

AUTHOR

802       Sullivan Beck (sbeck@cpan.org)
803
804
805
806perl v5.34.1                      2022-06-06                Date::Manip::TZ(3)
Impressum