Subject: ANNOUNCE: Date::Manip 5.07 (now with business dates)
From: Sullivan Beck <[email-masked]>
Date: 15 Dec 1996 20:00:14 GMT
Newsgroups: comp.lang.perl.announce,comp.lang.perl.misc

I have just uploaded Date::Manip 5.07 to CPAN.  It should be available for
download within a day or two.
I have included the README file below.

For users of old versions of Date::Manip, you need to check the Date::Manip::TZ
variable.  If you get the message:
  ERROR:  Date::Manip unable to determine TimeZone.
it means that Date::Manip couldn't find a timezone anywhere that met RFC
822 standards, so you need to set it explicitely.  You can set it either at
the top of the Manip.pm file, or in your .DateManip.cnf file.  In the next
version I will add some non RFC 822 timezones (like PST8PDT and
US/Pacific), but I haven't had time to do it yet.  Past versions were
distributed with the timezone defaulting to "EST" if no RFC 822 timezone
name could be found which is why this error didn't occur previously.  The
man page has a list of all supported timezone names.

Copyright (c) 1995,1996 Sullivan Beck. All rights reserved.
This program is free software; you can redistribute it and/or
modify it under the same terms as Perl itself.

Notes for version 5.07:
  DateCalc can now handle three modes: exact, approximate, and business
    mode.  Business mode allows you to ignore weekends/holidays in
    calculations.
  A config file has now been added to configure Date::Manip as well as to
    define holidays.  Date_Init has been changed to handle a new, flexible
    way of configuring options.  There are lots of new config variables.
  Deltas are now almost always all positive or all negative (making them
    much more natural to work with).
  Date_GetNext and Date_GetPrev enhanced.
  Added a much needed test suite.

  Added new formats to UnixDate: %q, %P, %o, %s (changed), %g
  Added new formats to ParseDate:
    sunday week 22 [in 1996] [at 12:00]
    22nd sunday [in 1996] [at 12:00]
    sunday 22nd week [in 1996] [at 12:00]
    next/last friday [at time]
    next/last week [at time]
    in 2 weeks [at time]
    2 weeks ago [at time]
    Friday in 2 weeks
    in 2 weeks on friday
    Friday 2 weeks ago
    2 weeks ago friday
  Added weeks to ParseDateDelta.
  Added routine Date_SecsSince1970GMT
  Date_SetTime now handles international time formats.
  Subroutines which require 4 digit years now do error checking.

  Several bug fixes.

  Version 5.07 has a few minor incompatibilities with previous versions:
    The %s format has changed.  The old %s (secs since 1970) is %o.  %s
       is now secs since 1970 GMT.
    By default, deltas are stored with fewer signs.  If you want signs for
       each delta element, set the config variable DeltaSigns=1.
    Date_Init arguments changed.  The old method is still supported, but
       old format calls to Date_Init should be rewritten.

  ***NOTE***  The next version of Date::Manip will feature compatibility
  with ISO 8601.  The standard date format is YYYY-MM-DD and YY-MM-DD (with
  a number of variations).  This represents an incompatiblity with older
  versions of Date::Manip.  Based on common American usage, I have parsed
  dates in the form MM%DD%YY with any of the character ". / -" as separators.
  That is, 12-10-1965, 12/10/1965, and 12.10.1965 all worked.  Since "-" is
  the standard character for ISO 8601 dates, there are a number of conflicts
  between ISO 8601 formats and previously allowed format.  In the event of a
  conflict, the ISO 8601 date will take priority.  Although I will try to
  minimize the incompatibilities, I would encourage people to NOT use "-" as
  a separator.  If they are used, change them to "/" before passing the date
  to Date::Manip.  Comments and questions are welcome.

  ############################################################################
  If you would like to stay informed about future versions of this module,
  and especially if you are interested in beta testing future versions,
  please let me know by email at:
    [email-masked]

  The newest version (which should be considered a beta version) is available
  through my home page:
    http://www.qtp.ufl.edu/~beck
  Feel free to try it out.

  The current (non-beta) version of this module is available from you nearest
  CPAN site and is NOT available from my home page.  I will announce new
  (non-beta) releases in comp.lang.perl.misc and comp.lang.perl.announce.  
  ############################################################################

This is a set of routines designed to make any common date/time
manipulation easy to do.  Operations such as comparing two times,
calculating a time a given amount of time from another, or parsing
international times are all easily done.

Date::Manip deals only with the Gregorian calendar (the one currently in
use).  The Julian calendar defined leap years as every 4th year.  The
Gregorian calendar improved this by making every 100th year NOT a leap
year, unless it was also the 400th year.  The Gregorian calendar has been
extrapolated back to the year 1000 AD and forward to the year 9999 AD.
Note that in historical context, the Julian calendar was in use until 1582
when the Gregorian calendar was adopted by the Catholic church.  Protestant
countries did not accept it until later; Germany and Netherlands in 1698,
British Empire in 1752, Russia in 1918.  Note that the Gregorian calendar
is itself imperfect.  Each year is on average 26 seconds too long, which
means that every 3,323 years, a day should be removed from the calendar.
No attempt is made to correct for that.

Date::Manip is therefore not equipped to truly deal with historacle dates,
but should be able to perform (virtually) any operation dealing with a
modern time and date.

Among other things, Date::Manip allow you to:

1.  Enter a date and be able to choose any format conveniant

2.  Compare two dates, entered in widely different formats to determine
    which is earlier

3.  Extract any information you want from ANY date using a format string
    similar to the Unix date command

4.  Determine the amount of time between two dates

5.  Add a time offset to a date to get a second date (i.e. determine the
    date 132 days ago or 2 years and 3 months after Jan 2, 1992)

6.  Work with dates with dates using international formats (foreign month
    names, 12-10-95 referring to October rather than December, etc.).

Each of these tasks is trivial (one or two lines at most) with this package.

Although the word date is used extensively here, it is actually somewhat
misleading.  Date::Manip works with the full date AND time (year, month,
day, hour, minute, second).

In the documentation below, US formats are used, but in most (if not all)
cases, a non-English equivalent will work equally well.

EXAMPLES:

1.  Parsing a date from any conveniant format

  $date=&ParseDate("today");
  $date=&ParseDate("1st thursday in June 1992");
  $date=&ParseDate("05-10-93");
  $date=&ParseDate("12:30 Dec 12th 1880");
  $date=&ParseDate("8:00pm december tenth");
  if (! $date) {
    # Error in the date
  }

2.  Compare two dates

  $date1=&ParseDate($string1);
  $date2=&ParseDate($string2);
  if ($date1 lt $date2) {
    # date1 is earlier
  } else {
    # date2 is earlier (or the two dates are identical)
  }

3.  Extract information from a date.

  print &UnixDate("today","The time is now %T on %b %e, %Y.");
  =>  "The time is now 13:24:08 on Feb  3, 1996."

4.  The amount of time between two dates.

  $date1=&ParseDate($string1);
  $date2=&ParseDate($string2);
  $delta=&DateCalc($date1,$date2,\$err);
  => 0:0:DD:HH:MM:SS   the days, hours, minutes, and seconds between the two
  $delta=&DateCalc($date1,$date2,\$err,1);
  => YY:MM:DD:HH:MM:SS  the years, months, etc. between the two

  Read the documentation in the man page for an explanation of the difference.

5.  To determine a date a given offset from another.

  $date=&DateCalc("today","+ 3hours 12minutes 6 seconds",\$err);
  $date=&DateCalc("12 hours ago","12:30 6Jan90",\$err);

  It even works with business days:

  $date=&DateCalc("today","+ 3 business days",\$err);

6.  To work with dates in another language.

  &Date_Init("Language=French","DateFormat=non-US");
  $date=&ParseDate("1er decembre 1990");

NOTE: Some date forms do not work as well in languages other than English,
but this is not because DateManip is incapable of doing so (almost nothing
in this module is language dependent).  It is simply that I do not have the
correct translation available for some words.  If there is a date form that
works in English but does not work in a language you need, let me know and
if you can provide me the translation, I will fix DateManip.

For documentation on all of the date manipulation routines, read the
man page.

AUTHOR

Sullivan Beck ([email-masked])