Date::Manip Gymnastics

There are actually several Perl modules related to time manipulation including Date::Calc, Date::Format, Date::Parse, and the one we're going to use, Date::Manip. All of these modules are available from your nearest CPAN mirror. Each module has its own capabilities and syntax, some of which overlap. We're going to focus on Date::Manip because it is powerful, the easiest to understand, and easy to install in both Unix and Windows based Perl installations. The minor disadvantage to Date::Manip is that it is slower and less efficient than some of the other time modules; this needn't be much of a concern unless your Perl script makes real intensive use of time calculations.

Although Date::Manip can perform many time-related feats, let's first focus on parsing human friendly dates. Humans, with our penchant for non-standardization, basically write times and dates a zillion different ways: "April 15, 1980 5pm" or "4/15/80 5:00" or "15 Apr 1980 5 PM" and on and on. To make matters worse, Americans and Europeans often reverse the placement of month and day of month, with Canadians split on whose side to take, causing all sorts of havoc ("March 6th or June 3rd??"). The Date::Manip module contains a function, &ParseDate, which tries its darndest to make sense out of a wide variety of date strings.

The examples below assume that you've downloaded and installed the Date::Manip module! One brief caveat: Date::Manip needs to determine the timezone of your machine, and it will attempt to do so in a variety of ways. If it fails an error message will appear. The module documentation contains several suggestions for providing the timezone to this module, and we've included one of these techniques in the script examples below, in Eastern Standard Time, or EST. You needn't include the timezone code line if Date::Manip is able to determine your timezone otherwise.

use Date::Manip;

#time zone info (if necessary)
&Date_Init("TZ=EST");

$someday="November 15th, 1999 12:30PM EST";
$parsed=&ParseDate($someday);

The module will read the string $someday and extract the relevant date and time information. This data is stored in the variable $parsed in the internal format in which Date::Manip represents time. Using the $parsed variable we can now manipulate this date in a wide number of ways, as Date::Manip supports quite a few acrobatic subroutines. Our goal right now, though, is to convert into epoch seconds, as that ties in with everything we've talked about so far in this article.

One of the subroutines offered by Date::Manip is &UnixDate, which converts a date into Unix format. We can leverage this to translate the date in $parsed into a Unix-friendly epoch time in seconds:

$epoch=&UnixDate($parsed,"%s");

The proof is in the pudding:

print scalar localtime($epoch);

Yields:

Mon Nov 15 12:30:00 1999

For the sake of cleanliness, we can compress this entire conversion from human format to epoch time in one line of Perl code (the linewraps and indentations are merely for web page legibility):

print scalar localtime(
              &UnixDate(
               &ParseDate("November 15th, 1999 12:30PM EST"),
               "%s")
             );

Reversing Time
The Perl You Need to Know
Calendar Calisthenics