NAME

MooseX::Timestamp - simple timestamp type for Moose, with Time Zone

SYNOPSIS

 use MooseX::TimestampTZ qw(:all);

 print zone 0;       # +0000
 print zone 0, 1;    # Z
 print zone 12*3600; # +1200

 print offset_s "Z";     # 0
 print offset_s "+1200"; # 43200   (= 12 * 3600)

 # local times
 print timestamptz;   # 2007-12-06 23:23:22+1300
 print timestamptz 0; # 1970-01-01 12:00:00+1200

 # UTC times
 print gmtimestamptz;     # 2007-12-06 10:23:22+0000
 print gmtimestamptz 0;   # 1970-01-01 00:00:00+0000

 # hires timestamps
 print tmtimestamptz 0.123;  # 1970-01-01 00:00:00.123+0000

 use MooseX::TimestampTZ ":all" => { hires => 1 };
 print tmtimestamptz;     #  2010-07-20 14:13:23.73418+1200

 # conversion the other way
 print epoch "1970-01-01 00:00:00+0000"; # 0
 print epoch "1970-01-01 12:00:00+1200"; # 0

 print for epochtz "1970-01-01 12:00:00+1200"; # 0, 43200

 # you can get these ISO forms if you want, too.  functions
 # that take a timestamptz accept either
 package SomewhereElse;
 use MooseX::TimestampTZ gmtimestamptz => { use_z => 1 };
 print gmtimestamptz 0;   # 1970-01-01 00:00:00Z

 package MyClass;
 use Moose;
 has 'stamp' =>
         isa => "Timestamp",
         is => "rw",
         coerce => 1;

 package main;
 my $obj = MyClass->new(stamp => "2007-01-02 12:00:12"); # ok
 $obj->stamp("2007-01-02 12:01");
 $obj->stamp("2007-01-02 12");
 $obj->stamp("2007-01-02 12:00:00Gibbons");  #fail

DESCRIPTION

This module provides floating dates on the Gregorian calendar without much code. It operates in (one particular variant of) ISO-8601 date format with time zone, and epoch times. Sub-second resolution is not yet supported.

FUNCTIONS

The following functions are available for import. If you want to import them all, use the :all import group, as below:

  use MooseX::TimestampTZ qw(:all);

zone(Int $offset, Bool $use_z = false)

Returns the timezone of the given offset. Pass $use_z to select returning "Z" as a timezone if the offset is 0.

offset_s(Str)

Returns the offset corresponding to the given timezone. Does NOT accept nicknames like "EST", etc (which EST did you mean, US or Australian Eastern Standard Time?).

timestamptz(time_t $time_t = time(), Bool $use_z = false)

Returns the passed epoch time as a valid TimestampTZ, according to the local time zone rules in effect. $use_z functions as with zone.

gmtimestamptz(time_t $time_t = time(), Bool $use_z = false)

Returns the passed epoch time as a valid TimestampTZ, corresponding to the time in UTC. $use_z functions as with zone, and if passed this function will always return TimestampTZs ending with Z.

epoch()

Synonym for the built-in time().

epoch(TimestampTZ)

Converts the passed TimestampTZ value to an epoch time. Does not perform any coercion - the passed value must already have a time zone on it. You may omit any part of the time, specify the time zone in hours or with a Z, and optionally separate your time from your date with a T. Single digit values for fields are accepted.

Example valid forms:

  2007-12-07 16:34:02+1200
  2007-12-07 16:34+12
  2007-12-07 04Z
  2007-12-7T4Z
  2007-12-7+12
  2007120704:12:32    # Date::Manip format

Examples of ISO-8601 valid forms which are not currently accepted:

  07-12-07Z
  071207Z
  20071207Z           # seperators required
  2007120704Z
  -12-07Z             # no year specified

No locale-specific date forms, such as / delimited dates, are accepted.

epochtz(...)

Just like epoch(), except returns the timezone as well.

TYPES AND COERCIONS

The following subtypes are defined by this module:

TimestampTZ

This is a subtype of Str which conforms to one of the two normalized forms of a TimestampTZ (either with a Z, or without).

Rules exist to coerce Str, Timestamp and time_t to this type, and are available by using the coerce => 1 flag on a Moose attribute declaration:

  package Widget;
  use MooseX::TimestampTZ;
  has 'created' =>
          isa => TimestampTZ,
          is => "rw",
          coerce => 1;

With the above, if you set created to a time_t value, it will automatically get converted into a TimestampTZ in the current time zone.

A TimestampTZ value with a fractional second part is considered valid, regardless of whether hires is passed to the importer.

New in 0.07: Timestamp to TimestampTZ conversion now happens in local time, not UTC.

time_t

time_t is a nicer way of writing an epoch time. If you set coerce => 1 on your accessors, then you can happily pass in timestamps. As of MooseX::Timestamp 0.07, time_t is a Num, not merely an Int.

EXPORTS

The default exporting action of this module is to export the timestamptz, gmtimestamptz and epoch methods. To avoid this, pass an empty argument list to the use statement:

  use MooseX::TimestampTZ ();

ISO-8601 "Z" TIMEZONE

Several of the functions which return a timezone may be told to return "Z" if the offset is 0, that is, the time is in UTC. To select this, pass a true second argument to any of the three functions (zone, timestamptz and gmtimestamptz), or curry them on import;

 use MooseX::TimestampTZ qw(:default), defaults => { use_z => 1 };

You can also curry individual functions like this:

 use MooseX::TimestampTZ zone => { use_z => 1 };

BUGS

This module is relatively slow, as conversions and calls to timegm and friends happen far too often, really - especially with coercion.

AUTHOR AND LICENSE

Sam Vilain, <samv@cpan.org>

Copyright 2007, Sam Vilain. All Rights Reserved. This program is Free Software; you may use it and/or redistribute it under the terms of Perl itself.

cpanm MooseX::Timestamp

perl -MCPAN -e shell
install MooseX::Timestamp