NAME

MooseX::Timestamp - simple timestamp type for Moose

SYNOPSIS

 use MooseX::Timestamp;

 print timestamp;          # 2007-12-06 23:15:42
 print timestamp 0;        # 1970-01-01 12:00:00
 print timestamp 0.0001;   # 1970-01-01 12:00:00.0001
 print timestamp gmtime 0; # 1970-01-01 00:00:00

 use POSIX qw(strftime);
 print strftime("%a", posixtime "2007-12-06 23:15"); # Thu

 #...

 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 a timestamp type as a Str subtype for Moose. This is a much more lightweight format than, say, DateTime, with the disadvantage that it does not support native operations on the dates.

This module provides floating dates on the Gregorian calendar without much code. It operates in (one or two particular variants of) ISO-8601 date format, and POSIX-style 6-number lists.

Note: you probably want the functions provided by MooseX::TimestampTZ most of the time, as they deal in unix epoch times.

FUNCTIONS

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

  use MooseX::Timestamp qw(:all);

timestamp(time_t $time = time())

timestamp(@posixtime)

Converts from a POSIX-style array of time components, or an epoch time, into a Timestamp. If an epoch time is passed, the local timezone rules are used for conversion into a wallclock time. See "timestamptz" in TimestampTZ for a version which returns the time zone as well.

posixtime()

Alias for the built-in localtime; this will not return a hi-res time unless one is passed in.

posixtime(Timestamp)

Converts a Timestamp into a POSIX-style array of time components. They are NOT guaranteed to be valid.

This accepts a similar set of input values to TimestampTZ::epoch; see its documentation ("epoch" in TimestampTZ) for a list. The defining difference is that Timestamps passed into this function MUST NOT have a time zone (or "Z") attached.

valid_posixtime(@posixtime)

This function croaks with an error if the passed POSIX-style array of time components are found to be out of range in any way. This function contains leap year rules and passes through leap seconds.

TYPES AND COERCIONS

One type is defined by this module.

Timestamp

This is a subtype of Str which conforms to the normalized form of a Timestamp.

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

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

  package main;
  my $widget = new Widget;
  $widget->created("2007-12-07");
  print $widget->created;  # 2007-12-07 00:00:00

With the above, if you set created to a value such as automatically get converted into a Timestamp in the current time zone.

Timestamps may contain fractional components, but the results of conversions from floating point are truncated at the microsecond level.

EXPORTS

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

  use MooseX::Timestamp ();

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