NAME

Time::Piece::ISO - ISO 8601 Subclass of Time::Piece

SYNOPSIS

  use Time::Piece::ISO;

  my $t = localtime;
  print "Time is $t\n"; # prints "Time is 2002-04-25T21:17:52"
  print "Year is ", $t->year, "\n";

  $t = Time::Piece::ISO->strptime('2002-04-25T21:17:52');
  print "Time is $t\n"; # prints "Time is 2002-04-25T21:17:52"
  print "Year is ", $t->year, "\n";

DESCRIPTION

This module subclasses Time::Piece in order to change its stringification and string comparison behavior to use the ISO 8601 format instead of localtime's ctime format. Although it does break the backwards compatibility with the builtin localtime and gmtime functions that Time::Piece offers, Time::Piece::ISO is designed to promote the more standard ISO format as a new way of handling dates.

This module also overrides Time::Piece's strptime() method to return a Time::Piece::ISO object, and to default to the ISO-8601 format ("%Y-%m-%dT%H:%M:%S") instead of the ctime format for parsing date/time strings.

I decided to create this module for two simple reasons: First, default support for the ISO 8601 date format seems to be the direction in which Perl 6 is heading. And second, the ISO 8601 format tends to be more widely compatible with RDBMS date time column type formats.

That said, the DateTime module has since been developed and released, and it should probably be preferred to this module whenever possible.

EXPORT

Like Time::Piece, Time::Piece::ISO exports two functions by default. These are localtime() and gmtime(), and they replace the builtin functions with the same names. The return values of these functions are Time::Piece::ISO objects, and they work exactly like Time::Piece objects except that, in a double-string context, they output an ISO 8601 formatted date string rather than the default ctime(3) value.

  my $t = gmtime;
  print "Time is $t\n"; # prints "Time is 2002-04-25T21:17:52"

By extension of the double-quoted string context, Time::Piece::ISO objects also use the ISO 8601 format for string (cmp) comparisons.

This does break backward compatibility with the builtin versions of the functions, so if you'd like to use Time::Piece::ISO objects while preserving the old functionality of localtime() and gmtime(), import Time::Piece::ISO without importing any of its functions:

  use Time::Piece::ISO ();

METHODS

iso

Time::Piece::ISO adds one method to the many already offered by Time::Piece. The iso() method acts as a synonym for Time::Piece's datetime() method, but is guaranteed to always return a strict ISO 8601 date string.

  my $t = localtime;
  print "Time is ", $t->iso, "\n"; # prints "Time is 2002-04-25T21:17:52"

strptime

Time::Piece::ISO overrides Time::Piece's strptime() method to return a Time::Piece::ISO object, and to default to the ISO-8601 format ("%Y-%m-%dT%H:%M:%S") instead of the ctime format for parsing date/time strings.

  my $t = Time::Piece::ISO->strptime('2002-04-25T21:17:52');
  print "Time is $t\n"; # prints "Time is 2002-04-25T21:17:52"
  print "Year is ", $t->year, "\n";

OVERLOADING

All operator overloading offered by Time::Piece remains in place. Only the cmp and double-quoted string operators have been overloaded by Time::Piece::ISO. This is so that it will evaluate and and compare the time only in an ISO 8601 format rather than the ctime date format used by the Time::Piece.

SUPPORT

This module is stored in an open GitHub repository. Feel free to fork and contribute!

Please file bug reports via GitHub Issues or by sending mail to bug-Time-Piece-ISO@rt.cpan.org.

AUTHOR

David E. Wheeler <david@justatheory.com>, extending Matt Seargent's <matt@seargent.org> Time::Piece module.

SEE ALSO

Time::Piece

The base class for Time::Piece::ISO.

DateTime

The base class for the Perl date/time suite. This will likely become the canonical date and time module, and should be used in preference to Time::Piece::ISO whenever possible.

COPYRIGHT AND LICENSE

Copyright (c) 2002-2011, David E. Wheeler. Some Rights Reserved.

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

cpanm Time::Piece::ISO

perl -MCPAN -e shell
install Time::Piece::ISO