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

This documentation describes version 1.00 of Time::Format.pm, September 24, 2004.

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

 $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{$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 CW%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 "CWyyyy, the three-letter month abbreviation is CWMon".

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: CWyyyy, CWmm, CWdd, CWhh, CWmm, CWss. 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 CW$t[4]++; $t[5]+=1900 as you manually format times or dates.

Note that CWmm (and related codes) are used both for months and minutes. This is a feature. CW%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 how often do you need the day of the year (strftime's CW%j) or the week number (strftime's CW%W)?

For capabilities that CW%time does not provide, CW%strftime provides an interface to POSIX's CWstrftime, and CW%manip provides an interface to the Date::Manip module's CWUnixDate 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 CW%time and CWtime_format.

time

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

Formats a unix time number (seconds since the epoch) 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

    m          1- or 2-digit month, 1-12
    mm         2-digit month, 01-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

    d          day number, 1-31
    dd         day number, 01-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

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

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

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

    s          second, 0-59
    ss         second, 00-59
    ?s         second, 0-59 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. The second codes (CWs, CWss, CW?s) can be 60 or 61 in rare circumstances (leap seconds, if your system supports such). Anything in the format string other than the above patterns is left intact. Any character preceded by a backslash is left alone and not used for any part of a format code. See the QUOTING section for more details. 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: CWWeekday, CWMonth, time zone, and the single-character codes. The mixed-case Month, Mon, Weekday, and Day codes return the name of the month or weekday in the preferred case representation for the locale currently in effect. Thus in an English-speaking locale, the seventh month would be July (uppercase first letter, lowercase rest); while in a French-speaking locale, it would be juillet (all lowercase). See the QUOTING section for ways to control the case of month/weekday names. Note that the "CWmm, CWm, and CW?m" formats are ambiguous. CW%time tries to guess whether you meant month or minute based on nearby characters in the format string. Thus, a format of "CWyyyy/mm/dd hh:mm:ss is correctly parsed as year month day, hour minute second". If CW%time cannot determine whether you meant month or minute, it leaves the CWmm, CWm, or CW?m untranslated. To remove the ambiguity, you can use the following codes:

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

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

In other words, append "CW{on} or CW{in} to make CWm, CWmm, or CW?m" unambiguous. Note: Previous version of Time::Format (before v0.05) used the codes "CW2mon, CW1mon, CW?mon, CW2min, CW1min, and CW?min" to denote unambiguous months and minutes. These codes have been removed and are no longer supported.

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, or who need week numbers or other features CW%time does not provide.

manip

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

Provides an interface to the Date::Manip module's CWUnixDate 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 inputs accepted. If you want to use the CW%time codes, but need the input flexibility of CW%manip, you can use Date::Manip's CW%s format and nest the calls:

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

time_format

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

This is a function interface to CW%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 CW%strftime. It simply calls POSIX::CWstrftime, but it does provide a bit of an advantage over calling CWstrftime 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 CW%manip. It calls Date::Manip::CWUnixDate under the hood. It does not provide much of an advantage over calling CWUnixDate directly, except that you can omit the CW$when parameter in order to get the current time.

This section applies to the format strings used by CW%time and CWtime_format only.

Sometimes it is necessary to suppress expansion of some format characters in a format string. For example:

    $time{'Hour: hh; Minute: mm{in}; Second: ss'};

In the above expression, the H in Hour would be expanded, as would the d in Second. The result would be something like:

    8our: 08; Minute: 10; Secon17: 30

It would not be a good solution to break the above statement out into three calls to CW%time:

    "Hour: $time{hh}; Minute: $time{'mm{in}'}; Second: $time{ss}"

because the time could change from one call to the next, which would be a problem when the numbers roll over (for example, a split second after 7:59:59).

For this reason, you can escape individual format codes with a backslash:

    $time{'\Hour: hh; Minute: mm{in}; Secon\d: ss'};

Note that with double-quoted (and qq//) strings, the backslash must be doubled, because Perl first interpolates the string:

    $time{"\\Hour: hh; Minute: mm{in}; Secon\\d: ss"};

For added convenience, Time::Format simulates Perl's built-in \Q and \E inline quoting operators. Anything in a string between a \Q and \E will not be interpolated as any part of any formatting code:

    $time{'\QHour:\E hh; \QMinute:\E mm{in}; \QSecond:\E ss'};

Again, within interpolated strings, the backslash must be doubled, or else Perl will interpret and remove the \Q...\E sequence before Time::Format gets it:

    $time{"\\QHour:\\E hh; \\QMinute:\\E mm{in}; \\QSecond\\E: ss"};

Time::Format also recognizes and simulates the \U, \L, \u, and \l sequences. This is really only useful for finer control of the Month, Mon, Weekday, and Day formats. For example, in some locales, the month names are all-lowercase by convention. At the start of a sentence, you may want to ensure that the first character is uppercase:

    $time{'\uMonth \Qis the finest month of all.'};

Again, be sure to use \Q, and be sure to double the backslashes in interpolated strings, otherwise you'll get something ugly like:

    July i37 ste fine37t july of all.

 $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.
                                                                               .
                                                                               .
 # Rename a file based on today's date:
 rename $file, "$file_$time{yyyymmdd}";

 # Rename a file based on its last-modify date:
 rename $file, "$file_$time{'yyyymmdd',(stat $file)[9]}";

 # stftime examples
 $strftime{'%A %B %d, %Y'}                 Thursday June 05, 2003
 $strftime{'%A %B %d, %Y',time+86400}      Friday June 06, 2003

 # manip examples
 $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

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.

Programmers in non-English locales may want to provide an alias to CW%time in their own preferred language. This can be done by assigning CW\%time to a typeglob:

    # French
    use Time::Format;
    use vars '%temps';  *temps = \%time;
    print "C'est aujourd'hui le $temps{'d Month'}\n";

    # German
    use Time::Format;
    use vars '%zeit';   *zeit = \%time;
    print "Heutiger Tag ist $zeit{'d.m.yyyy'}\n";

etc.

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 CW:all tag will import all of these into your namespace. Example:

 use Time::Format ':all';

The format string used by CW%time must not have $; as a substring anywhere. $; (by default, ASCII character 28, or 1C hex) is used to separate values passed to the tied hash, and thus Time::Format will interpret your format string to be two or more arguments if it contains $;. The CWtime_format function does not have this limitation.

 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).

 Time::Format_XS is optional but will make C<%time> and C<time_format>
     much faster.  The version of Time::Format_XS installed must match
     the version of Time::Format installed; otherwise Time::Format will
     not use it (and will issue a warning).

Eric J. Roode, roode@cpan.org

Copyright (c) 2003-2004 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.