/ 
Time-Format-0.06
River stage two • 10 direct dependents • 22 total dependents
/ Time::Format

NAME

Time::Format - Easy-to-use date/time formatting.

VERSION

This documentation describes version 0.06 of Time::Format.pm, June 20, 2003.

SYNOPSIS

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

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";

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

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";

DESCRIPTION

This module creates global pseudovariables which format dates and times. 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 %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 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.

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 it's 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 hey, how often do you need the day of the year (strftime's %j) or the week number (strftime's %W)?

For capabilities that %time does not provide, %strftime provides an interface to POSIX's strftime, and %manip provides an interface to the Date::Manip module's UnixDate function.

VARIABLES

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

Formats a unix time number according to the specified format. If the time expression is omitted, the current time is used. The format string may contain any of the following:

yyyy       4-digit year
yy         2-digit year

mm         2-digit month, 01-12
m          1- or 2-digit month, 1-12
?m         month with leading space if < 10

Month      full month name, mixed-case
MONTH      full month name, uppercase
month      full month name, lowercase
Mon        3-letter month abbreviation, mixed-case
MON  mon   ditto, uppercase and lowercase versions

dd         day number, 01-31
d          day number, 1-31
?d         day with leading space if < 10
th         day suffix (st, nd, rd, or th)
TH         uppercase suffix

Weekday    weekday name, mixed-case
WEEKDAY    weekday name, uppercase
weekday    weekday name, lowercase
Day        3-letter weekday name, mixed-case
DAY  day   ditto, uppercase and lowercase versions

hh         hour, 00-23
h          hour, 0-23
?h         hour, 0-23 with leading space if < 10

HH         hour, 01-12
H          hour, 1-12
?H         hour, 1-12 with leading space if < 10

mm         minute, 00-59
m          minute, 0-59
?m         minute, 0-59 with leading space if < 10

ss         second, 00-61
s          second, 0-61
?s         second, 0-61 with leading space if < 10
mmm        millisecond, 000-999
uuuuuu     microsecond, 000000-999999

am   a.m.  The string "am" or "pm" (second form with periods)
pm   p.m.  same as "am" or "a.m."
AM   A.M.  same as "am" or "a.m." but uppercase
PM   P.M.  same as "AM" or "A.M."

tz         time zone abbreviation

Millisecond and microsecond require Time::HiRes, otherwise they'll always be zero. Timezone requires POSIX, otherwise it'll be the empty string.

Anything in the format string other than the above patterns is left intact. Also, any character preceded by a backslash is left alone and not used for any part of a format code.

For the most part, each of the above formatting codes takes up as much space as the output string it generates. The exceptions are the codes whose output is variable length: Weekday, Month, time zone, and the single-character codes.

Note that the "mm", "m", and "?m" formats are ambiguous. %time tries to guess whether you meant "month" or "minute" based on nearby characters in the format string. Thus, a format of "yyyy/mm/dd hh:mm:ss" is correctly parsed as "year month day, hour minute second". To remove the ambiguity, you can use the following codes:

mm{on}       month, 01-12
m{on}        month, 1-12
?m{on}       month, 1-12 with leading space if < 10

mm{in}       minute, 00-59
m{in}        minute, 0-59
?m{in}       minute, 0-59 with leading space if < 10

In other words, append "{on}" or "{in}" to make "mm", "m", or "?m" unambiguous.

Note: Previous version of Time::Format (before v0.05) used the codes "2mon", "1mon", "?mon", "2min", "1min", and "?min" denote unambiguous months and minutes. These codes are deprecated and will be removed before v1.0.

strftime
$strftime{$format, $sec,$min,$hour, $mday,$mon,$year, $wday,$yday,$isdst}
$strftime{$format, $unixtime}
$strftime{$format}

For those who prefer strftime(3)'s weird % formats, or who need POSIX compliance.

manip
$manip{$format};
$manip{$format,$when};

Provides an interface to the Date::Manip module's UnixDate function. This function is rather slow, but can parse a very wide variety of date input. See the Date::Manip module for details about the formats accepted.

If you want to use the %time codes, but need the input flexibility of %manip, you can use Date::Manip's %s format and nest the calls:

print "$time{'yyyymmdd',$manip{'%s','last sunday'}}";

FUNCTIONS

time_format
time_format($format);
time_format($format, $unix_time);

This is a function interface to %time. It accepts the same formatting codes and everything. This is provided for people who want their function calls to look like function calls, not hashes. :-) The following two are equivalent:

$x = $time{'yyyy/mm/dd'};
$x = time_format('yyyy/mm/dd');
time_strftime
time_strftime($format, $sec,$min,$hour, $mday,$mon,$year, $wday,$yday,$isdst);
time_strftime($format, $unixtime);
time_strftime($format);

This is a function interface to %strftime. It simply calls POSIX::strftime, but it does provide a bit of an advantage over calling strftime directly, in that you can pass the time as a unix time (seconds since the epoch), or omit it in order to get the current time.

time_manip
manip($format);
manip($format,$when);

This is a function interface to %manip. It calls Date::Manip::UnixDate under the hood, but it has a slight advantage over calling UnixDate directly, in that you can omit the $when parameter in order to get the current time.

EXAMPLES

$time{'Weekday Month d, yyyy'}   Thursday June 5, 2003
$time{'Day Mon d, yyyy'}         Thu Jun 5, 2003
$time{'dd/mm/yyyy'}              05/06/2003
$time{yymmdd}                    030605
$time{'yymmdd',time-86400}       030604
$time{'dth of Month'}            5th of June

$time{'H:mm:ss am'}              1:02:14 pm
$time{'hh:mm:ss.uuuuuu'}         13:02:14.171447

$time{'yyyy/mm{on}/dd hh:mm{in}:ss.mmm'}  2003/06/05 13:02:14.171
$time{'yyyy/mm/dd hh:mm:ss.mmm'}          2003/06/05 13:02:14.171

$time{"It's H:mm."}              It'14 1:02.    # OOPS!
$time{"It'\\s H:mm."}            It's 1:02.     # Backslash fixes it.

$strftime{'%A %B %e, %Y'}                 Thursday June  5, 2003
$strftime{'%A %B %e, %Y',time+86400}      Friday June  6, 2003

$manip{'%m/%d/%Y'}                                   06/05/2003
$manip{'%m/%d/%Y','yesterday'}                       06/04/2003
$manip{'%m/%d/%Y','first monday in November 2000'}   11/06/2000

INTERNATIONALIZATION

If the I18N::Langinfo module is available, Time::Format will return weekday and month names in the language appropriate for the current locale. If not, English names will be used.

Some testers have suggested making alternate hash variable names available for different languages. Thus, for example, a French programmer could use %temps instead of %time, and a German could use %zeit. This would be nice, but would require Time::Format (and its author!) to provide an equivalent to the word 'time' in an arbitrary number of languages.

Instead, I would recommend that non-English programmers provide an alias to %time in their own preferred language. This can be done by assigning \%time to a typeglob:

# French
use Time::Format;
use vars '%temps';  *temps = \%time;

# German
use Time::Format;
use vars '%zeit';   *zeit = \%time;

etc.

EXPORTS

The following symbols are exported into your namespace by default:

%time
time_format

The following symbols are available for import into your namespace:

%strftime
%manip
time_strftime
time_manip

The :all tag will import all of these into your namespace. Example:

use Time::Format ':all';

REQUIREMENTS

Carp (included with Perl).
Exporter (included with Perl).
I18N::Langinfo, if you want non-English locales to work.
POSIX, if you choose to use %strftime or want the C<tz> format to work.
Time::HiRes, if you want the C<mmm> and C<uuuuuu> time formats to work.
Date::Manip, if you choose to use %manip.
Time::Local (only needed to run the 'make test' suite).

AUTHOR / COPYRIGHT

Eric J. Roode, roode@cpan.org

Copyright (c) 2003 by Eric J. Roode. All Rights Reserved. This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

If you have suggestions for improvement, please drop me a line. If you make improvements to this software, I ask that you please send me a copy of your changes. Thanks.