blib/lib/JSCalendar/Duration.pm

filter: Statementstmt 100% 108 / 108 Branchbran 89.7% 70 / 78 Conditioncond 100% 44 / 44 MC/DCmcdc 100% 24 / 24 Subroutinesub 100% 11 / 11 Podpod 100% 4 / 4 totaltotal 97.0% 261 / 269 CC 55 SCAR 27.5
CC
55
Cov
97%
_seconds_to_duration
24.0
_duration_to_seconds
19.0
signed_duration_to_seconds
5.1
CRAP 15.6
↑ Summary
1 package JSCalendar::Duration 0.006;
2 # ABSTRACT: Convert seconds to JSCalendar durations and back
3  
4 1 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
5 1 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
6  
7 1 ▶use Carp qw(croak);
Subroutine BEGIN: called CC=1 SCAR=0.0
8 1 ▶use Exporter qw(import);
Subroutine BEGIN: called CC=1 SCAR=0.0
9  
10 1 our @EXPORT = qw(seconds_to_duration duration_to_seconds);
11 1 our @EXPORT_OK = qw(seconds_to_signed_duration signed_duration_to_seconds);
12  
13 # The most whole seconds we will convert in either direction. This is the
14 # largest integer that a double can hold exactly, so it is safe on every Perl.
15 1 my $MAX_SECONDS = '9007199254740991'; # 2**53 - 1
16  
17 130 ▶sub duration_to_seconds {
Subroutine duration_to_seconds: called CC=3 SCAR=11.4
Pod documented
18 130 my $input = shift;
19  
20 130 ▶ croak("Usage: duration_to_seconds(\$duration). (Extra args provided: @_)")
Branch: 1 branch
BranchTrueFalseTotal
if @_ 0 130 130
21 if @_;
22  
23 130 ▶ croak('Usage: duration_to_seconds($duration)')
Branch: 1 branch
BranchTrueFalseTotal
unless defined $input 0 130 130
24 unless defined $input;
25  
26 130 return _duration_to_seconds($input, $input);
27 }
28  
29 # Convert $toparse, an unsigned duration, to seconds. $input is what the
30 # public function was given, which may have more to it than $toparse, and is
31 # used in error messages.
32 164 ▶sub _duration_to_seconds {
Subroutine _duration_to_seconds: called CC=19 SCAR=29.4
33 164 my ($input, $toparse) = @_;
34  
35 # Let's get that out of the way
36 164 ▶ return '0' if $toparse eq 'P0D';
Branch: 1 branch
BranchTrueFalseTotal
if $toparse eq "P0D" 8 156 164
37  
38 156 my $seconds = 0;
39  
40 156 ▶ if ($toparse =~ /\P{ASCII}/) {
Branch: 1 branch
BranchTrueFalseTotal
if ($toparse =~ /\P{ASCII}/) 1 155 156
41 1 croak("Invalid duration '$input', must be entirely ASCII");
42 }
43  
44 155 ▶ unless ($toparse =~ s/^P//) {
Branch: 1 branch
BranchTrueFalseTotal
unless ($toparse =~ s/^P//) 14 141 155
45 14 croak("Invalid duration '$input', must start with 'P'");
46 }
47  
48 141 ▶ unless (length $toparse) {
Branch: 1 branch
BranchTrueFalseTotal
unless (length $toparse) 2 139 141
49 2 croak("Invalid duration '$input', no components after 'P'");
50 }
51  
52 # RFC 8984 allows weeks to be followed by days and a time component, unlike
53 # RFC 5545 and earlier JSCalendar drafts, where weeks had to stand alone.
54 139 ▶ if ($toparse =~ s/^(\d+)W//) {
Branch: 1 branch
BranchTrueFalseTotal
if ($toparse =~ s/^(\d+)W//) 20 119 139
55 20 $seconds += (86400 * 7 * $1);
56 }
57  
58 139 ▶ if ($toparse =~ s/^(\d+)D//) {
Branch: 1 branch
BranchTrueFalseTotal
if ($toparse =~ s/^(\d+)D//) 41 98 139
59 41 $seconds += (86400 * $1);
60 }
61  
62 139 ▶ unless (length $toparse) {
Branch: 1 branch
BranchTrueFalseTotal
unless (length $toparse) 17 122 139
63 17 _assert_not_too_many_seconds($input, $seconds);
64 14 return $seconds;
65 }
66  
67 122 ▶ unless ($toparse =~ s/^T//) {
Branch: 1 branch
BranchTrueFalseTotal
unless ($toparse =~ s/^T//) 11 111 122
68 11 croak("Invalid duration '$input', expected T here: '$toparse'");
69 }
70  
71 111 ▶ unless (length $toparse) {
Branch: 1 branch
BranchTrueFalseTotal
unless (length $toparse) 4 107 111
72 4 croak("Invalid duration '$input', no components after 'T'");
73 }
74  
75 107 my ($has_hours, $has_minutes);
76  
77 107 ▶ if ($toparse =~ s/^(\d+)H//) {
Branch: 1 branch
BranchTrueFalseTotal
if ($toparse =~ s/^(\d+)H//) 38 69 107
78 38 $seconds += (3600 * $1);
79 38 $has_hours = 1;
80 }
81  
82 107 ▶ if ($toparse =~ s/^(\d+)M//) {
Branch: 1 branch
BranchTrueFalseTotal
if ($toparse =~ s/^(\d+)M//) 42 65 107
83 42 $seconds += (60 * $1);
84 42 $has_minutes = 1;
85 }
86  
87 107 my $fraction;
88  
89 107 ▶ if ($toparse =~ s/^(\d+)(\.\d+)?S//) {
Branch: 1 branch
BranchTrueFalseTotal
if ($toparse =~ s/^(\d+)(\.\d+)?S//) 77 30 107
90 77 (my $whole, $fraction) = ($1, $2);
91  
92 # In the grammar, dur-hour may only be followed by dur-minute, so seconds
93 # can't come right after hours: PT1H1S must be PT1H0M1S.
94 77 ▶ if ($has_hours && !$has_minutes) {
Branch: 1 branch
BranchTrueFalseTotal
if ($has_hours and not $has_minutes) 6 71 77
Condition100%3/3
$has_hours and not $has_minutes
!ll&&!rl&&r
48236
MC/DC100%2/2
$has_hours and not $has_minutes
$has_hours not $has_minutes
Truth table100%3/3
A and not(B)
A= $has_hoursB= not $has_minutes
ABresult
0X0
100
111
95 6 croak("Invalid duration '$input', seconds may not follow hours without minutes");
96 }
97  
98 # RFC 8984: "Fractional second values MUST NOT have trailing zeros", and
99 # that includes a fraction of all zeros.
100 71 ▶ if (defined $fraction && $fraction =~ /0\z/) {
Branch: 1 branch
BranchTrueFalseTotal
if (defined $fraction and $fraction =~ /0\z/) 7 64 71
Condition100%3/3
defined $fraction and $fraction =~ /0\z/
!ll&&!rl&&r
34307
MC/DC100%2/2
defined $fraction and $fraction =~ /0\z/
defined $fraction $fraction =~ /0\z/
Truth table100%3/3
A and B
A= defined $fractionB= $fraction =~ /0\z/
ABresult
0X0
100
111
101 7 croak("Invalid duration '$input', fractional seconds may not end in zero");
102 }
103  
104 64 $seconds += $whole;
105 }
106  
107 94 ▶ if (length $toparse) {
Branch: 1 branch
BranchTrueFalseTotal
if (length $toparse) 19 75 94
108 19 croak("Invalid duration '$input': confused by '$toparse'");
109 }
110  
111 75 _assert_not_too_many_seconds($input, $seconds);
112  
113 69 ▶ return defined $fraction ? $seconds + $fraction : $seconds;
Branch: 1 branch
BranchTrueFalseTotal
defined $fraction ? : 30 39 69
114 }
115  
116 # $seconds is the whole seconds in the duration $input, added up from its
117 # components. If the true total is over $MAX_SECONDS, the computed one is too,
118 # even if the arithmetic was inexact or overflowed to infinity, because rounding
119 # never carries a value past a number it can represent exactly, like 2**53.
120 92 ▶sub _assert_not_too_many_seconds {
Subroutine _assert_not_too_many_seconds: called CC=2 SCAR=6.9
121 92 my ($input, $seconds) = @_;
122  
123 92 ▶ if ($seconds > $MAX_SECONDS) {
Branch: 1 branch
BranchTrueFalseTotal
if ($seconds > $MAX_SECONDS) 9 83 92
124 9 croak("Invalid duration '$input', whole seconds exceed $MAX_SECONDS");
125 }
126 }
127  
128 71 ▶sub seconds_to_duration {
Subroutine seconds_to_duration: called CC=3 SCAR=11.4
Pod documented
129 71 my $input = shift;
130  
131 71 ▶ croak("Usage: seconds_to_duration(\$seconds). (Extra args provided: @_)")
Branch: 1 branch
BranchTrueFalseTotal
if @_ 0 71 71
132 if @_;
133  
134 71 ▶ croak('Usage: seconds_to_duration($seconds)')
Branch: 1 branch
BranchTrueFalseTotal
unless defined $input 0 71 71
135 unless defined $input;
136  
137 71 return _seconds_to_duration('seconds_to_duration', $input, $input);
138 }
139  
140 # Convert $toparse, a non-negative number of seconds, to a duration. $input is
141 # what the public function, named by $func, was given, which may have more to
142 # it than $toparse, and both are used in error messages.
143 100 ▶sub _seconds_to_duration {
Subroutine _seconds_to_duration: called CC=24 SCAR=31.8
144 100 my ($func, $input, $toparse) = @_;
145  
146 100 ▶ unless (length $toparse) {
Branch: 1 branch
BranchTrueFalseTotal
unless (length $toparse) 4 96 100
147 4 croak("Usage: $func(\$seconds). (Non-number value provided: '$input')");
148 }
149  
150 96 my $dec = q{};
151  
152 # RFC 8984 forbids trailing zeros in the fraction, and forbids a fraction
153 # that is entirely zero, so we drop them, possibly leaving nothing.
154 96 ▶ if ($toparse =~ s/\.([0-9]+)\z//) {
Branch: 1 branch
BranchTrueFalseTotal
if ($toparse =~ s/\.([0-9]+)\z//) 37 59 96
155 37 ($dec = $1) =~ s/0+\z//;
156 }
157  
158 # .1 becomes "", we want 0 after
159 96 ▶ $toparse ||= 0;
Condition100%2/2
$toparse ||= 0
l!l
8511
MC/DC100%1/1
$toparse ||= 0
$toparse
Truth table100%2/2
A
A= $toparse
Aresult
11
00
160  
161 96 ▶ if ($toparse && $toparse !~ /\A[0-9]+\z/) {
Branch: 1 branch
BranchTrueFalseTotal
if ($toparse and not $toparse =~ /\A[0-9]+\z/) 22 74 96
Condition100%3/3
$toparse and not $toparse =~ /\A[0-9]+\z/
!ll&&!rl&&r
116322
MC/DC100%2/2
$toparse and not $toparse =~ /\A[0-9]+\z/
$toparse not $toparse =~ /\A[0-9]+\z/
Truth table100%3/3
A and not(B)
A= $toparseB= not $toparse =~ /\A[0-9]+\z/
ABresult
0X0
100
111
162 22 croak("Usage: $func(\$seconds). (Non-number value provided: '$input')");
163 }
164  
165 # Compare as strings before doing arithmetic, so oversized inputs cannot
166 # overflow or lose precision. This limit is exact even on floating-point
167 # Perl builds; the fractional part is kept separately as a string.
168 74 $toparse =~ s/\A0+(?=[0-9])//;
169 74 ▶ if (length($toparse) > length($MAX_SECONDS)
Branch: 1 branch
BranchTrueFalseTotal
if (length $toparse > length $MAX_SECONDS or length $toparse == length $MAX_SECONDS and $toparse gt $MAX_SECONDS) 7 67 74
Condition100%6/6
length $toparse > length $MAX_SECONDS or length $toparse == length $MAX_SECONDS and $toparse gt $MAX_SECONDS
l!l&&r!l&&!r
4367
length $toparse == length $MAX_SECONDS and $toparse gt $MAX_SECONDS
!ll&&!rl&&r
6253
MC/DC100%3/3
length $toparse > length $MAX_SECONDS or length $toparse == length $MAX_SECONDS and $toparse gt $MAX_SECONDS
length $toparse > length $MAX_SECONDS length $toparse == length $MAX_SECONDS $toparse gt $MAX_SECONDS
Truth table100%4/4
A or B and C
A= length $toparse > length $MAX_SECONDSB= length $toparse == length $MAX_SECONDSC= $toparse gt $MAX_SECONDS
ABCresult
1XX1
0111
00X0
0100
170 || (length($toparse) == length($MAX_SECONDS) && $toparse gt $MAX_SECONDS)) {
171 7 croak("Usage: $func(\$seconds). (Whole seconds exceed $MAX_SECONDS: '$input')");
172 }
173  
174 67 my ($durday, $durtime) = ("", "");
175  
176 # This division may be done in floating point, where the quotient can be
177 # inexact. It is still safe to truncate: below 2**53, the rounding error is
178 # always less than 1/86400, the smallest amount by which a quotient can fall
179 # short of the next whole day, so it can never round up to it. Raising
180 # $MAX_SECONDS would break this.
181 67 my $days = int($toparse / 86400);
182 67 $toparse %= 86400;
183  
184 67 ▶ if ($days && $days % 7 == 0 && $toparse == 0 && !length $dec) {
Branch: 1 branch
BranchTrueFalseTotal
if ($days and $days % 7 == 0 and $toparse == 0 and not length $dec) 4 63 67
Condition100%9/9
$days and $days % 7 == 0 and $toparse == 0 and not length $dec
!ll&&!rl&&r
6124
$days and $days % 7 == 0 and $toparse == 0
!ll&&!rl&&r
6016
$days and $days % 7 == 0
!ll&&!rl&&r
41197
MC/DC100%4/4
$days and $days % 7 == 0 and $toparse == 0 and not length $dec
$days $days % 7 == 0 $toparse == 0 not length $dec
Truth table100%5/5
A and B and C and not(D)
A= $daysB= $days % 7 == 0C= $toparse == 0D= not length $dec
ABCDresult
0XXX0
10XX0
110X0
11100
11111
185 4 return 'P' . ($days/7) . "W";
186 }
187  
188 63 ▶ $durday = "${days}D" if $days;
Branch: 1 branch
BranchTrueFalseTotal
if $days 22 41 63
189  
190 63 my $hours = int($toparse / 3600);
191 63 $toparse %= 3600;
192  
193 63 ▶ $durtime = "${hours}H" if $hours;
Branch: 1 branch
BranchTrueFalseTotal
if $hours 19 44 63
194  
195 63 my $minutes = int($toparse / 60);
196 63 my $seconds = $toparse % 60;
197  
198 # The grammar only permits seconds after minutes, so if we have hours and
199 # seconds, we need minutes even if there are zero of them.
200 63 ▶ $durtime .= "${minutes}M" if $minutes || ($hours && ($seconds || length $dec));
Branch: 1 branch
BranchTrueFalseTotal
if $minutes or $hours and $seconds || length $dec 27 36 63
Condition100%9/9
$minutes or $hours and $seconds || length $dec
l!l&&r!l&&!r
19836
$hours and $seconds || length $dec
!ll&&!rl&&r
3338
$seconds or length $dec
l!l&&r!l&&!r
533
MC/DC100%4/4
$minutes or $hours and $seconds || length $dec
$minutes $hours $seconds length $dec
Truth table100%5/5
A or B and C or D
A= $minutesB= $hoursC= $secondsD= length $dec
ABCDresult
1XXX1
011X1
01011
00XX0
01000
201  
202 63 ▶ if (length $dec) {
Branch: 2 branches
BranchTrueFalseTotal
if (length $dec) { } 26 37 63
elsif ($seconds) { } 18 19 37
203 26 $durtime .= "${seconds}.${dec}S";
204 } elsif ($seconds) {
205 18 $durtime .= "${seconds}S";
206 }
207  
208 # P<zero>D
209 63 ▶ return "P0D" unless $durday || $durtime;
Branch: 1 branch
BranchTrueFalseTotal
unless $durday or $durtime 6 57 63
Condition100%3/3
$durday or $durtime
l!l&&r!l&&!r
22356
MC/DC100%2/2
$durday or $durtime
$durday $durtime
Truth table100%3/3
A or B
A= $durdayB= $durtime
ABresult
1X1
011
000
210  
211 57 ▶ $durtime = "T$durtime" if $durtime;
Branch: 1 branch
BranchTrueFalseTotal
if $durtime 52 5 57
212  
213 57 return "P" . $durday . $durtime;
214 }
215  
216 34 ▶sub signed_duration_to_seconds {
Subroutine signed_duration_to_seconds: called CC=5 SCAR=16.2
Pod documented
217 34 my $input = shift;
218  
219 34 ▶ croak("Usage: signed_duration_to_seconds(\$duration). (Extra args provided: @_)")
Branch: 1 branch
BranchTrueFalseTotal
if @_ 0 34 34
220 if @_;
221  
222 34 ▶ croak('Usage: signed_duration_to_seconds($duration)')
Branch: 1 branch
BranchTrueFalseTotal
unless defined $input 0 34 34
223 unless defined $input;
224  
225 34 my ($sign, $duration) = $input =~ /\A([-+]?)(.*)\z/s;
226  
227 34 my $seconds = _duration_to_seconds($input, $duration);
228  
229 19 ▶ return($sign eq '-' && $seconds != 0 ? -$seconds : $seconds);
Branch: 1 branch
BranchTrueFalseTotal
$sign eq '-' && $seconds != 0 ? : 10 9 19
Condition100%3/3
$sign eq "-" and $seconds != 0
!ll&&!rl&&r
7210
MC/DC100%2/2
$sign eq "-" and $seconds != 0
$sign eq "-" $seconds != 0
Truth table100%3/3
A and B
A= $sign eq "-"B= $seconds != 0
ABresult
0X0
100
111
230 }
231  
232 29 ▶sub seconds_to_signed_duration {
Subroutine seconds_to_signed_duration: called CC=5 SCAR=16.2
Pod documented
233 29 my $input = shift;
234  
235 29 ▶ croak("Usage: seconds_to_signed_duration(\$seconds). (Extra args provided: @_)")
Branch: 1 branch
BranchTrueFalseTotal
if @_ 0 29 29
236 if @_;
237  
238 29 ▶ croak('Usage: seconds_to_signed_duration($seconds)')
Branch: 1 branch
BranchTrueFalseTotal
unless defined $input 0 29 29
239 unless defined $input;
240  
241 29 my ($sign, $seconds) = $input =~ /\A([-+]?)(.*)\z/s;
242  
243 29 my $duration = _seconds_to_duration(
244 'seconds_to_signed_duration',
245 $input,
246 $seconds,
247 );
248  
249 14 ▶ return($sign eq '-' && $duration ne 'P0D' ? "-$duration" : $duration);
Branch: 1 branch
BranchTrueFalseTotal
$sign eq '-' && $duration ne 'P0D' ? : 9 5 14
Condition100%3/3
$sign eq "-" and $duration ne "P0D"
!ll&&!rl&&r
329
MC/DC100%2/2
$sign eq "-" and $duration ne "P0D"
$sign eq "-" $duration ne "P0D"
Truth table100%3/3
A and B
A= $sign eq "-"B= $duration ne "P0D"
ABresult
0X0
100
111
250 }
251  
252 1 1;
253  
254 =pod
255  
256 =encoding UTF-8
257  
258 =head1 NAME
259  
260 JSCalendar::Duration - Convert seconds to JSCalendar durations and back
261  
262 =head1 VERSION
263  
264 version 0.006
265  
266 =head1 SYNOPSIS
267  
268 use JSCalendar::Duration qw(
269 seconds_to_duration
270 duration_to_seconds
271 );
272  
273 # 104403.1
274 my $seconds = duration_to_seconds("P1DT5H0M3.1S");
275  
276 # P1D
277 my $duration = seconds_to_duration('86400');
278  
279 =head1 DESCRIPTION
280  
281 This module converts between a duration of time as specified by seconds and
282 a JSCalendar Duration or SignedDuration, as defined in RFC 8984 sections 1.4.6
283 and 1.4.7.
284  
285 =head1 PERL VERSION
286  
287 This module should work on any version of perl still receiving updates from
288 the Perl 5 Porters. This means it should work on any version of perl
289 released in the last two to three years. (That is, if the most recently
290 released version is v5.40, then this module should work on both v5.40 and
291 v5.38.)
292  
293 Although it may work on older versions of perl, no guarantee is made that the
294 minimum required version will not be increased. The version may be increased
295 for any reason, and there is no promise that patches will be accepted to
296 lower the minimum required perl.
297  
298 =head1 EXPORTS
299  
300 =head2 seconds_to_duration
301  
302 my $duration = seconds_to_duration("86401.2");
303  
304 Converts seconds to a JSCalendar duration representation.
305  
306 The whole seconds must not exceed 9007199254740991 (2**53 - 1), the largest
307 integer in the portable exact integer range. Larger values throw an exception.
308 Fractional seconds are handled separately and do not count toward this limit.
309  
310 =head2 duration_to_seconds
311  
312 my $seconds = duration_to_seconds("P1DT4H");
313  
314 Converts a JSCalendar duration to seconds.
315  
316 The duration must not total more than 9007199254740991 (2**53 - 1) whole
317 seconds, the same limit as C<seconds_to_duration>. Longer durations throw an
318 exception.
319  
320 =head1 OPTIONAL EXPORTS
321  
322 These are not exported by default, but can be requested by name.
323  
324 =head2 seconds_to_signed_duration
325  
326 # -PT15M
327 my $duration = seconds_to_signed_duration(-900);
328  
329 Converts seconds, which may be negative, to a JSCalendar SignedDuration.
330 Negative values get a leading C<->. Positive values and zero get no sign.
331 The magnitude has the same whole-seconds limit as C<seconds_to_duration>.
332  
333 =head2 signed_duration_to_seconds
334  
335 # -900
336 my $seconds = signed_duration_to_seconds("-PT15M");
337  
338 Converts a JSCalendar SignedDuration, which may have a leading C<+> or C<->,
339 to seconds, which will be negative if the duration had a leading C<->.
340 The magnitude has the same whole-seconds limit as C<duration_to_seconds>.
341  
342 =head1 SEE ALSO
343  
344 =over 4
345  
346 =item L<https://www.rfc-editor.org/rfc/rfc8984.html#section-1.4.6>
347  
348 The JSCalendar Duration type, in RFC 8984.
349  
350 =item L<https://www.rfc-editor.org/rfc/rfc8984.html#section-1.4.7>
351  
352 The JSCalendar SignedDuration type, in RFC 8984.
353  
354 =back
355  
356 =head1 AUTHOR
357  
358 Matthew Horsfall <wolfsage@gmail.com>
359  
360 =head1 CONTRIBUTORS
361  
362 =for stopwords Mohammad S Anwar Ricardo Signes
363  
364 =over 4
365  
366 =item *
367  
368 Mohammad S Anwar <mohammad.anwar@yahoo.com>
369  
370 =item *
371  
372 Ricardo Signes <rjbs@semiotic.systems>
373  
374 =item *
375  
376 Ricardo Signes <rjbs@users.noreply.github.com>
377  
378 =back
379  
380 =head1 COPYRIGHT AND LICENSE
381  
382 This software is copyright (c) 2018 by Matthew Horsfall.
383  
384 This is free software; you can redistribute it and/or modify it under
385 the same terms as the Perl 5 programming language system itself.
386  
387 =cut
388  
389 __END__
↑ Summary