[OpenSPARC-T2-DV] / tools / perl-5.8.0 / man / man3 / Date::Manip.3

.\" Automatically generated by Pod::Man v1.34, Pod::Parser v1.13
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sh \" Subsection heading
.br
.if t .Sp
.ne 5
.PP
\fB\\$1\fR
.PP
..
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  | will give a
.\" real vertical bar.  \*(C+ will give a nicer C++.  Capital omega is used to
.\" do unbreakable dashes and therefore won't be available.  \*(C` and \*(C'
.\" expand to `' in nroff, nothing in troff, for use with C<>.
.tr \(*W-|\(bv\*(Tr
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.if \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.\"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.hy 0
.if n .na
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "MANIP 1"
.TH MANIP 1 "2003-07-02" "perl v5.8.0" "User Contributed Perl Documentation"
.SH "NAME"
Date::Manip \- date manipulation routines
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& use Date::Manip;
.Ve
.PP
.Vb 3
\& $date = ParseDate(\e@args);
\& $date = ParseDate($string);
\& $date = ParseDate(\e$string);
.Ve
.PP
.Vb 2
\& @date = UnixDate($date,@format);
\& $date = UnixDate($date,@format);
.Ve
.PP
.Vb 3
\& $delta = ParseDateDelta(\e@args);
\& $delta = ParseDateDelta($string);
\& $delta = ParseDateDelta(\e$string);
.Ve
.PP
.Vb 2
\& @str = Delta_Format($delta,$dec,@format);
\& $str = Delta_Format($delta,$dec,@format);
.Ve
.PP
.Vb 2
\& $recur = ParseRecur($string,$base,$date0,$date1,$flags);
\& @dates = ParseRecur($string,$base,$date0,$date1,$flags);
.Ve
.PP
.Vb 1
\& $flag = Date_Cmp($date1,$date2);
.Ve
.PP
.Vb 1
\& $d = DateCalc($d1,$d2 [,$errref] [,$del]);
.Ve
.PP
.Vb 2
\& $date = Date_SetTime($date,$hr,$min,$sec);
\& $date = Date_SetTime($date,$time);
.Ve
.PP
.Vb 1
\& $date = Date_SetDateField($date,$field,$val [,$nocheck]);
.Ve
.PP
.Vb 2
\& $date = Date_GetPrev($date,$dow,$today,$hr,$min,$sec);
\& $date = Date_GetPrev($date,$dow,$today,$time);
.Ve
.PP
.Vb 2
\& $date = Date_GetNext($date,$dow,$today,$hr,$min,$sec);
\& $date = Date_GetNext($date,$dow,$today,$time);
.Ve
.PP
.Vb 1
\& $version = DateManipVersion;
.Ve
.PP
.Vb 1
\& $flag = Date_IsWorkDay($date [,$flag]);
.Ve
.PP
.Vb 2
\& $date = Date_NextWorkDay($date,$off [,$time]);
\& $date = Date_PrevWorkDay($date,$off [,$time]);
.Ve
.PP
.Vb 1
\& $name = Date_IsHoliday($date);
.Ve
.PP
.Vb 2
\& $listref = Events_List($date);
\& $listref = Events_List($date0,$date1);
.Ve
.PP
.Vb 4
\& &Date_Init();
\& &Date_Init("VAR=VAL","VAR=VAL",...);
\& @list = Date_Init();
\& @list = Date_Init("VAR=VAL","VAR=VAL",...);
.Ve
.PP
The above routines all check to make sure that Date_Init is called.  If it
hasn't been, they will call it automatically.  As a result, there is usually
no need to call Date_Init explicitely unless you want to change some of the
config variables (described below).
.PP
The following routines are used by the above routines (though they can also
be called directly).  \f(CW$y\fR may be entered as either a 2 or 4 digit year (it
will be converted to a 4 digit year based on the variable YYtoYYYY
described below).  Month and day should be numeric in all cases.  Most (if
not all) of the information below can be gotten from UnixDate which is
really the way I intended it to be gotten, but there are reasons to use
these (these are significantly faster).
.PP
***NOTE*** Unlike the routines listed above, the following routines do \s-1NOT\s0
explicitely call Date_Init.  You must make sure that Date_Init has been
called, either by you explicitely, or by one of the above routines before you
use these routines.
.PP
.Vb 11
\& $day = Date_DayOfWeek($m,$d,$y);
\& $secs = Date_SecsSince1970($m,$d,$y,$h,$mn,$s);
\& $secs = Date_SecsSince1970GMT($m,$d,$y,$h,$mn,$s);
\& $days = Date_DaysSince1BC($m,$d,$y);
\& $day = Date_DayOfYear($m,$d,$y);
\& $days = Date_DaysInYear($y);
\& $wkno = Date_WeekOfYear($m,$d,$y,$first);
\& $flag = Date_LeapYear($y);
\& $day = Date_DaySuffix($d);
\& $tz = Date_TimeZone();
\& ($y,$m,$d,$h,$mn,$s) = Date_NthDayOfYear($y,$n);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
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 \s-1ANY\s0 desired date/time
operation easily, not necessarily quickly.  Also, it is definitely oriented
towards the type of operations we (as people) tend to think of rather than
those operations used routinely by computers.  There are other modules that
can do a subset of the operations available in Date::Manip much quicker
than those presented here, so be sure to read the section \s-1SHOULD\s0 I \s-1USE\s0
\&\s-1DATE::MANIP\s0 below before deciding which of the Date and Time modules from
\&\s-1CPAN\s0 is for you.
.PP
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 \s-1NOT\s0
a leap year, unless it was also the 400th year.  The Gregorian calendar has
been extrapolated back to the year 0000 \s-1AD\s0 and forward to the year 9999 \s-1AD\s0.
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 and at some point will need to be corrected.  No attempt
is made to correct for that, and my great great great grandchildren will be
long dead before this even occurs, so it's not an immediate concern.  Yes,
this is the same type of attitute that caused the great Y2K problem... but
I have an excuse: I don't know what the correction will be, so I can't
possible implement it.  Nobody doubted that the year after 1999 would be
known as 2000 :\-).
.PP
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.
.PP
Date::Manip has (or will have) functionality to work with several fundamental
types of data.
.IP "\s-1DATE\s0" 4
.IX Item "DATE"
Although the word date is used extensively here, it is actually somewhat
misleading.  Date::Manip works with the full date \s-1AND\s0 time (year, month,
day, hour, minute, second and weeks when appropriate).  It doesn't work
with fractional seconds.  Timezones are also supported to some extent.
.Sp
\&\s-1NOTE:\s0  Much better support for timezones (including Daylight Savings Time)
is planned for the future.
.IP "\s-1DELTA\s0" 4
.IX Item "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.
.IP "\s-1RECURRENCE\s0" 4
.IX Item "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.
.IP "\s-1GRAIN\s0" 4
.IX Item "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.
.Sp
\&\s-1NOTE:\s0  Support for this will be added in the future.
.IP "\s-1HOLIDAYS\s0 and \s-1EVENTS\s0" 4
.IX Item "HOLIDAYS and EVENTS"
These are basically a named time.  Holidays are used in business mode
calculations.  Events allow things like calendar and scheduling
applications to be designed much more easily.
.PP
Among other things, Date::Manip allow you to:
.PP
1.  Enter a date and be able to choose any format convenient
.PP
2.  Compare two dates, entered in widely different formats
    to determine which is earlier
.PP
3.  Extract any information you want from \s-1ANY\s0 date using a
    format string similar to the Unix date command
.PP
4.  Determine the amount of time between two dates
.PP
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)
.PP
6.  Work with dates with dates using international formats
    (foreign month names, 12/10/95 referring to October
    rather than December, etc.).
.PP
7.  To find a list of dates where a recurring event happens.
.PP
Each of these tasks is trivial (one or two lines at most) with this package.
.SH "EXAMPLES"
.IX Header "EXAMPLES"
In the documentation below, \s-1US\s0 formats are used, but in most (if not all)
cases, a non-English equivalent will work equally well.
.PP
1.  Parsing a date from any convenient format
.PP
.Vb 8
\&  $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
\&  }
.Ve
.PP
2.  Compare two dates
.PP
.Vb 10
\&  $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
\&  }
.Ve
.PP
3.  Extract information from a date.
.PP
.Vb 2
\&  print &UnixDate("today","It is now %T on %b %e, %Y.");
\&    =>  "It is now 13:24:08 on Feb  3, 1996."
.Ve
.PP
4.  The amount of time between two dates.
.PP
.Vb 8
\&  $date1 = ParseDate($string1);
\&  $date2 = ParseDate($string2);
\&  $delta = DateCalc($date1,$date2,\e$err);
\&    => 0:0:WK:DD:HH:MM:SS   the weeks, days, hours, minutes,
\&                            and seconds between the two
\&  $delta = DateCalc($date1,$date2,\e$err,1);
\&    => YY:MM:WK:DD:HH:MM:SS  the years, months, etc. between
\&                             the two
.Ve
.PP
.Vb 2
\&  Read the documentation below for an explanation of the
\&  difference.
.Ve
.PP
5.  To determine a date a given offset from another.
.PP
.Vb 2
\&  $date = DateCalc("today","+ 3hours 12minutes 6 seconds",\e$err);
\&  $date = DateCalc("12 hours ago","12:30 6Jan90",\e$err);
.Ve
.PP
.Vb 1
\&  It even works with business days:
.Ve
.PP
.Vb 1
\&  $date = DateCalc("today","+ 3 business days",\e$err);
.Ve
.PP
6.  To work with dates in another language.
.PP
.Vb 2
\&  &Date_Init("Language=French","DateFormat=non-US");
\&  $date = ParseDate("1er decembre 1990");
.Ve
.PP
7.  To find a list of dates where a recurring event happens
    (including quite complex ones).
.PP
.Vb 2
\&  # To find the 2nd tuesday of every month
\&  @date = ParseRecur("0:1*2:2:0:0:0",$base,$start,$stop);
.Ve
.PP
.Vb 2
\&  # To find the Monday after easter in 1997-1999.
\&  @date = ParseRecur("*1997-1999:0:0:0:0:0:0*EASTER,ND1");
.Ve
.PP
\&\s-1NOTE:\s0 Some date forms do not work as well in languages other than English,
but this is not because Date::Manip 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 Date::Manip.
.SH "SHOULD I USE DATE::MANIP"
.IX Header "SHOULD I USE DATE::MANIP"
If you look in \s-1CPAN\s0, you'll find that there are a number of Date and Time
packages.  Is Date::Manip the one you should be using?  In my opinion, the
answer is no most of the time.  This sounds odd coming from the author of
the software, but read on.
.PP
Date::Manip is written entirely in perl.  It's the most powerful of the
date modules.  It's also the biggest and slowest.
.PP
Since Date::Manip is written entirely in perl, and depends on no other
module not in a standard perl distribution, Date::Manip has no dependancies
to meet.  Other modules have dependancies on a C compiler or other perl
modules.  Since it is fairly easy to satisfy these dependancies for
anyone who is reasonably familiar with perl modules, this is not a
huge advantage that Date::Manip has.
.PP
On the other hand, simpler perl modules tend to be faster than Date::Manip,
and modules written in C are significantly faster than their perl
counterparts (at least if they're done right).  The TimeDate and
Time-modules modules are written in perl, but are much simpler (and
hence, faster) than Date::Manip.  The Date::Calc module is written in C
and is a good module for doing many date calculations much faster than
Date::Manip.  Between these three, most of your common date operations
can be done.
.PP
Date::Manip is certainly the most powerful of the Date modules.  To the
best of my knowledge, it will do everything that any other date module will
do (not just the ones I listed above), and there are a number of features
that Date::Manip has that none of the other modules have.  Date::Manip is
the \*(L"Swiss Army Knife\*(R" of Date modules.  I'm trying to build a library
which can do _EVERY_ conceivable date/time manipulation that you'll run
into in everyday life.
.PP
Although I am working on making Date::Manip faster, it will never be as
fast as other modules.  And before anyone asks, Date::Manip will never
be translated to C (at least by me).  I write C because I have to.  I
write perl because I like to.  Date::Manip is something I do because it
interests me, not something I'm paid for.
.PP
Date::Manip is also big.  The last time I looked, it's one of the largest
\&\s-1CPAN\s0 modules there is.  If you ignore modules like Tk, \s-1LWP\s0, etc. which are
actually packages of modules, it may be the largest.  It's true that
Date::Manip will do almost every date operation you could imagine... but
you rarely need all that power.  I'm working on reducing the footprint of
Date::Manip, but even at it's slimmest, it'll outweigh the other modules by
a good bit.
.PP
If you are going to be using the module in cases where performance is an
important factor (started up in a \s-1CGI\s0 program being run by your web server
5,000 times a second), you should check out one of the other Date or Time
modules in \s-1CPAN\s0.  If you're only doing fairly simple date operations
(parsing common date formats, finding the difference between two dates,
etc.), the other modules will almost certainly suffice.  If you're doing
one operation very repetitively (parsing 10,000 dates from a database), you
are probably better off writing your own functions (perhaps bypassing all
date modules entirely) designed specifically for your needs.
.PP
On the other hand, if you want one solution for all your date needs, don't
need peak speed, or are trying to do more exotic date operations,
Date::Manip is for you.  Operations on things like business dates, foreign
language dates, holidays and other recurring events, etc. are available
more-or-less exclusively in Date::Manip.
.SH "ROUTINES"
.IX Header "ROUTINES"
.IP "ParseDate" 4
.IX Item "ParseDate"
.Vb 3
\& $date = ParseDate(\e@args);
\& $date = ParseDate($string);
\& $date = ParseDate(\e$string);
.Ve
.Sp
This takes an array or a string containing a date and parses it.  When the
date is included as an array (for example, the arguments to a program) the
array should contain a valid date in the first one or more elements
(elements after a valid date are ignored).  Elements containing a valid
date are shifted from the array.  The largest possible number of elements
which can be correctly interpreted as a valid date are always used.  If a
string is entered rather than an array, that string is tested for a valid
date.  The string is unmodified, even if passed in by reference.
.Sp
The real work is done in the ParseDateString routine.
.Sp
The ParseDate routine is primarily used to handle command line arguments.
If you have a command where you want to enter a date as a command line
argument, you can use Date::Manip to make something like the following
work:
.Sp
.Vb 1
\&  mycommand -date Dec 10 1997 -arg -arg2
.Ve
.Sp
No more reading man pages to find out what date format is required in a
man page.
.Sp
Historical note: this is originally why the Date::Manip routines were
written (though long before they were released as the Date::Manip module).
I was using a bunch of programs (primarily batch queue managers) where
dates and times were entered as command line options and I was getting
highly annoyed at the many different (but not compatible) ways that they
had to be entered.  Date::Manip originally consisted of basically 1 routine
which I could pass \*(L"@ARGV\*(R" to and have it remove a date from the beginning.
.IP "ParseDateString" 4
.IX Item "ParseDateString"
.Vb 1
\& $date = ParseDateString($string);
.Ve
.Sp
This routine is called by ParseDate, but it may also be called directly
to save some time (a negligable amount).
.Sp
\&\s-1NOTE:\s0  One of the most frequently asked questions that I have gotten
is how to parse seconds since the epoch.  ParseDateString cannot simply
parse a number as the seconds since the epoch (it conflicts with some
\&\s-1ISO\-8601\s0 date formats).  There are two ways to get this information.
First, you can do the following:
.Sp
.Vb 2
\&    $secs = ...         # seconds since Jan 1, 1970  00:00:00 GMT
\&    $date = &DateCalc("Jan 1, 1970  00:00:00 GMT",$secs);
.Ve
.Sp
Second, you can call it directly as:
.Sp
.Vb 1
\&    $date = &ParseDateString("epoch $secs");
.Ve
.Sp
To go backwards, just use the \*(L"%s\*(R" format of UnixDate:
.Sp
.Vb 1
\&    $secs = &UnixDate($date,"%s");
.Ve
.Sp
A full date actually includes 2 parts: date and time.  A time must include
hours and minutes and can optionally include seconds, fractional seconds,
an am/pm type string, and a timezone.  For example:
.Sp
.Vb 5
\&     [at] HH:MN              [Zone]
\&     [at] HH:MN         [am] [Zone]
\&     [at] HH:MN:SS      [am] [Zone]
\&     [at] HH:MN:SS.SSSS [am] [Zone]
\&     [at] HH            am   [Zone]
.Ve
.Sp
Hours can be written using 1 or 2 digits, but the single digit form may
only be used when no ambiguity is introduced (i.e. when it is not
immediately preceded by a digit).
.Sp
A time is usually entered in 24 hour mode, but 12 hour mode can be used
as well if \s-1AM/PM\s0 are entered (\s-1AM\s0 can be entered as \s-1AM\s0 or A.M. or other
variations depending on the language).
.Sp
Fractional seconds are also supported in parsing but the fractional part is
discarded (with \s-1NO\s0 rounding ocurring).
.Sp
Timezones always appear immediately after the time.  A number of different
forms are supported (see the section TIMEZONEs below).
.Sp
Incidentally, the time is removed from the date before the date is parsed,
so the time may appear before or after the date, or between any two parts
of the date.
.Sp
Valid date formats include the \s-1ISO\s0 8601 formats:
.Sp
.Vb 18
\&   YYYYMMDDHHMNSSF...
\&   YYYYMMDDHHMNSS
\&   YYYYMMDDHHMN
\&   YYYYMMDDHH
\&   YY-MMDDHHMNSSF...
\&   YY-MMDDHHMNSS
\&   YY-MMDDHHMN
\&   YY-MMDDHH
\&   YYYYMMDD
\&   YYYYMM
\&   YYYY
\&   YY-MMDD
\&   YY-MM
\&   YY
\&   YYYYwWWD      ex.  1965-W02-2
\&   YYwWWD
\&   YYYYDOY       ex.  1965-045
\&   YYDOY
.Ve
.Sp
In the above list, \s-1YYYY\s0 and \s-1YY\s0 signify 4 or 2 digit years, \s-1MM\s0, \s-1DD\s0, \s-1HH\s0, \s-1MN\s0, \s-1SS\s0
refer to two digit month, day, hour, minute, and second respectively.  F...
refers to fractional seconds (any number of digits) which will be ignored.
The last 4 formats can be explained by example:  1965\-w02\-2 refers to Tuesday
(day 2) of the 2nd week of 1965.  1965\-045 refers to the 45th day of 1965.
.Sp
In all cases, parts of the date may be separated by dashes \*(L"\-\*(R".  If this is
done, 1 or 2 digit forms of \s-1MM\s0, \s-1DD\s0, etc. may be used.  All dashes are
optional except for those given in the table above (which \s-1MUST\s0 be included
for that format to be correctly parsed).  So 19980820, 1998\-0820,
1998\-08\-20, 1998\-8\-20, and 199808\-20 are all equivalent, but that date may
\&\s-1NOT\s0 be written as 980820 (it must be written as 98\-0820).
.Sp
\&\s-1NOTE:\s0  Even though not allowed in the standard, the timezone for an \s-1ISO\-8601\s0
date is flexible and may be any of the timezones understood by Date::Manip.
.Sp
Additional date formats are available which may or may not be common including:
.Sp
.Vb 3
\&  MM/DD  **
\&  MM/DD/YY  **
\&  MM/DD/YYYY  **
.Ve
.Sp
.Vb 3
\&  mmmDD       DDmmm                   mmmYYYY/DD     mmmYYYY
\&  mmmDD/YY    DDmmmYY     DD/YYmmm    YYYYmmmDD      YYYYmmm
\&  mmmDDYYYY   DDmmmYYYY   DDYYYYmmm   YYYY/DDmmm
.Ve
.Sp
Where mmm refers to the name of a month.  All parts of the date can be
separated by valid separators (space, \*(L"/\*(R", or \*(L".\*(R").  The separator \*(L"\-\*(R" may
be used as long as it doesn't conflict with an \s-1ISO\s0 8601 format, but this
is discouraged since it is easy to overlook conflicts.  For example, the
format \s-1MM/DD/YY\s0 is just fine, but MM-DD-YY does not work since it conflicts
with \s-1YY\-MM\-DD\s0.  To be safe, if \*(L"\-\*(R" is used as a separator in a non-ISO
format, they should be turned into \*(L"/\*(R" before calling the Date::Manip
routines.  As with \s-1ISO\s0 8601 formats, all separators are optional except for
those given as a \*(L"/\*(R" in the list above.
.Sp
** Note that with these formats, Americans tend to write month first, but
many other countries tend to write day first.  The latter behavior can be
obtained by setting the config variable DateFormat to something other than
\&\*(L"\s-1US\s0\*(R" (see \s-1CUSTOMIZING\s0 \s-1DATE::MANIP\s0 below).
.Sp
Date separators are treated very flexibly (they are converted to spaces),
so the following dates are all equivalent:
.Sp
.Vb 3
\&   12/10/1965
\&   12-10 / 1965
\&   12 // 10 -. 1965
.Ve
.Sp
In some cases, this may actually be \s-1TOO\s0 flexible, but no attempt is made to
trap this.
.Sp
Years can be entered as 2 or 4 digits, days and months as 1 or 2 digits.
Both days and months must include 2 digits whenever they are immediately
adjacent to another numeric part of the date or time.  Date separators
are required if single digit forms of \s-1DD\s0 or \s-1MM\s0 are used.  If separators
are not used, the date will either be unparsable or will get parsed
incorrectly.
.Sp
Miscellaneous other allowed formats are:
  which dofw in mmm in \s-1YY\s0      \*(L"first sunday in june 1996 at 14:00\*(R" **
  dofw week num \s-1YY\s0             \*(L"sunday week 22 1995\*(R" **
  which dofw \s-1YY\s0                \*(L"22nd sunday at noon\*(R" **
  dofw which week \s-1YY\s0           \*(L"sunday 22nd week in 1996\*(R" **
  next/last dofw               \*(L"next friday at noon\*(R"
  next/last week/month         \*(L"next month\*(R"
  in num days/weeks/months     \*(L"in 3 weeks at 12:00\*(R"
  num days/weeks/months later  \*(L"3 weeks later\*(R"
  num days/weeks/months ago    \*(L"3 weeks ago\*(R"
  dofw in num week             \*(L"Friday in 2 weeks\*(R"
  in num weeks dofw            \*(L"in 2 weeks on friday\*(R"
  dofw num week ago            \*(L"Friday 2 weeks ago\*(R"
  num week ago dofw            \*(L"2 weeks ago friday\*(R"
  last day in mmm in \s-1YY\s0        \*(L"last day of October\*(R"
  dofw                         \*(L"Friday\*(R" (Friday of current week)
  Nth                          \*(L"12th\*(R", \*(L"1st\*(R" (day of current month)
  epoch \s-1SECS\s0                   seconds since the epoch (negative values
                               are supported)
.Sp
** Note that the formats \*(L"sunday week 22\*(R" and \*(L"22nd sunday\*(R" give very
different bahaviors.  \*(L"sunday week 22\*(R" returns the sunday of the 22nd week
of the year based on how week 1 is defined.  \s-1ISO\s0 8601 defines week one to
contain Jan 4, so \*(L"sunday week 1\*(R" might be the first or second sunday of
the current year, or the last sunday of the previous year.  \*(L"22nd sunday\*(R"
gives the actual 22nd time sunday occurs in a given year, regardless of the
definition of a week.
.Sp
Note that certain words such as \*(L"in\*(R", \*(L"at\*(R", \*(L"of\*(R", etc. which commonly appear
in a date or time are ignored.  Also, the year is always optional.
.Sp
In addition, the following strings are recognized:
  today     (exactly now \s-1OR\s0 today at a given time if a time is specified)
  now       (synonym for today)
  yesterday (exactly 24 hours ago unless a time is specified)
  tomorrow  (exactly 24 hours from now unless a time is specifed)
  noon      (12:00:00)
  midnight  (00:00:00)
Other languages have similar (and in some cases additional) strings.
.Sp
Some things to note:
.Sp
All strings are case insensitive.  \*(L"December\*(R" and \*(L"DEceMBer\*(R" both work.
.Sp
When a part of the date is not given, defaults are used: year defaults
to current year; hours, minutes, seconds to 00.
.Sp
The year may be entered as 2 or 4 digits.  If entered as 2 digits, it will
be converted to a 4 digit year.  There are several ways to do this based on
the value of the YYtoYYYY variable (described below).  The default behavior
it to force the 2 digit year to be in the 100 year period CurrYear\-89 to
CurrYear+10.  So in 1996, the range is [1907 to 2006], and the 2 digit year
05 would refer to 2005 but 07 would refer to 1907.  See \s-1CUSTOMIZING\s0
\&\s-1DATE::MANIP\s0 below for information on YYtoYYYY for other methods.
.Sp
Dates are always checked to make sure they are valid.
.Sp
In all of the formats, the day of week (\*(L"Friday\*(R") can be entered anywhere
in the date and it will be checked for accuracy.  In other words,
  \*(L"Tue Jul 16 1996 13:17:00\*(R"
will work but
  \*(L"Jul 16 1996 Wednesday 13:17:00\*(R"
will not (because Jul 16, 1996 is Tuesday, not Wednesday).  Note that
depending on where the weekday comes, it may give unexpected results when
used in array context (with ParseDate).  For example, the date
(\*(L"Jun\*(R",\*(L"25\*(R",\*(L"Sun\*(R",\*(L"1990\*(R") would return June 25 of the current year since
Jun 25, 1990 is not Sunday.
.Sp
The times \*(L"12:00 am\*(R", \*(L"12:00 pm\*(R", and \*(L"midnight\*(R" are not well defined.  For
good or bad, I use the following convention in Date::Manip:
  midnight = 12:00am = 00:00:00
  noon     = 12:00pm = 12:00:00
and the day goes from 00:00:00 to 23:59:59.  In other words, midnight is the
beginning of a day rather than the end of one.  The time 24:00:00 is also
allowed (though it is automatically transformed to 00:00:00 of the following
day).
.Sp
The format of the date returned is \s-1YYYYMMDDHH:MM:SS\s0.  The advantage of this
time format is that two times can be compared using simple string comparisons
to find out which is later.  Also, it is readily understood by a human.
Alternate forms can be used if that is more convenient.  See Date_Init below
and the config variable Internal.
.Sp
\&\s-1NOTE:\s0 The format for the date is going to change at some point in the future
to YYYYMMDDHH:MN:SS+HHMN*FLAGS.  In order to maintain compatibility, you
should use UnixDate to extract information from a date, and Date_Cmp to compare
two dates.  The simple string comparison will only work for dates in the same
timezone.
.IP "UnixDate" 4
.IX Item "UnixDate"
.Vb 2
\& @date = UnixDate($date,@format);
\& $date = UnixDate($date,@format);
.Ve
.Sp
This takes a date and a list of strings containing formats roughly
identical to the format strings used by the \s-1UNIX\s0 \fIdate\fR\|(1) command.  Each
format is parsed and an array of strings corresponding to each format is
returned.
.Sp
$date may be any string that can be parsed by ParseDateString.
.Sp
The format options are:
.Sp
.Vb 17
\& Year
\&     %y     year                     - 00 to 99
\&     %Y     year                     - 0001 to 9999
\&     %G     year                     - 0001 to 9999 (see below)
\&     %L     year                     - 0001 to 9999 (see below)
\& Month, Week
\&     %m     month of year            - 01 to 12
\&     %f     month of year            - " 1" to "12"
\&     %b,%h  month abbreviation       - Jan to Dec
\&     %B     month name               - January to December
\&     %U     week of year, Sunday
\&            as first day of week     - 01 to 53
\&     %W     week of year, Monday
\&            as first day of week     - 01 to 53
\& Day
\&     %j     day of the year          - 001 to 366
\&     %d     day of month             - 01 to 31
.Ve
.Sp
.Vb 47
\&     %e     day of month             - " 1" to "31"
\&     %v     weekday abbreviation     - " S"," M"," T"," W","Th"," F","Sa"
\&     %a     weekday abbreviation     - Sun to Sat
\&     %A     weekday name             - Sunday to Saturday
\&     %w     day of week              - 1 (Monday) to 7 (Sunday)
\&     %E     day of month with suffix - 1st, 2nd, 3rd...
\& Hour
\&     %H     hour                     - 00 to 23
\&     %k     hour                     - " 0" to "23"
\&     %i     hour                     - " 1" to "12"
\&     %I     hour                     - 01 to 12
\&     %p     AM or PM
\& Minute, Second, Timezone
\&     %M     minute                   - 00 to 59
\&     %S     second                   - 00 to 59
\&     %s     seconds from 1/1/1970 GMT- negative if before 1/1/1970
\&     %o     seconds from Jan 1, 1970
\&            in the current time zone
\&     %Z     timezone                 - "EDT"
\&     %z     timezone as GMT offset   - "+0100"
\& Date, Time
\&     %c     %a %b %e %H:%M:%S %Y     - Fri Apr 28 17:23:15 1995
\&     %C,%u  %a %b %e %H:%M:%S %z %Y  - Fri Apr 28 17:25:57 EDT 1995
\&     %g     %a, %d %b %Y %H:%M:%S %z - Fri, 28 Apr 1995 17:23:15 EDT
\&     %D,%x  %m/%d/%y                 - 04/28/95
\&     %l     date in ls(1) format
\&              %b %e $H:$M            - Apr 28 17:23  (if within 6 months)
\&              %b %e  %Y              - Apr 28  1993  (otherwise)
\&     %r     %I:%M:%S %p              - 05:39:55 PM
\&     %R     %H:%M                    - 17:40
\&     %T,%X  %H:%M:%S                 - 17:40:58
\&     %V     %m%d%H%M%y               - 0428174095
\&     %Q     %Y%m%d                   - 19961025
\&     %q     %Y%m%d%H%M%S             - 19961025174058
\&     %P     %Y%m%d%H%M%S             - 1996102517:40:58
\&     %F     %A, %B %e, %Y            - Sunday, January  1, 1996
\&     %J     %G-W%W-%w                - 1997-W02-2
\&     %K     %Y-%j                    - 1997-045
\& Other formats
\&     %n     insert a newline character
\&     %t     insert a tab character
\&     %%     insert a `%' character
\&     %+     insert a `+' character
\& The following formats are currently unused but may be used in the future:
\&     NO 1234567890 !@#$^&*()_|-=\e`[];',./~{}:<>?
\& They currently insert the character following the %, but may (and probably
\& will) change in the future as new formats are added.
.Ve
.Sp
If a lone percent is the final character in a format, it is ignored.
.Sp
Note that the ls format (%l) applies to date within the past \s-1OR\s0 future 6
months!
.Sp
The \f(CW%U\fR, \f(CW%W\fR, \f(CW%L\fR, and \f(CW%G\fR formats are used to support the \s-1ISO\-8601\s0 format:
YYYY\-wWW\-D.  In this format, a date is written as a year, the week of
the year, and the day of the week.  Technically, the week may be considered
to start on any day of the week, but Sunday and Monday are the two most
common choices, so both are supported.
.Sp
The \f(CW%U\fR and \f(CW%W\fR formats return a week-of-year number from 01 to 53, and
\&\f(CW%L\fR and \f(CW%G\fR return a 4\-digit year corresponding to the week.  Most of the
time, the \f(CW%L\fR and \f(CW%G\fR formats returns the same value as the \f(CW%Y\fR format,
but there is a problem with days occuring in the first or last week of
the year.
.Sp
The \s-1ISO\-8601\s0 representation of Jan 1, 1993 written in the YYYY-wWWW-D
format is actually 1992\-W53\-5.  In other words, Jan 1 is treates as being
in the last week of the preceding year.  Depending on the year, days in
the first week of a year may belong to the previous year, and days in the
final week of a year may belong to the next year.
.Sp
The \f(CW%L\fR and \f(CW%U\fR formats contains the year and week-of-year values treating
weeks as starting on Sunday.  The \f(CW%G\fR and \f(CW%W\fR formats are the year and
week-of-year values treating weeks as starting on Monday.
.Sp
%J returns the full \s-1ISO\-8601\s0 format (%G\-W%W\-%w).
.Sp
The formats used in this routine were originally based on date.pl (version
3.2) by Terry McGonigal, as well as a couple taken from different versions
of the Solaris \fIdate\fR\|(1) command.  Also, several have been added which are
unique to Date::Manip.
.IP "ParseDateDelta" 4
.IX Item "ParseDateDelta"
.Vb 3
\& $delta = ParseDateDelta(\e@args);
\& $delta = ParseDateDelta($string);
\& $delta = ParseDateDelta(\e$string);
.Ve
.Sp
This takes an array and shifts a valid delta date (an amount of time)
from the array.  Recognized deltas are of the form:
  +Yy +Mm +Ww +Dd +Hh +MNmn +Ss
      examples:
         +4 hours +3mn \-2second
         + 4 hr 3 minutes \-2
         4 hour + 3 min \-2 s
  +Y:+M:+W:+D:+H:+MN:+S
      examples:
         0:0:0:0:4:3:\-2
         +4:3:\-2
  mixed format
      examples:
         4 hour 3:\-2
.Sp
A field in the format +Yy is a sign, a number, and a string specifying
the type of field.  The sign is \*(L"+\*(R", \*(L"\-\*(R", or absent (defaults to the
next larger element).  The valid strings specifying the field type
are:
   y:  y, yr, year, years
   m:  m, mon, month, months
   w:  w, wk, ws, wks, week, weeks
   d:  d, day, days
   h:  h, hr, hour, hours
   mn: mn, min, minute, minutes
   s:  s, sec, second, seconds
.Sp
Also, the \*(L"s\*(R" string may be omitted.  The sign, number, and string may
all be separated from each other by any number of whitespaces.
.Sp
In the date, all fields must be given in the order: Y M W D H \s-1MN\s0 S.  Any
number of them may be omitted provided the rest remain in the correct
order.  In the 2nd (colon) format, from 2 to 7 of the fields may be given.
For example +D:+H:+MN:+S may be given to specify only four of the fields.
In any case, both the \s-1MN\s0 and S field may be present.  No spaces may be
present in the colon format.
.Sp
Deltas may also be given as a combination of the two formats.  For example,
the following is valid: +Yy +D:+H:+MN:+S.  Again, all fields must be given
in the correct order.
.Sp
The word \*(L"in\*(R" may be given (prepended in English) to the delta (\*(L"in 5 years\*(R")
and the word \*(L"ago\*(R" may be given (appended in English) (\*(L"6 months ago\*(R").  The
\&\*(L"in\*(R" is completely ignored.  The \*(L"ago\*(R" has the affect of reversing all signs
that appear in front of the components of the delta.  I.e. \*(L"\-12 yr 6 mon ago\*(R"
is identical to \*(L"+12yr +6mon\*(R" (don't forget that there is an implied minus
sign in front of the 6 because when no sign is explicitly given, it carries
the previously entered sign).
.Sp
One thing is worth noting.  The year/month and day/hour/min/sec parts are
returned in a \*(L"normalized\*(R" form.  That is, the signs are adjusted so as to
be all positive or all negative.  For example, \*(L"+ 2 day \- 2hour\*(R" does not
return \*(L"0:0:0:2:\-2:0:0\*(R".  It returns \*(L"+0:0:0:1:22:0:0\*(R" (1 day 22 hours
which is equivalent).  I find (and I think most others agree) that this is
a more useful form.
.Sp
Since the year/month and day/hour/min/sec parts must be normalized
separately there is the possibility that the sign of the two parts will be
different.  So, the delta \*(L"+ 2years \-10 months \- 2 days + 2 hours\*(R" produces
the delta \*(L"+1:2:\-0:1:22:0:0\*(R".
.Sp
It is possible to include a sign for all elements that is output.  See the
configuration variable DeltaSigns below.
.Sp
\&\s-1NOTE:\s0 The internal format of the delta changed in version 5.30 from
Y:M:D:H:MN:S to Y:M:W:D:H:MN:S .  Also, it is going to change again at some
point in the future to Y:M:W:D:H:MN:S*FLAGS .  Use the routine Delta_Format
to extract information rather than parsing it yourself.
.IP "Delta_Format" 4
.IX Item "Delta_Format"
.Vb 2
\& @str = Delta_Format($delta,$dec,@format);
\& $str = Delta_Format($delta,$dec,@format);
.Ve
.Sp
This is similar to the UnixDate routine except that it extracts information
from a delta.  Unlike the UnixDate routine, most of the formats are 2
characters instead of 1.
.Sp
Formats currently understood are:
.Sp
.Vb 6
\&   %Xv     : the value of the field named X
\&   %Xd     : the value of the field X, and all smaller fields, expressed in
\&             units of X
\&   %Xh     : the value of field X, and all larger fields, expressed in units
\&             of X
\&   %Xt     : the value of all fields expressed in units of X
.Ve
.Sp
.Vb 1
\&   X is one of y,M,w,d,h,m,s (case sensitive).
.Ve
.Sp
.Vb 1
\&   %%      : returns a "%"
.Ve
.Sp
\&\s-1NOTE:\s0 Delta_Format only understands \*(L"exact\*(R" relationships, so for any delta
that has a month component, there can be no mixing of the Y/M and
W/D/H/MN/S segments.  In other words, the delta 1:6:1:1:1:1:1 has a month
component, so asking for the total number of years (using the \f(CW%yd\fR format)
will return 1.5 (which is what 1 year 6 months is).  For deltas which have
\&\s-1NO\s0 month component, the relationship between years and days is known
(365.25 is used) and all formats work as expected (except that formats with
X equal to \*(L"M\*(R" are not allowed).
.Sp
So, the format \*(L"%hd\*(R" means the values of H, \s-1MN\s0, and S expressed in hours.
So for the delta \*(L"0:0:0:0:2:30:0\*(R", this format returns 2.5.  Similarly, the
format \*(L"%yd\*(R" means the value (in years) of both the Y and M fields, or,
if the month component is 0, it uses Y, W, D, H, \s-1MN\s0, S.
.Sp
The format \*(L"%hh\*(R" returns the value of W, D, and H expressed in hours if
the month component is non\-zero, or Y, W, D, H if the month component is 0.
.Sp
If \f(CW$dec\fR is non\-zero, the \f(CW%Xd\fR and \f(CW%Xt\fR values are formatted to contain \f(CW$dec\fR
decimal places.
.IP "ParseRecur" 4
.IX Item "ParseRecur"
.Vb 2
\& $recur = ParseRecur($string [,$base,$date0,$date1,$flags]);
\& @dates = ParseRecur($string [,$base,$date0,$date1,$flags]);
.Ve
.Sp
A recurrence refers to a recurring event.  A fully specified recurrence
requires (in most cases) 4 items: a recur description (describing the
frequency of the event), a base date (a date when the event occurred and
which other occurrences are based on), and a start and end date.  There may
be one or more flags included which modify the behavior of the recur
description.  The fully specified recurrence is written as:
.Sp
.Vb 1
\&  recur*flags*base*date0*date1
.Ve
.Sp
Here, base, date0, and date1 are any strings (which must not contain any
asterixes) which can be parsed by ParseDate.  flags is a comma separated
list of flags (described below), and recur is a string describing a
recurring event.
.Sp
If called in scalar context, it returns a string containing a fully
specified recurrence (or as much of it as can be determined with
unspecified fields left blank).  In list context, it returns a list of all
dates referred to by a recurrence if enough information is given in the
recurrence.  All dates returned are in the range:
.Sp
.Vb 1
\&  date0 <= date < date1
.Ve
.Sp
The argument \f(CW$string\fR can contain any of the parts of a full recurrence.
For example:
.Sp
.Vb 3
\&  recur
\&  recur*flags
\&  recur**base*date0*date1
.Ve
.Sp
The only part which is required is the recur description.  Any values
contained in \f(CW$string\fR are overridden or modified by values passed in as
parameters to ParseRecur.
.Sp
A recur description is a string of the format Y:M:W:D:H:MN:S .  Exactly one
of the colons may optionally be replaced by an asterisk, or an asterisk may
be prepended to the string.
.Sp
Any value \*(L"N\*(R" to the left of the asterisk refers to the \*(L"Nth\*(R" one.  Any
value to the right of the asterisk refers to a value as it appears on a
calendar/clock.  Values to the right can be listed a single values, ranges
(2 numbers separated by a dash \*(L"\-\*(R"), or a comma separated list of values
or ranges.  In a few cases, negative values are appropriate.
.Sp
This is best illustrated by example.
.Sp
.Vb 13
\&  0:0:2:1:0:0:0        every 2 weeks and 1 day
\&  0:0:0:0:5:30:0       every 5 hours and 30 minutes
\&  0:0:0:2*12:30:0      every 2 days at 12:30 (each day)
\&  3*1:0:2:12:0:0       every 3 years on Jan 2 at noon
\&  0:1*0:2:12,14:0:0    2nd of every month at 12:00 and 14:00
\&  1:0:0*45:0:0:0       45th day of every year
\&  0:1*4:2:0:0:0        4th tuesday (day 2) of every month
\&  0:1*-1:2:0:0:0       last tuesday of every month
\&  0:1:0*-2:0:0:0       2nd to last day of every month
\&  0:0:3*2:0:0:0        every 3rd tuesday (every 3 weeks on 2nd day of week)
\&  1:0*12:2:0:0:0       tuesday of the 12th week of each year
\&  *1990-1995:12:0:1:0:0:0
\&                       Dec 1 in 1990 through 1995
.Ve
.Sp
.Vb 2
\&  0:1*2:0:0:0:0        the start of the 2nd week of every month (see Note 2)
\&  1*1:2:0:0:0:0        the start of the 2nd week in January each year (Note 2)
.Ve
.Sp
I realize that this looks a bit cryptic, but after a discussion on the
\&\s-1CALENDAR\s0 mailing list, it looked like there was no concise, flexible
notation for handling recurring events.  \s-1ISO\s0 8601 notations were very bulky
and lacked the flexibility I wanted.  As a result, I developed this
notation (based on crontab formats, but with much more flexibility) which
fits in well with this module, and which is able to express every type of
recurring event I could think of.
.Sp
\&\s-1NOTE:\s0 If a recurrence has a date0 and date1 in it \s-1AND\s0 a date0 and date1
are passed in to the function, both sets of criteria apply.  If flags are
passed in, they override any flags in the recurrence \s-1UNLESS\s0 the flags
passed in start with a plus (+) character in which case they are appended
to the flags in the recurrence.
.Sp
\&\s-1NOTE:\s0 There is no way to express the following with a single recurrence:
.Sp
.Vb 1
\&  every day at 12:30 and 1:00
.Ve
.Sp
You have to use two recurrences to do this.
.Sp
\&\s-1NOTE:\s0 A recurrence specifying the week of a month is \s-1NOT\s0 clearly defined
in common usage.  What is the 1st week in a month?  The behavior (with
respect to this module) is well defined (using the FDn and FIn flags
below), but in common usage, this is so ambiguous that this form should
probably never be used.  It is included here solely for the sake of
completeness.
.Sp
\&\s-1NOTE:\s0 Depending on whether M and W are 0 or nonzero, D means different
things.  This is given in the following table.
.Sp
.Vb 6
\&  M  W  D (when right of an asterisk) refers to
\&  -  -  -------------------------------------------
\&  0  0  day of year (1-366)
\&  M  0  day of month (1-31)
\&  0  W  day of week (1-7),  W refers to the week of year
\&  M  W  the Wth (1-5 or -1 to -5) occurrence of Dth (1-7) day of week in month
.Ve
.Sp
\&\s-1NOTE:\s0 Base dates are only used with some types of recurrences.  For example,
.Sp
.Vb 1
\&  0:0:3*2:0:0:0        every 3rd tuesday
.Ve
.Sp
requires a base date.  If a base date is specified which doesn't match the
criteria (for example, if a base date falling on Monday were passed in with
this recurrence), the base date is moved forward to the first relevant date.
.Sp
Other dates do not require a base date.  For example:
.Sp
.Vb 1
\&  0:0*3:2:0:0:0        third tuesday of every month
.Ve
.Sp
A recurrence written in the above format does \s-1NOT\s0 provide default values
for base, date0, or date1.  They must be specified in order to get a list
of dates.
.Sp
A base date is not used entirely.  It is only used to provide the parts
necessary for the left part of a recurrence.  For example, the recurrence:
.Sp
.Vb 1
\&  1:3*0:4:0:0:0        every 1 year, 3 months on the 4th day of the month
.Ve
.Sp
would only use the year and month of the base date.
.Sp
There are a small handful of English strings which can be parsed in place
of a numerical recur description.  These include:
.Sp
.Vb 8
\&  every 2nd day [in 1997]
\&  every 2nd day in June [1997]
\&  2nd day of every month [in 1997]
\&  2nd tuesday of every month [in 1997]
\&  last tuesday of every month [in 1997]
\&  every tuesday [in 1997]
\&  every 2nd tuesday [in 1997]
\&  every 2nd tuesday in June [1997]
.Ve
.Sp
Each of these set base, date0, and date1 to a default value (the current
year with Jan 1 being the base date is the default if the year and month
are missing).
.Sp
The following flags (case insensitive) are understood:
.Sp
.Vb 7
\&  MWn   : n is 1-7.  The first week of the month is the week
\&          which contains the first occurrence of day n (1=Monday).
\&          MW2 means that the first week contains the first Tuesday
\&          of the month.
\&  MDn   : n is 1-7.  The first week of the month contains the
\&          actual date (1st through 7th).  MD4 means that the first
\&          week of the month contains the 4th of that month.
.Ve
.Sp
.Vb 4
\&  PDn   : n is 1-7.  Means the previous day n not counting today
\&  PTn   : n is 1-7.  Means the previous day n counting today
\&  NDn   : n is 1-7.  Means the next day n not counting today
\&  NTn   : n is 1-7.  Means the next day n counting today
.Ve
.Sp
.Vb 4
\&  FDn   : n is any number.  Means step forward n days.
\&  BDn   : n is any number.  Means step backward n days.
\&  FWn   : n is any number.  Means step forward n workdays.
\&  BWn   : n is any number.  Means step backward n workdays.
.Ve
.Sp
.Vb 3
\&  CWD   : the closest work day (using the TomorrowFirst config variable).
\&  CWN   : the closest work day (looking forward first).
\&  CWP   : the closest work day (looking backward first).
.Ve
.Sp
.Vb 3
\&  NWD   : next work day counting today
\&  PWD   : previous work day counting today
\&  DWD   : next/previous work day (TomorrowFirst config) counting today
.Ve
.Sp
.Vb 2
\&  EASTER: select easter for this year (the M, W, D fields are ignored
\&          in the recur).
.Ve
.Sp
\&\s-1NOTE:\s0 only one of MWn and MDn can be set.  If both are set, only the
last one is used.  The default is \s-1MW7\s0 (i.e. the first week contains
the first Sunday).
.Sp
\&\s-1CWD\s0, \s-1CWN\s0, and \s-1CWP\s0 will usually return the same value, but if you are
starting at the middle day of a 3\-day weekend (for example), it will return
either the first work day of the following week, or the last work day of
the previous week depending on whether it looks forward or backward first.
.Sp
All flags are applied \s-1AFTER\s0 the recurrence dates are calculated, and they
may move a date outside of the date0 to date1 range.  No check is made for
this.
.Sp
The workday flags do not act exactly the same as a business mode calculation.
For example, a date that is Saturday with a \s-1FW1\s0 steps forward to the first
workday (i.e. Monday).
.IP "Date_Cmp" 4
.IX Item "Date_Cmp"
.Vb 1
\& $flag = Date_Cmp($date1,$date2);
.Ve
.Sp
This takes two dates and compares them.  Almost all dates can be compared
using the perl \*(L"cmp\*(R" command.  The only time this will not work is when
comparing dates in different timezones.  This routine will take that into
account.
.Sp
\&\s-1NOTE:\s0  This routine currently does little more than use \*(L"cmp\*(R", but once
the internal format for storing dates is in place (where timezone information
is kept as part of the date), this routine will become more important.  You
should use this routine in prepartation for that version.
.IP "DateCalc" 4
.IX Item "DateCalc"
.Vb 1
\& $d = DateCalc($d1,$d2 [,\e$err] [,$mode]);
.Ve
.Sp
This takes two dates, deltas, or one of each and performs the appropriate
calculation with them.  Dates must be a string that can be parsed by
&ParseDateString.  Deltas must be a string that can be parsed by
&ParseDateDelta.  Two deltas add together to form a third delta.  A date
and a delta returns a 2nd date.  Two dates return a delta (the difference
between the two dates).
.Sp
Note that in many cases, it is somewhat ambiguous what the delta actually
refers to.  Although it is \s-1ALWAYS\s0 known how many months in a year, hours in
a day, etc., it is \s-1NOT\s0 known how many days form a month.  As a result, the
part of the delta containing month/year and the part with sec/min/hr/day
must be treated separately.  For example, \*(L"Mar 31, 12:00:00\*(R" plus a delta
of 1month 2days would yield \*(L"May 2 12:00:00\*(R".  The year/month is first
handled while keeping the same date.  Mar 31 plus one month is Apr 31 (but
since Apr only has 30 days, it becomes Apr 30).  Apr 30 + 2 days is May 2.
As a result, in the case where two dates are entered, the resulting delta
can take on two different forms.  By default ($mode=0), an absolutely
correct delta (ignoring daylight savings time) is returned in days, hours,
minutes, and seconds.
.Sp
If \f(CW$mode\fR is 1, the math is done using an approximate mode where a delta is
returned using years and months as well.  The year and month part is
calculated first followed by the rest.  For example, the two dates \*(L"Mar 12
1995\*(R" and \*(L"Apr 13 1995\*(R" would have an exact delta of \*(L"31 days\*(R" but in the
approximate mode, it would be returned as \*(L"1 month 1 day\*(R".  Also, \*(L"Mar 31\*(R"
and \*(L"Apr 30\*(R" would have deltas of \*(L"30 days\*(R" or \*(L"1 month\*(R" (since Apr 31
doesn't exist, it drops down to Apr 30).  Approximate mode is a more human
way of looking at things (you'd say 1 month and 2 days more often then 33
days), but it is less meaningful in terms of absolute time.  In approximate
mode \f(CW$d1\fR and \f(CW$d2\fR must be dates.  If either or both is a delta, the
calculation is done in exact mode.
.Sp
If \f(CW$mode\fR is 2, a business mode is used.  That is, the calculation is done
using business days, ignoring holidays, weekends, etc.  In order to
correctly use this mode, a config file must exist which contains the
section defining holidays (see documentation on the config file below).
The config file can also define the work week and the hours of the work
day, so it is possible to have different config files for different
businesses.
.Sp
For example, if a config file defines the workday as 08:00 to 18:00, a
work week consisting of Mon\-Sat, and the standard (American) holidays, then
from Tuesday at 12:00 to the following Monday at 14:00 is 5 days and 2
hours.  If the \*(L"end\*(R" of the day is reached in a calculation, it
automatically switches to the next day.  So, Tuesday at 12:00 plus 6 hours
is Wednesday at 08:00 (provided Wed is not a holiday).  Also, a date that
is not during a workday automatically becomes the start of the next
workday.  So, Sunday 12:00 and Monday at 03:00 both automatically becomes
Monday at 08:00 (provided Monday is not a holiday).  In business mode, any
combination of date and delta may be entered, but a delta should not
contain a year or month field (weeks are fine though).
.Sp
See below for some additional comments about business mode calculations.
.Sp
Note that a business week is treated the same as an exact week (i.e. from
Tuesday to Tuesday, regardless of holidays).  Because this means that the
relationship between days and weeks is \s-1NOT\s0 unambiguous, when a delta is
produced from two dates, it will be in terms of d/h/mn/s (i.e. no week
field).
.Sp
If \f(CW$mode\fR is 3 (which only applies when two dates are passed in), an exact
business mode is used.  In this case, it returns a delta as an exact number
of business days/hours/etc. between the two.  Weeks, months, and years are
ignored.
.Sp
Any other non-nil value of \f(CW$mode\fR is treated as \f(CW$mode\fR=1 (approximate mode).
.Sp
The mode can be automatically set in the dates/deltas passed by including a
key word somewhere in it.  For example, in English, if the word
\&\*(L"approximately\*(R" is found in either of the date/delta arguments, approximate
mode is forced.  Likewise, if the word \*(L"business\*(R" or \*(L"exactly\*(R" appears,
business/exact mode is forced (and \f(CW$mode\fR is ignored).  So, the two
following are equivalent:
.Sp
.Vb 2
\&   $date = DateCalc("today","+ 2 business days",\e$err);
\&   $date = DateCalc("today","+ 2 days",\e$err,2);
.Ve
.Sp
Note that if the keyword method is used instead of passing in \f(CW$mode\fR, it is
important that the keyword actually appear in the argument passed in to
DateCalc.  The following will \s-1NOT\s0 work:
.Sp
.Vb 3
\&   $delta = ParseDateDelta("+ 2 business days");
\&   $today = ParseDate("today");
\&   $date = DateCalc($today,$delta,\e$err);
.Ve
.Sp
because the mode keyword is removed from a date/delta by the parse routines,
and the mode is reset each time a parse routine is called.  Since DateCalc
parses both of its arguments, whatever mode was previously set is ignored.
.Sp
If \e$err is passed in, it is set to:
   1 is returned if \f(CW$d1\fR is not a delta or date
   2 is returned if \f(CW$d2\fR is not a delta or date
   3 is returned if the date is outside the years 1000 to 9999
This argument is optional, but if included, it must come before \f(CW$mode\fR.
.Sp
Nothing is returned if an error occurs.
.Sp
When a delta is returned, the signs such that it is strictly positive or
strictly negative (\*(L"1 day \- 2 hours\*(R" would never be returned for example).
The only time when this cannot be enforced is when two deltas with a
year/month component are entered.  In this case, only the signs on the
day/hour/min/sec part are standardized.
.IP "Date_SetTime" 4
.IX Item "Date_SetTime"
.Vb 2
\& $date = Date_SetTime($date,$hr,$min,$sec);
\& $date = Date_SetTime($date,$time);
.Ve
.Sp
This takes a date (any string that may be parsed by ParseDateString) and
sets the time in that date.  For example, one way to get the time for 7:30
tomorrow would be to use the lines:
.Sp
.Vb 2
\&   $date = ParseDate("tomorrow");
\&   $date = Date_SetTime($date,"7:30");
.Ve
.Sp
Note that in this routine (as well as the other routines below which use
a time argument), no real parsing is done on the times.  As a result,
.Sp
.Vb 1
\&   $date = Date_SetTime($date,"13:30");
.Ve
.Sp
works, but
.Sp
.Vb 1
\&   $date = Date_SetTime($date,"1:30 PM");
.Ve
.Sp
doesn't.
.IP "Date_SetDateField" 4
.IX Item "Date_SetDateField"
.Vb 1
\& $date = Date_SetDateField($date,$field,$val [,$nocheck]);
.Ve
.Sp
This takes a date and sets one of it's fields to a new value.  \f(CW$field\fR is
any of the strings \*(L"y\*(R", \*(L"m\*(R", \*(L"d\*(R", \*(L"h\*(R", \*(L"mn\*(R", \*(L"s\*(R" (case insensitive) and
\&\f(CW$val\fR is the new value.
.Sp
If \f(CW$nocheck\fR is non\-zero, no check is made as to the validity of the date.
.IP "Date_GetPrev" 4
.IX Item "Date_GetPrev"
.Vb 4
\& $date = Date_GetPrev($date,$dow, $curr [,$hr,$min,$sec]);
\& $date = Date_GetPrev($date,$dow, $curr [,$time]);
\& $date = Date_GetPrev($date,undef,$curr,$hr,$min,$sec);
\& $date = Date_GetPrev($date,undef,$curr,$time);
.Ve
.Sp
This takes a date (any string that may be parsed by ParseDateString) and finds
the previous occurrence of either a day of the week, or a certain time of day.
.Sp
If \f(CW$dow\fR is defined, the previous occurrence of the day of week is returned.
\&\f(CW$dow\fR may either be a string (such as \*(L"Fri\*(R" or \*(L"Friday\*(R") or a number
(between 1 and 7).  The date of the previous \f(CW$dow\fR is returned.
.Sp
If \f(CW$date\fR falls on the day of week given by \f(CW$dow\fR, the date returned depends
on \f(CW$curr\fR.  If \f(CW$curr\fR is 0, the date returned is a week before \f(CW$date\fR.  If
\&\f(CW$curr\fR is 1, the date returned is the same as \f(CW$date\fR.  If \f(CW$curr\fR is 2, the date
returned (including the time information) is required to be before \f(CW$date\fR.
.Sp
If a time is passed in (either as separate hours, minutes, seconds or as a
time in \s-1HH:MM:SS\s0 or \s-1HH:MM\s0 format), the time on this date is set to it.  The
following examples should illustrate the use of Date_GetPrev:
.Sp
.Vb 4
\&    date                   dow    curr  time            returns
\&    Fri Nov 22 18:15:00    Thu    any   12:30           Thu Nov 21 12:30:00
\&    Fri Nov 22 18:15:00    Fri    0     12:30           Fri Nov 15 12:30:00
\&    Fri Nov 22 18:15:00    Fri    1/2   12:30           Fri Nov 22 12:30:00
.Ve
.Sp
.Vb 2
\&    Fri Nov 22 18:15:00    Fri    1     18:30           Fri Nov 22 18:30:00
\&    Fri Nov 22 18:15:00    Fri    2     18:30           Fri Nov 15 18:30:00
.Ve
.Sp
If \f(CW$dow\fR is undefined, then a time must be entered, and the date returned is
the previous occurrence of this time.  If \f(CW$curr\fR is non\-zero, the current
time is returned if it matches the criteria passed in.  In other words, the
time returned is the last time that a digital clock (in 24 hour mode) would
have displayed the time you passed in.  If you define hours, minutes and
seconds default to 0 and you might jump back as much as an entire day.  If
hours are undefined, you are looking for the last time the minutes/seconds
appeared on the digital clock, so at most, the time will jump back one hour.
.Sp
.Vb 7
\&    date               curr  hr     min    sec      returns
\&    Nov 22 18:15:00    0/1   18     undef  undef    Nov 22 18:00:00
\&    Nov 22 18:15:00    0/1   18     30     0        Nov 21 18:30:00
\&    Nov 22 18:15:00    0     18     15     undef    Nov 21 18:15:00
\&    Nov 22 18:15:00    1     18     15     undef    Nov 22 18:15:00
\&    Nov 22 18:15:00    0     undef  15     undef    Nov 22 17:15:00
\&    Nov 22 18:15:00    1     undef  15     undef    Nov 22 18:15:00
.Ve
.IP "Date_GetNext" 4
.IX Item "Date_GetNext"
.Vb 4
\& $date = Date_GetNext($date,$dow, $curr [,$hr,$min,$sec]);
\& $date = Date_GetNext($date,$dow, $curr [,$time]);
\& $date = Date_GetNext($date,undef,$curr,$hr,$min,$sec);
\& $date = Date_GetNext($date,undef,$curr,$time);
.Ve
.Sp
Similar to Date_GetPrev.
.IP "Date_IsHoliday" 4
.IX Item "Date_IsHoliday"
.Vb 1
\& $name = Date_IsHoliday($date);
.Ve
.Sp
This returns undef if \f(CW$date\fR is not a holiday, or a string containing the
name of the holiday otherwise.  An empty string is returned for an unnamed
holiday.
.IP "Events_List" 4
.IX Item "Events_List"
.Vb 3
\& $ref = Events_List($date);
\& $ref = Events_List($date ,0      [,$flag]);
\& $ref = Events_List($date0,$date1 [,$flag]);
.Ve
.Sp
This returns a list of events.  Events are defined in the Events section
of the config file (discussed below).
.Sp
In the first form (a single argument), \f(CW$date\fR is any string containing a
date.  A list of events active at that precise time will be returned.
The format is similar to when \f(CW$flag\fR=0, except only a single time will
be returned.
.Sp
In all other cases, a range of times will be used.  If the 2nd argument
evaluates to 0, the range of times will be the 24 hour period from
midnight to midnight containing \f(CW$date\fR.  Otherwise, the range is given
by the two dates.
.Sp
The value of \f(CW$flag\fR determines the format of the information that is
returned.
.Sp
With \f(CW$flag\fR=0, the events are returned as a reference to a list of the form:
.Sp
.Vb 1
\&  [ date, [ list_of_events ], date, [ list_of_events ], ... ]
.Ve
.Sp
For example, if the following events are defined (using the syntax
discussed below in the description of the Event section of the config
file):
.Sp
.Vb 5
\&  2000-01-01 ; 2000-03-21  = Winter
\&  2000-03-22 ; 2000-06-21  = Spring
\&  2000-02-01               = Event1
\&  2000-05-01               = Event2
\&  2000-04-01-12:00:00      = Event3
.Ve
.Sp
might result in the following output:
.Sp
.Vb 2
\&  &Events_List("2000-04-01")
\&   => [ 2000040100:00:00, [ Spring ] ]
.Ve
.Sp
.Vb 2
\&  &Events_List("2000-04-01 12:30");
\&   => [ 2000040112:30:00, [ Spring, Event3 ] ]
.Ve
.Sp
.Vb 4
\&  &Events_List("2000-04-01",0);
\&   => [ 2000040100:00:00, [ Spring ],
\&        2000040112:00:00, [ Spring, Event3 ],
\&        2000040113:00:00, [ Spring ] ]
.Ve
.Sp
.Vb 5
\&  &Events_List("2000-03-15","2000-04-10");
\&   => [ 2000031500:00:00, [ Winter ],
\&        2000032200:00:00, [ Spring ]
\&        2000040112:00:00, [ Spring, Event3 ]
\&        2000040113:00:00, [ Spring ] ]
.Ve
.Sp
Much more complicated events can be defined using recurrences.
.Sp
When \f(CW$flag\fR is non\-zero, the format of the output is changed.  If \f(CW$flag\fR
is 1, then a tally of the amount of time given to each event is returned.
Time for which two or more events apply is counted for both.
.Sp
.Vb 4
\&  &Events_List("2000-03-15","2000-04-10",1);
\&   => { Winter => +0:0:1:0:0:0:0,
\&        Spring => +0:0:2:5:0:0:0,
\&        Event3 => +0:0:0:0:1:0:0 }
.Ve
.Sp
When \f(CW$flag\fR is 2, a more complex tally with no event counted twice is
returned.
.Sp
.Vb 4
\&  &Events_List("2000-03-15","2000-04-10",2);
\&   => { Winter => +0:0:1:0:0:0:0,
\&        Spring => +0:0:2:4:23:0:0,
\&        Event3+Spring => +0:0:0:0:1:0:0 }
.Ve
.Sp
The hash contains one element for each combination of events.
.IP "Date_DayOfWeek" 4
.IX Item "Date_DayOfWeek"
.Vb 1
\& $day = Date_DayOfWeek($m,$d,$y);
.Ve
.Sp
Returns the day of the week (1 for Monday, 7 for Sunday).
.Sp
All arguments must be numeric.
.IP "Date_SecsSince1970" 4
.IX Item "Date_SecsSince1970"
.Vb 1
\& $secs = Date_SecsSince1970($m,$d,$y,$h,$mn,$s);
.Ve
.Sp
Returns the number of seconds since Jan 1, 1970 00:00 (negative if date is
earlier).
.Sp
All arguments must be numeric.
.IP "Date_SecsSince1970GMT" 4
.IX Item "Date_SecsSince1970GMT"
.Vb 1
\& $secs = Date_SecsSince1970GMT($m,$d,$y,$h,$mn,$s);
.Ve
.Sp
Returns the number of seconds since Jan 1, 1970 00:00 \s-1GMT\s0 (negative if date
is earlier).  If CurrTZ is \*(L"\s-1IGNORE\s0\*(R", the number will be identical to
Date_SecsSince1970 (i.e. the date given will be treated as being in \s-1GMT\s0).
.Sp
All arguments must be numeric.
.IP "Date_DaysSince1BC" 4
.IX Item "Date_DaysSince1BC"
.Vb 1
\& $days = Date_DaysSince1BC($m,$d,$y);
.Ve
.Sp
Returns the number of days since Dec 31, 1BC.  This includes the year 0000.
.Sp
All arguments must be numeric.
.IP "Date_DayOfYear" 4
.IX Item "Date_DayOfYear"
.Vb 1
\& $day = Date_DayOfYear($m,$d,$y);
.Ve
.Sp
Returns the day of the year (001 to 366)
.Sp
All arguments must be numeric.
.IP "Date_NthDayOfYear" 4
.IX Item "Date_NthDayOfYear"
.Vb 1
\& ($y,$m,$d,$h,$mn,$s) = Date_NthDayOfYear($y,$n);
.Ve
.Sp
Returns the year, month, day, hour, minutes, and decimal seconds given
a floating point day of the year.
.Sp
All arguments must be numeric.  \f(CW$n\fR must be greater than or equal to 1
and less than 366 on non-leap years and 367 on leap years.
.Sp
\&\s-1NOTE:\s0 When \f(CW$n\fR is a decimal number, the results are non-intuitive perhaps.
Day 1 is Jan 01 00:00.  Day 2 is Jan 02 00:00.  Intuitively, you
might think of day 1.5 as being 1.5 days after Jan 01 00:00, but this
would mean that Day 1.5 was Jan 02 12:00 (which is later than Day 2).
The best way to think of this function is a timeline starting at 1 and
ending at 366 (in a non-leap year).  In terms of a delta, think of \f(CW$n\fR
as the number of days after Dec 31 00:00 of the previous year.
.IP "Date_DaysInYear" 4
.IX Item "Date_DaysInYear"
.Vb 1
\& $days = Date_DaysInYear($y);
.Ve
.Sp
Returns the number of days in the year (365 or 366)
.IP "Date_DaysInMonth" 4
.IX Item "Date_DaysInMonth"
.Vb 1
\& $days = Date_DaysInMonth($m,$y);
.Ve
.Sp
Returns the number of days in the month.
.IP "Date_WeekOfYear" 4
.IX Item "Date_WeekOfYear"
.Vb 1
\& $wkno = Date_WeekOfYear($m,$d,$y,$first);
.Ve
.Sp
Figure out week number.  \f(CW$first\fR is the first day of the week which is
usually 1 (Monday) or 7 (Sunday), but could be any number between 1 and 7
in practice.
.Sp
All arguments must be numeric.
.Sp
\&\s-1NOTE:\s0 This routine should only be called in rare cases.  Use UnixDate with
the \f(CW%W\fR, \f(CW%U\fR, \f(CW%J\fR, \f(CW%L\fR formats instead.  This routine returns a week between 0
and 53 which must then be \*(L"fixed\*(R" to get into the \s-1ISO\-8601\s0 weeks from 1 to
53.  A date which returns a week of 0 actually belongs to the last week of
the previous year.  A date which returns a week of 53 may belong to the
first week of the next year.
.IP "Date_LeapYear" 4
.IX Item "Date_LeapYear"
.Vb 1
\& $flag = Date_LeapYear($y);
.Ve
.Sp
Returns 1 if the argument is a leap year
Written by David Muir Sharnoff <muir@idiom.com>
.IP "Date_DaySuffix" 4
.IX Item "Date_DaySuffix"
.Vb 1
\& $day = Date_DaySuffix($d);
.Ve
.Sp
Add `st', `nd', `rd', `th' to a date (ie 1st, 22nd, 29th).  Works for
international dates.
.IP "Date_TimeZone" 4
.IX Item "Date_TimeZone"
.Vb 1
\& $tz = Date_TimeZone;
.Ve
.Sp
This determines and returns the local timezone.  If it is unable to determine
the local timezone, the following error occurs:
.Sp
.Vb 1
\&   ERROR: Date::Manip unable to determine TimeZone.
.Ve
.Sp
See The \s-1TIMEZONES\s0 section below for more information.
.IP "Date_ConvTZ" 4
.IX Item "Date_ConvTZ"
.Vb 4
\& $date = Date_ConvTZ($date);
\& $date = Date_ConvTZ($date,$from);
\& $date = Date_ConvTZ($date,"",$to);
\& $date = Date_ConvTZ($date,$from,$to);
.Ve
.Sp
This converts a date (which \s-1MUST\s0 be in the format returned by ParseDate)
from one timezone to another.
.Sp
If it is called with no arguments, the date is converted from the local
timezone to the timezone specified by the config variable ConvTZ (see
documentation on ConvTZ below).  If ConvTZ is set to \*(L"\s-1IGNORE\s0\*(R", no
conversion is done.
.Sp
If called with \f(CW$from\fR but no \f(CW$to\fR, the timezone is converted from the
timezone in \f(CW$from\fR to ConvTZ (of \s-1TZ\s0 if ConvTZ is not set).  Again, no
conversion is done if ConvTZ is set to \*(L"\s-1IGNORE\s0\*(R".
.Sp
If called with \f(CW$to\fR but no \f(CW$from\fR, \f(CW$from\fR defaults to ConvTZ (if set) or the
local timezone otherwise.  Although this does not seem immediately obvious,
it actually makes sense.  By default, all dates that are parsed are
converted to ConvTZ, so most of the dates being worked with will be stored
in that timezone.
.Sp
If Date_ConvTZ is called with both \f(CW$from\fR and \f(CW$to\fR, the date is converted
from the timezone \f(CW$from\fR to \f(CW$to\fR.
.Sp
\&\s-1NOTE:\s0 As in all other cases, the \f(CW$date\fR returned from Date_ConvTZ has no
timezone information included as part of it, so calling UnixDate with the
\&\*(L"%z\*(R" format will return the timezone that Date::Manip is working in
(usually the local timezone).
.Sp
Example:  To convert 2/2/96 noon \s-1PST\s0 to \s-1CST\s0 (regardless of what timezone
you are in, do the following:
.Sp
.Vb 2
\& $date = ParseDate("2/2/96 noon");
\& $date = Date_ConvTZ($date,"PST","CST");
.Ve
.Sp
Both timezones \s-1MUST\s0 be in one of the formats listed below in the section
\&\s-1TIMEZONES\s0.
.IP "Date_Init" 4
.IX Item "Date_Init"
.Vb 4
\& &Date_Init();
\& &Date_Init("VAR=VAL","VAR=VAL",...);
\& @list = Date_Init();
\& @list = Date_Init("VAR=VAL","VAR=VAL",...);
.Ve
.Sp
Normally, it is not necessary to explicitly call Date_Init.  The first
time any of the other routines are called, Date_Init will be called to set
everything up.  If for some reason you want to change the configuration of
Date::Manip, you can pass the appropriate string or strings into Date_Init
to reinitialize things.
.Sp
The strings to pass in are of the form \*(L"VAR=VAL\*(R".  Any number may be
included and they can come in any order.  \s-1VAR\s0 may be any configuration
variable.  A list of all configuration variables is given in the section
\&\s-1CUSTOMIZING\s0 \s-1DATE::MANIP\s0 below.  \s-1VAL\s0 is any allowed value for that variable.
For example, to switch from English to French and use non-US format (so
that 12/10 is Oct 12), do the following:
.Sp
.Vb 1
\&  &Date_Init("Language=French","DateFormat=non-US");
.Ve
.Sp
If Date_Init is called in list context, it will return a list of all
config variables and their values suitable for passing in to Date_Init
to return Date::Manip to the current state.  The only possible problem is
that by default, holidays will not be erased, so you may need to prepend
the \*(L"EraseHolidays=1\*(R" element to the list.
.IP "Date_IsWorkDay" 4
.IX Item "Date_IsWorkDay"
.Vb 1
\&  $flag = Date_IsWorkDay($date [,$flag]);
.Ve
.Sp
This returns 1 if \f(CW$date\fR is a work day.  If \f(CW$flag\fR is non\-zero, the time is
checked to see if it falls within work hours.  It returns an empty string
if \f(CW$date\fR is not valid.
.IP "Date_NextWorkDay" 4
.IX Item "Date_NextWorkDay"
.Vb 1
\&  $date = Date_NextWorkDay($date,$off [,$time]);
.Ve
.Sp
Finds the day \f(CW$off\fR work days from now.  If \f(CW$time\fR is passed in, we must also
take into account the time of day.
.Sp
If \f(CW$time\fR is not passed in, day 0 is today (if today is a workday) or the
next work day if it isn't.  In any case, the time of day is unaffected.
.Sp
If \f(CW$time\fR is passed in, day 0 is now (if now is part of a workday) or the
start of the very next work day.
.IP "Date_PrevWorkDay" 4
.IX Item "Date_PrevWorkDay"
.Vb 1
\&  $date = Date_PrevWorkDay($date,$off [,$time]);
.Ve
.Sp
Similar to Date_NextWorkDay.
.IP "Date_NearestWorkDay" 4
.IX Item "Date_NearestWorkDay"
.Vb 1
\&  $date = Date_NearestWorkDay($date [,$tomorrowfirst]);
.Ve
.Sp
This looks for the work day nearest to \f(CW$date\fR.  If \f(CW$date\fR is a work day, it
is returned.  Otherwise, it will look forward or backwards in time 1 day
at a time until a work day is found.  If \f(CW$tomorrowfirst\fR is non-zero (or if
it is omitted and the config variable TomorrowFirst is non\-zero), we look
to the future first.  Otherwise, we look in the past first.  In other words,
in a normal week, if \f(CW$date\fR is Wednesday, \f(CW$date\fR is returned.  If \f(CW$date\fR is
Saturday, Friday is returned.  If \f(CW$date\fR is Sunday, Monday is returned.  If
Wednesday is a holiday, Thursday is returned if \f(CW$tomorrowfirst\fR is non-nil
or Tuesday otherwise.
.IP "DateManipVersion" 4
.IX Item "DateManipVersion"
.Vb 1
\&  $version = DateManipVersion;
.Ve
.Sp
Returns the version of Date::Manip.
.SH "TIMEZONES"
.IX Header "TIMEZONES"
The following timezone names are currently understood (and can be used in
parsing dates).  These are zones defined in \s-1RFC\s0 822.
.PP
.Vb 5
\&    Universal:  GMT, UT
\&    US zones :  EST, EDT, CST, CDT, MST, MDT, PST, PDT
\&    Military :  A to Z (except J)
\&    Other    :  +HHMM or -HHMM
\&    ISO 8601 :  +HH:MM, +HH, -HH:MM, -HH
.Ve
.PP
In addition, the following timezone abbreviations are also accepted.  In a
few cases, the same abbreviation is used for two different timezones (for
example, \s-1NST\s0 stands for Newfoundland Standard \-0330 and North Sumatra +0630).
In these cases, only 1 of the two is available.  The one preceded by a \*(L"#\*(R"
sign is \s-1NOT\s0 available but is documented here for completeness.  This list of
zones comes in part from the Time::Zone module by Graham Barr, David Muir
Sharnoff, and Paul Foley (with several additions by myself).
.PP
.Vb 93
\&      IDLW    -1200    International Date Line West
\&      NT      -1100    Nome
\&      HST     -1000    Hawaii Standard
\&      CAT     -1000    Central Alaska
\&      AHST    -1000    Alaska-Hawaii Standard
\&      AKST    -0900    Alaska Standard
\&      YST     -0900    Yukon Standard
\&      HDT     -0900    Hawaii Daylight
\&      AKDT    -0800    Alaska Daylight
\&      YDT     -0800    Yukon Daylight
\&      PST     -0800    Pacific Standard
\&      PDT     -0700    Pacific Daylight
\&      MST     -0700    Mountain Standard
\&      MDT     -0600    Mountain Daylight
\&      CST     -0600    Central Standard
\&      CDT     -0500    Central Daylight
\&      EST     -0500    Eastern Standard
\&      ACT     -0500    Brazil, Acre
\&      SAT     -0400    Chile
\&      BOT     -0400    Bolivia
\&      EDT     -0400    Eastern Daylight
\&      AST     -0400    Atlantic Standard
\&      AMT     -0400    Brazil, Amazon
\&      ACST    -0400    Brazil, Acre Daylight
\&     #NST     -0330    Newfoundland Standard       nst=North Sumatra    +0630
\&      NFT     -0330    Newfoundland
\&     #GST     -0300    Greenland Standard          gst=Guam Standard    +1000
\&     #BST     -0300    Brazil Standard             bst=British Summer   +0100
\&      BRST    -0300    Brazil Standard
\&      BRT     -0300    Brazil Standard
\&      AMST    -0300    Brazil, Amazon Daylight
\&      ADT     -0300    Atlantic Daylight
\&      ART     -0300    Argentina
\&      NDT     -0230    Newfoundland Daylight
\&      AT      -0200    Azores
\&      BRST    -0200    Brazil Daylight (official time)
\&      FNT     -0200    Brazil, Fernando de Noronha
\&      WAT     -0100    West Africa
\&      FNST    -0100    Brazil, Fernando de Noronha Daylight
\&      GMT     +0000    Greenwich Mean
\&      UT      +0000    Universal (Coordinated)
\&      UTC     +0000    Universal (Coordinated)
\&      WET     +0000    Western European
\&      CET     +0100    Central European
\&      FWT     +0100    French Winter
\&      MET     +0100    Middle European
\&      MEZ     +0100    Middle European
\&      MEWT    +0100    Middle European Winter
\&      SWT     +0100    Swedish Winter
\&      BST     +0100    British Summer              bst=Brazil standard  -0300
\&      GB      +0100    GMT with daylight savings
\&      WEST    +0000    Western European Daylight
\&      CEST    +0200    Central European Summer
\&      EET     +0200    Eastern Europe, USSR Zone 1
\&      FST     +0200    French Summer
\&      MEST    +0200    Middle European Summer
\&      MESZ    +0200    Middle European Summer
\&      METDST  +0200    An alias for MEST used by HP-UX
\&      SAST    +0200    South African Standard
\&      SST     +0200    Swedish Summer              sst=South Sumatra    +0700
\&      EEST    +0300    Eastern Europe Summer
\&      BT      +0300    Baghdad, USSR Zone 2
\&      MSK     +0300    Moscow
\&      EAT     +0300    East Africa
\&      IT      +0330    Iran
\&      ZP4     +0400    USSR Zone 3
\&      MSD     +0300    Moscow Daylight
\&      ZP5     +0500    USSR Zone 4
\&      IST     +0530    Indian Standard
\&      ZP6     +0600    USSR Zone 5
\&      NOVST   +0600    Novosibirsk time zone, Russia
\&      NST     +0630    North Sumatra               nst=Newfoundland Std -0330
\&     #SST     +0700    South Sumatra, USSR Zone 6  sst=Swedish Summer   +0200
\&      JAVT    +0700    Java
\&      CCT     +0800    China Coast, USSR Zone 7
\&      AWST    +0800    Australian Western Standard
\&      WST     +0800    West Australian Standard
\&      PHT     +0800    Asia Manila
\&      JST     +0900    Japan Standard, USSR Zone 8
\&      ROK     +0900    Republic of Korea
\&      ACST    +0930    Australian Central Standard
\&      CAST    +0930    Central Australian Standard
\&      AEST    +1000    Australian Eastern Standard
\&      EAST    +1000    Eastern Australian Standard
\&      GST     +1000    Guam Standard, USSR Zone 9  gst=Greenland Std    -0300
\&      ACDT    +1030    Australian Central Daylight
\&      CADT    +1030    Central Australian Daylight
\&      AEDT    +1100    Australian Eastern Daylight
\&      EADT    +1100    Eastern Australian Daylight
\&      IDLE    +1200    International Date Line East
\&      NZST    +1200    New Zealand Standard
\&      NZT     +1200    New Zealand
\&      NZDT    +1300    New Zealand Daylight
.Ve
.PP
Others can be added in the future upon request.
.PP
Date::Manip must be able to determine the timezone the user is in.  It does
this by looking in the following places:
.PP
.Vb 6
\&   $Date::Manip::TZ (set with Date_Init or in Manip.pm)
\&   $ENV{TZ}
\&   the unix `date` command (if available)
\&   $main::TZ
\&   /etc/TIMEZONE
\&   /etc/timezone
.Ve
.PP
At least one of these should contain a timezone in one of the supported
forms.  If none do by default, the \s-1TZ\s0 variable must be set with Date_Init.
.PP
The timezone may be in the STD#DST format (in which case both abbreviations
must be in the table above) or any of the formats described above.  The
STD#DST format is \s-1NOT\s0 available when parsing a date however.  The following
forms are also available and are treated similar to the STD#DST forms:
.PP
.Vb 8
\&      US/Pacific
\&      US/Mountain
\&      US/Central
\&      US/Eastern
\&      Canada/Pacific
\&      Canada/Mountain
\&      Canada/Central
\&      Canada/Eastern
.Ve
.SH "BUSINESS MODE"
.IX Header "BUSINESS MODE"
Anyone using business mode is going to notice a few quirks about it which
should be explained.  When I designed business mode, I had in mind what \s-1UPS\s0
tells me when they say 2 day delivery, or what the local business which
promises 1 business day turnaround really means.
.PP
If you do a business day calculation (with the workday set to 9:00\-5:00),
you will get the following:
.PP
.Vb 2
\&   Saturday at noon + 1 business day = Tuesday at 9:00
\&   Saturday at noon - 1 business day = Friday at 9:00
.Ve
.PP
What does this mean?
.PP
We have a business that works 9\-5 and they have a drop box so I can drop
things off over the weekend and they promise 1 business day turnaround.  If
I drop something off Friday night, Saturday, or Sunday, it doesn't matter.
They're going to get started on it Monday morning.  It'll be 1 business day
to finish the job, so the earliest I can expect it to be done is around
17:00 Monday or 9:00 Tuesday morning.  Unfortunately, there is some
ambiguity as to what day 17:00 really falls on, similar to the ambiguity
that occurs when you ask what day midnight falls on.  Although it's not the
only answer, Date::Manip treats midnight as the beginning of a day rather
than the end of one.  In the same way, 17:00 is equivalent to 9:00 the next
day and any time the date calculations encounter 17:00, it automatically
switch to 9:00 the next day.  Although this introduces some quirks, I think
this is justified.  You just have to treat 17:00/9:00 as being ambiguous
(in the same way you treat midnight as being ambiguous).
.PP
Equivalently, if I want a job to be finished on Saturday (despite the fact
that I cannot pick it up since the business is closed), I have to drop it
off no later than Friday at 9:00.  That gives them a full business day to
finish it off.  Of course, I could just as easily drop it off at 17:00
Thursday, or any time between then and 9:00 Friday.  Again, it's a matter
of treating 9:00 as ambiguous.
.PP
So, in case the business date calculations ever produce results that you
find confusing, I believe the solution is to write a wrapper which,
whenever it sees a date with the time of exactly 9:00, it treats it
specially (depending on what you want.
.PP
So Saturday + 1 business day = Tuesday at 9:00 (which means anything
from Monday 17:00 to Tuesday 9:00), but Monday at 9:01 + 1 business
day = Tuesday at 9:01 which is exact.
.PP
If this is not exactly what you have in mind, don't use the DateCalc
routine.  You can probably get whatever behavior you want using the
routines Date_IsWorkDay, Date_NextWorkDay, and Date_PrevWorkDay described
above.
.SH "CUSTOMIZING DATE::MANIP"
.IX Header "CUSTOMIZING DATE::MANIP"
There are a number of variables which can be used to customize the way
Date::Manip behaves.  There are also several ways to set these variables.
.PP
At the top of the Manip.pm file, there is a section which contains all
customization variables.  These provide the default values.
.PP
These can be overridden in a global config file if one is present (this
file is optional).  If the GlobalCnf variable is set in the Manip.pm file,
it contains the full path to a config file.  If the file exists, it's
values will override those set in the Manip.pm file.  A sample config file
is included with the Date::Manip distribution.  Modify it as appropriate
and copy it to some appropriate directory and set the GlobalCnf variable in
the Manip.pm file.
.PP
Each user can have a personal config file which is of the same form as the
global config file.  The variables PersonalCnf and PersonalCnfPath set the
name and search path for the personal config file.  This file is also
optional.  If present, it overrides any values set in the global file.
.PP
\&\s-1NOTE:\s0 if you use business mode calculations, you must have a config file
(either global or personal) since this is the only place where you can
define holidays.
.PP
Finally, any variables passed in through Date_Init override all other
values.
.PP
A config file can be composed of several sections.  The first section sets
configuration variables.  Lines in this section are of the form:
.PP
.Vb 1
\&   VARIABLE = VALUE
.Ve
.PP
For example, to make the default language French, include the line:
.PP
.Vb 1
\&   Language = French
.Ve
.PP
Only variables described below may be used.  Blank lines and lines beginning
with a pound sign (#) are ignored.  All spaces are optional and strings are
case insensitive.
.PP
A line which starts with an asterisk (*) designates a new section.  For
example, the \s-1HOLIDAY\s0 section starts with a line:
.PP
.Vb 1
\&   *Holiday
.Ve
.PP
The various sections are defined below.
.SH "DATE::MANIP VARIABLES"
.IX Header "DATE::MANIP VARIABLES"
All Date::Manip variables which can be used are described in the following
section.
.IP "IgnoreGlobalCnf" 4
.IX Item "IgnoreGlobalCnf"
If this variable is used (any value is ignored), the global config file
is not read.  It must be present in the initial call to Date_Init or the
global config file will be read.
.IP "EraseHolidays" 4
.IX Item "EraseHolidays"
If this variable is used (any value is ignored), the current list of
defined holidays is erased.  A new set will be set the next time a
config file is read in.  This can be set in either the global config file
or as a Date_Init argument (in which case holidays can be read in from
both the global and personal config files) or in the personal config file
(in which case, only holidays in the personal config file are counted).
.IP "PathSep" 4
.IX Item "PathSep"
This is a regular expression used to separate multiple paths.  For example,
on Unix, it defaults to a colon (:) so that multiple paths can be written
\&\s-1PATH1:PATH2\s0 .  For Win32 platforms, it defaults to a semicolon (;) so that
paths such as \*(L"c:\e;d:\e\*(R" will work.
.IP "GlobalCnf" 4
.IX Item "GlobalCnf"
This variable can be passed into Date_Init to point to a global
configuration file.  The value must be the complete path to a config file.
.Sp
By default, no global config file is read.  Any time a global config file
is read, the holidays are erased.
.Sp
Paths may have a tilde (~) expansion on platforms where this is supported
(currently Unix and \s-1VMS\s0).
.IP "PersonalCnf" 4
.IX Item "PersonalCnf"
This variable can be passed into Date_Init or set in a global config file
to set the name of the personal configuration file.
.Sp
The default name for the config file is .DateManip.cnf on all Unix
platforms and Manip.cnf on all non-Unix platforms (because some of them
insist on 8.3 character filenames :\-).
.IP "PersonalCnfPath" 4
.IX Item "PersonalCnfPath"
This is a list of paths separated by the separator specified by the PathSep
variable.  These paths are each checked for the PersonalCnf config file.
.Sp
Paths may have a tilde (~) expansion on platforms where this is supported
(currently Unix and \s-1VMS\s0).
.IP "Language" 4
.IX Item "Language"
Date::Manip can be used to parse dates in many different languages.
Currently, it is configured to read  the following languages (the version
in which they added is included for historical interest):
.Sp
.Vb 13
\&  English      (default)
\&  French       (5.02)
\&  Swedish      (5.05)
\&  German       (5.31)
\&  Dutch        (5.32)     aka Nederlands
\&  Polish       (5.32)
\&  Spanish      (5.33)
\&  Portuguese   (5.34)
\&  Romanian     (5.35)
\&  Italian      (5.35)
\&  Russian      (5.41)
\&  Turkish      (5.41)
\&  Danish       (5.41)
.Ve
.Sp
Others can be added easily.  Language is set to the language used to parse
dates.  If you are interested in providing a translation for a new
language, email me (see the \s-1AUTHOR\s0 section below) and I'll send you a list
of things that I need.
.IP "DateFormat" 4
.IX Item "DateFormat"
Different countries look at the date 12/10 as Dec 10 or Oct 12.  In the
United States, the first is most common, but this certainly doesn't hold
true for other countries.  Setting DateFormat to \*(L"\s-1US\s0\*(R" forces the first
behavior (Dec 10).  Setting DateFormat to anything else forces the second
behavior (Oct 12).
.IP "\s-1TZ\s0" 4
.IX Item "TZ"
If set, this defines the local timezone.  See the \s-1TIMEZONES\s0 section above
for information on it's format.
.IP "ConvTZ" 4
.IX Item "ConvTZ"
All date comparisons and calculations must be done in a single time zone in
order for them to work correctly.  So, when a date is parsed, it should be
converted to a specific timezone.  This allows dates to easily be compared
and manipulated as if they are all in a single timezone.
.Sp
The ConvTZ variable determines which timezone should be used to store dates
in.  If it is left blank, all dates are converted to the local timezone
(see the \s-1TZ\s0 variable above).  If it is set to one of the timezones listed
above, all dates are converted to this timezone.  Finally, if it is set to
the string \*(L"\s-1IGNORE\s0\*(R", all timezone information is ignored as the dates are
read in (in this case, the two dates \*(L"1/1/96 12:00 \s-1GMT\s0\*(R" and \*(L"1/1/96 12:00
\&\s-1EST\s0\*(R" would be treated as identical).
.IP "Internal" 4
.IX Item "Internal"
When a date is parsed using ParseDate, that date is stored in an internal
format which is understood by the Date::Manip routines UnixDate and
DateCalc.  Originally, the format used to store the date internally was:
.Sp
.Vb 1
\&   YYYYMMDDHH:MN:SS
.Ve
.Sp
It has been suggested that I remove the colons (:) to shorten this to:
.Sp
.Vb 1
\&   YYYYMMDDHHMNSS
.Ve
.Sp
The main advantage of this is that some databases are colon delimited which
makes storing a date from Date::Manip tedious.
.Sp
In order to maintain backwards compatibility, the Internal variable was
introduced.  Set it to 0 (to use the old format) or 1 (to use the new
format).
.IP "FirstDay" 4
.IX Item "FirstDay"
It is sometimes necessary to know what day of week is regarded as first.
By default, this is set to Monday, but many countries and people will
prefer Sunday (and in a few cases, a different day may be desired).  Set
the FirstDay variable to be the first day of the week (1=Monday, 7=Sunday)
Monday should be chosen to to comply with \s-1ISO\s0 8601.
.IP "WorkWeekBeg, WorkWeekEnd" 4
.IX Item "WorkWeekBeg, WorkWeekEnd"
The first and last days of the work week.  By default, Monday and Friday.
WorkWeekBeg must come before WorkWeekEnd numerically.  The days are
numbered from 1 (Monday) to 7 (Sunday).
.Sp
There is no way to handle an odd work week of Thu to Mon for example or 10
days on, 4 days off.
.IP "WorkDay24Hr" 4
.IX Item "WorkDay24Hr"
If this is non\-nil, a work day is treated as being 24 hours long.  The
WorkDayBeg and WorkDayEnd variables are ignored in this case.
.IP "WorkDayBeg, WorkDayEnd" 4
.IX Item "WorkDayBeg, WorkDayEnd"
The times when the work day starts and ends.  WorkDayBeg must come before
WorkDayEnd (i.e. there is no way to handle the night shift where the work
day starts one day and ends another).  Also, the workday \s-1MUST\s0 be more than
one hour long (of course, if this isn't the case, let me know... I want a
job there!).
.Sp
The time in both can be in any valid time format (including international
formats), but seconds will be ignored.
.IP "TomorrowFirst" 4
.IX Item "TomorrowFirst"
Periodically, if a day is not a business day, we need to find the nearest
business day to it.  By default, we'll look to \*(L"tomorrow\*(R" first, but if this
variable is set to 0, we'll look to \*(L"yesterday\*(R" first.  This is only used in
the Date_NearestWorkDay and is easily overridden (see documentation for that
function).
.IP "DeltaSigns" 4
.IX Item "DeltaSigns"
Prior to Date::Manip version 5.07, a negative delta would put negative
signs in front of every component (i.e. \*(L"0:0:\-1:\-3:0:\-4\*(R").  By default,
5.07 changes this behavior to print only 1 or two signs in front of the
year and day elements (even if these elements might be zero) and the sign
for year/month and day/hour/minute/second are the same.  Setting this
variable to non-zero forces deltas to be stored with a sign in front of
every element (including elements equal to 0).
.IP "Jan1Week1" 4
.IX Item "Jan1Week1"
\&\s-1ISO\s0 8601 states that the first week of the year is the one which contains
Jan 4 (i.e. it is the first week in which most of the days in that week
fall in that year).  This means that the first 3 days of the year may
be treated as belonging to the last week of the previous year.  If this
is set to non\-nil, the \s-1ISO\s0 8601 standard will be ignored and the first
week of the year contains Jan 1.
.IP "YYtoYYYY" 4
.IX Item "YYtoYYYY"
By default, a 2 digit year is treated as falling in the 100 year period of
\&\s-1CURR\-89\s0 to \s-1CURR+10\s0.  YYtoYYYY may be set to any integer N to force a 2
digit year into the period CURR-N to \s-1CURR+\s0(99\-N).  A value of 0 forces
the year to be the current year or later.  A value of 99 forces the year
to be the current year or earlier.  Since I do no checking on the value of
YYtoYYYY, you can actually have it any positive or negative value to force
it into any century you want.
.Sp
YYtoYYYY can also be set to \*(L"C\*(R" to force it into the current century, or
to \*(L"C##\*(R" to force it into a specific century.  So, no (1998), \*(L"C\*(R" forces
2 digit years to be 1900\-1999 and \*(L"C18\*(R" would force it to be 1800\-1899.
.Sp
It can also be set to the form \*(L"C####\*(R" to force it into a specific 100
year period.  C1950 refers to 1950\-2049.
.IP "UpdateCurrTZ" 4
.IX Item "UpdateCurrTZ"
If a script is running over a long period of time, the timezone may change
during the course of running it (i.e. when daylight savings time starts or
ends).  As a result, parsing dates may start putting them in the wrong time
zone.  Since a lot of overhead can be saved if we don't have to check the
current timezone every time a date is parsed, by default checking is turned
off.  Setting this to non-nil will force timezone checking to be done every
time a date is parsed... but this will result in a considerable performance
penalty.
.Sp
A better solution would be to restart the process on the two days per year
where the timezone switch occurs.
.IP "IntCharSet" 4
.IX Item "IntCharSet"
If set to 0, use the \s-1US\s0 character set (7\-bit \s-1ASCII\s0) to return strings such
as the month name.  If set to 1, use the appropriate international character
set.  For example, If you want your French representation of Decemeber to
have the accent over the first \*(L"e\*(R", you'll want to set this to 1.
.IP "ForceDate" 4
.IX Item "ForceDate"
This variable can be set to a date in the format: \s-1YYYY\-MM\-DD\-HH:MN:SS\s0
to force the current date to be interpreted as this date.  Since the current
date is used in parsing, this string will not be parsed and \s-1MUST\s0 be in the
format given above.
.SH "HOLIDAY SECTION"
.IX Header "HOLIDAY SECTION"
The holiday section of the config file is used to define holidays.  Each
line is of the form:
.PP
.Vb 1
\&   DATE = HOLIDAY
.Ve
.PP
\&\s-1HOLIDAY\s0 is the name of the holiday (or it can be blank in which case the
day will still be treated as a holiday... for example the day after
Thanksgiving or Christmas is often a work holiday though neither are
named).
.PP
\&\s-1DATE\s0 is a string which can be parsed to give a valid date in any year.  It
can be of the form
.PP
.Vb 4
\&   Date
\&   Date + Delta
\&   Date - Delta
\&   Recur
.Ve
.PP
A valid holiday section would be:
.PP
.Vb 1
\&   *Holiday
.Ve
.PP
.Vb 3
\&   1/1                             = New Year's Day
\&   third Monday in Feb             = Presidents' Day
\&   fourth Thu in Nov               = Thanksgiving
.Ve
.PP
.Vb 2
\&   # The Friday after Thanksgiving is an unnamed holiday most places
\&   fourth Thu in Nov + 1 day       =
.Ve
.PP
.Vb 3
\&   1*0:0:0:0:0:0*EASTER            = Easter
\&   1*11:0:11:0:0:0*CWD             = Veteran's Day (observed)
\&   1*0:0:0:0:0:0*EASTER,PD5        = Good Friday
.Ve
.PP
In a Date + Delta or Date \- Delta string, you can use business mode by
including the appropriate string (see documentation on DateCalc) in the
Date or Delta.  So (in English), the first workday before Christmas could
be defined as:
.PP
.Vb 1
\&   12/25 - 1 business day          =
.Ve
.PP
The date's may optionally contain the year.  For example, the dates
.PP
.Vb 2
\&  1/1
\&  1/1/1999
.Ve
.PP
refers to Jan 1 in any year or in only 1999 respectively.  For dates that
refer to any year, the date must be written such that by simply appending
the year (separated by spaces) it can be correctly interpreted.  This
will work for everything except \s-1ISO\s0 8601 dates, so \s-1ISO\s0 8601 dates may
not be used in this case.
.PP
In cases where you are interested in business type calculations, you'll
want to define most holidays using recurrences, since they can define
when a holiday is celebrated in the financial world.  For example,
Christmas chould be defined as:
.PP
.Vb 1
\&   1*12:0:24:0:0:0*FW1  = Christmas
.Ve
.PP
\&\s-1NOTE:\s0 It was pointed out to me that using a similar type recurrence to
define New Years does not work.  The recurrence:
.PP
.Vb 1
\&   1*12:0:31:0:0:0*FW1
.Ve
.PP
fails (worse, it goes into an infinite loop).  The problem is that each
holiday definition is applied to a specific year and it expects to find
the holiday for that year.  When this recurrence is applied to the year
1995, it returns the holiday for 1996 and fails.
.PP
Use the recurrence:
.PP
.Vb 1
\&   1*1:0:1:0:0:0*NWD
.Ve
.PP
instead.
.PP
If you wanted to define both Christmas and Boxing days (Boxing is the
day after Christmas, and is celebrated in some parts of the world), you
could do it in one of the following ways:
.PP
.Vb 2
\&   1*12:0:24:0:0:0*FW1  = Christmas
\&   1*12:0:25:0:0:0*FW1  = Boxing
.Ve
.PP
.Vb 2
\&    1*12:0:24:0:0:0*FW1 = Christmas
\&   01*12:0:24:0:0:0*FW1 = Boxing
.Ve
.PP
.Vb 2
\&   1*12:0:24:0:0:0*FW1   = Christmas
\&   1*12:0:25:0:0:0*FW1,a = Boxing
.Ve
.PP
The following examples will \s-1NOT\s0 work:
.PP
.Vb 2
\&   1*12:0:24:0:0:0*FW1  = Christmas
\&   1*12:0:24:0:0:0*FW2  = Boxing
.Ve
.PP
.Vb 2
\&   1*12:0:24:0:0:0*FW1  = Christmas
\&   1*12:0:24:0:0:0*FW1  = Boxing
.Ve
.PP
The reasoning behind all this is as follows:
.PP
Holidays go into affect the minute they are parsed.  So, in the case of:
.PP
.Vb 2
\&   1*12:0:24:0:0:0*FW1  = Christmas
\&   1*12:0:24:0:0:0*FW2  = Boxing
.Ve
.PP
the minute the first line is parsed, Christmas is defined as a holiday.
The second line then steps forward 2 work days (skipping Christmas since
that's no longer a work day) and define the work day two days after
Christmas, \s-1NOT\s0 the day after Christmas.
.PP
An good alternative would appear to be:
.PP
.Vb 2
\&   1*12:0:24:0:0:0*FW1  = Christmas
\&   1*12:0:24:0:0:0*FW1  = Boxing
.Ve
.PP
This unfortunately fails because the recurrences are currently stored in a
hash.  Since these two recurrences are identical, they fail (the first one
is overwritten by the second and in essense, Christmas is never defined).
.PP
To fix this, make them unique with either a fake flag (which is ignored):
.PP
.Vb 1
\&   1*12:0:24:0:0:0*FW1,a  = Boxing
.Ve
.PP
or adding an innocuous 0 somewhere:
.PP
.Vb 1
\&   01*12:0:24:0:0:0*FW1   = Boxing
.Ve
.PP
The other good alternative would be to make two completely different
recurrences such as:
.PP
.Vb 2
\&   1*12:0:24:0:0:0*FW1  = Christmas
\&   1*12:0:25:0:0:0*FW1  = Boxing
.Ve
.PP
At times, you may want to switch back and forth between two holiday files.
This can be done by calling the following:
.PP
.Vb 4
\&  &Date_Init("EraseHolidays=1","PersonalCnf=FILE1");
\&  ...
\&  &Date_Init("EraseHolidays=1","PersonalCnf=FILE2");
\&  ...
.Ve
.SH "EVENTS SECTION"
.IX Header "EVENTS SECTION"
The Events section of the config file is similar to the Holiday section.
It is used to name certain days or times, but there are a few important
differences:
.IP "Events can be assigned to any time and duration" 4
.IX Item "Events can be assigned to any time and duration"
All holidays are exactly 1 day long.  They are assigned to a period
of time from midnight to midnight.
.Sp
Events can be based at any time of the day, and may be of any duration.
.IP "Events don't affect business mode calculations" 4
.IX Item "Events don't affect business mode calculations"
Unlike holidays, events are completely ignored when doing business
mode calculations.
.PP
Whereas holidays were added with business mode math in mind, events
were added with calendar and scheduling applications in mind.
.PP
Every line in the events section is of the form:
.PP
.Vb 1
\&   EVENT = NAME
.Ve
.PP
where \s-1NAME\s0 is the name of the event, and \s-1EVENT\s0 defines when it occurs
and it's duration.  An \s-1EVENT\s0 can be defined in the following ways:
.PP
.Vb 4
\&   Date
\&   Date*
\&   Recur    [NYI]
\&   Recur*   [NYI]
.Ve
.PP
.Vb 3
\&   Date  ; Date
\&   Date  ; Delta
\&   Recur ; Delta   [NYI]
.Ve
.PP
.Vb 2
\&   Date  ; Delta ; Delta   [NYI]
\&   Recur ; Delta ; Delta   [NYI]
.Ve
.PP
Here, Date* refers to a string containing a Date with \s-1NO\s0 \s-1TIME\s0 fields
(Jan 12, 1/1/2000, 2010\-01\-01) while Date does contain time fields.
Similarily, Recur* stands for a recurrence with the time fields all
equal to 0) while Recur stands for a recurrence with at least one
non-zero time field.
.PP
Both Date* and Recur* refer to an event very similar to a holiday which
goes from midnight to midnight.
.PP
Date and Recur refer to events which occur at the time given and with
a duration of 1 hour.
.PP
Events given by \*(L"Date ; Date\*(R", \*(L"Date ; Delta\*(R", and \*(L"Recur ; Delta\*(R"
contain both the starting date and either ending date or duration.
.PP
Events given as three elements \*(L"Date ; Delta ; Delta\*(R" or \*(L"Recur ; Delta ;
Delta\*(R" take a date and add both deltas to it to give the starting and
ending time of the event.  The order and sign of the deltas is
unimportant (and both can be the same sign to give a range of times
which does not contain the base date).
.PP
Items marked with [\s-1NYI\s0] are not yet implemented but will be by the
time this is released.
.SH "BACKWARDS INCOMPATIBILITIES"
.IX Header "BACKWARDS INCOMPATIBILITIES"
For the most part, Date::Manip has remained backward compatible at every
release.  There have been a few minor incompatibilities introduced at
various stages.  Major differences are marked with bullets.
.IP "\s-1VERSION\s0 5.41" 4
.IX Item "VERSION 5.41"
.PD 0
.IP "Changed path separator for \s-1VMS\s0" 4
.IX Item "Changed path separator for VMS"
.PD
Since \*(L":\*(R" is used in some \s-1VMS\s0 paths, it should not have been used as
the path separator.  It has been changed to a newline (\*(L"\en\*(R") character.
.IP "Delta_Format behavior changed" 4
.IX Item "Delta_Format behavior changed"
The entire delta is exact if no month component is present (previously,
no year or month component could be present).
.IP "\s-1VERSION\s0 5.38" 4
.IX Item "VERSION 5.38"
.PD 0
.IP "Removed Date_DaysSince999" 4
.IX Item "Removed Date_DaysSince999"
.PD
The Date_DaysSince999 function (deprecated in 5.35) has been removed.
.IP "\s-1VERSION\s0 5.35" 4
.IX Item "VERSION 5.35"
.RS 4
.PD 0
.IP "Deprected Date_DaysSince999" 4
.IX Item "Deprected Date_DaysSince999"
.PD
In fixing support for the years 0000\-0999, I rewrote Date_DaysSince999 to
be Date_DaysSince1BC.  The Date_DaysSince999 function will be removed.
.IP "\(bu Added PathSep variable" 4
.IX Item "Added PathSep variable"
In order to better support Win32 platforms, I added the PathSep config
variable.  This will allow the use of paths such as \*(L"c:\edate\*(R" on Win32
platforms.  Old config files on Win32 platforms (which were not working
correctly in many cases) may not work if they contain path information to
the personal config file.
.RE
.RS 4
.RE
.IP "\s-1VERSION\s0 5.34" 4
.IX Item "VERSION 5.34"
.RS 4
.PD 0
.IP "\(bu All Date::Manip variables are no longer accessible" 4
.IX Item "All Date::Manip variables are no longer accessible"
.PD
Previously, Date::Manip variables were declared using a full package name.
Now, they are declared with the \fImy()\fR function.  This means that internal
variables are no longer accessible outside of the module.
.IP "Week interpretation in business mode deltas" 4
.IX Item "Week interpretation in business mode deltas"
A business mode delta containing a week value used to be treated as 7 days.
A much more likely interpretation of a week is Monday to Monday, regardless
of holidays, so this is now the behavior.
.IP "%z UnixDate format" 4
.IX Item "%z UnixDate format"
The \f(CW%z\fR UnixDate format used to return the Timezone abbreviation.  It now
returns it as a \s-1GMT\s0 offset (i.e. \-0500).  \f(CW%Z\fR still returns the Timezone
abbreviation.
.ie n .IP "Formats ""22nd sunday"" returns the intuitive value" 4
.el .IP "Formats ``22nd sunday'' returns the intuitive value" 4
.IX Item "Formats 22nd sunday returns the intuitive value"
The date \*(L"22nd sunday\*(R" used to return the Sunday of the 22nd week of the
year (which could be the 21st, 22nd, or 23rd Sunday of the year depending
on how weeks were defined).  Now, it returns the 22nd Sunday of the year
regardless.
.IP "Separator in DD/YYmmm and mmmDD/YY formats no longer optional" 4
.IX Item "Separator in DD/YYmmm and mmmDD/YY formats no longer optional"
Previously, the date \*(L"Dec1065\*(R" would return Dec 10, 1965.  After adding
the YYYYmmm and mmmYYYY formats, this was no longer possible.  The separator
between \s-1DD\s0 and \s-1YY\s0 is no longer optional, so
.Sp
.Vb 2
\&   Dec1065     returns December 1, 1065
\&   Dec10/65    returns December 10, 1965
.Ve
.IP "\(bu Date_Cmp added" 4
.IX Item "Date_Cmp added"
This is not a backwards incompatibility... but is added to help prepare for
a future incompatibility.  In one of the next versions of Date::Manip, the
internal format of the date will change to include timezone information.
All date comparisons should be made using Date_Cmp (which currently does
nothing more than call the perl \*(L"cmp\*(R" command, but which will important
when comparing dates that include the timezone).
.RE
.RS 4
.RE
.IP "\s-1VERSION\s0 5.32" 4
.IX Item "VERSION 5.32"
.RS 4
.PD 0
.IP "Date_Init arguments" 4
.IX Item "Date_Init arguments"
.PD
The old style Date_Init arguments that were deprecated in version 5.07
have been removed.
.IP "\(bu DateManip.cnf change" 4
.IX Item "DateManip.cnf change"
Changed .DateManip.cnf to Manip.cnf (to get rid of problems on \s-1OS\s0's
that insist on 8.3 filenames) for all non-Unix platforms (Wintel, \s-1VMS\s0,
Mac).  For all Unix platforms, it's still .DateManip.cnf .  It will only
look in the user's home directory on \s-1VMS\s0 and Unix.
.RE
.RS 4
.RE
.IP "\s-1VERSION\s0 5.30" 4
.IX Item "VERSION 5.30"
.RS 4
.PD 0
.IP "\(bu Delta format changed" 4
.IX Item "Delta format changed"
.PD
A week field has been added to the internal format of the delta.  It now
reads \*(L"Y:M:W:D:H:MN:S\*(R" instead of \*(L"Y:M:D:H:MN:S\*(R".
.RE
.RS 4
.RE
.IP "\s-1VERSION\s0 5.21" 4
.IX Item "VERSION 5.21"
.RS 4
.PD 0
.IP "Long running processes may give incorrect timezone" 4
.IX Item "Long running processes may give incorrect timezone"
.PD
A process that runs during a timezone change (Daylight Saving Time
specifically) may report the wrong timezone.  See the UpdateCurrTZ variable
for more information.
.ie n .IP "UnixDate ""%J"", ""%W"", and ""%U"" formats fixed" 4
.el .IP "UnixDate ``%J'', ``%W'', and ``%U'' formats fixed" 4
.IX Item "UnixDate %J, %W, and %U formats fixed"
The \f(CW%J\fR, \f(CW%W\fR, and \f(CW%U\fR will no longer report a week 0 or a week 53 if it should
really be week 1 of the following year.  They now report the correct week
number according to \s-1ISO\s0 8601.
.RE
.RS 4
.RE
.IP "\s-1VERSION\s0 5.20" 4
.IX Item "VERSION 5.20"
.RS 4
.PD 0
.IP "\(bu ParseDate formats removed (\s-1ISO\s0 8601 compatibility)" 4
.IX Item "ParseDate formats removed (ISO 8601 compatibility)"
.PD
Full support for \s-1ISO\s0 8601 formats was added.  As a result, some formats
which previously worked may no longer be parsed since they conflict with an
\&\s-1ISO\s0 8601 format.  These include MM-DD-YY (conflicts with \s-1YY\-MM\-DD\s0) and
\&\s-1YYMMDD\s0 (conflicts with \s-1YYYYMM\s0).  \s-1MM/DD/YY\s0 still works, so the first form
can be kept easily by changing \*(L"\-\*(R" to \*(L"/\*(R".  \s-1YYMMDD\s0 can be changed to
YY-MM-DD before being parsed.  Whenever parsing dates using dashes as
separators, they will be treated as \s-1ISO\s0 8601 dates.  You can get around
this by converting all dashes to slashes.
.IP "\(bu Week day numbering" 4
.IX Item "Week day numbering"
The day numbering was changed from 0\-6 (sun\-sat) to 1\-7 (mon\-sun) to be
\&\s-1ISO\s0 8601 compatible.  Weeks start on Monday (though this can be overridden
using the FirstDay config variable) and the 1st week of the year contains
Jan 4 (though it can be forced to contain Jan 1 with the Jan1Week1 config
variable).
.RE
.RS 4
.RE
.IP "\s-1VERSION\s0 5.07" 4
.IX Item "VERSION 5.07"
.RS 4
.PD 0
.ie n .IP "UnixDate ""%s"" format" 4
.el .IP "UnixDate ``%s'' format" 4
.IX Item "UnixDate %s format"
.PD
Used to return the number of seconds since 1/1/1970 in the current
timezone.  It now returns the number of seconds since 1/1/1970 \s-1GMT\s0.
The \*(L"%o\*(R" format was added which returns what \*(L"%s\*(R" previously did.
.IP "Internal format of delta" 4
.IX Item "Internal format of delta"
The format for the deltas returned by ParseDateDelta changed.  Previously,
each element of a delta had a sign attached to it (+1:+2:+3:+4:+5:+6).  The
new format removes all unnecessary signs by default (+1:2:3:4:5:6).  Also,
because of the way deltas are normalized (see documentation on
ParseDateDelta), at most two signs are included.  For backwards
compatibility, the config variable DeltaSigns was added.  If set to 1, all
deltas include all 6 signs.
.IP "Date_Init arguments" 4
.IX Item "Date_Init arguments"
The format of the Date_Init calling arguments changed.  The
old method
.Sp
.Vb 1
\&  &Date_Init($language,$format,$tz,$convtz);
.Ve
.Sp
is still supported , but this support will likely disappear in the future.
Use the new calling format instead:
.Sp
.Vb 1
\&  &Date_Init("var=val","var=val",...);
.Ve
.Sp
\&\s-1NOTE:\s0  The old format is no longer supported as of version 5.32 .
.RE
.RS 4
.RE
.SH "KNOWN PROBLEMS"
.IX Header "KNOWN PROBLEMS"
The following are not bugs in Date::Manip, but they may give some people
problems.
.IP "Unable to determine TimeZone" 4
.IX Item "Unable to determine TimeZone"
Perhaps the most common problem occurs when you get the error:
.Sp
.Vb 1
\&   Error: Date::Manip unable to determine TimeZone.
.Ve
.Sp
Date::Manip tries hard to determine the local timezone, but on some
machines, it cannot do this (especially non-unix systems).  To fix this,
just set the \s-1TZ\s0 variable, either at the top of the Manip.pm file,, in the
DateManip.cnf file, or in a call to Date_Init.  I suggest using the form
\&\*(L"\s-1EST5EDT\s0\*(R" so you don't have to change it every 6 months when going to or
from daylight savings time.
.Sp
Windows \s-1NT\s0 does not seem to set the TimeZone by default.  From the
Perl\-Win32\-Users mailing list:
.Sp
.Vb 7
\&   > How do I get the TimeZone on my NT?
\&   >
\&   >      $time_zone = $ENV{'TZ'};
\&   >
\&   You have to set the variable before, WinNT doesn't set it by
\&   default.  Open the properties of "My Computer" and set a SYSTEM
\&   variable TZ to your timezone.   Jenda@Krynicky.cz
.Ve
.Sp
This might help out some \s-1NT\s0 users.
.Sp
A minor (false) assumption that some users might make is that since
Date::Manip passed all of it's tests at install time, this should not occur
and are surprised when it does.
.Sp
Some of the tests are timezone dependent.  Since the tests all include
input and expected output, I needed to know in advance what timezone they
would be run in.  So, the tests all explicitly set the timezone using the
\&\s-1TZ\s0 configuration variable passed into Date_Init.  Since this overrides any
other method of determining the timezone, Date::Manip uses this and doesn't
have to look elsewhere for the timezone.
.Sp
When running outside the tests, Date::Manip has to rely on it's other
methods for determining the timezone.
.IP "Complaining about getpwnam/getpwuid" 4
.IX Item "Complaining about getpwnam/getpwuid"
Another problem is when running on Micro$oft \s-1OS\s0'es.  I have added many
tests to catch them, but they still slip through occasionally.  If any ever
complain about getpwnam/getpwuid, simply add one of the lines:
.Sp
.Vb 2
\&  $ENV{OS} = Windows_NT
\&  $ENV{OS} = Windows_95
.Ve
.Sp
to your script before
.Sp
.Vb 1
\&  use Date::Manip
.Ve
.IP "Date::Manip is slow" 4
.IX Item "Date::Manip is slow"
The reasons for this are covered in the \s-1SHOULD\s0 I \s-1USE\s0 \s-1DATE::MANIP\s0 section
above.
.Sp
Some things that will definitely help:
.Sp
Version 5.21 does run noticeably faster than earlier versions due to
rethinking some of the initialization, so at the very least, make sure you
are running this version or later.
.Sp
\&\s-1ISO\-8601\s0 dates are parsed first and fastest.  Use them whenever possible.
.Sp
Avoid parsing dates that are referenced against the current time (in 2
days, today at noon, etc.).  These take a lot longer to parse.
.Sp
.Vb 4
\&   Example:  parsing 1065 dates with version 5.11 took 48.6 seconds, 36.2
\&   seconds with version 5.21, and parsing 1065 ISO-8601 dates with version
\&   5.21 took 29.1 seconds (these were run on a slow, overloaded computer with
\&   little memory... but the ratios should be reliable on a faster computer).
.Ve
.Sp
Business date calculations are extremely slow.  You should consider
alternatives if possible (i.e. doing the calculation in exact mode and then
multiplying by 5/7).  There will be an approximate business mode in one of
the next versions which will be much faster (though less accurate) which
will do something like this.  Whenever possible, use this mode.  And who
needs a business date more accurate than \*(L"6 to 8 weeks\*(R" anyway huh :\-)
.Sp
Never call Date_Init more than once.  Unless you're doing something very
strange, there should never be a reason to anyway.
.IP "Sorting Problems" 4
.IX Item "Sorting Problems"
If you use Date::Manip to sort a number of dates, you must call Date_Init
either explicitly, or by way of some other Date::Manip routine before it
is used in the sort.  For example, the following code fails:
.Sp
.Vb 12
\&   use Date::Manip;
\&   # &Date_Init;
\&   sub sortDate {
\&       my($date1, $date2);
\&       $date1 = &ParseDate($a);
\&       $date2 = &ParseDate($b);
\&       return (&Date_Cmp($date1,$date2));
\&   }
\&   @dates = ("Fri 16 Aug 96",
\&            "Mon 19 Aug 96",
\&            "Thu 15 Aug 96");
\&   @i=sort sortDate @dates;
.Ve
.Sp
but if you uncomment the Date_Init line, it works.  The reason for this is
that the first time you call Date_Init, it initializes a number of items
used by Date::Manip.  Some of these have to be sorted (regular expressions
sorted by length to ensure the longest match).  It turns out that perl
has a bug in it which does not allow a sort within a sort.  At some point,
this should be fixed, but for now, the best thing to do is to call Date_Init
explicitly.  The bug exists in all versions up to 5.005 (I haven't
tested 5.6.0 yet).
.Sp
\&\s-1NOTE:\s0 This is an \s-1EXTREMELY\s0 inefficient way to sort data.  Instead, you
should parse the dates with ParseDate, sort them using a normal string
comparison, and then convert them back to the format desired using
UnixDate.
.IP "\s-1RCS\s0 Control" 4
.IX Item "RCS Control"
If you try to put Date::Manip under \s-1RCS\s0 control, you are going to have
problems.  Apparently, \s-1RCS\s0 replaces strings of the form \*(L"$Date...$\*(R" with
the current date.  This form occurs all over in Date::Manip.  To prevent the
\&\s-1RCS\s0 keyword expansion, checkout files using \*(L"co \-ko\*(R".  Since very few people
will ever have a desire to do this (and I don't use \s-1RCS\s0), I have not worried
about it.
.SH "KNOWN BUGS"
.IX Header "KNOWN BUGS"
.IP "Daylight Savings Times" 4
.IX Item "Daylight Savings Times"
Date::Manip does not handle daylight savings time, though it does handle
timezones to a certain extent.  Converting from \s-1EST\s0 to \s-1PST\s0 works fine.
Going from \s-1EST\s0 to \s-1PDT\s0 is unreliable.
.Sp
The following examples are run in the winter of the \s-1US\s0 East coast (i.e.
in the \s-1EST\s0 timezone).
.Sp
.Vb 2
\&        print UnixDate(ParseDate("6/1/97 noon"),"%u"),"\en";
\&        => Sun Jun  1 12:00:00 EST 1997
.Ve
.Sp
June 1 \s-1EST\s0 does not exist.  June 1st is during \s-1EDT\s0.  It should print:
.Sp
.Vb 1
\&        => Sun Jun  1 00:00:00 EDT 1997
.Ve
.Sp
Even explicitly adding the timezone doesn't fix things (if anything, it
makes them worse):
.Sp
.Vb 2
\&        print UnixDate(ParseDate("6/1/97 noon EDT"),"%u"),"\en";
\&        => Sun Jun  1 11:00:00 EST 1997
.Ve
.Sp
Date::Manip converts everything to the current timezone (\s-1EST\s0 in this case).
.Sp
Related problems occur when trying to do date calculations over a timezone
change.  These calculations may be off by an hour.
.Sp
Also, if you are running a script which uses Date::Manip over a period of
time which starts in one time zone and ends in another (i.e. it switches
form Daylight Savings Time to Standard Time or vice versa), many things may
be wrong (especially elapsed time).
.Sp
I hope to fix these problems in a future release so that it would convert
everything to the current zones (\s-1EST\s0 or \s-1EDT\s0).
.SH "BUGS AND QUESTIONS"
.IX Header "BUGS AND QUESTIONS"
If you find a bug in Date::Manip, please send it directly to me (see the
\&\s-1AUTHOR\s0 section below) rather than posting it to one of the newsgroups.
Although I try to keep up with the comp.lang.perl.* groups, all too often I
miss news (flaky news server, articles expiring before I caught them, 1200
articles to wade through and I missed one that I was interested in, etc.).
.PP
When filing a bug report, please include the following information:
.PP
.Vb 2
\&  o  The version of Date::Manip you are using.  You can get this by using
\&     the script:
.Ve
.PP
.Vb 2
\&        use Date::Manip;
\&        print &DateManipVersion(),"\en";
.Ve
.PP
.Vb 1
\&  o  The output from "perl -V"
.Ve
.PP
If you have a problem using Date::Manip that perhaps isn't a bug (can't
figure out the syntax, etc.), you're in the right place.  Go right back to
the top of this man page and start reading.  If this still doesn't answer
your question, mail me (again, please mail me rather than post to the
newsgroup).
.SH "YEAR 2000"
.IX Header "YEAR 2000"
In hindsight, the fact that I've only been asked once (so far) if Date::Manip
is year 2000 compliant surprises me a bit.  Still, as 2000 approaches and
this buzzword starts flying around more and more frantically, other's might
follow suit, so this section answers the question.
.PP
Is Date::Manip year 2000 compliant?
.PP
This question is largely meaningless.  Date::Manip is basically just a
parser.  You give it a date and it'll manipulate it.  Date::Manip does
store the date internally as a 4 digit year, and performs all operations
using this internal representation, so I will state that Date::Manip is
\&\s-1CAPABLE\s0 of writing Y2K compliant code.
.PP
But Date::Manip is simply a library.  If you use it correctly, your code
can be Y2K compliant.  If you don't, your code may not be Y2K compliant.
.PP
The bottom line is this:
.PP
.Vb 2
\&  Date::Manip is a library that is capable of being used to write Y2K
\&  compliant code.  It may also be used to write non-Y2K compliant code.
.Ve
.PP
.Vb 3
\&  If your code is NOT Y2K compliant, it is NOT due to any deficiency in
\&  Date::Manip.  Rather, it is due to poor programming on the part of the
\&  person using Date::Manip.
.Ve
.PP
For an excellent treatment of the Y2K problem, see the article by Tom
Christiansen at:
.PP
.Vb 1
\&  http://language.perl.com/news/y2k.html
.Ve
.PP
A slightly better question is \*(L"Is Perl year 2000 compliant\*(R"?  This is
covered in the perl \s-1FAQ\s0 (section 4) and in the article by Tom Crhistiansen.
.PP
The best question is \*(L"For what dates is Date::Manip useful?\*(R"  It definitely
can't handle \s-1BC\s0 dates, or dates past Dec 31, 9999.  So Date::Manip works
during the years 1000 to 9999.
.PP
In practical terms however, Date::Manip deals with the Gregorian calendar,
and is therefore useful in the period that that calendar has been, or will
be, in effect.  The Gregorian calendar was first adopted by the Catholic
church in 1582, but some countries were still using the Julian calendar as
late as the early part of the 20th century.  Also, at some point (probably
no earlier than the year 3000 and possibly much later), the Gregorian
system is going to have to be modified slightly since the current system of
leap years is off by a few seconds a year.  So...  in practical terms,
Date::Manip is _probably_ useful from 1900 to 3000.
.PP
One other note is that Date::Manip will \s-1NOT\s0 handle 3 digit years.  So, if
you store the year as an offset from 1900 (which is 2 digits now, but will
become 3 digits in 2000), these will \s-1NOT\s0 be parsable by Date::Manip.
.SH "VERSION NUMBERS"
.IX Header "VERSION NUMBERS"
A note about version numbers.
.PP
Prior to version 5.00, Date::Manip was distributed as a perl4 library.
There were no numbering conventions in place, so I used a simple
\&\s-1MAJOR\s0.MINOR numbering scheme.
.PP
With version 5.00, I switched to a perl5 module and at that time switched
to the perl5 numbering convention of a major version followed by a 2 digit
minor version.
.PP
As of 5.41/5.42, all versions released to \s-1CPAN\s0 will be even numbered.  Odd
numbered will be development versions available from my web site.  For
example, after 5.40 was released, I started making changes, and called
the development version 5.41.  When released to \s-1CPAN\s0, it was called 5.42.
I may add a third digit to development versions (i.e. 5.41.9) to keep
track of important changes in the development version.
.SH "ACKNOWLEDGMENTS"
.IX Header "ACKNOWLEDGMENTS"
There are many people who have contributed to Date::Manip over the years
that I'd like to thank.  The most important contributions have come in the
form of suggestions and bug reports by users.  I have tried to include the
name of every person who first suggested each improvement or first reported
each bug.  These are included in the \s-1HISTORY\s0 file in the Date::Manip
distribution in the order the changes are made.  The list is simply too
long to appear here, but I appreciate their help.
.PP
A number of people have made suggestions or reported bugs which are not
mentioned in the \s-1HISTORY\s0 file.  These include suggestions which have not
been implemented and people who have made a suggestion or bug report which
has already been suggested/reported by someone else.  For those who's
suggestions have not yet been implemented, they will be added to the
\&\s-1HISTORY\s0 file when (if) their suggestions are implemented.  For everyone
else, thank you too.  I'd much rather have a suggestion made twice than not
at all.
.PP
Thanks to Alan Cezar and Greg Schiedler for paying me to implement the
Events_List routine.  They gave me the idea, and were then willing to pay
me for my time to get it implemented quickly.
.PP
I'd also like a couple of authors.  Date::Manip has recently been getting
some really good press in a couple of books.  Since no one's paying me to
write Date::Manip, seeing my module get a good review in a book written by
someone else really makes my day.  My thanks to Nate Padwardhan and Clay
Irving (Programming with Perl Modules \*(-- part of the O'Reilly Perl Resource
Kit); and Tom Christiansen and Nathan Torkington (The Perl Cookbook).
Also, thanks to any other authors who've written about Date::Manip who's
books I haven't seen.
.SH "AUTHOR"
.IX Header "AUTHOR"
Sullivan Beck (sbeck@cpan.org)
.PP
You can always get the newest beta version of Date::Manip (which may fix
problems in the current \s-1CPAN\s0 version... and may add others) from my home
page:
.PP
http://www.cise.ufl.edu/~sbeck/