Copyright (c) 1995-1999 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.

For information on installing Date::Manip, see the INSTALL file included in
the distribution.

Please send questions or bug reports to me rather than posting them to
a newsgroup since I may miss them there, BUT read the next paragraph
before you automatically start firing off email to me!

If you have questions about Date::Manip, refer to the Date::Manip man page
included as pod documentation in the Manip.pm file.  Don't know what I'm
talking about?  Read the perlpod man page.  Alternately, an online version
of the Date::Manip man page is included in my home page given below.
PLEASE read the man page thoroughly before posting any questions about
Date::Manip to a newsgroup or emailing me.  If you've done this, I'll be
glad to answer any questions not covered in the man page.


** IMPORTANT NOTE (5.30) **

I plan on changing the internal format for a date to include the timezone.
The format will be YYYYMMDDHH:MN:SS*Timezone (instead of the ISO 8601
format YYYYMMDDHH:MN:SS+HHMN previously listed here).  Timezone will be in
the format US/Eastern to allow me to handle daylight savings time
situations.  In order to prepare for this, you are encouraged not to parse
or compare dates yourself.  Use UnixDate and Date_Cmp instead.


Notes for version 5.34:
  *** Added Date_Cmp routine in prepartion for the internale format change.
  Lots of bug fixes.
  Lots of documentation fixes.
  Added exact business mode for date calculations.
  Changed interpretation of business week (now the same as 7 days).
  Added Portuguese.
  *** Declared all variables with my(VAR) so there's no access to internals.
  Changed %z UnixDate format to return GMT offset.
  Fixed "22nd sunday" to return the 22nd sunday of the year instead of
    sunday of week 22.
  Added mmmYYYY and YYYYmmm formats.
  Added a couple more timezones.

Backwards incompatibilities:

  Version 5.34
    A business week is now interpreted the same as an exact week.
    *** All Date::Manip variables are declared with my(VAR), so no
      more access to internals.
    %z UnixDate format now returns the timezone as a GMT offset.  %Z still
      returns the abbreviation.
    The format "22nd sunday" now returns the real 22nd sunday, NOT the sunday
      of week 22 (based on whatever definition of week 1 is active).
    "DDYYmmm" and "mmmDDYY" formats changed to "DD/YYmmm" and "mmmDD/YY".
    *** Date_Cmp added in preparation for the change in internal format to
      include the timezone.


  ############################################################################
  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:
    sbeck@cise.ufl.edu

  The newest version (which should be considered a beta version) is available
  through my home page:
    http://www.cise.ufl.edu/~sbeck/
  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.  From the very beginning, the main
focus of Date::Manip has been to be able to do ANY desired date/time
operation easily, not necessarily quickly.  There are other modules that
can do a small subset of the operations available in Date::Manip much
quicker than those presented here, so if speed is a primary issue, you
should look elsewhere.  Check out the CPAN listing of Time and Date
modules.  But for sheer flexibility, I believe that Date::Manip is your
best bet.

Date::Manip deals with time as it is presented 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 historical dates,
but should be able to perform (virtually) any operation dealing with a
modern time and date.

Date::Manip has (or will have) functionality to work with several fundamental
types of data.

DATE

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).  It doesn't work with fractional seconds.
Timezones are also supported.

NOTE:  Much better support for timezones (including Daylight Savings Time)
is planned for the future.

DELTA

This refers to a duration or elapsed time.  One thing to note is that, as
used in this module, a delta refers only to the amount of time elapsed.  It
includes no information about a starting or ending time.

RECURRENCE

A recurrence is simply a notation for defining when a recurring event
occurs.  For example, if an event occurs every other Friday or every
4 hours, this can be defined as a recurrence.  With a recurrence and a
starting and ending date, you can get a list of dates in that period when
a recurring event occurs.

GRAIN

The granularity of a time basically refers to how accurate you wish to
treat a date.  For example, if you want to compare two dates to see if
they are identical at a granularity of days, then they only have to occur
on the same day.  At a granularity of an hour, they have to occur within
an hour of each other, etc.

NOTE:  Support for this will be added soon.

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.).

7.  To find a list of dates where a recurring event happens.

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

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);
  $flag=&Date_Cmp($date1,$date2);
  if ($flag<0) {
    # date1 is earlier
  } elsif ($flag==0) {
    # the two dates are identical
  } else {
    # date2 is earlier
  }

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

7.  To find a list of dates where a recurring event happens.

  # To find the 2nd tuesday of every month
  @date=&ParseRecur("0:1*2:2:0:0:0",$base,$start,$stop);

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 (sbeck@cise.ufl.edu)

