blib/lib/DateTime/TimeZone/SystemV.pm

filter: Statementstmt 98.0% 148 / 151 Branchbran 96.6% 87 / 90 Conditioncond 78.5% 11 / 14 MC/DCmcdc 50.0% 3 / 6 Subroutinesub 100% 24 / 24 Podpod 100% 11 / 11 totaltotal 95.9% 284 / 296 CC 53 SCAR 24.2
CC
53
Cov
96%
new
26.0
_is_dst_for_local_datetime
7.0
_rule_doy
6.0
CRAP 11.2
↑ Summary
1 =head1 NAME
2  
3 DateTime::TimeZone::SystemV - System V and POSIX timezone strings
4  
5 =head1 SYNOPSIS
6  
7 use DateTime::TimeZone::SystemV;
8  
9 $tz = DateTime::TimeZone::SystemV->new(
10 name => "US Eastern",
11 recipe => "EST5EDT,M3.2.0,M11.1.0");
12 $tz = DateTime::TimeZone::SystemV->new(
13 "EST5EDT,M3.2.0,M11.1.0");
14  
15 if($tz->is_floating) { ...
16 if($tz->is_utc) { ...
17 if($tz->is_olson) { ...
18 $category = $tz->category;
19 $tz_string = $tz->name;
20  
21 if($tz->has_dst_changes) { ...
22 if($tz->is_dst_for_datetime($dt)) { ...
23 $offset = $tz->offset_for_datetime($dt);
24 $abbrev = $tz->short_name_for_datetime($dt);
25 $offset = $tz->offset_for_local_datetime($dt);
26  
27 =head1 DESCRIPTION
28  
29 An instance of this class represents a timezone that was specified by
30 means of a System V timezone recipe or an extended form of the same syntax
31 (such as that specified by POSIX). These can express a plain offset from
32 Universal Time, or a system of two offsets (standard and daylight saving
33 time) switching on a yearly cycle according to certain types of rule.
34  
35 This class implements the L<DateTime::TimeZone> interface, so that its
36 instances can be used with L<DateTime> objects.
37  
38 =head1 SYSTEM V TIMEZONE RECIPE SYSTEM
39  
40 This module supports multiple versions of the timezone recipe syntax
41 derived from System V. Specifically, it supports the version specified
42 by POSIX.1, and the extension of the POSIX format that is used by version
43 3 of the L<tzfile(5)> file format.
44  
45 A timezone may be specified that has a fixed offset by the
46 syntax "I<aaa>I<ooo>", or a timezone with DST by the syntax
47 "I<aaa>I<ooo>I<aaa>[I<ooo>]B<,>I<rrr>B<,>I<rrr>". "I<aaa>" specifies an
48 abbreviation by which an offset is known, "I<ooo>" specifies the offset,
49 and "I<rrr>" is a rule for when DST starts or ends. For backward
50 compatibility, the rules part may also be omitted from a DST-using
51 timezone, in which case some built-in default rules are used; don't rely
52 on those rules being useful.
53  
54 An abbreviation must be a string of three or more characters from ASCII
55 alphanumerics, "B<+>", and "B<->". If it contains only ASCII alphabetic
56 characters then the abbreviation specification "I<aaa>" may be simply
57 the abbreviation. Otherwise "I<aaa>" must consist of the abbreviation
58 wrapped in angle brackets ("B<< < >>...B<< > >>"). The angle bracket
59 form is always allowed. POSIX allows an implementation to set an upper
60 limit on the length of timezone abbreviations. The limit is known as
61 C<TZNAME_MAX>, and is required to be no less than 6 (characters/bytes).
62 Abbreviations longer than 6 characters are therefore not portable.
63 This class imposes no such limit.
64  
65 An offset (from Universal Time), "I<ooo>", is given in hours, or
66 hours and minutes, or hours and minutes and seconds, with an optional
67 preceding sign. Hours, minutes, and seconds must be separated by colons.
68 The hours may be one or two digits, and the minutes and seconds must be
69 two digits each. The maximum magnitude permitted is 24:59:59. The sign
70 in the specification is the opposite of the sign of the actual offset.
71 If no sign is given then the default is "B<+>", meaning a timezone that
72 is behind UT (or equal to UT if the offset is zero). If no DST offset
73 is specified, it defaults to one hour ahead of the standard offset.
74  
75 A DST-using timezone has one transition to DST and one transition to
76 standard time in each Gregorian year. The transitions may be in either
77 order within the year. If the transitions are in different orders from
78 year to year then the behaviour is undefined; don't rely on it remaining
79 the same in future versions. Likewise, the behaviour is generally
80 undefined if transitions coincide. However, in the L<tzfile(5)> variant,
81 if the rules specify a transition to DST at 00:00 standard time on 1
82 January and a transition to standard time at 24:00 standard time on 31
83 December, which makes the transitions coincide with those of adjacent
84 years, then the timezone is treated as observing DST all year.
85  
86 A transition rule "I<rrr>" takes the form "I<ddd>[B</>I<ttt>]", where
87 "I<ddd>" is the rule giving the day on which the transition notionally
88 takes place and "I<ttt>" is the time of day at which the transition
89 takes place. (A time of day outside the usual 24-hour range can make
90 the transition actually take place on a different day.) The time may be
91 given in hours, or hours and minutes, or hours and minutes and seconds.
92 Hours, minutes, and seconds must be separated by colons. The minutes
93 and seconds must be two digits each. In the POSIX variant, the hours
94 may be one or two digits, with no preceding sign, and the time stated may
95 range from 00:00:00 to 24:59:59 (almost an hour into the following day).
96 In the L<tzfile(5)> variant, the hours may be one to three digits, with
97 optional preceding sign, and the time stated may range from -167:59:59
98 to +167:59:59 (a span of a little over two weeks). If the time is not
99 stated then it defaults to 02:00:00. The time for the transition to DST
100 is interpreted according to the standard offset, and the time for the
101 transition to standard time is interpreted according to the DST offset.
102 (Thus normally the transition time is interpreted according to the offset
103 that prevailed immediately before the transition.)
104  
105 A day rule "I<ddd>" may take three forms. Firstly, "B<J>I<nnn>" means the
106 month-day date that is the I<nnn>th day of a non-leap year. Thus "B<J59>"
107 means the February 28 and "B<J60>" means March 1 (even in a leap year).
108 February 29 cannot be specified this way.
109  
110 Secondly, if "I<ddd>" is just a decimal number, it means the (1+I<ddd>)th
111 day of the year. February 29 counts in this case, and it is not possible
112 to specify December 31 of a leap year.
113  
114 Thirdly, "I<ddd>" may have the form "B<M>I<m>B<.>I<w>B<.>I<d>" means day
115 I<d> of the I<w>th week of the I<m>th month. The day is given as a single
116 digit, with "B<0>" meaning Sunday and "B<6>" meaning Saturday. The first
117 week contains days 1 to 7 of the month, the second week contains days 8
118 to 14, and so on. If "I<w>" is "B<5>" then the last week of the month
119 (containing its last seven days) is used, rather than the fifth week
120 (which is incomplete).
121  
122 Examples:
123  
124 =over
125  
126 =item MUT-4
127  
128 Mauritius time, since 1907: 4 hours ahead of UT all year.
129  
130 =item EST5EDT,M3.2.0,M11.1.0
131  
132 US Eastern timezone with DST, from 2007 onwards. 5 hours behind UT in
133 winter and 4 hours behind in summer. Changes on the second Sunday in
134 March and the first Sunday in November, in each case at 02:00 local time.
135  
136 =item NST3:30NDT,M3.2.0/0:01,M11.1.0/0:01
137  
138 Newfoundland timezone with DST, from 2007 onwards. 3.5 hours behind UT
139 in winter and 2.5 hours behind in summer. Changes on the second Sunday in
140 March and the first Sunday in November, in each case at 00:01 local time.
141  
142 =item GMT0BST,M3.5.0/1,M10.5.0
143  
144 UK civil time, from 1996 onwards. On UT during the winter, calling
145 it "GMT", and 1 hour ahead of UT during the summer, called "BST".
146 Changes on the last Sunday in March and the last Sunday in October,
147 in each case at 01:00 UT.
148  
149 =item EST-10EST,M10.5.0,M3.5.0/3
150  
151 Australian Eastern timezone, from 2007 onwards. 10 hours ahead of UT in
152 the southern winter (the middle of the calendar year), and 11 hours ahead
153 in the southern summer. Changes to DST on the last Sunday in October,
154 and back on the last Sunday in March, in each case at 02:00 standard time
155 (16:00 UT of the preceding day).
156  
157 =item EET-2EEST,M3.5.4/24,M9.3.6/145
158  
159 Palestinian civil time, from 2012 onwards. 2 hours ahead of UT in winter
160 and 3 hours ahead in summer. Changes at the end (24:00 local time) of
161 the last Thursday in March and 01:00 local time on the Friday following
162 the third Saturday in September (that is, the Friday falling between
163 September 21 and September 27 inclusive). The extended time-of-day "145",
164 meaning 01:00 of the day six days after the nominal day, is only valid
165 in the L<tzfile(5)> variant of the System V syntax. The time-of-day
166 "24" is not so restricted, being permitted by POSIX.
167  
168 =back
169  
170 =cut
171  
172 package DateTime::TimeZone::SystemV;
173  
174 5 ▶{ use 5.006; }
Subroutine BEGIN: called CC=1 SCAR=0.0
175 5 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
176 5 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
177  
178 5 ▶use Carp qw(croak);
Subroutine BEGIN: called CC=1 SCAR=0.0
179 5 ▶use Date::ISO8601 0.000
Subroutine BEGIN: called CC=1 SCAR=0.0
180 5 qw(month_days ymd_to_cjdn present_ymd year_days cjdn_to_yd cjdn_to_ywd);
181 5 ▶use Params::Classify 0.000 qw(is_undef is_string);
Subroutine BEGIN: called CC=1 SCAR=0.0
182  
183 5 our $VERSION = "0.010";
184  
185 5 my $rdn_epoch_cjdn = 1721425;
186  
187 5 my $abbrev_rx = qr#[A-Za-z]{3,}|\<[-+0-9A-Za-z]{3,}\>#;
188 5 my $offset_rx = qr#[-+]?(?:2[0-4]|[01]?[0-9])(?::[0-5][0-9](?::[0-5][0-9])?)?#;
189 5 my $rule_date_rx = qr#J0*(?:3(?:[0-5][0-9]|6[0-5])|[12]?[0-9][0-9]|[1-9])
190 |0*(?:3(?:[0-5][0-9]|6[0-4])|[12]?[0-9][0-9]|[0-9])
191 |M0*(?:1[0-2]|[1-9])\.0*[1-5]\.0*[0-6]#x;
192 5 my $posix_rule_time_rx =
193 qr#(?:2[0-4]|[01]?[0-9])(?::[0-5][0-9](?::[0-5][0-9])?)?#;
194 5 my $tzfile3_rule_time_rx =
195 qr#[-+]?(?:16[0-7]|1[0-5][0-9]|0[0-9][0-9]|[0-9]{1,2})
196 (?::[0-5][0-9](?::[0-5][0-9])?)?#x;
197 5 my $posix_rule_dt_rx = qr#${rule_date_rx}(?:/${posix_rule_time_rx})?#o;
198 5 my $tzfile3_rule_dt_rx = qr#${rule_date_rx}(?:/${tzfile3_rule_time_rx})?#o;
199 5 my $posix_tz_rx = qr#${abbrev_rx}${offset_rx}
200 (?:${abbrev_rx}(?:${offset_rx})?
201 (?:,${posix_rule_dt_rx},${posix_rule_dt_rx})?)?#xo;
202 5 my $tzfile3_tz_rx = qr#${abbrev_rx}${offset_rx}
203 (?:${abbrev_rx}(?:${offset_rx})?
204 (?:,${tzfile3_rule_dt_rx},${tzfile3_rule_dt_rx})?)?#xo;
205  
206 5 my %tz_rx = (
207 posix => $posix_tz_rx,
208 tzfile3 => $tzfile3_tz_rx,
209 );
210  
211 58 ▶sub _parse_abbrev($) {
Subroutine _parse_abbrev: called CC=2 SCAR=6.9
212 58 my($spec) = @_;
213 58 ▶ return $spec =~ /\A\<(.*)\>\z/s ? $1 : $spec;
Branch: 1 branch
BranchTrueFalseTotal
$spec =~ /\A\<(.*)\>\z/s ? : 2 56 58
214 }
215  
216 64 ▶sub _parse_offset($) {
Subroutine _parse_offset: called CC=5 SCAR=16.1
217 64 my($spec) = @_;
218 64 my($sign, $h, $m, $s) =
219 ($spec =~ /\A([-+]?)([0-9]+)(?::([0-9]+)(?::([0-9]+))?)?\z/);
220 64 ▶ return ($sign eq "-" ? 1 : -1) *
Branch: 3 branches
BranchTrueFalseTotal
$sign eq '-' ? : 16 48 64
defined $m ? : 6 58 64
defined $s ? : 2 4 6
Condition100%2/2
($sign eq '-' ? 1 : -1) * ($h * 3600 + (defined $m ? $m * 60 + (defined $s ? $s : 0) : 0)) || 0
l!l
595
MC/DC100%1/1
($sign eq '-' ? 1 : -1) * ($h * 3600 + (defined $m ? $m * 60 + (defined $s ? $s : 0) : 0)) || 0
($sign eq '-' ? 1 : -1) * ($h * 3600 + (defined $m ? $m * 60 + (defined $s ? $s : 0) : 0))
Truth table100%2/2
A
A= ($sign eq '-' ? 1 : -1) * ($h * 3600 + (defined $m ? $m * 60 + (defined $s ? $s : 0) : 0))
Aresult
11
00
221 ($h*3600 + (defined($m) ? $m*60 + (defined($s) ? $s : 0) : 0))
222 || 0;
223 }
224  
225 52 ▶sub _parse_rule($$) {
Subroutine _parse_rule: called CC=2 SCAR=6.9
226 52 my($spec, $offset) = @_;
227 52 my($drule, $tod) = split(m#/#, $spec);
228 return {
229 52 ▶ drule => $drule,
Branch: 1 branch
BranchTrueFalseTotal
defined $tod ? : 24 28 52
230 sod => -$offset +
231 (defined($tod) ? -_parse_offset($tod) : 7200),
232 };
233 }
234  
235 =head1 CONSTRUCTOR
236  
237 =over
238  
239 =item DateTime::TimeZone::SystemV->new(ATTR => VALUE, ...)
240  
241 Constructs and returns a L<DateTime>-compatible timezone object that
242 implements the timezone described by the recipe given in the arguments.
243 The following attributes may be given:
244  
245 =over
246  
247 =item B<name>
248  
249 Name for the timezone object. This will be returned by the C<name>
250 method described below, and will be included in certain error messages.
251 If not given, then the recipe is used as the timezone name.
252  
253 =item B<recipe>
254  
255 The short textual timezone recipe, as described in L</SYSTEM V TIMEZONE
256 RECIPE SYSTEM>. Must be given.
257  
258 =item B<system>
259  
260 Keyword identifying the particular variant of the recipe system according
261 to which the recipe is to be interpreted. It may be:
262  
263 =over
264  
265 =item B<posix> (default)
266  
267 As specified by POSIX.1.
268  
269 =item B<tzfile3>
270  
271 As specified by version 3 of the L<tzfile(5)> file format.
272  
273 =back
274  
275 =back
276  
277 =item DateTime::TimeZone::SystemV->new(RECIPE)
278  
279 Simpler way to invoke the above constructor in the usual case. Only the
280 recipe is given; it will be interpreted according to POSIX system,
281 and the recipe will also be used as the timezone name.
282  
283 =cut
284  
285 56 ▶sub new {
Subroutine new: called CC=26 SCAR=32.6
Pod documented
286 56 my $class = shift;
287 56 ▶ unshift @_, "recipe" if @_ == 1;
Branch: 1 branch
BranchTrueFalseTotal
if @_ == 1 22 34 56
288 56 my $self = bless({}, $class);
289 56 my $recipe;
290 my $system;
291 56 ▶ while(@_) {
Branch: 1 branch
BranchTrueFalseTotal
if (@_) 70 39 109
292 70 my $attr = shift;
293 70 my $value = shift;
294 70 ▶ if($attr eq "name") {
Branch: 3 branches
BranchTrueFalseTotal
if ($attr eq 'name') { } 10 60 70
elsif ($attr eq 'recipe') { } 43 17 60
elsif ($attr eq 'system') { } 16 1 17
295 croak "timezone name specified redundantly"
296 10 ▶ if exists $self->{name};
Branch: 1 branch
BranchTrueFalseTotal
if exists $self->{"name"} 1 9 10
297 9 ▶ croak "timezone name must be a string"
Branch: 1 branch
BranchTrueFalseTotal
unless rand $value 4 5 9
298 unless is_string($value);
299 5 $self->{name} = $value;
300 } elsif($attr eq "recipe") {
301 43 ▶ croak "recipe specified redundantly"
Branch: 1 branch
BranchTrueFalseTotal
if defined $recipe 1 42 43
302 if defined $recipe;
303 42 ▶ croak "recipe must be a string"
Branch: 1 branch
BranchTrueFalseTotal
unless rand $value 4 38 42
304 unless is_string($value);
305 38 $recipe = $value;
306 } elsif($attr eq "system") {
307 16 ▶ croak "system identifier specified redundantly"
Branch: 1 branch
BranchTrueFalseTotal
if defined $system 1 15 16
308 if defined $system;
309 15 ▶ croak "system identifier must be a string"
Branch: 1 branch
BranchTrueFalseTotal
unless rand $value 4 11 15
310 unless is_string($value);
311 croak "system identifier not recognised"
312 11 ▶ unless exists $tz_rx{$value};
Branch: 1 branch
BranchTrueFalseTotal
unless exists $tz_rx{$value} 1 10 11
313 10 $system = $value;
314 } else {
315 1 croak "unrecognised attribute `$attr'";
316 }
317 }
318 39 ▶ croak "recipe not specified" unless defined $recipe;
Branch: 1 branch
BranchTrueFalseTotal
unless defined $recipe 2 37 39
319 37 ▶ $self->{name} = $recipe unless exists $self->{name};
Branch: 1 branch
BranchTrueFalseTotal
unless exists $self->{"name"} 34 3 37
320 37 ▶ $system = "posix" unless defined $system;
Branch: 1 branch
BranchTrueFalseTotal
unless defined $system 28 9 37
321 37 ▶ croak "not a valid SysV-style timezone recipe"
Branch: 1 branch
BranchTrueFalseTotal
unless $recipe =~ /\A$tz_rx{$system}\z/ 5 32 37
322 unless $recipe =~ /\A$tz_rx{$system}\z/;
323 32 $recipe =~ /\A($abbrev_rx)($offset_rx)/og;
324 32 my($std_abbrev, $std_offset) = ($1, $2);
325 32 $self->{std_abbrev} = _parse_abbrev($std_abbrev);
326 32 $self->{std_offset} = _parse_offset($std_offset);
327 32 ▶ return $self if $recipe =~ /\G\z/gc;
Branch: 1 branch
BranchTrueFalseTotal
if $recipe =~ /\G\z/cg 6 26 32
328 26 $recipe =~ /\G($abbrev_rx)($offset_rx)?/g;
329 26 my($dst_abbrev, $dst_offset) = ($1, $2);
330 26 $self->{dst_abbrev} = _parse_abbrev($dst_abbrev);
331 $self->{dst_offset} = defined($dst_offset) ?
332 26 ▶ _parse_offset($dst_offset) : $self->{std_offset} + 3600;
Branch: 1 branch
BranchTrueFalseTotal
defined $dst_offset ? : 8 18 26
333 26 my($start_rule, $end_rule);
334 26 ▶ if($recipe =~ /\G,(.*),(.*)/g) {
Branch: 1 branch
BranchTrueFalseTotal
if ($recipe =~ /\G,(.*),(.*)/g) { } 16 10 26
335 16 ($start_rule, $end_rule) = ($1, $2);
336 } else {
337 # default to US 1976 rules, which is what the ruleless
338 # old SysV style specs were expected to do
339 10 ($start_rule, $end_rule) = ("M4.5.0", "M10.5.0");
340 }
341 26 $self->{start_rule} = _parse_rule($start_rule, $self->{std_offset});
342 26 $self->{end_rule} = _parse_rule($end_rule, $self->{dst_offset});
343 26 ▶ if($system eq "tzfile3" &&
Branch: 1 branch
BranchTrueFalseTotal
if ($system eq "tzfile3" and $self->{"start_rule"}{"drule"} =~ /\A(?:J0*1|0+)\z/ and $self->{"start_rule"}{"sod"} == -$self->{"std_offset"} and $self->{"end_rule"}{"drule"} =~ /\AJ0*365\z/ and $self->{"end_rule"}{"sod"} == 86400 - $self->{"std_offset"}) 2 24 26
Condition75%9/12
$system eq "tzfile3" and $self->{"start_rule"}{"drule"} =~ /\A(?:J0*1|0+)\z/ and $self->{"start_rule"}{"sod"} == -$self->{"std_offset"} and $self->{"end_rule"}{"drule"} =~ /\AJ0*365\z/ and $self->{"end_rule"}{"sod"} == 86400 - $self->{"std_offset"}
!ll&&!rl&&r
2402
$system eq "tzfile3" and $self->{"start_rule"}{"drule"} =~ /\A(?:J0*1|0+)\z/ and $self->{"start_rule"}{"sod"} == -$self->{"std_offset"} and $self->{"end_rule"}{"drule"} =~ /\AJ0*365\z/
!ll&&!rl&&r
2402
$system eq "tzfile3" and $self->{"start_rule"}{"drule"} =~ /\A(?:J0*1|0+)\z/ and $self->{"start_rule"}{"sod"} == -$self->{"std_offset"}
!ll&&!rl&&r
2402
$system eq "tzfile3" and $self->{"start_rule"}{"drule"} =~ /\A(?:J0*1|0+)\z/
!ll&&!rl&&r
2132
MC/DC40%2/5
$system eq "tzfile3" and $self->{"start_rule"}{"drule"} =~ /\A(?:J0*1|0+)\z/ and $self->{"start_rule"}{"sod"} == -$self->{"std_offset"} and $self->{"end_rule"}{"drule"} =~ /\AJ0*365\z/ and $self->{"end_rule"}{"sod"} == 86400 - $self->{"std_offset"}
$system eq "tzfile3" $self->{"start_rule"}{"drule"} =~ /\A(?:J0*1|0+)\z/ $self->{"start_rule"}{"sod"} == -$self->{"std_offset"} $self->{"end_rule"}{"drule"} =~ /\AJ0*365\z/ $self->{"end_rule"}{"sod"} == 86400 - $self->{"std_offset"}
Truth table50%3/6
A and B and C and D and E
A= $system eq "tzfile3"B= $self->{"start_rule"}{"drule"} =~ /\A(?:J0*1|0+)\z/C= $self->{"start_rule"}{"sod"} == -$self->{"std_offset"}D= $self->{"end_rule"}{"drule"} =~ /\AJ0*365\z/E= $self->{"end_rule"}{"sod"} == 86400 - $self->{"std_offset"}
ABCDEresult
0XXXX0
10XXX0
110XX0
1110X0
111100
111111
344 $self->{start_rule}->{drule} =~ /\A(?:J0*1|0+)\z/ &&
345 $self->{start_rule}->{sod} == -$self->{std_offset} &&
346 $self->{end_rule}->{drule} =~ /\AJ0*365\z/ &&
347 $self->{end_rule}->{sod} == 86400-$self->{std_offset}) {
348 delete $self->{$_}
349 2 foreach qw(std_abbrev std_offset start_rule end_rule);
350 }
351 26 return $self;
352 }
353  
354 =back
355  
356 =head1 METHODS
357  
358 These methods are all part of the L<DateTime::TimeZone> interface.
359 See that class for the general meaning of these methods; the documentation
360 below only comments on the specific behaviour of this class.
361  
362 =head2 Identification
363  
364 =over
365  
366 =item $tz->is_floating
367  
368 Returns false.
369  
370 =cut
371  
372 2 ▶sub is_floating { 0 }
Subroutine is_floating: called CC=1 SCAR=0.0
Pod documented
373  
374 =item $tz->is_utc
375  
376 Returns false.
377  
378 =cut
379  
380 2 ▶sub is_utc { 0 }
Subroutine is_utc: called CC=1 SCAR=0.0
Pod documented
381  
382 =item $tz->is_olson
383  
384 Returns false.
385  
386 =cut
387  
388 2 ▶sub is_olson { 0 }
Subroutine is_olson: called CC=1 SCAR=0.0
Pod documented
389  
390 =item $tz->category
391  
392 Returns C<undef>, because the category concept doesn't properly apply
393 to these timezones.
394  
395 =cut
396  
397 2 ▶sub category { undef }
Subroutine category: called CC=1 SCAR=0.0
Pod documented
398  
399 =item $tz->name
400  
401 Returns the timezone name. Usually this is the recipe that was supplied
402 to the constructor, but it can be overridden by the constructor's B<name>
403 attribute.
404  
405 =cut
406  
407 6 ▶sub name { $_[0]->{name} }
Subroutine name: called CC=1 SCAR=0.0
Pod documented
408  
409 =back
410  
411 =head2 Offsets
412  
413 =over
414  
415 =item $tz->has_dst_changes
416  
417 Returns a truth value indicating whether the timezone includes a DST offset.
418  
419 =cut
420  
421 2 ▶sub has_dst_changes { exists $_[0]->{dst_abbrev} }
Subroutine has_dst_changes: called CC=1 SCAR=0.0
Pod documented
422  
423 =item $tz->is_dst_for_datetime(DT)
424  
425 I<DT> must be a L<DateTime>-compatible object (specifically, it must
426 implement the C<utc_rd_values> method). Returns a truth value indicating
427 whether the timezone is on DST at the instant represented by I<DT>.
428  
429 =cut
430  
431 4483 ▶sub _rule_doy($$) {
Subroutine _rule_doy: called CC=6 SCAR=18.0
432 4483 my($drule, $year) = @_;
433 4483 ▶ if($drule =~ /\AJ([0-9]+)\z/) {
Branch: 3 branches
BranchTrueFalseTotal
if ($drule =~ /\AJ([0-9]+)\z/) { } 1497 2986 4483
elsif ($drule =~ /\A([0-9]+)\z/) { } 384 2602 2986
elsif ($drule =~ /\AM([0-9]+)\.([0-9]+)\.([0-9]+)\z/) { } 2602 0 2602
434 1497 my $j = $1;
435 1497 ▶ if($j < 60) {
Branch: 1 branch
BranchTrueFalseTotal
if ($j < 60) { } 390 1107 1497
436 390 return $j;
437 } else {
438 1107 return year_days($year) - 365 + $j;
439 }
440 } elsif($drule =~ /\A([0-9]+)\z/) {
441 384 return 1 + $1;
442 } elsif($drule =~ /\AM([0-9]+)\.([0-9]+)\.([0-9]+)\z/) {
443 2602 my($m, $w, $dow) = ($1, $2, $3);
444 2602 ▶ my $fdom = ($w == 5 ? month_days($year, $m) : $w*7) - 6;
Branch: 1 branch
BranchTrueFalseTotal
$w == 5 ? : 1954 648 2602
445 2602 my(undef, undef, $fdow) =
446 cjdn_to_ywd(ymd_to_cjdn($year, $m, $fdom));
447 2602 my $dom = $fdom + ($dow + 7 - $fdow) % 7;
448 2602 my(undef, $doy) = cjdn_to_yd(ymd_to_cjdn($year, $m, $dom));
449 2602 return $doy;
450 } else {
451 0 die "internal error: unrecognised day rule";
452 }
453 }
454  
455 907 ▶sub _is_dst_for_utc_rdn_sod {
Subroutine _is_dst_for_utc_rdn_sod: called CC=3 SCAR=11.0
456 907 my($self, $rdn, $sod) = @_;
457 907 my($year, $doy) = cjdn_to_yd($rdn + $rdn_epoch_cjdn);
458 907 my $soy = $doy * 86400 + $sod;
459 907 my @latest_change;
460 907 foreach my $change_type (qw(end_rule start_rule)) {
461 1814 for(my $y = $year+1, my $doff = year_days($year); ;
462 $doff -= year_days(--$y)) {
463 my $change_soy =
464 ($doff + _rule_doy($self->{$change_type}
465 ->{drule}, $y))
466 4483 * 86400 + $self->{$change_type}->{sod};
467 4483 ▶ if($change_soy <= $soy) {
Branch: 1 branch
BranchTrueFalseTotal
if ($change_soy <= $soy) 1814 2669 4483
468 1814 push @latest_change, $change_soy;
469 1814 last;
470 }
471 }
472 }
473 907 return $latest_change[1] > $latest_change[0];
474 }
475  
476 816 ▶sub is_dst_for_datetime {
Subroutine is_dst_for_datetime: called CC=4 SCAR=13.9
Pod documented
477 816 my($self, $dt) = @_;
478 816 ▶ return 0 unless exists $self->{dst_abbrev};
Branch: 1 branch
BranchTrueFalseTotal
unless exists $self->{"dst_abbrev"} 27 789 816
479 789 ▶ return 1 unless exists $self->{std_abbrev};
Branch: 1 branch
BranchTrueFalseTotal
unless exists $self->{"std_abbrev"} 54 735 789
480 735 my($utc_rdn, $utc_sod) = $dt->utc_rd_values;
481 735 ▶ $utc_sod = 86399 if $utc_sod >= 86400;
Branch: 1 branch
BranchTrueFalseTotal
if $utc_sod >= 86400 15 720 735
482 735 return $self->_is_dst_for_utc_rdn_sod($utc_rdn, $utc_sod);
483 }
484  
485 =item $tz->offset_for_datetime(DT)
486  
487 I<DT> must be a L<DateTime>-compatible object (specifically, it must
488 implement the C<utc_rd_values> method). Returns the offset from UT that
489 is in effect at the instant represented by I<DT>, in seconds.
490  
491 =cut
492  
493 272 ▶sub offset_for_datetime {
Subroutine offset_for_datetime: called CC=2 SCAR=6.9
Pod documented
494 272 my($self, $dt) = @_;
495 272 ▶ return $self->{$self->is_dst_for_datetime($dt) ?
Branch: 1 branch
BranchTrueFalseTotal
$self->is_dst_for_datetime($dt) ? : 135 137 272
496 "dst_offset" : "std_offset"};
497 }
498  
499 =item $tz->short_name_for_datetime(DT)
500  
501 I<DT> must be a L<DateTime>-compatible object (specifically, it
502 must implement the C<utc_rd_values> method). Returns the time scale
503 abbreviation for the offset that is in effect at the instant represented
504 by I<DT>.
505  
506 =cut
507  
508 272 ▶sub short_name_for_datetime {
Subroutine short_name_for_datetime: called CC=2 SCAR=6.9
Pod documented
509 272 my($self, $dt) = @_;
510 272 ▶ return $self->{$self->is_dst_for_datetime($dt) ?
Branch: 1 branch
BranchTrueFalseTotal
$self->is_dst_for_datetime($dt) ? : 135 137 272
511 "dst_abbrev" : "std_abbrev"};
512 }
513  
514 =item $tz->offset_for_local_datetime(DT)
515  
516 I<DT> must be a L<DateTime>-compatible object (specifically, it
517 must implement the C<local_rd_values> method). Takes the local
518 time represented by I<DT> (regardless of what absolute time it also
519 represents), and interprets that as a local time in the timezone of the
520 timezone object (not the timezone used in I<DT>). Returns the offset
521 from UT that is in effect at that local time, in seconds.
522  
523 If the local time given is ambiguous due to a nearby offset change, the
524 numerically lower offset (usually the standard one) is returned with no
525 warning of the situation. If the local time given does not exist due
526 to a nearby offset change, the method C<die>s saying so.
527  
528 =cut
529  
530 172 ▶sub _local_to_utc_rdn_sod($$$) {
Subroutine _local_to_utc_rdn_sod: called CC=3 SCAR=11.3
531 172 my($rdn, $sod, $offset) = @_;
532 172 $sod -= $offset;
533 172 ▶ while($sod < 0) {
Branch: 1 branch
BranchTrueFalseTotal
if ($sod < 0) 0 172 172
534 0 $rdn--;
535 0 $sod += 86400;
536 }
537 172 ▶ while($sod >= 86400) {
Branch: 1 branch
BranchTrueFalseTotal
if ($sod >= 86400) 36 172 208
538 36 $rdn++;
539 36 $sod -= 86400;
540 }
541 172 return ($rdn, $sod);
542 }
543  
544 96 ▶sub _is_dst_for_local_datetime {
Subroutine _is_dst_for_local_datetime: called CC=7 SCAR=19.5
545 96 my($self, $dt) = @_;
546 96 ▶ return 0 unless exists $self->{dst_abbrev};
Branch: 1 branch
BranchTrueFalseTotal
unless exists $self->{"dst_abbrev"} 6 90 96
547 90 ▶ return 1 unless exists $self->{std_abbrev};
Branch: 1 branch
BranchTrueFalseTotal
unless exists $self->{"std_abbrev"} 4 86 90
548 86 my($lcl_rdn, $lcl_sod) = $dt->local_rd_values;
549 86 ▶ $lcl_sod = 86399 if $lcl_sod >= 86400;
Branch: 1 branch
BranchTrueFalseTotal
if $lcl_sod >= 86400 0 86 86
550 my($std_rdn, $std_sod) =
551 86 _local_to_utc_rdn_sod($lcl_rdn, $lcl_sod, $self->{std_offset});
552 my($dst_rdn, $dst_sod) =
553 86 _local_to_utc_rdn_sod($lcl_rdn, $lcl_sod, $self->{dst_offset});
554 86 my $std_ok = !$self->_is_dst_for_utc_rdn_sod($std_rdn, $std_sod);
555 86 my $dst_ok = $self->_is_dst_for_utc_rdn_sod($dst_rdn, $dst_sod);
556 86 ▶ if($std_ok) {
Branch: 1 branch
BranchTrueFalseTotal
if ($std_ok) { } 43 43 86
557 43 ▶ if($dst_ok) {
Branch: 1 branch
BranchTrueFalseTotal
if ($dst_ok) { } 4 39 43
558 4 return $self->{std_offset} > $self->{dst_offset};
559 } else {
560 39 return 0;
561 }
562 } else {
563 43 ▶ if($dst_ok) {
Branch: 1 branch
BranchTrueFalseTotal
if ($dst_ok) { } 39 4 43
564 39 return 1;
565 } else {
566 4 croak "local time @{[
567 4 present_ymd($lcl_rdn + $rdn_epoch_cjdn)
568 ]}T@{[
569 4 sprintf(q(%02d:%02d:%02d),
570 int($lcl_sod/3600),
571 int($lcl_sod/60)%60,
572 $lcl_sod%60)
573 4 ]} does not exist in the @{[$self->{name}]} timezone ".
574 "due to offset change";
575 }
576 }
577 }
578  
579 96 ▶sub offset_for_local_datetime {
Subroutine offset_for_local_datetime: called CC=2 SCAR=6.9
Pod documented
580 96 my($self, $dt) = @_;
581 96 ▶ return $self->{$self->_is_dst_for_local_datetime($dt) ?
Branch: 1 branch
BranchTrueFalseTotal
$self->_is_dst_for_local_datetime($dt) ? : 45 47 92
582 "dst_offset" : "std_offset"};
583 }
584  
585 =back
586  
587 =head1 SEE ALSO
588  
589 L<DateTime>,
590 L<DateTime::TimeZone>,
591 L<POSIX.1|http://www.opengroup.org/onlinepubs/000095399/basedefs/xbd_chap08.html>,
592 L<tzfile(5)>
593  
594 =head1 AUTHOR
595  
596 Andrew Main (Zefram) <zefram@fysh.org>
597  
598 =head1 COPYRIGHT
599  
600 Copyright (C) 2007, 2009, 2010, 2011, 2012, 2013, 2017
601 Andrew Main (Zefram) <zefram@fysh.org>
602  
603 =head1 LICENSE
604  
605 This module is free software; you can redistribute it and/or modify it
606 under the same terms as Perl itself.
607  
608 =cut
609  
610 5 1;
↑ Summary