view release on metacpan or  search on metacpan

lib/Image/Synchronize/Timerange.pm  view on Meta::CPAN

  ($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

=head2 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

=head2 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

=head2 Modify

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

=head1 METHODS

=cut

use Modern::Perl;

use Carp;
use Clone qw(clone);
use Image::Synchronize::Timestamp;
use Scalar::Util qw(blessed looks_like_number);

use parent qw(Clone);

use overload
  '='   => \&clone,
  '-'   => \&subtract,
  '+'   => \&add,
  '""'  => \&stringify,
  '<=>' => \&three_way_cmp;

=head2 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 L<Image::Synchronize::Timestamp>, and can also be specified in the
same ways as for L<Image::Synchronize::Timestamp/new>.  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 C</>), then if the beginning or end are unsigned numbers
then they're not interpreted as "seconds since the epoch" (as
L<Image::Synchronize::Timestamp/new> 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 C<undef> if invalid arguments are supplied, including if the
range end comes before the range beginning.

=cut

sub new {
  my $invocant = shift;
  my $class = ref($invocant) || $invocant; # object or class name
  my $self = bless {}, $class;
  if ( scalar(@_) == 1 ) {
    if ( Image::Synchronize::Timestamp->istypeof( $_[0] ) ) {