1DateTime::TimeZone::SysUtseemrV(C3o)ntributed Perl DocumDeantteaTtiimoen::TimeZone::SystemV(3)
2
3
4

NAME

6       DateTime::TimeZone::SystemV - System V and POSIX timezone strings
7

SYNOPSIS

9               use DateTime::TimeZone::SystemV;
10
11               $tz = DateTime::TimeZone::SystemV->new(
12                       name => "US Eastern",
13                       recipe => "EST5EDT,M3.2.0,M11.1.0");
14               $tz = DateTime::TimeZone::SystemV->new(
15                       "EST5EDT,M3.2.0,M11.1.0");
16
17               if($tz->is_floating) { ...
18               if($tz->is_utc) { ...
19               if($tz->is_olson) { ...
20               $category = $tz->category;
21               $tz_string = $tz->name;
22
23               if($tz->has_dst_changes) { ...
24               if($tz->is_dst_for_datetime($dt)) { ...
25               $offset = $tz->offset_for_datetime($dt);
26               $abbrev = $tz->short_name_for_datetime($dt);
27               $offset = $tz->offset_for_local_datetime($dt);
28

DESCRIPTION

30       An instance of this class represents a timezone that was specified by
31       means of a System V timezone recipe or an extended form of the same
32       syntax (such as that specified by POSIX).  These can express a plain
33       offset from Universal Time, or a system of two offsets (standard and
34       daylight saving time) switching on a yearly cycle according to certain
35       types of rule.
36
37       This class implements the DateTime::TimeZone interface, so that its
38       instances can be used with DateTime objects.
39

SYSTEM V TIMEZONE RECIPE SYSTEM

41       This module supports multiple versions of the timezone recipe syntax
42       derived from System V.  Specifically, it supports the version specified
43       by POSIX.1, and the extension of the POSIX format that is used by
44       version 3 of the tzfile(5) file format.
45
46       A timezone may be specified that has a fixed offset by the syntax
47       "aaaooo", or a timezone with DST by the syntax
48       "aaaoooaaa[ooo],rrr,rrr".  "aaa" specifies an abbreviation by which an
49       offset is known, "ooo" specifies the offset, and "rrr" is a rule for
50       when DST starts or ends.  For backward compatibility, the rules part
51       may also be omitted from a DST-using timezone, in which case some
52       built-in default rules are used; don't rely on those rules being
53       useful.
54
55       An abbreviation must be a string of three or more characters from ASCII
56       alphanumerics, "+", and "-".  If it contains only ASCII alphabetic
57       characters then the abbreviation specification "aaa" may be simply the
58       abbreviation.  Otherwise "aaa" must consist of the abbreviation wrapped
59       in angle brackets ("<...>").  The angle bracket form is always allowed.
60       POSIX allows an implementation to set an upper limit on the length of
61       timezone abbreviations.  The limit is known as "TZNAME_MAX", and is
62       required to be no less than 6 (characters/bytes).  Abbreviations longer
63       than 6 characters are therefore not portable.  This class imposes no
64       such limit.
65
66       An offset (from Universal Time), "ooo", is given in hours, or hours and
67       minutes, or hours and minutes and seconds, with an optional preceding
68       sign.  Hours, minutes, and seconds must be separated by colons.  The
69       hours may be one or two digits, and the minutes and seconds must be two
70       digits each.  The maximum magnitude permitted is 24:59:59.  The sign in
71       the specification is the opposite of the sign of the actual offset.  If
72       no sign is given then the default is "+", meaning a timezone that is
73       behind UT (or equal to UT if the offset is zero).  If no DST offset is
74       specified, it defaults to one hour ahead of the standard offset.
75
76       A DST-using timezone has one transition to DST and one transition to
77       standard time in each Gregorian year.  The transitions may be in either
78       order within the year.  If the transitions are in different orders from
79       year to year then the behaviour is undefined; don't rely on it
80       remaining the same in future versions.  Likewise, the behaviour is
81       generally undefined if transitions coincide.  However, in the tzfile(5)
82       variant, if the rules specify a transition to DST at 00:00 standard
83       time on 1 January and a transition to standard time at 24:00 standard
84       time on 31 December, which makes the transitions coincide with those of
85       adjacent years, then the timezone is treated as observing DST all year.
86
87       A transition rule "rrr" takes the form "ddd[/ttt]", where "ddd" is the
88       rule giving the day on which the transition notionally takes place and
89       "ttt" is the time of day at which the transition takes place.  (A time
90       of day outside the usual 24-hour range can make the transition actually
91       take place on a different day.)  The time may be given in hours, or
92       hours and minutes, or hours and minutes and seconds.  Hours, minutes,
93       and seconds must be separated by colons.  The minutes and seconds must
94       be two digits each.  In the POSIX variant, the hours may be one or two
95       digits, with no preceding sign, and the time stated may range from
96       00:00:00 to 24:59:59 (almost an hour into the following day).  In the
97       tzfile(5) variant, the hours may be one to three digits, with optional
98       preceding sign, and the time stated may range from -167:59:59 to
99       +167:59:59 (a span of a little over two weeks).  If the time is not
100       stated then it defaults to 02:00:00.  The time for the transition to
101       DST is interpreted according to the standard offset, and the time for
102       the transition to standard time is interpreted according to the DST
103       offset.  (Thus normally the transition time is interpreted according to
104       the offset that prevailed immediately before the transition.)
105
106       A day rule "ddd" may take three forms.  Firstly, "Jnnn" means the
107       month-day date that is the nnnth day of a non-leap year.  Thus "J59"
108       means the February 28 and "J60" means March 1 (even in a leap year).
109       February 29 cannot be specified this way.
110
111       Secondly, if "ddd" is just a decimal number, it means the (1+ddd)th day
112       of the year.  February 29 counts in this case, and it is not possible
113       to specify December 31 of a leap year.
114
115       Thirdly, "ddd" may have the form "Mm.w.d" means day d of the wth week
116       of the mth month.  The day is given as a single digit, with "0" meaning
117       Sunday and "6" meaning Saturday.  The first week contains days 1 to 7
118       of the month, the second week contains days 8 to 14, and so on.  If "w"
119       is "5" then the last week of the month (containing its last seven days)
120       is used, rather than the fifth week (which is incomplete).
121
122       Examples:
123
124       MUT-4
125           Mauritius time, since 1907: 4 hours ahead of UT all year.
126
127       EST5EDT,M3.2.0,M11.1.0
128           US Eastern timezone with DST, from 2007 onwards.  5 hours behind UT
129           in winter and 4 hours behind in summer.  Changes on the second
130           Sunday in March and the first Sunday in November, in each case at
131           02:00 local time.
132
133       NST3:30NDT,M3.2.0/0:01,M11.1.0/0:01
134           Newfoundland timezone with DST, from 2007 onwards.  3.5 hours
135           behind UT in winter and 2.5 hours behind in summer.  Changes on the
136           second Sunday in March and the first Sunday in November, in each
137           case at 00:01 local time.
138
139       GMT0BST,M3.5.0/1,M10.5.0
140           UK civil time, from 1996 onwards.  On UT during the winter, calling
141           it "GMT", and 1 hour ahead of UT during the summer, called "BST".
142           Changes on the last Sunday in March and the last Sunday in October,
143           in each case at 01:00 UT.
144
145       EST-10EST,M10.5.0,M3.5.0/3
146           Australian Eastern timezone, from 2007 onwards.  10 hours ahead of
147           UT in the southern winter (the middle of the calendar year), and 11
148           hours ahead in the southern summer.  Changes to DST on the last
149           Sunday in October, and back on the last Sunday in March, in each
150           case at 02:00 standard time (16:00 UT of the preceding day).
151
152       EET-2EEST,M3.5.4/24,M9.3.6/145
153           Palestinian civil time, from 2012 onwards.  2 hours ahead of UT in
154           winter and 3 hours ahead in summer.  Changes at the end (24:00
155           local time) of the last Thursday in March and 01:00 local time on
156           the Friday following the third Saturday in September (that is, the
157           Friday falling between September 21 and September 27 inclusive).
158           The extended time-of-day "145", meaning 01:00 of the day six days
159           after the nominal day, is only valid in the tzfile(5) variant of
160           the System V syntax.  The time-of-day "24" is not so restricted,
161           being permitted by POSIX.
162

CONSTRUCTOR

164       DateTime::TimeZone::SystemV->new(ATTR => VALUE, ...)
165           Constructs and returns a DateTime-compatible timezone object that
166           implements the timezone described by the recipe given in the
167           arguments.  The following attributes may be given:
168
169           name
170               Name for the timezone object.  This will be returned by the
171               "name" method described below, and will be included in certain
172               error messages.  If not given, then the recipe is used as the
173               timezone name.
174
175           recipe
176               The short textual timezone recipe, as described in "SYSTEM V
177               TIMEZONE RECIPE SYSTEM".  Must be given.
178
179           system
180               Keyword identifying the particular variant of the recipe system
181               according to which the recipe is to be interpreted.  It may be:
182
183               posix (default)
184                   As specified by POSIX.1.
185
186               tzfile3
187                   As specified by version 3 of the tzfile(5) file format.
188
189       DateTime::TimeZone::SystemV->new(RECIPE)
190           Simpler way to invoke the above constructor in the usual case.
191           Only the recipe is given; it will be interpreted according to POSIX
192           system, and the recipe will also be used as the timezone name.
193

METHODS

195       These methods are all part of the DateTime::TimeZone interface.  See
196       that class for the general meaning of these methods; the documentation
197       below only comments on the specific behaviour of this class.
198
199   Identification
200       $tz->is_floating
201           Returns false.
202
203       $tz->is_utc
204           Returns false.
205
206       $tz->is_olson
207           Returns false.
208
209       $tz->category
210           Returns "undef", because the category concept doesn't properly
211           apply to these timezones.
212
213       $tz->name
214           Returns the timezone name.  Usually this is the recipe that was
215           supplied to the constructor, but it can be overridden by the
216           constructor's name attribute.
217
218   Offsets
219       $tz->has_dst_changes
220           Returns a truth value indicating whether the timezone includes a
221           DST offset.
222
223       $tz->is_dst_for_datetime(DT)
224           DT must be a DateTime-compatible object (specifically, it must
225           implement the "utc_rd_values" method).  Returns a truth value
226           indicating whether the timezone is on DST at the instant
227           represented by DT.
228
229       $tz->offset_for_datetime(DT)
230           DT must be a DateTime-compatible object (specifically, it must
231           implement the "utc_rd_values" method).  Returns the offset from UT
232           that is in effect at the instant represented by DT, in seconds.
233
234       $tz->short_name_for_datetime(DT)
235           DT must be a DateTime-compatible object (specifically, it must
236           implement the "utc_rd_values" method).  Returns the time scale
237           abbreviation for the offset that is in effect at the instant
238           represented by DT.
239
240       $tz->offset_for_local_datetime(DT)
241           DT must be a DateTime-compatible object (specifically, it must
242           implement the "local_rd_values" method).  Takes the local time
243           represented by DT (regardless of what absolute time it also
244           represents), and interprets that as a local time in the timezone of
245           the timezone object (not the timezone used in DT).  Returns the
246           offset from UT that is in effect at that local time, in seconds.
247
248           If the local time given is ambiguous due to a nearby offset change,
249           the numerically lower offset (usually the standard one) is returned
250           with no warning of the situation.  If the local time given does not
251           exist due to a nearby offset change, the method "die"s saying so.
252

SEE ALSO

254       DateTime, DateTime::TimeZone, POSIX.1
255       <http://www.opengroup.org/onlinepubs/000095399/basedefs/xbd_chap08.html>,
256       tzfile(5)
257

AUTHOR

259       Andrew Main (Zefram) <zefram@fysh.org>
260
262       Copyright (C) 2007, 2009, 2010, 2011, 2012, 2013, 2017 Andrew Main
263       (Zefram) <zefram@fysh.org>
264

LICENSE

266       This module is free software; you can redistribute it and/or modify it
267       under the same terms as Perl itself.
268
269
270
271perl v5.36.0                      2023-01-20    DateTime::TimeZone::SystemV(3)
Impressum