Have you ever wanted to:

  o  Enter a date (either at a prompt or as part of an argument
     list) and be able to choose any format conveniant?

  o  Compare two dates, entered in widely different formats?

  o  Be able to extract any information you want from ANY date
     using a format string similar to the Unix date command?

  o  Be able to determine the amount of time between two dates?

  o  Be able to add a time offset to a date to get a second
     date (i.e. report the date 132 days ago or 2 years and
     3 months after Jan 2, 1992)?

This package makes all of the above tasks trivial.
  Note:  Although the word date is used here and elsewhere in the
  package, it is actually misleading.  This package works with a
  full date AND time (year, month, day, hour, minute, second).

The routine &ParseDate converts a date from one of several formats
understood to a simple internal format (YYYYMMDDHH:MN:SS).  It works
on a list finding the maximum number of elements which form a valid
time/date.  This is especially useful when interpreting @ARGV (which
is what this routine was originally written for).  If the script was
called by one of the following:
   my_perl_script.pl -date 13:05 12/10/95          -option2 -option3
   my_perl_script.pl -date Dec 10 1995 13:05       -option2 -option3
   my_perl_script.pl -date 10 december 95 13:05:00 -option2 -option3
the following lines correctly parse @ARGV:
   shift(@ARGV);              # to remove "-date"
   $date=&ParseDate(\@ARGV);
All elements in @ARGV which form the date are removed leaving @ARGV
equal to (-option2,-option3).

This method can be a bit deceptive since any kind of typo may lead
to erroneous results.  For example, typing:
   my_perl_script.pl -date 12/10/95 13:055
would return a date (12/10/95) but would leave 13:055 as the first
element of @ARGV since it cannot be parsed to form a valid date.

A safer way to use ParseDate would be to combine all elements in
@ARGV which are known to be part of the date into a single string
and use the call:
   $date=&ParseDate([$str]);
If $str contains a valid date, that date is returned.  Otherwise,
$date will be empty indicating an invalid date.

Another routine similar to &ParseDate is &ParseDateDelta.  This reads a
time offset rather than a time.  Strings such as " + 5 hours 3 minutes", "6
years 5 months ago", or "in 1 day 2:10:00" are all understood.  See the
full description of the routine for a full description of the different
formats.  This offset can be passed to &DateCalc (described below).

DateCalc is used to add dates and offsets together.  The format is
   $d=&DateCalc($d1,$d2,\$err,$del)
where $d1 and $d2 are dates or deltas (or can be interpreted to be such).
For example, the following:
   $d=&DateCalc("now","6 months ago",\$err,0)
will return a date which is exactly 6 months earlier then the current
time and date.  DateCalc can be used to determine the amount of time
between two dates, add two offsets together, or add an offset to a date
to get another date.  Read the full description of the routine for an
explanation of $err and $del.

To convert the date returned by &ParseDate to any other format, use the
routine &UnixDate:
   @date=&UnixDate($date,@format)
where $date is a date returned from &ParseDate and @format is a list of
strings containing formats similar to the unix date command.  For example,
the lines:
   $date=&ParseDate(["Dec 25 1995  07:00"]);
   ($d)=&UnixDate($date,"%A  $b %d %Y");
   print "$d\n";
would return
   Monday  Dec 25 1995
A list of all formats is contained in the description of UnixDate.