The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Image-Synchronize-1.0
River stage zero No dependents
++
/ Image::Synchronize::Timestamp

NAME

Image::Synchronize::Timestamp - a timestamp class

SYNOPSIS

  # parse Exif timestamp text with offset from UTC
  $t = Image::Synchronize::Timestamp->new('2010:06:27 17:44:12+03:00');

  # or with - as date component separator
  $t = Image::Synchronize::Timestamp->new('2010-06-27 17:44:12+03:00');

  # or with T as date/time separator (ISO 8601)
  $t = Image::Synchronize::Timestamp->new('2010-06-27T17:44:12+03:00');

  # or without timezone offset
  $t2 = Image::Synchronize::Timestamp->new('2010:06:27 17:50:00');

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

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

  $t3 = $t->clone;              # clone
  $t == $t3;                    # test equality
  $t != $t2;                    # test inequality
  print "$t";                   # back to text format

SUBROUTINES/METHODS

new

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

Construct a new instance. If $value is a number, then it is taken to represent the number of seconds since the epoch (in UTC). If $value is defined but is not a number, then it is parsed as a timestamp in text format. See set_from_text for details of the supported formats.

If $value is specified but no timestamp can be extracted from it, then returns undef. If $value is not specified, then returns an empty instance.

istypeof

  $ok = Image::Synchronize::Timestamp->istypeof($item);

Returns a true value if $item is an instance of (a subclass of) Image::Synchronize::Timestamp, and a false value otherwise.

time_local

  $time = $t->time_local;       # range beginning or instant
  @times = $t->time_local;      # range beginning and end

In list context, returns the number of non-leap seconds since the epoch in the timezone associated with the timestamp, for both the range beginning and range end -- or undef for whichever of those isn't included in $t.

In scalar context, returns the value for the range beginning (or single instant) only.

time_utc

  $time = $t->time_utc;

Returns the number of non-leap seconds since the epoch in UTC, or undef if the timestamp is empty or has no timezone offset.

has_timezone_offset

  Returns a true value if timestamp C<$t> has a timezone offset, and a
  false value otherwise.

offset_from_utc

  $offset = $t->offset_from_utc;

Returns the timezone offset from UTC in seconds, or undef if no timezone offset is known.

clone

  $t2 = $t->clone;

Returns a clone of the specified Image::Synchronize::Timestamp.

identical

  $t1->identical($t2);

Returns true if the two Image::Synchronize::Timestamp are identical, and false otherwise. They are identical if both the time and the timezone offset are equal in both.

<=>

  $t1 <=> $t2;

Returns -1, zero, or 1 depending on whether $t1 indicates an earlier, equal, or later instant of time than $t2.

-

  $difference = $t2 - $t1;

Returns the difference (in seconds) between the two timestamps $t2 and $t1. If at least one of the two does not have a timezone offset, then both timestamps are assumed to be in the same timezone.

+

  $sum = $t + $seconds;
  $sum = $seconds + $t;

Returns the timestamp that is $seconds later than timestamp $t.

combine

  $t3 = $t1->combine($t2);

Returns a clone of $t1 with undefined parts (time or time zone offset) copied from $t2. $t1 and $t2 are not modified.

stringify

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

Returns a text version of $t, in Exif format. If $t contains no timezone offset, then the returned text is like '2000:01:02 03:04:05', showing the year, month, day, hour, minute, and second. If $t does contain a timezone offset, then that offset gets appended and is like '+06:00', showing the signed hour and minute of the offset with respect to UTC. If the timezone offset includes a number of seconds unequal to zero, then that number of seconds is included in the offset text as well (e.g., '+06:00:03'). These examples are for timezones where the clock time is approximately 6 hours greater than UTC.

If $t was set from undefined text, then $t->stringify returns undef, and "$t" returns ''.

display_iso

  $t->display_iso

Returns a text representation of the timestamp in ISO8601 format, for example 2001-02-23T14:47:22+01:00 for a timestamp representing 14 hours 47 minutes 22 seconds (= 22 seconds past 2:47 pm) on February 23rd of 2001.

display_utc

  $text = $t->display_utc;

Returns a text version of $t, in UTC in ISO 8601 format. The returned text is like '2000-01-02T03:04:05Z', showing the year, month, day, hour, minute, and second. If $t includes timezone information, then that is taken into account. Otherwise, $t is assumed to be in UTC already.

If $t was set from undefined text, then $t->display_utc returns undef.

set_from_text

  $t->set_from_text($text);

Sets $t to the instant of time expressed by text $text, discarding any previous contents of $t.

The text must specify a date and a time. The date must consist of three numbers (year, month, day) separated by either a colon : or a dash -. The time must consist of three numbers (hour, minute, second) separated by a colon :. The date and time must be separated by a single whitespace or a capital T.

Optionally, an offset from UTC may be specified, as two numbers, of which the first one must be signed and represents hours, and the second one must be separated from the first by a colon : and represents minutes.

These formats include the format of Exif timestamps, for example '2010:06:27 17:44:12+03:00' or '2010:06:27 17:50:00', and also the ISO 8601 formats '2010-06-27T17:44:12+03:00' or '2010-06-27T17:50:00'.

The example timestamps with timezone offset represent June 27th of the year 2010, at 44 minutes and 12 seconds past 5 o'clock in the afternoon, in a timezone where the clock reads 3 hours later than UTC. The corresponding UTC time is 14:44:12.

If the text cannot be parsed as a timestamp, then the Image::Synchronize::Timestamp is left without contents.

Returns $t.

set_timezone_offset_if_not_set

  $t->set_timezone_offset_if_not_set($offset);

Sets the timezone offset of $t to $offset, unless $t already has a timezone offset, in which case $t is not modified.

Returns $t.

set_timezone_offset

  $t->set_timezone_offset($offset);

Sets the timezone offset of $t to <$offset>. If $t already had a timezone offset, then adjusts the clock time so it refers to the same instant of time as before but now relative to the new timezone.

If $offset is undef, then the timezone of $t becomes undefined.

Returns the object.

local_offset_from_utc

  $t->local_offset_from_utc

Returns the difference between the local timezone and UTC, in seconds. The local timezone is the timezone that is valid at the specified time $t (for the environment of the current process).

clone_to_local_timezone

  $t->clone_to_local_timezone

Returns a clone of timestamp $t with its timezone set to the local timezone (for the environment of the current process).

set_to_local_timezone

  $t->set_to_local_timezone

Sets the timezone of timestamp $t to the local timezone (for the environment of the current process). If $t already had a timezone offset, then adjusts the clock time so it refers to the same instant of time as before but now relative to the local timezone.

Returns the adjusted $t.

set_to_local_timezone_if_not_set

  $t->set_to_local_timezone_if_not_set

Sets the timezone of timestamp $t to the local timezone (for the environment of the current process) if it has no timezone offset yet.

Returns the adjusted $t.

remove_timezone

  $t->remove_timezone

Removes the timezone offset from timestamp $t. The clock time remains the same. Returns modified $t.

to_utc

  $t->to_utc

Returns a clone of timestamp $t with its timezone set to UTC.

set_to_utc

  $t->set_to_utc

Sets the timezone of timestamp $t to UTC. If $t already had a timezone offset, then adjusts the clock time so it refers to the same instant of time as before but now relative to UTC.

Returns the adjusted $t.

set_to_utc_if_not_set

  $t->set_to_utc_if_not_set

Sets the timezone of timestamp $t to UTC if it has no timezone offset yet.

Returns the adjusted $t.

date

  $t->date;

Returns the date part of the text version (as produced by "stringify") of the timestamp.

time

  $t->time;

Returns the time part of the text version (as produced by "stringify") of the timestamp -- excluding the timezone, if any.

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.