Time::Format 1.02

Time::Format is a Perl module for easy-to-use date/time formatting.

SYNOPSIS

use Time::Format qw(%time %strftime %manip);

$time{$format}
$time{$format, $unixtime}

print "Today is $time{yyyy/mm/dd}n";
print "Yesterday was $time{yyyy/mm/dd, time-24*60*60}n";
print "The time is $time{hh:mm:ss}n";
print "Another time is $time{H:mm am tz, $another_time}n";
print "Timestamp: $time{yyyymmdd.hhmmss.mmm}n";
%time also accepts Date::Manip strings and DateTime objects:
$dm = Date::Manip::ParseDate(last monday);
print "Last monday was $time{Month d, yyyy, $dm}";
$dt = DateTime->new (....);
print "Heres another date: $time{m/d/yy, $dt}";
It also accepts most ISO-8601 date/time strings:
$t = 2005/10/31T17:11:09; # date separator: / or - or .
$t = 2005-10-31 17.11.09; # in-between separator: T or _ or space
$t = 20051031_171109; # time separator: : or .
$t = 20051031171109; # separators may be omitted
$t = 2005/10/31; # date-only is okay
$t = 17:11:09; # time-only is okay
# But not:
$t = 20051031; # date-only without separators
$t = 171109; # time-only without separators
# ...because those look like epoch time numbers.
%strftime works like POSIXs strftime, if you like those %-formats.
$strftime{$format}
$strftime{$format, $unixtime}
$strftime{$format, $sec,$min,$hour, $mday,$mon,$year, $wday,$yday,$isdst}

print "POSIXish: $strftime{%A, %B %d, %Y, 0,0,0,12,11,95,2}n";
print "POSIXish: $strftime{%A, %B %d, %Y, 1054866251}n";
print "POSIXish: $strftime{%A, %B %d, %Y}n"; # current time
%manip works like Date::Manips UnixDate function.
$manip{$format};
$manip{$format, $when};

print "Date::Manip: $manip{%m/%d/%Y}n"; # current time
print "Date::Manip: $manip{%m/%d/%Y,last Tuesday}n";
These can also be used as standalone functions:
use Time::Format qw(time_format time_strftime time_manip);

print "Today is ", time_format(yyyy/mm/dd, $some_time), "n";
print "POSIXish: ", time_strftime(%A %B %d, %Y,$some_time), "n";
print "Date::Manip: ", time_manip(%m/%d/%Y,$some_time), "n";

This module creates global pseudovariables which format dates and times, according to formatting codes you pass to them in strings.

The %time formatting codes are designed to be easy to remember and use, and to take up just as many characters as the output time value whenever possible. For example, the four-digit year code is "yyyy", the three-letter month abbreviation is "Mon".

The nice thing about having a variable-like interface instead of function calls is that the values can be used inside of strings (as well as outside of strings in ordinary expressions). Dates are frequently used within strings (log messages, output, data records, etc.), so having the ability to interpolate them directly is handy.

Perl allows arbitrary expressions within curly braces of a hash, even when that hash is being interpolated into a string. This allows you to do computations on the fly while formatting times and inserting them into strings. See the "yesterday" example above.

The format strings are designed with programmers in mind. What do you need most frequently? 4-digit year, month, day, 24-based hour, minute, second -- usually with leading zeroes. These six are the easiest formats to use and remember in Time::Format: yyyy, mm, dd, hh, mm, ss. Variants on these formats follow a simple and consistent formula. This module is for everyone who is weary of trying to remember strftime(3)s arcane codes, or of endlessly writing $t[4]++; $t[5]+=1900 as you manually format times or dates.

Note that mm (and related codes) are used both for months and minutes. This is a feature. %time resolves the ambiguity by examining other nearby formatting codes. If its in the context of a year or a day, "month" is assumed. If in the context of an hour or a second, "minute" is assumed.

The format strings are not meant to encompass every date/time need ever conceived. But how often do you need the day of the year (strftimes %j) or the week number (strftimes %W)?

For capabilities that %time does not provide, %strftime provides an interface to POSIXs strftime, and %manip provides an interface to the Date::Manip modules UnixDate function.

If the companion module Time::Format_XS is also installed, Time::Format will detect and use it. This will result in a significant speed increase for %time and time_format.