NAME

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

SYNOPSIS

  # from single text value
  $r = Image::Synchronize::Timerange
    ->new('2010-06-26 17:44:12+03:00/2010-06-26 18:03:44+03:00');

  # or from two text values
  $r = Image::Synchronize::Timerange
    ->new('2010-06-26 17:44:12+03:00', '2010-06-26 18:03:44+03:00');

  # or from two "time" values
  $r = Image::Synchronize::Timerange
    ->new('2010-06-26 17:44:12+03:00', '2010-06-26 18:03:44+03:00');

  # omit range end date or timezone if the same as for range start
  $r = Image::Synchronize::Timerange
    ->new('2010-06-26 17:44:12+03:00/18:03:44');

  # number of non-leap seconds since the epoch
  @time_local = $r->time_local;  # in local timezone
  @time_utc = $r->time_utc;      # in UTC

  @offset = $r->offset_from_utc; # in seconds

  # in scalar context refers only to range beginning
  $time_local = $r->time_local;  # in local timezone
  $time_utc = $r->time_utc;      # in UTC

  $offset = $r->offset_from_utc; # in seconds

  $r2 = $r->clone;              # clone
  $r2 == $r;                    # test equality
  $r2 != $r;                    # test inequality
  print "$r";                   # back to text format

METHODS

new

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

  # range beginning and range end

  #  from text representation
  $r = Image::Synchronize::Timerange->new($text);

  #  from two values;
  $r = Image::Synchronize::Timerange->new($v1, $v2);
  # Each value may be an Image::Synchronize::Timestamp, a time value,
  # or a text value

  # range of length zero

  #  from text representation
  $r = Image::Synchronize::Timerange->new($text);

  #  from one value
  $r = Image::Synchronize::Timerange->new($v1);

  # The value may be an Image::Synchronize::Timestamp, a time value,
  # or a text value

Construct a new instance.

If a timezone offset is specified for the range beginning or the range end but not for both, then the specified timezone offset applies to both.

If invalid arguments are supplied, then returns undef.

set_from_text

  $r->set_from_text($text);

Set the range based on the $text. If $text is not a valid text representation of a time range, then leaves $r unchanged and returns undef. Otherwise returns $r after updating it.

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.

offset_from_utc

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

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->length;

Returns the length of the time range, in seconds.

set_timezone_offset

  $r->set_timezone_offset($target_timezone_offset);

Sets the timezone of the beginning and end of the range to $target_timezone_offset seconds relative to UTC.

If the beginning or end of the range already had a timezone offset and if $target_timezone_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 $target_timezone_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->set_local_timezone;

Sets or changes 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.

set_local_standard_timezone

 $r->set_local_standard_timezone;

Sets or changes the timezone of the beginning and end of the range to the local standard timezone of the Perl process, without Daylight Savings Time. Returns the instance.

clone

  $r2 = $r->clone;

Returns a clone of the specified Image::Synchronize::Timerange. The clone is a deep copy of the original, so a subsequent change of the original does not affect the clone.

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.

<=>

  $r1 <=> $r2;
  $r1->three_way_cmp($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.

-

 $shifted = $r - $offset;

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

+

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

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

  $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 ''.

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.

AUTHOR

Louis Strous <LS@quae.nl>

LICENSE AND COPYRIGHT

Copyright (c) 2016-2018 Louis Strous.

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

cpanm Image::Synchronize

perl -MCPAN -e shell
install Image::Synchronize