view release on metacpan or  search on metacpan

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

Check type

  Image::Synchronize::Timestamp->istypeof($t); # true
  Image::Synchronize::Timestamp->istypeof(3);  # false
  $t->istypeof(3);              # same as previous

=head2 Combine

  $t = Image::Synchronize::Timestamp->new('17:44:12+03:00');
  $t2 = $t + 30;                # 17:44:42+03:00
  $t2 = 30 + $t;                # same as previous
  $t3 = $t + $t2;               # ERROR: cannot add two timestamps

  $t2 += 100;                   # shift forward by 100 seconds

  $d = $t2 - $t;                #  30
  $t2 = $t - 20;                #  17:43:52+03:00
  $t3 = -$t;                    # -17:44:12+03:00

  $t3 -= 100;                   # shift backward by 100 seconds

=head2 Compare

  $t1 = Image::Synchronize::Timestamp->new('+17:44:12+03:00');
  $t2 = Image::Synchronize::Timestamp->new('+15:44:12+01:00');
  $t3 = Image::Synchronize::Timestamp->new('+17:00:00+03:00');

The following five are true

  $t1 == $t2;                   # same instant, also eq
  $t3 < $t1;                    # also <=, le, lt
  $t2 >= $t3;                   # also >, gt, ge
  $t3 != $t2;                   # not the same instant, also ne
  $t1->identical($t1);          # same clock time and timezone

  $t1 == $t2;            # true: same instant
  $t1->identical($t2);   # false: not same clock time and timezone

Three-way compare

  $t1 <=> $t2;                  # 0: same instant
  $t1 <=> $t3;                  # >0: first one is later
  $t3 <=> $t1;                  # <0: first one is earlier

=head2 Modify

  $t->set_from_text($text);     # replace old value
  $t->adjust_timezone_offset($offset); # shift to new timezone
  $t->adjust_to_local_timezone; # of local system at given instant
  $t->adjust_to_utc;
  $t->set_timezone_offset($offset); # keep clock time, replace timezone
  $t->remove_timezone;
  $t->adjust_nodate;            # reinterpret without date
  $t->adjust_todate;            # reinterpret with date

=head1 SUBROUTINES/METHODS

=cut

use Modern::Perl;

use Carp;
use Clone qw(clone);
use Scalar::Util qw(blessed looks_like_number);
use Time::Local v1.30 qw(timegm_modern timelocal_modern);

use parent qw(Clone);
# Clone provides a 'clone' member

use overload
  '='   => \&clone,    # copy constructor: doesn't overload assignment
  '-'   => \&subtract,
  '+'   => \&add,
  '""'  => \&stringify,
  '<=>' => \&three_way_cmp,
  'cmp' => \&three_way_cmp,
  ;

# CREATE/PARSE

=head2 new

  $t = Image::Synchronize::Timestamp->new;
  $t = Image::Synchronize::Timestamp->new($value);
  $t2 = $t->new($value);

Construct a new instance.  If C<$value> is a number, then it is taken
to represent the number of seconds since the epoch, in an undefined
timezone.  If C<$value> is defined but is not a number, then it is
parsed as a timestamp in text format.  See L</set_from_text> for
details of the supported formats.

If C<$value> is specified but no timestamp can be extracted from it,
then returns C<undef>.  If C<$value> is not specified, then returns an
empty instance that can be filled using L</set_from_text>.

=cut

sub new {
  my $invocant = shift;
  my $class = ref($invocant) || $invocant; # object or class name
  my $self = bless {}, $class;
  if ( scalar(@_) ) {
    $self->set_from_text($_[0]);
    return undef unless defined $self->{time};
  }
  return $self;
}

=head2 clone

  $t->clone;

Creates a clone of C<$t>.  The clone is a "deep copy" so modifying any
part of the clone does not affect any part of the original.

Calling C<clone> explicitly is useful if you need to modify the clone
and want to leave the original unchanged.  For example,

  $t2 = $t->clone->set_timezone(0); # does not modify $t