Recipe 3.8. Printing a Date
Author: Tom Christiansen & Nathan Torkington
Date: 1999-07-02T01:30:42Z

#

| Chapter 3 Dates and Times |

## 3.8. Printing a Date

### Problem

You need to print a date and time shown in Epoch seconds format in human-readable form.

### Solution

Simply call `localtime` or `gmtime` in scalar context, which takes an Epoch second value and returns a string of the form `Tue` `May` `26` `05:15:20` `1998`:

    $STRING = localtime($EPOCH_SECONDS);

Alternatively, the `strftime` function in the standard POSIX module supports a more customizable output format, and takes individual DMYHMS values:

    use POSIX qw(strftime);
    $STRING = strftime($FORMAT, $SECONDS, $MINUTES, $HOUR,
                       $DAY_OF_MONTH, $MONTH, $YEAR, $WEEKDAY,
                       $YEARDAY, $DST);

The CPAN module Date::Manip has a `UnixDate` routine that works like a specialized form `sprintf` designed to handle dates. Pass it a Date::Manip date value. Using Date::Manip in lieu of POSIX::strftime has the advantage of not requiring a POSIX-compliant system.

    use Date::Manip qw(UnixDate);
    $STRING = UnixDate($DATE, $FORMAT);

### Discussion

The simplest solution is built into Perl already: the `localtime` function. In scalar context, it returns the string formatted in a particular way:

    Sun Sep 21 15:33:36 1997

This makes for simple code, although it restricts the format of the string:

    use Time::Local;
    $time = timelocal(50, 45, 3, 18, 0, 73);
    print "Scalar localtime gives: ", scalar(localtime($time)), "\n";
    Scalar localtime gives: Thu Jan 18 03:45:50 1973

Of course, `localtime` requires the date and time in Epoch seconds. The `POSIX::strftime` function takes a set of individual DMYMHS values and a format and returns a string. The format is similar to a `printf` format; `%` directives specify fields in the output string. A full list of these directives is available in your system's documentation for `strftime`. `strftime` expects the individual values representing the date and time to be the same range as the values returned by `localtime`:

    use POSIX qw(strftime);
    use Time::Local;
    $time = timelocal(50, 45, 3, 18, 0, 73);
    print "strftime gives: ", strftime("%A %D", localtime($time)), "\n";
    strftime gives: Thursday 01/18/73

All values are shown in their national representation when using POSIX::strftime. So, if you run it in France, your program would print `"Sunday"` as `"Dimanche"`. Be warned: Perl's interface to the POSIX function `strftime` always converts the date, assuming that it falls in the current time zone.

If you don't have access to POSIX's `strftime` function, there's always the trusty Date::Manip CPAN module, described in Recipe 3.6.

    use Date::Manip qw(ParseDate UnixDate);
    $date = ParseDate("18 Jan 1973, 3:45:50");
    $datestr = UnixDate($date, "%a %b %e %H:%M:%S %z %Y");    # as scalar
    print "Date::Manip gives: $datestr\n";
    Date::Manip gives: Thu Jan 18 03:45:50 GMT 1973

### See Also

The `gmtime` and `localtime` functions in perlfunc (1) and Chapter 3 of Programming Perl; perllocale (1); your system's strftime (3) manpage; the documentation for the POSIX module (also in Chapter 7 of Programming Perl); the documentation for the CPAN module Date::Manip

3.7. Parsing Dates and Times from Strings |  | 3.9. High-Resolution Timers