/ 
Image-Synchronize-2.011
River stage zero No dependents
/ Image::Synchronize::Timerange

NAME

Image::Synchronize::Timerange - a timestamp range class

SYNOPSIS

Create/Parse

From two text or Image::Synchronize::Timestamp or numeric values

$r = Image::Synchronize::Timerange->new($begin, $end);

From one text value specifying beginning and end

$r = Image::Synchronize::Timerange->new("$begin/$end");

From a text or Image::Synchronize::Timestamp or numeric value specifying a range of no duration

$r = Image::Synchronize::Timerange->new($begin);

Using object instead of class name as invocant

$r2 = $r->new($text);        # $r2 and $r are unrelated

Assignment/clone

$r2 = $r->clone;              # assigns a clone
$r2 = $r; # copies *reference*; $t and $t2 refer to the same object

Stringify

$r = Image::Synchronize::Timerange
  ->new('2001-02-03T04:05:06+07:00/11:15');
print "$r"; # ISO8601 format: '2001-02-03T04:05:06+07:00/11:15'
print $r->stringify           # same as previous
print $r->display_iso;        # same as previous
print $r->display_utc;   # ISO in UTC: 2001-02-02T21:05:06Z/03T04:15
print $r->display_time;       # no dates

Query

Extract the beginning and end as Image::Synchronize::Timestamp:

$timestamp_begin = $r->begin;
$timestamp_end   = $r->end;

Number of non-leap seconds since the epoch

($time_local_begin, $time_local_end) = $r->time_local;
($time_utc_begin, $time_utc_end)     = $r->time_utc;

Timezone offset in seconds relative to UTC

($timezone_offset_begin, $timezone_offset_end) = $r->timezone_offset;

In scalar context refers only to range beginning

$time_local_begin      = $r->time_local;
$time_utc_begin        = $r->time_utc;
$timezone_offset_begin = $r->timezone_offset;

The duration

$duration = $r->duration;

Check if an instant is within the time range

$bool = $r->contains_instant($instant);
$bool = $r->contains_local($instant);

Check for presence of parts

$bool = $r->has_timezone_offset;
$bool = $r->is_empty;

Check type

Image::Synchronize::Timerange->istypeof($r); # true
Image::Synchronize::Timerange->istypeof(6); # false
$r->istypeof(6);              # same as previous

Combine

$r2 = $r + 30;                # shift copy forward by 30 seconds
$r2 = 30 + $r;                # same as previous
$r += 30;                     # shift forward by 30 seconds
$r3 = $r + $r2                # ERROR: cannot add timeranges

$r2 = $r - 30;                # shift copy backward by 30 seconds
$r -= 30;                     # shift backward by 30 seconds
$r3 = $r - $r2;               # ERROR: cannot subtract timeranges

Compare

$r2 == $r;                    # same range
$r2 != $r;                    # not the same range
$r->identical($r2);           # same clock times and timezone
$r <=> $r2;                   # three way comparison
# < <= => > can also be used, but the interpretation is not obvious

Modify

$r->set_from_text($text);     # replace old value
$r->adjust_timezone_offset($offset);

METHODS

new

# empty range
$r = Image::Synchronize::Timerange->new;

# from two values (L<Image::Synchronize::Timestamp> or text or
# numbers)
$r = Image::Synchronize::Timerange->new($begin, $end);

# from a single text value specifying begin and end:
$r = Image::Synchronize::Timerange->new("$begin/$end");

# a range of length zero
$r = Image::Synchronize::Timerange->new($begin);

Construct a new instance.

The beginning and (optionally) end of the range can each be instances of Image::Synchronize::Timestamp, and can also be specified in the same ways as for "new" in Image::Synchronize::Timestamp. If the date or timezone offset are missing from one but present in the other, then they are shared with the peer.

If the range beginning and end are specified in a single text value (separated by /), then if the beginning or end are unsigned numbers then they're not interpreted as "seconds since the epoch" (as "new" in Image::Synchronize::Timestamp does) but as clock hours. So,

'2001-02-03T04:05:06/07'

is interpreted as

'2001-02-03T04:05:06/2001-02-03T07:00'

Returns undef if invalid arguments are supplied, including if the range end comes before the range beginning.

clone

$r2 = $r->clone;

Returns a clone of $r. The clone is a deep copy of the original, so a subsequent change of the original does not affect the clone.

stringify

$text = $r->stringify;
$text = "$r";

Returns a text version of $r, in ISO 8601 format.

If $r is empty, then $t->stringify returns undef, and "$r" returns ''.

$text = $r->display_iso;

An alias for "stringify".

display_utc

$text = $r->display_utc;

Displays the time range relative to UTC, in ISO-8601 format.

display_time

$text = $r->display_time;

Returns a text version of $r with the range beginning and (if present) end as signed time values since the epoch in the associated timezone, followed by the designation of that timezone. The hour number is not restricted to be less than 24 and can be negative.

This is useful for time ranges without dates. If $r was created with date parts, then the displayed number of hours is likely to be very large.

begin

$t = $r->begin;

Returns an Image::Synchronize::Timestamp representing the beginning of the range.

end

$t = $r->end;

Returns an Image::Synchronize::Timestamp representing the end of the range.

time_local

@time = $r->time_local;       # range begin and end
$time = $r->time_local;       # range begin only

Returns the number of non-leap seconds since the epoch in the timezone associated with the timestamp, if known. Otherwise returns undef.

In list context, processes both the beginning and end of the range. In scalar context, processes only the beginning.

time_utc

@time = $r->time_utc;         # range begin and end
$time = $r->time_local;       # range begin only

Returns the number of non-leap seconds since the epoch in UTC, if known. Otherwise returns undef.

In list context, processes both the beginning and end of the range. In scalar context, processes only the beginning.

timezone_offset

@offset = $r->timezone_offset;
$offset = $r->timezone_offset;

Returns the timezone offset from UTC in seconds, if known. Otherwise returns undef.

In list context, processes both the beginning and end of the range. In scalar context, processes only the beginning.

length

$l = $r->duration;

Returns the duration of the time range, in seconds.

has_timezone_offset

$bool = $r->has_timezone_offset;

Returns a true value if the time range has a timezone offset, and a false value otherwise.

is_empty

Returns a true value if the time range is empty, i.e., has no beginning and no end. Returns a false value otherwise.

istypeof

$ok = $class->istypeof($item);
$ok = $object->istypeof($item);    # queries $item, not $object

Returns a true value if $item is an instance of (a subclass of) the specified $class, or of the class that the specified $object belongs to. Returns a false value otherwise, including when $item is not an object.

contains_instant

$ok = $r->contains_instant($instant);

If $instant is a number, then it is interpreted as a "time" value as returned by the time function; i.e., the number of non-leap seconds since the epoch, in UTC. Returns a true value if $r has a timezone offset and if the specified instant of time is not outside of the range, or a defined but false value if $r has a timezone offset but the specified instant of time is outside of the range, or undef if $r has no timezone offset so that its relationship with UTC is unknown.

If $instant is an Image::Synchronize::Timestamp, then returns undef if $instant has a timezone offset but $r does not, or vice versa. Otherwise, returns a true value if the instant of time is not outside of the range, or a defined but false value if the instant of time is outside of the range.

Both boundaries are included in the range.

contains_local

$ok = $r->contains_local($instant);

Like "contains_instant", but disregarding timezone offsets.

If $instant is a number, then it is interpreted as a "time" value as returned by the time function; i.e., the number of non-leap seconds since the epoch. Otherwise, $instant must be an Image::Synchronize::Timestamp.

Returns a true value if the time indicated by $instant, disregarding its timezone offset if any, is within (not outside) the range indicated by $r, also disregarding its timezone offset if any. Otherwise returns a false value.

+

$shifted = $r + $offset;
$shifted = $offset + $r;

Returns a range that is like $r but shifted into the future by $offset seconds.

-

$shifted = $r - $offset;

Returns a range that is like $r but shifted into the past by $offset seconds.

<=>

$r1 <=> $r2;

Returns an integer value between -3 and +3, inclusive, that indicates the position of range $r1 relative to that of range $r2. Returns 0 only if the two ranges indicate the same period of time (when reduced to the same timezone). Returns a negative number if $r1 is deemed to come before $r2, or a positive number if $r1 is deemed to come after $r2.

If $r1 is entirely before $r2 (i.e., the end of $r1 comes before the beginning of $r2), then returns -3.

Otherwise, if $r1 is entirely after $r2 (i.e., the beginning of $r1 comes after the end of $r2), then returns +3.

Otherwise $r1 and $r2 overlap in at least one point. If the middle time of $r1 comes before the middle time of $r2, then returns -2.

Otherwise, if the middle time of $r1 comes after the middle time of $r2, then returns +2.

Otherwise, the middle times are equal. Then returns -1, 0, or +1 depending on whether the begin time of $r1 comes before, is equal to, or comes after the begin time of $r2.

If any of the relevant timestamps lack a timezone offset, then they are assumed to be in the same timezone. Otherwise the timezone offsets are taken into account.

==

$r1 == $r2;

Returns a true value if <=> returns 0, ie., when the two ranges represent the same interval of time (when reduced to the same timezone).

!=

$r1 != $r2;

Returns a true value if <=> returns non-0, i.e., when the two ranges do not represent the same interval of time (when reduced to the same timezone).

$r1 < $r2;
$r1 <= $r2;
$r1 => $r2;
$r1 > $r2;

Returns a true value if <=> returns a negative value, a zero or negative value, a zero or positive value, or a positive value, respectively.

identical

$r1->identical($r2);

Returns a true value if the two Image::Synchronize::Timeranges are identical, and a false value otherwise. They are identical if the local time and the timezone offset of the beginning and end of the range are equal between both instances.

set_from_text

$r->set_from_text($text);

Set the range based on the $text (similar to Image::Synchronize::Timerange->new($text), discarding any previous contents of $r.

Returns $r.

adjust_timezone_offset

$r->adjust_timezone_offset($offset);

Adjusts the timezone of the beginning and end of the range to $offset seconds relative to UTC.

If the beginning or end of the range already had a timezone offset and if $offset is defined, then the local time of the beginning or end gets adjusted such that the indicated instant of time remains the same.

If the beginning and end of the range already had a timezone offset and if $_offset is undefined, then the local time of the end of the range is converted into the same timezone as the beginning of the range before the timezone offsets are removed, so that the length of the range remains the same.

Returns the instance after adjustment.

set_local_timezone

$r->adjust_to_local_timezone;

Adjusts the timezone of the beginning and end of the range to the local timezone of the Perl process, including the effects of Daylight Savings Time if appropriate. Returns the instance.

If the range beginning or end do not have a timezone yet, then this method may set the wrong timezone offset for part of the days on which Daylight Savings Time begins or ends.

AUTHOR

Louis Strous <LS@quae.nl>

LICENSE AND COPYRIGHT

Copyright (c) 2016-2020 Louis Strous.

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

2 POD Errors

The following errors were encountered while parsing the POD:

Around line 246:

Unknown directive: =head

Around line 592:

Unknown directive: =head