Synchronize/Timerange.pm

filter: Statementstmt 81.6% 142 / 174 Branchbran 63.5% 61 / 96 Conditioncond 59.7% 43 / 72 MC/DCmcdc 34.8% 15 / 43 Subroutinesub 81.0% 30 / 37 Podpod 62.9% 17 / 27 totaltotal 68.6% 308 / 449 CC 76 SCAR 22.9
CC
76
Cov
72%
display_time
30.0
normalize
27.3
istypeof
12.0
CRAP 9.9
« Synchronize/GpsPositionCollection.pm ↑ Summary Synchronize/ProgressBar.pm »
1 package Image::Synchronize::Timerange;
2
3 =head1 NAME
4
5 Image::Synchronize::Timerange - a timestamp range class
6
7 =head1 SYNOPSIS
8
9 =head2 Create/Parse
10
11 From two text or L<Image::Synchronize::Timestamp> or numeric values
12
13 $r = Image::Synchronize::Timerange->new($begin, $end);
14
15 From one text value specifying beginning and end
16
17 $r = Image::Synchronize::Timerange->new("$begin/$end");
18
19 From a text or L<Image::Synchronize::Timestamp> or numeric value
20 specifying a range of no duration
21
22 $r = Image::Synchronize::Timerange->new($begin);
23
24 Using object instead of class name as invocant
25
26 $r2 = $r->new($text); # $r2 and $r are unrelated
27
28 Assignment/clone
29
30 $r2 = $r->clone; # assigns a clone
31 $r2 = $r; # copies *reference*; $t and $t2 refer to the same object
32
33 =head2 Stringify
34
35 $r = Image::Synchronize::Timerange
36 ->new('2001-02-03T04:05:06+07:00/11:15');
37 print "$r"; # ISO8601 format: '2001-02-03T04:05:06+07:00/11:15'
38 print $r->stringify # same as previous
39 print $r->display_iso; # same as previous
40 print $r->display_utc; # ISO in UTC: 2001-02-02T21:05:06Z/03T04:15
41 print $r->display_time; # no dates
42
43 =head2 Query
44
45 Extract the beginning and end as L<Image::Synchronize::Timestamp>:
46
47 $timestamp_begin = $r->begin;
48 $timestamp_end = $r->end;
49
50 Number of non-leap seconds since the epoch
51
52 ($time_local_begin, $time_local_end) = $r->time_local;
53 ($time_utc_begin, $time_utc_end) = $r->time_utc;
54
55 Timezone offset in seconds relative to UTC
56
57 ($timezone_offset_begin, $timezone_offset_end) = $r->timezone_offset;
58
59 In scalar context refers only to range beginning
60
61 $time_local_begin = $r->time_local;
62 $time_utc_begin = $r->time_utc;
63 $timezone_offset_begin = $r->timezone_offset;
64
65 The duration
66
67 $duration = $r->duration;
68
69 Check if an instant is within the time range
70
71 $bool = $r->contains_instant($instant);
72 $bool = $r->contains_local($instant);
73
74 Check for presence of parts
75
76 $bool = $r->has_timezone_offset;
77 $bool = $r->is_empty;
78
79 Check type
80
81 Image::Synchronize::Timerange->istypeof($r); # true
82 Image::Synchronize::Timerange->istypeof(6); # false
83 $r->istypeof(6); # same as previous
84
85 =head2 Combine
86
87 $r2 = $r + 30; # shift copy forward by 30 seconds
88 $r2 = 30 + $r; # same as previous
89 $r += 30; # shift forward by 30 seconds
90 $r3 = $r + $r2 # ERROR: cannot add timeranges
91
92 $r2 = $r - 30; # shift copy backward by 30 seconds
93 $r -= 30; # shift backward by 30 seconds
94 $r3 = $r - $r2; # ERROR: cannot subtract timeranges
95
96 =head2 Compare
97
98 $r2 == $r; # same range
99 $r2 != $r; # not the same range
100 $r->identical($r2); # same clock times and timezone
101 $r <=> $r2; # three way comparison
102 # < <= => > can also be used, but the interpretation is not obvious
103
104 =head2 Modify
105
106 $r->set_from_text($text); # replace old value
107 $r->adjust_timezone_offset($offset);
108
109 =head1 METHODS
110
111 =cut
112
113 3 ▶use Modern::Perl;
Subroutine BEGIN: called CC=1 SCAR=0.0
114
115 3 ▶use Carp;
Subroutine BEGIN: called CC=1 SCAR=0.0
116 3 ▶use Clone qw(clone);
Subroutine BEGIN: called CC=1 SCAR=0.0
117 3 ▶use Image::Synchronize::Timestamp;
Subroutine BEGIN: called CC=1 SCAR=0.0
118 3 ▶use Scalar::Util qw(blessed looks_like_number);
Subroutine BEGIN: called CC=1 SCAR=0.0
119
120 3 ▶use parent qw(Clone);
Subroutine BEGIN: called CC=1 SCAR=0.0
121
122 use overload
123 3 ▶ '=' => \&clone,
Subroutine BEGIN: called CC=1 SCAR=0.0
124 '-' => \&subtract,
125 '+' => \&add,
126 '""' => \&stringify,
127 3 '<=>' => \&three_way_cmp;
128
129 =head2 new
130
131 # empty range
132 $r = Image::Synchronize::Timerange->new;
133
134 # from two values (L<Image::Synchronize::Timestamp> or text or
135 # numbers)
136 $r = Image::Synchronize::Timerange->new($begin, $end);
137
138 # from a single text value specifying begin and end:
139 $r = Image::Synchronize::Timerange->new("$begin/$end");
140
141 # a range of length zero
142 $r = Image::Synchronize::Timerange->new($begin);
143
144 Construct a new instance.
145
146 The beginning and (optionally) end of the range can each be instances
147 of L<Image::Synchronize::Timestamp>, and can also be specified in the
148 same ways as for L<Image::Synchronize::Timestamp/new>. If the date or
149 timezone offset are missing from one but present in the other, then
150 they are shared with the peer.
151
152 If the range beginning and end are specified in a single text value
153 (separated by C</>), then if the beginning or end are unsigned numbers
154 then they're not interpreted as "seconds since the epoch" (as
155 L<Image::Synchronize::Timestamp/new> does) but as clock hours. So,
156
157 '2001-02-03T04:05:06/07'
158
159 is interpreted as
160
161 '2001-02-03T04:05:06/2001-02-03T07:00'
162
163 Returns C<undef> if invalid arguments are supplied, including if the
164 range end comes before the range beginning.
165
166 =cut
167
168 82 ▶sub new {
Subroutine new: called CC=10 SCAR=24.7
Pod documented
169 82 my $invocant = shift;
170 82 ▶ my $class = ref($invocant) || $invocant; # object or class name
Condition33%1/3
ref $invocant || $invocant
l!l&&r!l&&!r
0820
MC/DC0%0/2
ref $invocant || $invocant
ref $invocant $invocant
Truth table33%1/3
A || B
A= ref $invocantB= $invocant
ABresult
1X1
011
000
171 82 my $self = bless {}, $class;
172 82 ▶ if ( scalar(@_) == 1 ) {
Branch: 2 branches
BranchTrueFalseTotal
if (scalar @_ == 1) { } 78 4 82
elsif (scalar @_ >= 2) { } 3 1 4
173 78 ▶ if ( Image::Synchronize::Timestamp->istypeof( $_[0] ) ) {
Branch: 1 branch
BranchTrueFalseTotal
if ('Image::Synchronize::Timestamp'->istypeof($_[0])) { } 0 78 78
174
175 0 $self->{begin} = $_[0]->clone;
176 }
177 else {
178 78 ▶ return unless defined $self->set_from_text( $_[0] );
Branch: 1 branch
BranchTrueFalseTotal
unless defined $self->set_from_text($_[0]) 1 77 78
179 }
180 }
181 elsif ( scalar(@_) >= 2 ) {
182 3 my @values;
183 3 foreach ( 0 .. 1 ) {
184 6 ▶ if ( Image::Synchronize::Timestamp->istypeof( $_[$_] ) ) {
Branch: 1 branch
BranchTrueFalseTotal
if ('Image::Synchronize::Timestamp'->istypeof($_[$_])) { } 0 6 6
185 0 $values[$_] = $_[$_]->clone;
186 }
187 else {
188 6 $values[$_] = Image::Synchronize::Timestamp->new( $_[$_] );
189 }
190 }
191 3 ▶ return unless defined $values[0] and defined $values[1];
Branch: 1 branch
BranchTrueFalseTotal
unless defined $values[0] and defined $values[1] 0 3 3
Condition33%1/3
defined $values[0] and defined $values[1]
!ll&&!rl&&r
003
MC/DC0%0/2
defined $values[0] and defined $values[1]
defined $values[0] defined $values[1]
Truth table33%1/3
A and B
A= defined $values[0]B= defined $values[1]
ABresult
0X0
100
111
192 3 $self->{begin} = $values[0];
193 3 $self->{end} = $values[1];
194 }
195 81 return $self->normalize;
196 }
197
198 =head2 clone
199
200 $r2 = $r->clone;
201
202 Returns a clone of C<$r>. The clone is a deep copy of the original,
203 so a subsequent change of the original does not affect the clone.
204
205 =cut
206
207 # no code; provided by package Clone
208
209 =head2 stringify
210
211 $text = $r->stringify;
212 $text = "$r";
213
214 Returns a text version of C<$r>, in ISO 8601 format.
215
216 If C<$r> is empty, then C<< $t->stringify >> returns C<undef>, and
217 C<"$r"> returns C<''>.
218
219 =cut
220
221 27 ▶sub stringify {
Subroutine stringify: called CC=7 SCAR=19.6
Pod documented
222 27 my ($self) = @_;
223 27 ▶ return "" unless $self->begin;
Branch: 1 branch
BranchTrueFalseTotal
unless $self->begin 1 26 27
224 26 my $text = $self->begin->display_iso;
225 26 ▶ if ( $self->{end} ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($self->{"end"}) 26 0 26
226 26 my $text2 = $self->end->display_iso;
227 26 ▶ if ( $text2 ne $text ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($text2 ne $text) 13 13 26
228 13 my ($date) = $text =~ /^(.*?T)/;
229 13 ▶ if ( $text2 =~ /^\Q$date\E(.*)$/ ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($text2 =~ /^\Q$date\E(.*)$/u) 13 0 13
230
231 # range end has same date as range beginning; omit date
232 13 $text2 = $1;
233 }
234 13 my ($timezone) = $text =~ /([-+][^-+]+)$/;
235 13 ▶ if ( defined($timezone) and $text2 =~ /^(.*?)\Q$timezone\E$/ ) {
Branch: 1 branch
BranchTrueFalseTotal
if (defined $timezone and $text2 =~ /^(.*?)\Q$timezone\E$/u) 7 6 13
Condition66%2/3
defined $timezone and $text2 =~ /^(.*?)\Q$timezone\E$/u
!ll&&!rl&&r
067
MC/DC50%1/2
defined $timezone and $text2 =~ /^(.*?)\Q$timezone\E$/u
defined $timezone $text2 =~ /^(.*?)\Q$timezone\E$/u
Truth table66%2/3
A and B
A= defined $timezoneB= $text2 =~ /^(.*?)\Q$timezone\E$/u
ABresult
0X0
100
111
236
237 # range end has same timezone as range beginning; omit timezone
238 7 $text2 = $1;
239 }
240 13 $text = "$text/$text2";
241 }
242 }
243 26 return $text;
244 }
245
246 =head display_iso
247
248 $text = $r->display_iso;
249
250 An alias for L</stringify>.
251
252 =cut
253
254 0 ▶sub display_iso {
Subroutine display_iso: not called CC=1 SCAR=6.9
Pod undocumented
255 0 stringify(@_);
256 }
257
258 =head2 display_utc
259
260 $text = $r->display_utc;
261
262 Displays the time range relative to UTC, in ISO-8601 format.
263
264 =cut
265
266 0 ▶sub display_utc {
Subroutine display_utc: not called CC=1 SCAR=6.9
Pod documented
267 0 my ($self) = @_;
268 return $self->new($self->{begin}->adjust_to_utc,
269 0 $self->{end}->adjust_to_utc)->display_iso;
270 }
271
272 =head2 display_time
273
274 $text = $r->display_time;
275
276 Returns a text version of $r with the range beginning and (if present)
277 end as signed time values since the epoch in the associated timezone,
278 followed by the designation of that timezone. The hour number is not
279 restricted to be less than 24 and can be negative.
280
281 This is useful for time ranges without dates. If C<$r> was created
282 with date parts, then the displayed number of hours is likely to be
283 very large.
284
285 =cut
286
287 0 ▶sub display_time {
Subroutine display_time: not called CC=5 SCAR=34.0
Pod documented
288 0 my ($self) = @_;
289 0 ▶ my $front = defined($self->{begin})? $self->{begin}->display_time : '';
Branch: 1 branch
BranchTrueFalseTotal
defined $self->{'begin'} ? : 0 0 0
290 0 ▶ return '' if $front eq '';
Branch: 1 branch
BranchTrueFalseTotal
if $front eq "" 0 0 0
291 0 ▶ my $back = defined($self->{end})? $self->{end}->display_time: '';
Branch: 1 branch
BranchTrueFalseTotal
defined $self->{'end'} ? : 0 0 0
292 0 ▶ return $front . ($back? "/$back": '');
Branch: 1 branch
BranchTrueFalseTotal
$back ? : 0 0 0
293 }
294
295 =head2 begin
296
297 $t = $r->begin;
298
299 Returns an L<Image::Synchronize::Timestamp> representing the beginning
300 of the range.
301
302 =cut
303
304 751 ▶sub begin {
Subroutine begin: called CC=1 SCAR=0.0
Pod documented
305 751 my ($self) = @_;
306 751 return $self->{begin};
307 }
308
309 =head2 end
310
311 $t = $r->end;
312
313 Returns an L<Image::Synchronize::Timestamp> representing the end of
314 the range.
315
316 =cut
317
318 483 ▶sub end {
Subroutine end: called CC=1 SCAR=0.0
Pod documented
319 483 my ($self) = @_;
320 483 return $self->{end};
321 }
322
323 =head2 time_local
324
325 @time = $r->time_local; # range begin and end
326 $time = $r->time_local; # range begin only
327
328 Returns the number of non-leap seconds since the epoch in the timezone
329 associated with the timestamp, if known. Otherwise returns C<undef>.
330
331 In list context, processes both the beginning and end of the range.
332 In scalar context, processes only the beginning.
333
334 =cut
335
336 8 ▶sub time_local {
Subroutine time_local: called CC=1 SCAR=0.0
Pod documented
337 8 my ($self) = @_;
338 8 ▶ return $self->per_timestamp_( sub { $_[0]->time_local } );
Subroutine __ANON__: called CC=1 SCAR=0.0
339 }
340
341 =head2 time_utc
342
343 @time = $r->time_utc; # range begin and end
344 $time = $r->time_local; # range begin only
345
346 Returns the number of non-leap seconds since the epoch in UTC, if
347 known. Otherwise returns C<undef>.
348
349 In list context, processes both the beginning and end of the range.
350 In scalar context, processes only the beginning.
351
352 =cut
353
354 8 ▶sub time_utc {
Subroutine time_utc: called CC=1 SCAR=0.0
Pod documented
355 8 my ($self) = @_;
356 8 ▶ return $self->per_timestamp_( sub { $_[0]->time_utc } );
Subroutine __ANON__: called CC=1 SCAR=0.0
357 }
358
359 =head2 timezone_offset
360
361 @offset = $r->timezone_offset;
362 $offset = $r->timezone_offset;
363
364 Returns the timezone offset from UTC in seconds, if known. Otherwise
365 returns C<undef>.
366
367 In list context, processes both the beginning and end of the range.
368 In scalar context, processes only the beginning.
369
370 =cut
371
372 8 ▶sub timezone_offset {
Subroutine timezone_offset: called CC=1 SCAR=0.0
Pod documented
373 8 my ($self) = @_;
374 8 ▶ return $self->per_timestamp_( sub { $_[0]->timezone_offset } );
Subroutine __ANON__: called CC=1 SCAR=0.0
375 }
376
377 =head2 length
378
379 $l = $r->duration;
380
381 Returns the duration of the time range, in seconds.
382
383 =cut
384
385 8 ▶sub duration {
Subroutine duration: called CC=1 SCAR=0.0
Pod undocumented
386 8 my ($self) = @_;
387 8 return $self->end - $self->begin;
388 }
389
390 =head2 has_timezone_offset
391
392 $bool = $r->has_timezone_offset;
393
394 Returns a true value if the time range has a timezone offset, and a
395 false value otherwise.
396
397 =cut
398
399 0 ▶sub has_timezone_offset {
Subroutine has_timezone_offset: not called CC=1 SCAR=6.9
Pod documented
400 0 my ($self) = @_;
401 0 return $self->begin->has_timezone_offset;
402 }
403
404 =head2 is_empty
405
406 Returns a true value if the time range is empty, i.e., has no
407 beginning and no end. Returns a false value otherwise.
408
409 =cut
410
411 0 ▶sub is_empty {
Subroutine is_empty: not called CC=1 SCAR=6.9
Pod documented
412 0 my ($self) = @_;
413 0 return $self->begin->is_empty;
414 }
415
416 =head2 istypeof
417
418 $ok = $class->istypeof($item);
419 $ok = $object->istypeof($item); # queries $item, not $object
420
421 Returns a true value if C<$item> is an instance of (a subclass of) the
422 specified C<$class>, or of the class that the specified C<$object>
423 belongs to. Returns a false value otherwise, including when C<$item>
424 is not an object.
425
426 =cut
427
428 0 ▶sub istypeof {
Subroutine istypeof: not called CC=3 SCAR=24.8
Pod documented
429 0 my $invocant = shift;
430 0 ▶ my $class = ref($invocant) || $invocant; # object or class name
Condition0%0/3
ref $invocant || $invocant
l!l&&r!l&&!r
000
MC/DC0%0/2
ref $invocant || $invocant
ref $invocant $invocant
Truth table0%0/3
A || B
A= ref $invocantB= $invocant
ABresult
1X1
011
000
431 0 my ( $value ) = @_;
432 0 ▶ return blessed($value) && $value->isa($class);
Condition0%0/3
builtin::blessed($value) && $value->isa($class)
!ll&&!rl&&r
000
MC/DC0%0/2
builtin::blessed($value) && $value->isa($class)
builtin::blessed($value) $value->isa($class)
Truth table0%0/3
A && B
A= builtin::blessed($value)B= $value->isa($class)
ABresult
0X0
100
111
433 }
434
435 =head2 contains_instant
436
437 $ok = $r->contains_instant($instant);
438
439 If C<$instant> is a number, then it is interpreted as a "time" value
440 as returned by the C<time> function; i.e., the number of non-leap
441 seconds since the epoch, in UTC. Returns a true value if C<$r> has a
442 timezone offset and if the specified instant of time is not outside of
443 the range, or a defined but false value if C<$r> has a timezone offset
444 but the specified instant of time is outside of the range, or C<undef>
445 if C<$r> has no timezone offset so that its relationship with UTC is
446 unknown.
447
448 If C<$instant> is an L<Image::Synchronize::Timestamp>, then returns
449 C<undef> if C<$instant> has a timezone offset but C<$r> does not, or
450 vice versa. Otherwise, returns a true value if the instant of time is
451 not outside of the range, or a defined but false value if the instant
452 of time is outside of the range.
453
454 Both boundaries are included in the range.
455
456 =cut
457
458 12 ▶sub contains_instant {
Subroutine contains_instant: called CC=6 SCAR=18.0
Pod documented
459 12 my ( $self, $instant ) = @_;
460 12 ▶ if ( blessed($instant)
Branch: 1 branch
BranchTrueFalseTotal
if (builtin::blessed($instant) and 'Image::Synchronize::Timestamp'->istypeof($instant)) { } 6 6 12
Condition66%2/3
builtin::blessed($instant) and "Image::Synchronize::Timestamp"->istypeof($instant)
!ll&&!rl&&r
606
MC/DC50%1/2
builtin::blessed($instant) and "Image::Synchronize::Timestamp"->istypeof($instant)
builtin::blessed($instant) "Image::Synchronize::Timestamp"->istypeof($instant)
Truth table66%2/3
A and B
A= builtin::blessed($instant)B= "Image::Synchronize::Timestamp"->istypeof($instant)
ABresult
0X0
100
111
461 and Image::Synchronize::Timestamp->istypeof($instant) )
462 {
463 6 ▶ return ( $instant >= $self->begin && $instant <= $self->end );
Condition100%3/3
$instant >= $self->begin && $instant <= $self->end
!ll&&!rl&&r
114
MC/DC100%2/2
$instant >= $self->begin && $instant <= $self->end
$instant >= $self->begin $instant <= $self->end
Truth table100%3/3
A && B
A= $instant >= $self->beginB= $instant <= $self->end
ABresult
0X0
100
111
464 }
465 else { # assume it's a time value
466 # return undef if range has no timezone offset (because then we
467 # cannot tell where UTC instant is compared to it)
468 6 ▶ return unless defined $self->begin->timezone_offset;
Branch: 1 branch
BranchTrueFalseTotal
unless defined $self->begin->timezone_offset 0 6 6
469 6 ▶ return ( $instant >= $self->begin->time_utc
Condition100%3/3
$instant >= $self->begin->time_utc && $instant <= $self->end->time_utc
!ll&&!rl&&r
114
MC/DC100%2/2
$instant >= $self->begin->time_utc && $instant <= $self->end->time_utc
$instant >= $self->begin->time_utc $instant <= $self->end->time_utc
Truth table100%3/3
A && B
A= $instant >= $self->begin->time_utcB= $instant <= $self->end->time_utc
ABresult
0X0
100
111
470 && $instant <= $self->end->time_utc );
471 }
472 }
473
474 =head2 contains_local
475
476 $ok = $r->contains_local($instant);
477
478 Like L</contains_instant>, but disregarding timezone offsets.
479
480 If C<$instant> is a number, then it is interpreted as a "time" value
481 as returned by the C<time> function; i.e., the number of non-leap
482 seconds since the epoch. Otherwise, C<$instant> must be an
483 L<Image::Synchronize::Timestamp>.
484
485 Returns a true value if the time indicated by C<$instant>,
486 disregarding its timezone offset if any, is within (not outside) the
487 range indicated by C<$r>, also disregarding its timezone offset if
488 any. Otherwise returns a false value.
489
490 =cut
491
492 18 ▶sub contains_local {
Subroutine contains_local: called CC=3 SCAR=11.0
Pod documented
493 18 my ( $self, $time ) = @_;
494 18 ▶ $time = $time->time_local
Branch: 1 branch
BranchTrueFalseTotal
if ref $time 18 0 18
495 if ref $time; # assume an Image::Synchronize::Timestamp
496 18 ▶ return $self->begin->{time} <= $time && $self->end->{time} >= $time;
Condition100%3/3
$self->begin->{'time'} <= $time && $self->end->{'time'} >= $time
!ll&&!rl&&r
3312
MC/DC100%2/2
$self->begin->{'time'} <= $time && $self->end->{'time'} >= $time
$self->begin->{'time'} <= $time $self->end->{'time'} >= $time
Truth table100%3/3
A && B
A= $self->begin->{'time'} <= $timeB= $self->end->{'time'} >= $time
ABresult
0X0
100
111
497 }
498
499 =head2 +
500
501 $shifted = $r + $offset;
502 $shifted = $offset + $r;
503
504 Returns a range that is like C<$r> but shifted into the future by
505 C<$offset> seconds.
506
507 =cut
508
509 1 ▶sub add {
Subroutine add: called CC=3 SCAR=11.6
Pod undocumented
510 1 my ( $self, $other, $swap ) = @_;
511 1 ▶ if ( ref($other) ) {
Branch: 1 branch
BranchTrueFalseTotal
if (ref $other) 0 1 1
512 0 croak "Sorry, cannot add a "
513 . ref($other)
514 . " to an Image::Synchronize::Timerange\n";
515 }
516 1 my $result = $self->clone;
517 1 $result->{begin} += $other;
518 1 ▶ $result->{end} += $other if $result->{end};
Branch: 1 branch
BranchTrueFalseTotal
if $result->{"end"} 1 0 1
519 1 return $result;
520 }
521
522 =head2 -
523
524 $shifted = $r - $offset;
525
526 Returns a range that is like C<$r> but shifted into the past by
527 C<$offset> seconds.
528
529 =cut
530
531 1 ▶sub subtract {
Subroutine subtract: called CC=3 SCAR=11.6
Pod undocumented
532 1 my ( $self, $other, $swap ) = @_;
533 1 ▶ if ( ref($other) ) {
Branch: 1 branch
BranchTrueFalseTotal
if (ref $other) 0 1 1
534 0 croak "Sorry, cannot subtract a " . ref($other)
535 . " from an Image::Synchronize::Timerange\n";
536 }
537 1 my $result = $self->clone;
538 1 $result->{begin} -= $other;
539 1 ▶ $result->{end} -= $other if $result->{end};
Branch: 1 branch
BranchTrueFalseTotal
if $result->{"end"} 1 0 1
540 1 return $result;
541 }
542
543
544 =head2 <=>
545
546 $r1 <=> $r2;
547
548 Returns an integer value between -3 and +3, inclusive, that indicates
549 the position of range C<$r1> relative to that of range C<$r2>.
550 Returns 0 only if the two ranges indicate the same period of time
551 (when reduced to the same timezone). Returns a negative number if
552 C<$r1> is deemed to come before C<$r2>, or a positive number if C<$r1>
553 is deemed to come after C<$r2>.
554
555 If C<$r1> is entirely before C<$r2> (i.e., the end of C<$r1> comes
556 before the beginning of C<$r2>), then returns -3.
557
558 Otherwise, if C<$r1> is entirely after C<$r2> (i.e., the beginning of
559 C<$r1> comes after the end of C<$r2>), then returns +3.
560
561 Otherwise C<$r1> and C<$r2> overlap in at least one point. If the
562 middle time of C<$r1> comes before the middle time of C<$r2>, then
563 returns -2.
564
565 Otherwise, if the middle time of C<$r1> comes after the middle time
566 of C<$r2>, then returns +2.
567
568 Otherwise, the middle times are equal. Then returns -1, 0, or +1
569 depending on whether the begin time of C<$r1> comes before, is equal
570 to, or comes after the begin time of C<$r2>.
571
572 If any of the relevant timestamps lack a timezone offset, then they
573 are assumed to be in the same timezone. Otherwise the timezone
574 offsets are taken into account.
575
576 =head2 ==
577
578 $r1 == $r2;
579
580 Returns a true value if C<< <=> >> returns 0, ie., when the two ranges
581 represent the same interval of time (when reduced to the same
582 timezone).
583
584 =head2 !=
585
586 $r1 != $r2;
587
588 Returns a true value if C<< <=> >> returns non-0, i.e., when the two
589 ranges do not represent the same interval of time (when reduced to the
590 same timezone).
591
592 =head < <= => >
593
594 $r1 < $r2;
595 $r1 <= $r2;
596 $r1 => $r2;
597 $r1 > $r2;
598
599 Returns a true value if C<< <=> >> returns a negative value, a zero or
600 negative value, a zero or positive value, or a positive value,
601 respectively.
602
603 =cut
604
605 92 ▶sub three_way_cmp {
Subroutine three_way_cmp: called CC=5 SCAR=16.1
Pod undocumented
606 92 my ( $self, $other, $swap ) = @_;
607 92 ▶ return -3 if $self->end < $other->begin;
Branch: 1 branch
BranchTrueFalseTotal
if $self->end < $other->begin 14 78 92
608 78 ▶ return +3 if $self->begin > $other->end;
Branch: 1 branch
BranchTrueFalseTotal
if $self->begin > $other->end 14 64 78
609 64 my $middle1 = $self->begin + ( $self->end - $self->begin ) * 0.5;
610 64 my $middle2 = $other->begin + ( $other->end - $other->begin ) * 0.5;
611 64 ▶ return -2 if $middle1 < $middle2;
Branch: 1 branch
BranchTrueFalseTotal
if $middle1 < $middle2 17 47 64
612 47 ▶ return +2 if $middle1 > $middle2;
Branch: 1 branch
BranchTrueFalseTotal
if $middle1 > $middle2 17 30 47
613 30 return $self->begin <=> $other->begin;
614 }
615
616 =head2 identical
617
618 $r1->identical($r2);
619
620 Returns a true value if the two L<Image::Synchronize::Timerange>s are
621 identical, and a false value otherwise. They are identical if the
622 local time and the timezone offset of the beginning and end of the
623 range are equal between both instances.
624
625 =cut
626
627 26 ▶sub identical {
Subroutine identical: called CC=6 SCAR=19.3
Pod documented
628 26 my ( $self, $other ) = @_;
629
630 # if begin or end is defined in the one but not the other, then they
631 # are not identical
632 return
633 26 ▶ if defined( $self->begin ) != defined( $other->begin )
Branch: 1 branch
BranchTrueFalseTotal
if defined $self->begin != defined $other->begin or defined $self->end != defined $other->end 0 26 26
Condition33%1/3
defined $self->begin != defined $other->begin or defined $self->end != defined $other->end
l!l&&r!l&&!r
0026
MC/DC0%0/2
defined $self->begin != defined $other->begin or defined $self->end != defined $other->end
defined $self->begin != defined $other->begin defined $self->end != defined $other->end
Truth table33%1/3
A or B
A= defined $self->begin != defined $other->beginB= defined $self->end != defined $other->end
ABresult
1X1
011
000
634 or defined( $self->end ) != defined( $other->end );
635
636 # now begin and end are either defined in both or else not defined
637 # in both.
638
639 return (
640 (
641 26 ▶ not( defined( $self->begin ) )
Condition77%7/9
(!defined($self->begin) || $self->begin->identical($other->begin)) && (!defined($self->end) || $self->end->identical($other->end))
!ll&&!rl&&r
1448
not defined $self->begin or $self->begin->identical($other->begin)
l!l&&r!l&&!r
01214
not defined $self->end or $self->end->identical($other->end)
l!l&&r!l&&!r
084
MC/DC50%2/4
(!defined($self->begin) || $self->begin->identical($other->begin)) && (!defined($self->end) || $self->end->identical($other->end))
not defined $self->begin $self->begin->identical($other->begin) not defined $self->end $self->end->identical($other->end)
Truth table42%3/7
not(A) or B && not(C) or D
A= not defined $self->beginB= $self->begin->identical($other->begin)C= not defined $self->endD= $self->end->identical($other->end)
ABCDresult
00XX0
1X000
01000
1X1X1
1X011
011X1
01011
642 or $self->begin->identical( $other->begin )
643 )
644 and ( not( defined( $self->end ) )
645 or $self->end->identical( $other->end ) )
646 );
647 }
648
649 =head2 set_from_text
650
651 $r->set_from_text($text);
652
653 Set the range based on the C<$text> (similar to C<<
654 Image::Synchronize::Timerange->new($text) >>, discarding any previous
655 contents of C<$r>.
656
657 Returns C<$r>.
658
659 =cut
660
661 83 ▶sub set_from_text {
Subroutine set_from_text: called CC=10 SCAR=23.4
Pod documented
662 83 my ( $self, $text ) = @_;
663 83 delete $self->{$_} foreach qw(begin end);
664 83 ▶ if ( my ( $value1, $value2 ) = $text =~ m|^(.*?)/(.+)$| ) {
Branch: 1 branch
BranchTrueFalseTotal
if (() = $text =~ m[^(.*?)/(.+)$]u) { } 49 34 83
665 # we disallow interpretation of isolated unsigned number as
666 # "seconds from epoch" here
667 49 ▶ $value1 = "$value1:00" if $value1 =~ /^\d+$/;
Branch: 1 branch
BranchTrueFalseTotal
if $value1 =~ /^\d+$/u 0 49 49
668 49 ▶ $value2 = "$value2:00" if $value2 =~ /^\d+$/;
Branch: 1 branch
BranchTrueFalseTotal
if $value2 =~ /^\d+$/u 1 48 49
669 49 my $begin = Image::Synchronize::Timestamp->new($value1);
670 49 my $end = Image::Synchronize::Timestamp->new($value2);
671 49 ▶ return unless (defined($begin) && defined($end));
Branch: 1 branch
BranchTrueFalseTotal
unless defined $begin and defined $end 1 48 49
Condition66%2/3
defined $begin and defined $end
!ll&&!rl&&r
1048
MC/DC50%1/2
defined $begin and defined $end
defined $begin defined $end
Truth table66%2/3
A and B
A= defined $beginB= defined $end
ABresult
0X0
100
111
672 48 ▶ $self->{begin} = $begin if defined $begin;
Branch: 1 branch
BranchTrueFalseTotal
if defined $begin 48 0 48
673 48 ▶ $self->{end} = $end if defined $end;
Branch: 1 branch
BranchTrueFalseTotal
if defined $end 48 0 48
674 } else {
675 34 my $begin = Image::Synchronize::Timestamp->new($text);
676 34 ▶ return unless defined $begin;
Branch: 1 branch
BranchTrueFalseTotal
unless defined $begin 0 34 34
677 34 $self->{begin} = $begin;
678 };
679 82 return $self->normalize;
680 }
681
682 =head2 adjust_timezone_offset
683
684 $r->adjust_timezone_offset($offset);
685
686 Adjusts the timezone of the beginning and end of the range to
687 C<$offset> seconds relative to UTC.
688
689 If the beginning or end of the range already had a timezone offset and
690 if C<$offset> is defined, then the local time of the beginning or end
691 gets adjusted such that the indicated instant of time remains the
692 same.
693
694 If the beginning and end of the range already had a timezone offset
695 and if C<$_offset> is undefined, then the local time of the end of the
696 range is converted into the same timezone as the beginning of the
697 range before the timezone offsets are removed, so that the length of
698 the range remains the same.
699
700 Returns the instance after adjustment.
701
702 =cut
703
704 39 ▶sub adjust_timezone_offset {
Subroutine adjust_timezone_offset: called CC=7 SCAR=19.6
Pod documented
705 39 my ( $self, $target_timezone_offset ) = @_;
706 39 ▶ if ( $self->{end}
Branch: 1 branch
BranchTrueFalseTotal
if ($self->{"end"} and defined $self->{"end"}->timezone_offset and defined $self->{"begin"}->timezone_offset and $self->{"begin"}->timezone_offset != $self->{"end"}->timezone_offset and not defined $target_timezone_offset) 1 38 39
Condition83%10/12
$self->{"end"} and defined $self->{"end"}->timezone_offset and defined $self->{"begin"}->timezone_offset and $self->{"begin"}->timezone_offset != $self->{"end"}->timezone_offset and not defined $target_timezone_offset
!ll&&!rl&&r
3621
$self->{"end"} and defined $self->{"end"}->timezone_offset and defined $self->{"begin"}->timezone_offset and $self->{"begin"}->timezone_offset != $self->{"end"}->timezone_offset
!ll&&!rl&&r
21153
$self->{"end"} and defined $self->{"end"}->timezone_offset and defined $self->{"begin"}->timezone_offset
!ll&&!rl&&r
21018
$self->{"end"} and defined $self->{"end"}->timezone_offset
!ll&&!rl&&r
02118
MC/DC60%3/5
$self->{"end"} and defined $self->{"end"}->timezone_offset and defined $self->{"begin"}->timezone_offset and $self->{"begin"}->timezone_offset != $self->{"end"}->timezone_offset and not defined $target_timezone_offset
$self->{"end"} defined $self->{"end"}->timezone_offset defined $self->{"begin"}->timezone_offset $self->{"begin"}->timezone_offset != $self->{"end"}->timezone_offset not defined $target_timezone_offset
Truth table66%4/6
A and B and C and D and not(E)
A= $self->{"end"}B= defined $self->{"end"}->timezone_offsetC= defined $self->{"begin"}->timezone_offsetD= $self->{"begin"}->timezone_offset != $self->{"end"}->timezone_offsetE= not defined $target_timezone_offset
ABCDEresult
0XXXX0
10XXX0
110XX0
1110X0
111100
111111
707 and defined( $self->{end}->timezone_offset )
708 and defined( $self->{begin}->timezone_offset )
709 and $self->{begin}->timezone_offset != $self->{end}->timezone_offset
710 and not defined $target_timezone_offset )
711 {
712 # first convert end of range to same timezone as beginning
713 1 $self->{end}->adjust_timezone_offset( $self->{begin}->timezone_offset );
714 }
715 39 $self->{begin}->adjust_timezone_offset($target_timezone_offset);
716 $self->{end}->adjust_timezone_offset($target_timezone_offset)
717 39 ▶ if $self->{end};
Branch: 1 branch
BranchTrueFalseTotal
if $self->{"end"} 39 0 39
718 39 return $self->normalize;
719 }
720
721 =head2 set_local_timezone
722
723 $r->adjust_to_local_timezone;
724
725 Adjusts the timezone of the beginning and end of the range to the
726 local timezone of the Perl process, including the effects of Daylight
727 Savings Time if appropriate. Returns the instance.
728
729 If the range beginning or end do not have a timezone yet, then this
730 method may set the wrong timezone offset for part of the days on which
731 Daylight Savings Time begins or ends.
732
733 =cut
734
735 0 ▶sub adjust_to_local_timezone {
Subroutine adjust_to_local_timezone: not called CC=2 SCAR=17.9
Pod undocumented
736 0 my ($self) = @_;
737 0 $self->{begin}->adjust_to_local_timezone;
738 0 ▶ $self->{end}->adjust_to_local_timezone if $self->{end};
Branch: 1 branch
BranchTrueFalseTotal
if $self->{"end"} 0 0 0
739 0 return $self;
740 }
741
742 ###
743
744 # Calculates the nonnegative modulus of any two Perl numbers,
745 # including in particular floating-point numbers. The perl operator %
746 # is not good enough for this, because it truncates its arguments to
747 # integers at the beginning of the calculation. In list mode, mod($n,
748 # $d) returns ($q, $r) such that $n = $q*$d + $r with 0 <= $r <
749 # abs($d). In scalar mode, returns only $r.
750 37 ▶sub mod {
Subroutine mod: called CC=3 SCAR=11.8
Pod undocumented
751 37 my ($n, $d) = @_;
752 37 my ($q, $r);
753 37 eval {
754 37 $q = int($n/$d);
755 };
756 37 $r = $n - $q*$d;
757 # the "int" function truncates.
758 # $n $d $q $r
759 # 1.6 1 1 0.6
760 # -1.6 1 -1 -0.6
761 # 1.6 -1 -1 0.6
762 # -1.6 -1 1 -0.6
763 # We want 0 <= $r < abs($d)
764 37 ▶ if ($r < 0) {
Branch: 1 branch
BranchTrueFalseTotal
if ($r < 0) 0 37 37
765 0 --$q;
766 0 $r += abs($d);
767 }
768 37 ▶ return wantarray? ($q, $r): $r;
Branch: 1 branch
BranchTrueFalseTotal
wantarray ? : 37 0 37
769 }
770
771 # Splits a number into a multiple of another number and the
772 # nonnegative remainder.
773 37 ▶sub split_number {
Subroutine split_number: called CC=2 SCAR=7.1
Pod undocumented
774 37 my ($n, $d) = @_;
775 37 my ($q, $r) = mod($n, $d);
776 37 ▶ return wantarray? ($q*$d, $r): $r;
Branch: 1 branch
BranchTrueFalseTotal
wantarray ? : 37 0 37
777 }
778
779 # convert to a normalized format, in which both the range beginning
780 # and range end are defined if any of them are, and in which both the
781 # range beginning and range end have a date and timezone offset if any
782 # of them have one.
783 202 ▶sub normalize {
Subroutine normalize: called CC=15 SCAR=33.1
Pod undocumented
784 202 my ($self) = @_;
785 202 ▶ if ( $self->{begin} ) {
Branch: 2 branches
BranchTrueFalseTotal
if ($self->{'begin'}) { } 201 1 202
elsif ($self->{'end'}) { } 0 1 1
786 201 ▶ $self->{end} //= $self->{begin}->clone;
Condition66%2/3
$self->{"end"} //= $self->{"begin"}->clone
l!l&&r!l&&!r
167340
MC/DC0%0/2
$self->{"end"} //= $self->{"begin"}->clone
$self->{"end"} $self->{"begin"}->clone
Truth table66%2/3
A //= B
A= $self->{"end"}B= $self->{"begin"}->clone
ABresult
1X1
011
000
787 }
788 elsif ( $self->{end} ) {
789 0 ▶ $self->{begin} //= $self->{end}->clone;
Condition0%0/3
$self->{"begin"} //= $self->{"end"}->clone
l!l&&r!l&&!r
000
MC/DC0%0/2
$self->{"begin"} //= $self->{"end"}->clone
$self->{"begin"} $self->{"end"}->clone
Truth table0%0/3
A //= B
A= $self->{"begin"}B= $self->{"end"}->clone
ABresult
1X1
011
000
790 }
791 else { # neither beginning nor end: empty
792 1 return $self;
793 }
794 201 for (qw(local_time timezone_offset)) {
795 402 ▶ if ( exists $self->{begin}->{$_} ) {
Branch: 2 branches
BranchTrueFalseTotal
if (exists $self->{'begin'}{$_}) { } 130 272 402
elsif (exists $self->{'end'} and exists $self->{'end'}{$_}) { } 0 272 272
796 130 ▶ $self->{end}->{$_} //= $self->{begin}->{$_};
Condition66%2/3
$self->{"end"}{$_} //= $self->{"begin"}{$_}
l!l&&r!l&&!r
105250
MC/DC0%0/2
$self->{"end"}{$_} //= $self->{"begin"}{$_}
$self->{"end"}{$_} $self->{"begin"}{$_}
Truth table66%2/3
A //= B
A= $self->{"end"}{$_}B= $self->{"begin"}{$_}
ABresult
1X1
011
000
797 }
798 ▶ elsif ( exists $self->{end} and exists $self->{end}->{$_} ) {
Condition33%1/3
exists $self->{"end"} and exists $self->{"end"}{$_}
!ll&&!rl&&r
02720
MC/DC0%0/2
exists $self->{"end"} and exists $self->{"end"}{$_}
exists $self->{"end"} exists $self->{"end"}{$_}
Truth table33%1/3
A and B
A= exists $self->{"end"}B= exists $self->{"end"}{$_}
ABresult
0X0
100
111
799 0 $self->{begin}->{$_} = $self->{end}->{$_};
800 }
801 }
802 # handle "has_date": the difference between timestamps with and
803 # without dates.
804 201 ▶ if ($self->{begin}->{has_date}
Branch: 2 branches
BranchTrueFalseTotal
if ($self->{'begin'}{'has_date'} and not $self->{'end'}{'has_date'}) { } 37 164 201
elsif (not $self->{'begin'}{'has_date'} and $self->{'end'}{'has_date'}) { } 0 328 328
Condition66%2/3
$self->{"begin"}{"has_date"} and not $self->{"end"}{"has_date"}
!ll&&!rl&&r
016437
MC/DC50%1/2
$self->{"begin"}{"has_date"} and not $self->{"end"}{"has_date"}
$self->{"begin"}{"has_date"} not $self->{"end"}{"has_date"}
Truth table66%2/3
A and not(B)
A= $self->{"begin"}{"has_date"}B= not $self->{"end"}{"has_date"}
ABresult
0X0
100
111
805 && not($self->{end}->{has_date})) {
806 # only the beginning has a date: add it to the end
807 my ($date_instant, undef)
808 37 = split_number($self->{begin}->time_local, 86400);
809 37 $self->{end}->{time} += $date_instant;
810 37 $self->{end}->{has_date} = 1;
811 ▶ } elsif (not($self->{begin}->{has_date})
Condition33%1/3
not $self->{"begin"}{"has_date"} and $self->{"end"}{"has_date"}
!ll&&!rl&&r
16400
MC/DC0%0/2
not $self->{"begin"}{"has_date"} and $self->{"end"}{"has_date"}
not $self->{"begin"}{"has_date"} $self->{"end"}{"has_date"}
Truth table33%1/3
not(A) and B
A= not $self->{"begin"}{"has_date"}B= $self->{"end"}{"has_date"}
ABresult
0X0
100
111
812 && $self->{end}->{has_date}) {
813 # only the end has a date: add it to the beginning.
814 my ($date_instant, undef)
815 0 = split_number($self->{end}->time_local, 86400);
816 0 $self->{begin}->{time} += $date_instant;
817 0 $self->{begin}->{has_date} = 1;
818 }
819 201 ▶ return undef if $self->{begin} > $self->{end};
Branch: 1 branch
BranchTrueFalseTotal
if $self->{"begin"} > $self->{"end"} 0 201 201
820 201 return $self;
821 }
822
823 24 ▶sub per_timestamp_ {
Subroutine per_timestamp_: called CC=2 SCAR=7.6
Pod undocumented
824 24 my ( $self, $coderef, @args ) = @_;
825 24 ▶ if (wantarray) {
Branch: 1 branch
BranchTrueFalseTotal
if (wantarray) 24 0 24
826 24 return ( $coderef->( $self->begin, @args ),
827 $coderef->( $self->end, @args ) );
828 }
829 0 return $coderef->( $self->begin, @args );
830 }
831
832 =head1 AUTHOR
833
834 Louis Strous E<lt>LS@quae.nlE<gt>
835
836 =head1 LICENSE AND COPYRIGHT
837
838 Copyright (c) 2016-2020 Louis Strous.
839
840 This program is free software; you can redistribute it and/or modify
841 it under the same terms as Perl itself.
842
843 =cut
844
845 3 1;
« Synchronize/GpsPositionCollection.pm ↑ Summary Synchronize/ProgressBar.pm »