Printing a Date (Perl Cookbook, 2nd Edition)

## 3.8. Printing a Date

### 3.8.1. Problem

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

### 3.8.2. Solution

Call `localtime` or `gmtime` in scalar context, which takes an Epoch seconds value and returns a string of the form `Tue` `July` `22` `05:15:20` `2003`:

>     $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);

### 3.8.3. Discussion

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

>     Wed July 16 23:58:36 2003

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 individual DMYMHS values plus 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`. The `strftime` function expects the individual values representing the date and time to be in the same range as those 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` assumes the date 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

### 3.8.4. See Also

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

Copyright © 2003 O'Reilly & Associates. All rights reserved.