1 # Copyright (c) 1995-2003 Sullivan Beck. All rights reserved.

     2 # This program is free software; you can redistribute it and/or modify it

     3 # under the same terms as Perl itself.

     4 

     5 =head1 NAME

     6 

     7 Date::Manip - date manipulation routines

     8 

     9 =head1 SYNOPSIS

    10 

    11  use Date::Manip;

    12 

    13  $date = ParseDate(\@args);

    14  $date = ParseDate($string);

    15  $date = ParseDate(\$string);

    16 

    17  @date = UnixDate($date,@format);

    18  $date = UnixDate($date,@format);

    19 

    20  $delta = ParseDateDelta(\@args);

    21  $delta = ParseDateDelta($string);

    22  $delta = ParseDateDelta(\$string);

    23 

    24  @str = Delta_Format($delta,$dec,@format);

    25  $str = Delta_Format($delta,$dec,@format);

    26 

    27  $recur = ParseRecur($string,$base,$date0,$date1,$flags);

    28  @dates = ParseRecur($string,$base,$date0,$date1,$flags);

    29 

    30  $flag = Date_Cmp($date1,$date2);

    31 

    32  $d = DateCalc($d1,$d2 [,$errref] [,$del]);

    33 

    34  $date = Date_SetTime($date,$hr,$min,$sec);

    35  $date = Date_SetTime($date,$time);

    36 

    37  $date = Date_SetDateField($date,$field,$val [,$nocheck]);

    38 

    39  $date = Date_GetPrev($date,$dow,$today,$hr,$min,$sec);

    40  $date = Date_GetPrev($date,$dow,$today,$time);

    41 

    42  $date = Date_GetNext($date,$dow,$today,$hr,$min,$sec);

    43  $date = Date_GetNext($date,$dow,$today,$time);

    44 

    45  $version = DateManipVersion;

    46 

    47  $flag = Date_IsWorkDay($date [,$flag]);

    48 

    49  $date = Date_NextWorkDay($date,$off [,$time]);

    50  $date = Date_PrevWorkDay($date,$off [,$time]);

    51 

    52  $name = Date_IsHoliday($date);

    53 

    54  $listref = Events_List($date);

    55  $listref = Events_List($date0,$date1);

    56 

    57  &Date_Init();

    58  &Date_Init("VAR=VAL","VAR=VAL",...);

    59  @list = Date_Init();

    60  @list = Date_Init("VAR=VAL","VAR=VAL",...);

    61 

    62 The above routines all check to make sure that Date_Init is called.  If it

    63 hasn't been, they will call it automatically.  As a result, there is usually

    64 no need to call Date_Init explicitely unless you want to change some of the

    65 config variables (described below).

    66 

    67 The following routines are used by the above routines (though they can also

    68 be called directly).  $y may be entered as either a 2 or 4 digit year (it

    69 will be converted to a 4 digit year based on the variable YYtoYYYY

    70 described below).  Month and day should be numeric in all cases.  Most (if

    71 not all) of the information below can be gotten from UnixDate which is

    72 really the way I intended it to be gotten, but there are reasons to use

    73 these (these are significantly faster).

    74 

    75 ***NOTE*** Unlike the routines listed above, the following routines do NOT

    76 explicitely call Date_Init.  You must make sure that Date_Init has been

    77 called, either by you explicitely, or by one of the above routines before you

    78 use these routines.

    79 

    80  $day = Date_DayOfWeek($m,$d,$y);

    81  $secs = Date_SecsSince1970($m,$d,$y,$h,$mn,$s);

    82  $secs = Date_SecsSince1970GMT($m,$d,$y,$h,$mn,$s);

    83  $days = Date_DaysSince1BC($m,$d,$y);

    84  $day = Date_DayOfYear($m,$d,$y);

    85  $days = Date_DaysInYear($y);

    86  $wkno = Date_WeekOfYear($m,$d,$y,$first);

    87  $flag = Date_LeapYear($y);

    88  $day = Date_DaySuffix($d);

    89  $tz = Date_TimeZone();

    90  ($y,$m,$d,$h,$mn,$s) = Date_NthDayOfYear($y,$n);

    91 

    92 =head1 DESCRIPTION

    93 

    94 This is a set of routines designed to make any common date/time

    95 manipulation easy to do.  Operations such as comparing two times,

    96 calculating a time a given amount of time from another, or parsing

    97 international times are all easily done.  From the very beginning, the main

    98 focus of Date::Manip has been to be able to do ANY desired date/time

    99 operation easily, not necessarily quickly.  Also, it is definitely oriented

   100 towards the type of operations we (as people) tend to think of rather than

   101 those operations used routinely by computers.  There are other modules that

   102 can do a subset of the operations available in Date::Manip much quicker

   103 than those presented here, so be sure to read the section SHOULD I USE

   104 DATE::MANIP below before deciding which of the Date and Time modules from

   105 CPAN is for you.

   106 

   107 Date::Manip deals with time as it is presented the Gregorian calendar (the

   108 one currently in use).  The Julian calendar defined leap years as every 4th

   109 year.  The Gregorian calendar improved this by making every 100th year NOT

   110 a leap year, unless it was also the 400th year.  The Gregorian calendar has

   111 been extrapolated back to the year 0000 AD and forward to the year 9999 AD.

   112 Note that in historical context, the Julian calendar was in use until 1582

   113 when the Gregorian calendar was adopted by the Catholic church.  Protestant

   114 countries did not accept it until later; Germany and Netherlands in 1698,

   115 British Empire in 1752, Russia in 1918.  Note that the Gregorian calendar

   116 is itself imperfect and at some point will need to be corrected.  No attempt

   117 is made to correct for that, and my great great great grandchildren will be

   118 long dead before this even occurs, so it's not an immediate concern.  Yes,

   119 this is the same type of attitute that caused the great Y2K problem... but

   120 I have an excuse: I don't know what the correction will be, so I can't

   121 possible implement it.  Nobody doubted that the year after 1999 would be

   122 known as 2000 :-).

   123 

   124 Date::Manip is therefore not equipped to truly deal with historical dates,

   125 but should be able to perform (virtually) any operation dealing with a

   126 modern time and date.

   127 

   128 Date::Manip has (or will have) functionality to work with several fundamental

   129 types of data.

   130 

   131 =over 4

   132 

   133 =item DATE

   134 

   135 Although the word date is used extensively here, it is actually somewhat

   136 misleading.  Date::Manip works with the full date AND time (year, month,

   137 day, hour, minute, second and weeks when appropriate).  It doesn't work

   138 with fractional seconds.  Timezones are also supported to some extent.

   139 

   140 NOTE:  Much better support for timezones (including Daylight Savings Time)

   141 is planned for the future.

   142 

   143 =item DELTA

   144 

   145 This refers to a duration or elapsed time.  One thing to note is that, as

   146 used in this module, a delta refers only to the amount of time elapsed.  It

   147 includes no information about a starting or ending time.

   148 

   149 =item RECURRENCE

   150 

   151 A recurrence is simply a notation for defining when a recurring event

   152 occurs.  For example, if an event occurs every other Friday or every

   153 4 hours, this can be defined as a recurrence.  With a recurrence and a

   154 starting and ending date, you can get a list of dates in that period when

   155 a recurring event occurs.

   156 

   157 =item GRAIN

   158 

   159 The granularity of a time basically refers to how accurate you wish to

   160 treat a date.  For example, if you want to compare two dates to see if

   161 they are identical at a granularity of days, then they only have to occur

   162 on the same day.  At a granularity of an hour, they have to occur within

   163 an hour of each other, etc.

   164 

   165 NOTE:  Support for this will be added in the future.

   166 

   167 =item HOLIDAYS and EVENTS

   168 

   169 These are basically a named time.  Holidays are used in business mode

   170 calculations.  Events allow things like calendar and scheduling

   171 applications to be designed much more easily.

   172 

   173 =back

   174 

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

   176 

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

   178 

   179 2.  Compare two dates, entered in widely different formats

   180     to determine which is earlier

   181 

   182 3.  Extract any information you want from ANY date using a

   183     format string similar to the Unix date command

   184 

   185 4.  Determine the amount of time between two dates

   186 

   187 5.  Add a time offset to a date to get a second date (i.e.

   188     determine the date 132 days ago or 2 years and 3 months

   189     after Jan 2, 1992)

   190 

   191 6.  Work with dates with dates using international formats

   192     (foreign month names, 12/10/95 referring to October

   193     rather than December, etc.).

   194 

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

   196 

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

   198 

   199 =head1 EXAMPLES

   200 

   201 In the documentation below, US formats are used, but in most (if not all)

   202 cases, a non-English equivalent will work equally well.

   203 

   204 1.  Parsing a date from any convenient format

   205 

   206   $date = ParseDate("today");

   207   $date = ParseDate("1st thursday in June 1992");

   208   $date = ParseDate("05/10/93");

   209   $date = ParseDate("12:30 Dec 12th 1880");

   210   $date = ParseDate("8:00pm december tenth");

   211   if (! $date) {

   212     # Error in the date

   213   }

   214 

   215 2.  Compare two dates

   216 

   217   $date1 = ParseDate($string1);

   218   $date2 = ParseDate($string2);

   219   $flag = Date_Cmp($date1,$date2);

   220   if ($flag<0) {

   221     # date1 is earlier

   222   } elsif ($flag==0) {

   223     # the two dates are identical

   224   } else {

   225     # date2 is earlier

   226   }

   227 

   228 3.  Extract information from a date.

   229 

   230   print &UnixDate("today","It is now %T on %b %e, %Y.");

   231     =>  "It is now 13:24:08 on Feb  3, 1996."

   232 

   233 4.  The amount of time between two dates.

   234 

   235   $date1 = ParseDate($string1);

   236   $date2 = ParseDate($string2);

   237   $delta = DateCalc($date1,$date2,\$err);

   238     => 0:0:WK:DD:HH:MM:SS   the weeks, days, hours, minutes,

   239                             and seconds between the two

   240   $delta = DateCalc($date1,$date2,\$err,1);

   241     => YY:MM:WK:DD:HH:MM:SS  the years, months, etc. between

   242                              the two

   243 

   244   Read the documentation below for an explanation of the

   245   difference.

   246 

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

   248 

   249   $date = DateCalc("today","+ 3hours 12minutes 6 seconds",\$err);

   250   $date = DateCalc("12 hours ago","12:30 6Jan90",\$err);

   251 

   252   It even works with business days:

   253 

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

   255 

   256 6.  To work with dates in another language.

   257 

   258   &Date_Init("Language=French","DateFormat=non-US");

   259   $date = ParseDate("1er decembre 1990");

   260 

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

   262     (including quite complex ones).

   263 

   264   # To find the 2nd tuesday of every month

   265   @date = ParseRecur("0:1*2:2:0:0:0",$base,$start,$stop);

   266 

   267   # To find the Monday after easter in 1997-1999.

   268   @date = ParseRecur("*1997-1999:0:0:0:0:0:0*EASTER,ND1");

   269 

   270 NOTE: Some date forms do not work as well in languages other than English,

   271 but this is not because Date::Manip is incapable of doing so (almost nothing

   272 in this module is language dependent).  It is simply that I do not have the

   273 correct translation available for some words.  If there is a date form that

   274 works in English but does not work in a language you need, let me know and

   275 if you can provide me the translation, I will fix Date::Manip.

   276 

   277 =head1 SHOULD I USE DATE::MANIP

   278 

   279 If you look in CPAN, you'll find that there are a number of Date and Time

   280 packages.  Is Date::Manip the one you should be using?  In my opinion, the

   281 answer is no most of the time.  This sounds odd coming from the author of

   282 the software, but read on.

   283 

   284 Date::Manip is written entirely in perl.  It's the most powerful of the

   285 date modules.  It's also the biggest and slowest.

   286 

   287 Since Date::Manip is written entirely in perl, and depends on no other

   288 module not in a standard perl distribution, Date::Manip has no dependancies

   289 to meet.  Other modules have dependancies on a C compiler or other perl

   290 modules.  Since it is fairly easy to satisfy these dependancies for

   291 anyone who is reasonably familiar with perl modules, this is not a

   292 huge advantage that Date::Manip has.

   293 

   294 On the other hand, simpler perl modules tend to be faster than Date::Manip,

   295 and modules written in C are significantly faster than their perl

   296 counterparts (at least if they're done right).  The TimeDate and

   297 Time-modules modules are written in perl, but are much simpler (and

   298 hence, faster) than Date::Manip.  The Date::Calc module is written in C

   299 and is a good module for doing many date calculations much faster than

   300 Date::Manip.  Between these three, most of your common date operations

   301 can be done.

   302 

   303 Date::Manip is certainly the most powerful of the Date modules.  To the

   304 best of my knowledge, it will do everything that any other date module will

   305 do (not just the ones I listed above), and there are a number of features

   306 that Date::Manip has that none of the other modules have.  Date::Manip is

   307 the "Swiss Army Knife" of Date modules.  I'm trying to build a library

   308 which can do _EVERY_ conceivable date/time manipulation that you'll run

   309 into in everyday life.

   310 

   311 Although I am working on making Date::Manip faster, it will never be as

   312 fast as other modules.  And before anyone asks, Date::Manip will never

   313 be translated to C (at least by me).  I write C because I have to.  I

   314 write perl because I like to.  Date::Manip is something I do because it

   315 interests me, not something I'm paid for.

   316 

   317 Date::Manip is also big.  The last time I looked, it's one of the largest

   318 CPAN modules there is.  If you ignore modules like Tk, LWP, etc. which are

   319 actually packages of modules, it may be the largest.  It's true that

   320 Date::Manip will do almost every date operation you could imagine... but

   321 you rarely need all that power.  I'm working on reducing the footprint of

   322 Date::Manip, but even at it's slimmest, it'll outweigh the other modules by

   323 a good bit.

   324 

   325 If you are going to be using the module in cases where performance is an

   326 important factor (started up in a CGI program being run by your web server

   327 5,000 times a second), you should check out one of the other Date or Time

   328 modules in CPAN.  If you're only doing fairly simple date operations

   329 (parsing common date formats, finding the difference between two dates,

   330 etc.), the other modules will almost certainly suffice.  If you're doing

   331 one operation very repetitively (parsing 10,000 dates from a database), you

   332 are probably better off writing your own functions (perhaps bypassing all

   333 date modules entirely) designed specifically for your needs.

   334 

   335 On the other hand, if you want one solution for all your date needs, don't

   336 need peak speed, or are trying to do more exotic date operations,

   337 Date::Manip is for you.  Operations on things like business dates, foreign

   338 language dates, holidays and other recurring events, etc. are available

   339 more-or-less exclusively in Date::Manip.

   340 

   341 =head1 ROUTINES

   342 

   343 =over 4

   344 

   345 =item ParseDate

   346 

   347  $date = ParseDate(\@args);

   348  $date = ParseDate($string);

   349  $date = ParseDate(\$string);

   350 

   351 This takes an array or a string containing a date and parses it.  When the

   352 date is included as an array (for example, the arguments to a program) the

   353 array should contain a valid date in the first one or more elements

   354 (elements after a valid date are ignored).  Elements containing a valid

   355 date are shifted from the array.  The largest possible number of elements

   356 which can be correctly interpreted as a valid date are always used.  If a

   357 string is entered rather than an array, that string is tested for a valid

   358 date.  The string is unmodified, even if passed in by reference.

   359 

   360 The real work is done in the ParseDateString routine.

   361 

   362 The ParseDate routine is primarily used to handle command line arguments.

   363 If you have a command where you want to enter a date as a command line

   364 argument, you can use Date::Manip to make something like the following

   365 work:

   366 

   367   mycommand -date Dec 10 1997 -arg -arg2

   368 

   369 No more reading man pages to find out what date format is required in a

   370 man page.

   371 

   372 Historical note: this is originally why the Date::Manip routines were

   373 written (though long before they were released as the Date::Manip module).

   374 I was using a bunch of programs (primarily batch queue managers) where

   375 dates and times were entered as command line options and I was getting

   376 highly annoyed at the many different (but not compatible) ways that they

   377 had to be entered.  Date::Manip originally consisted of basically 1 routine

   378 which I could pass "@ARGV" to and have it remove a date from the beginning.

   379 

   380 =item ParseDateString

   381 

   382  $date = ParseDateString($string);

   383 

   384 This routine is called by ParseDate, but it may also be called directly

   385 to save some time (a negligable amount).

   386 

   387 NOTE:  One of the most frequently asked questions that I have gotten

   388 is how to parse seconds since the epoch.  ParseDateString cannot simply

   389 parse a number as the seconds since the epoch (it conflicts with some

   390 ISO-8601 date formats).  There are two ways to get this information.

   391 First, you can do the following:

   392 

   393     $secs = ...         # seconds since Jan 1, 1970  00:00:00 GMT

   394     $date = &DateCalc("Jan 1, 1970  00:00:00 GMT",$secs);

   395 

   396 Second, you can call it directly as:

   397 

   398     $date = &ParseDateString("epoch $secs");

   399 

   400 To go backwards, just use the "%s" format of UnixDate:

   401 

   402     $secs = &UnixDate($date,"%s");

   403 

   404 A full date actually includes 2 parts: date and time.  A time must include

   405 hours and minutes and can optionally include seconds, fractional seconds,

   406 an am/pm type string, and a timezone.  For example:

   407 

   408      [at] HH:MN              [Zone]

   409      [at] HH:MN         [am] [Zone]

   410      [at] HH:MN:SS      [am] [Zone]

   411      [at] HH:MN:SS.SSSS [am] [Zone]

   412      [at] HH            am   [Zone]

   413 

   414 Hours can be written using 1 or 2 digits, but the single digit form may

   415 only be used when no ambiguity is introduced (i.e. when it is not

   416 immediately preceded by a digit).

   417 

   418 A time is usually entered in 24 hour mode, but 12 hour mode can be used

   419 as well if AM/PM are entered (AM can be entered as AM or A.M. or other

   420 variations depending on the language).

   421 

   422 Fractional seconds are also supported in parsing but the fractional part is

   423 discarded (with NO rounding ocurring).

   424 

   425 Timezones always appear immediately after the time.  A number of different

   426 forms are supported (see the section TIMEZONEs below).

   427 

   428 Incidentally, the time is removed from the date before the date is parsed,

   429 so the time may appear before or after the date, or between any two parts

   430 of the date.

   431 

   432 Valid date formats include the ISO 8601 formats:

   433 

   434    YYYYMMDDHHMNSSF...

   435    YYYYMMDDHHMNSS

   436    YYYYMMDDHHMN

   437    YYYYMMDDHH

   438    YY-MMDDHHMNSSF...

   439    YY-MMDDHHMNSS

   440    YY-MMDDHHMN

   441    YY-MMDDHH

   442    YYYYMMDD

   443    YYYYMM

   444    YYYY

   445    YY-MMDD

   446    YY-MM

   447    YY

   448    YYYYwWWD      ex.  1965-W02-2

   449    YYwWWD

   450    YYYYDOY       ex.  1965-045

   451    YYDOY

   452 

   453 In the above list, YYYY and YY signify 4 or 2 digit years, MM, DD, HH, MN, SS

   454 refer to two digit month, day, hour, minute, and second respectively.  F...

   455 refers to fractional seconds (any number of digits) which will be ignored.

   456 The last 4 formats can be explained by example:  1965-w02-2 refers to Tuesday

   457 (day 2) of the 2nd week of 1965.  1965-045 refers to the 45th day of 1965.

   458 

   459 In all cases, parts of the date may be separated by dashes "-".  If this is

   460 done, 1 or 2 digit forms of MM, DD, etc. may be used.  All dashes are

   461 optional except for those given in the table above (which MUST be included

   462 for that format to be correctly parsed).  So 19980820, 1998-0820,

   463 1998-08-20, 1998-8-20, and 199808-20 are all equivalent, but that date may

   464 NOT be written as 980820 (it must be written as 98-0820).

   465 

   466 NOTE:  Even though not allowed in the standard, the timezone for an ISO-8601

   467 date is flexible and may be any of the timezones understood by Date::Manip.

   468 

   469 Additional date formats are available which may or may not be common including:

   470 

   471   MM/DD  **

   472   MM/DD/YY  **

   473   MM/DD/YYYY  **

   474 

   475   mmmDD       DDmmm                   mmmYYYY/DD     mmmYYYY

   476   mmmDD/YY    DDmmmYY     DD/YYmmm    YYYYmmmDD      YYYYmmm

   477   mmmDDYYYY   DDmmmYYYY   DDYYYYmmm   YYYY/DDmmm

   478 

   479 Where mmm refers to the name of a month.  All parts of the date can be

   480 separated by valid separators (space, "/", or ".").  The separator "-" may

   481 be used as long as it doesn't conflict with an ISO 8601 format, but this

   482 is discouraged since it is easy to overlook conflicts.  For example, the

   483 format MM/DD/YY is just fine, but MM-DD-YY does not work since it conflicts

   484 with YY-MM-DD.  To be safe, if "-" is used as a separator in a non-ISO

   485 format, they should be turned into "/" before calling the Date::Manip

   486 routines.  As with ISO 8601 formats, all separators are optional except for

   487 those given as a "/" in the list above.

   488 

   489 ** Note that with these formats, Americans tend to write month first, but

   490 many other countries tend to write day first.  The latter behavior can be

   491 obtained by setting the config variable DateFormat to something other than

   492 "US" (see CUSTOMIZING DATE::MANIP below).

   493 

   494 Date separators are treated very flexibly (they are converted to spaces),

   495 so the following dates are all equivalent:

   496 

   497    12/10/1965

   498    12-10 / 1965

   499    12 // 10 -. 1965

   500 

   501 In some cases, this may actually be TOO flexible, but no attempt is made to

   502 trap this.

   503 

   504 Years can be entered as 2 or 4 digits, days and months as 1 or 2 digits.

   505 Both days and months must include 2 digits whenever they are immediately

   506 adjacent to another numeric part of the date or time.  Date separators

   507 are required if single digit forms of DD or MM are used.  If separators

   508 are not used, the date will either be unparsable or will get parsed

   509 incorrectly.

   510 

   511 Miscellaneous other allowed formats are:

   512   which dofw in mmm in YY      "first sunday in june 1996 at 14:00" **

   513   dofw week num YY             "sunday week 22 1995" **

   514   which dofw YY                "22nd sunday at noon" **

   515   dofw which week YY           "sunday 22nd week in 1996" **

   516   next/last dofw               "next friday at noon"

   517   next/last week/month         "next month"

   518   in num days/weeks/months     "in 3 weeks at 12:00"

   519   num days/weeks/months later  "3 weeks later"

   520   num days/weeks/months ago    "3 weeks ago"

   521   dofw in num week             "Friday in 2 weeks"

   522   in num weeks dofw            "in 2 weeks on friday"

   523   dofw num week ago            "Friday 2 weeks ago"

   524   num week ago dofw            "2 weeks ago friday"

   525   last day in mmm in YY        "last day of October"

   526   dofw                         "Friday" (Friday of current week)

   527   Nth                          "12th", "1st" (day of current month)

   528   epoch SECS                   seconds since the epoch (negative values

   529                                are supported)

   530 

   531 ** Note that the formats "sunday week 22" and "22nd sunday" give very

   532 different bahaviors.  "sunday week 22" returns the sunday of the 22nd week

   533 of the year based on how week 1 is defined.  ISO 8601 defines week one to

   534 contain Jan 4, so "sunday week 1" might be the first or second sunday of

   535 the current year, or the last sunday of the previous year.  "22nd sunday"

   536 gives the actual 22nd time sunday occurs in a given year, regardless of the

   537 definition of a week.

   538 

   539 Note that certain words such as "in", "at", "of", etc. which commonly appear

   540 in a date or time are ignored.  Also, the year is always optional.

   541 

   542 In addition, the following strings are recognized:

   543   today     (exactly now OR today at a given time if a time is specified)

   544   now       (synonym for today)

   545   yesterday (exactly 24 hours ago unless a time is specified)

   546   tomorrow  (exactly 24 hours from now unless a time is specifed)

   547   noon      (12:00:00)

   548   midnight  (00:00:00)

   549 Other languages have similar (and in some cases additional) strings.

   550 

   551 Some things to note:

   552 

   553 All strings are case insensitive.  "December" and "DEceMBer" both work.

   554 

   555 When a part of the date is not given, defaults are used: year defaults

   556 to current year; hours, minutes, seconds to 00.

   557 

   558 The year may be entered as 2 or 4 digits.  If entered as 2 digits, it will

   559 be converted to a 4 digit year.  There are several ways to do this based on

   560 the value of the YYtoYYYY variable (described below).  The default behavior

   561 it to force the 2 digit year to be in the 100 year period CurrYear-89 to

   562 CurrYear+10.  So in 1996, the range is [1907 to 2006], and the 2 digit year

   563 05 would refer to 2005 but 07 would refer to 1907.  See CUSTOMIZING

   564 DATE::MANIP below for information on YYtoYYYY for other methods.

   565 

   566 Dates are always checked to make sure they are valid.

   567 

   568 In all of the formats, the day of week ("Friday") can be entered anywhere

   569 in the date and it will be checked for accuracy.  In other words,

   570   "Tue Jul 16 1996 13:17:00"

   571 will work but

   572   "Jul 16 1996 Wednesday 13:17:00"

   573 will not (because Jul 16, 1996 is Tuesday, not Wednesday).  Note that

   574 depending on where the weekday comes, it may give unexpected results when

   575 used in array context (with ParseDate).  For example, the date

   576 ("Jun","25","Sun","1990") would return June 25 of the current year since

   577 Jun 25, 1990 is not Sunday.

   578 

   579 The times "12:00 am", "12:00 pm", and "midnight" are not well defined.  For

   580 good or bad, I use the following convention in Date::Manip:

   581   midnight = 12:00am = 00:00:00

   582   noon     = 12:00pm = 12:00:00

   583 and the day goes from 00:00:00 to 23:59:59.  In other words, midnight is the

   584 beginning of a day rather than the end of one.  The time 24:00:00 is also

   585 allowed (though it is automatically transformed to 00:00:00 of the following

   586 day).

   587 

   588 The format of the date returned is YYYYMMDDHH:MM:SS.  The advantage of this

   589 time format is that two times can be compared using simple string comparisons

   590 to find out which is later.  Also, it is readily understood by a human.

   591 Alternate forms can be used if that is more convenient.  See Date_Init below

   592 and the config variable Internal.

   593 

   594 NOTE: The format for the date is going to change at some point in the future

   595 to YYYYMMDDHH:MN:SS+HHMN*FLAGS.  In order to maintain compatibility, you

   596 should use UnixDate to extract information from a date, and Date_Cmp to compare

   597 two dates.  The simple string comparison will only work for dates in the same

   598 timezone.

   599 

   600 =item UnixDate

   601 

   602  @date = UnixDate($date,@format);

   603  $date = UnixDate($date,@format);

   604 

   605 This takes a date and a list of strings containing formats roughly

   606 identical to the format strings used by the UNIX date(1) command.  Each

   607 format is parsed and an array of strings corresponding to each format is

   608 returned.

   609 

   610 $date may be any string that can be parsed by ParseDateString.

   611 

   612 The format options are:

   613 

   614  Year

   615      %y     year                     - 00 to 99

   616      %Y     year                     - 0001 to 9999

   617      %G     year                     - 0001 to 9999 (see below)

   618      %L     year                     - 0001 to 9999 (see below)

   619  Month, Week

   620      %m     month of year            - 01 to 12

   621      %f     month of year            - " 1" to "12"

   622      %b,%h  month abbreviation       - Jan to Dec

   623      %B     month name               - January to December

   624      %U     week of year, Sunday

   625             as first day of week     - 01 to 53

   626      %W     week of year, Monday

   627             as first day of week     - 01 to 53

   628  Day

   629      %j     day of the year          - 001 to 366

   630      %d     day of month             - 01 to 31

   631 

   632      %e     day of month             - " 1" to "31"

   633      %v     weekday abbreviation     - " S"," M"," T"," W","Th"," F","Sa"

   634      %a     weekday abbreviation     - Sun to Sat

   635      %A     weekday name             - Sunday to Saturday

   636      %w     day of week              - 1 (Monday) to 7 (Sunday)

   637      %E     day of month with suffix - 1st, 2nd, 3rd...

   638  Hour

   639      %H     hour                     - 00 to 23

   640      %k     hour                     - " 0" to "23"

   641      %i     hour                     - " 1" to "12"

   642      %I     hour                     - 01 to 12

   643      %p     AM or PM

   644  Minute, Second, Timezone

   645      %M     minute                   - 00 to 59

   646      %S     second                   - 00 to 59

   647      %s     seconds from 1/1/1970 GMT- negative if before 1/1/1970

   648      %o     seconds from Jan 1, 1970

   649             in the current time zone

   650      %Z     timezone                 - "EDT"

   651      %z     timezone as GMT offset   - "+0100"

   652  Date, Time

   653      %c     %a %b %e %H:%M:%S %Y     - Fri Apr 28 17:23:15 1995

   654      %C,%u  %a %b %e %H:%M:%S %z %Y  - Fri Apr 28 17:25:57 EDT 1995

   655      %g     %a, %d %b %Y %H:%M:%S %z - Fri, 28 Apr 1995 17:23:15 EDT

   656      %D,%x  %m/%d/%y                 - 04/28/95

   657      %l     date in ls(1) format

   658               %b %e $H:$M            - Apr 28 17:23  (if within 6 months)

   659               %b %e  %Y              - Apr 28  1993  (otherwise)

   660      %r     %I:%M:%S %p              - 05:39:55 PM

   661      %R     %H:%M                    - 17:40

   662      %T,%X  %H:%M:%S                 - 17:40:58

   663      %V     %m%d%H%M%y               - 0428174095

   664      %Q     %Y%m%d                   - 19961025

   665      %q     %Y%m%d%H%M%S             - 19961025174058

   666      %P     %Y%m%d%H%M%S             - 1996102517:40:58

   667      %F     %A, %B %e, %Y            - Sunday, January  1, 1996

   668      %J     %G-W%W-%w                - 1997-W02-2

   669      %K     %Y-%j                    - 1997-045

   670  Other formats

   671      %n     insert a newline character

   672      %t     insert a tab character

   673      %%     insert a `%' character

   674      %+     insert a `+' character

   675  The following formats are currently unused but may be used in the future:

   676      NO 1234567890 !@#$^&*()_|-=\`[];',./~{}:<>?

   677  They currently insert the character following the %, but may (and probably

   678  will) change in the future as new formats are added.

   679 

   680 If a lone percent is the final character in a format, it is ignored.

   681 

   682 Note that the ls format (%l) applies to date within the past OR future 6

   683 months!

   684 

   685 The %U, %W, %L, and %G formats are used to support the ISO-8601 format:

   686 YYYY-wWW-D.  In this format, a date is written as a year, the week of

   687 the year, and the day of the week.  Technically, the week may be considered

   688 to start on any day of the week, but Sunday and Monday are the two most

   689 common choices, so both are supported.

   690 

   691 The %U and %W formats return a week-of-year number from 01 to 53, and

   692 %L and %G return a 4-digit year corresponding to the week.  Most of the

   693 time, the %L and %G formats returns the same value as the %Y format,

   694 but there is a problem with days occuring in the first or last week of

   695 the year.

   696 

   697 The ISO-8601 representation of Jan 1, 1993 written in the YYYY-wWWW-D

   698 format is actually 1992-W53-5.  In other words, Jan 1 is treates as being

   699 in the last week of the preceding year.  Depending on the year, days in

   700 the first week of a year may belong to the previous year, and days in the

   701 final week of a year may belong to the next year.

   702 

   703 The %L and %U formats contains the year and week-of-year values treating

   704 weeks as starting on Sunday.  The %G and %W formats are the year and

   705 week-of-year values treating weeks as starting on Monday.

   706 

   707 %J returns the full ISO-8601 format (%G-W%W-%w).

   708 

   709 The formats used in this routine were originally based on date.pl (version

   710 3.2) by Terry McGonigal, as well as a couple taken from different versions

   711 of the Solaris date(1) command.  Also, several have been added which are

   712 unique to Date::Manip.

   713 

   714 =item ParseDateDelta

   715 

   716  $delta = ParseDateDelta(\@args);

   717  $delta = ParseDateDelta($string);

   718  $delta = ParseDateDelta(\$string);

   719 

   720 This takes an array and shifts a valid delta date (an amount of time)

   721 from the array.  Recognized deltas are of the form:

   722   +Yy +Mm +Ww +Dd +Hh +MNmn +Ss

   723       examples:

   724          +4 hours +3mn -2second

   725          + 4 hr 3 minutes -2

   726          4 hour + 3 min -2 s

   727   +Y:+M:+W:+D:+H:+MN:+S

   728       examples:

   729          0:0:0:0:4:3:-2

   730          +4:3:-2

   731   mixed format

   732       examples:

   733          4 hour 3:-2

   734 

   735 A field in the format +Yy is a sign, a number, and a string specifying

   736 the type of field.  The sign is "+", "-", or absent (defaults to the

   737 next larger element).  The valid strings specifying the field type

   738 are:

   739    y:  y, yr, year, years

   740    m:  m, mon, month, months

   741    w:  w, wk, ws, wks, week, weeks

   742    d:  d, day, days

   743    h:  h, hr, hour, hours

   744    mn: mn, min, minute, minutes

   745    s:  s, sec, second, seconds

   746 

   747 Also, the "s" string may be omitted.  The sign, number, and string may

   748 all be separated from each other by any number of whitespaces.

   749 

   750 In the date, all fields must be given in the order: Y M W D H MN S.  Any

   751 number of them may be omitted provided the rest remain in the correct

   752 order.  In the 2nd (colon) format, from 2 to 7 of the fields may be given.

   753 For example +D:+H:+MN:+S may be given to specify only four of the fields.

   754 In any case, both the MN and S field may be present.  No spaces may be

   755 present in the colon format.

   756 

   757 Deltas may also be given as a combination of the two formats.  For example,

   758 the following is valid: +Yy +D:+H:+MN:+S.  Again, all fields must be given

   759 in the correct order.

   760 

   761 The word "in" may be given (prepended in English) to the delta ("in 5 years")

   762 and the word "ago" may be given (appended in English) ("6 months ago").  The

   763 "in" is completely ignored.  The "ago" has the affect of reversing all signs

   764 that appear in front of the components of the delta.  I.e. "-12 yr 6 mon ago"

   765 is identical to "+12yr +6mon" (don't forget that there is an implied minus

   766 sign in front of the 6 because when no sign is explicitly given, it carries

   767 the previously entered sign).

   768 

   769 One thing is worth noting.  The year/month and day/hour/min/sec parts are

   770 returned in a "normalized" form.  That is, the signs are adjusted so as to

   771 be all positive or all negative.  For example, "+ 2 day - 2hour" does not

   772 return "0:0:0:2:-2:0:0".  It returns "+0:0:0:1:22:0:0" (1 day 22 hours

   773 which is equivalent).  I find (and I think most others agree) that this is

   774 a more useful form.

   775 

   776 Since the year/month and day/hour/min/sec parts must be normalized

   777 separately there is the possibility that the sign of the two parts will be

   778 different.  So, the delta "+ 2years -10 months - 2 days + 2 hours" produces

   779 the delta "+1:2:-0:1:22:0:0".

   780 

   781 It is possible to include a sign for all elements that is output.  See the

   782 configuration variable DeltaSigns below.

   783 

   784 NOTE: The internal format of the delta changed in version 5.30 from

   785 Y:M:D:H:MN:S to Y:M:W:D:H:MN:S .  Also, it is going to change again at some

   786 point in the future to Y:M:W:D:H:MN:S*FLAGS .  Use the routine Delta_Format

   787 to extract information rather than parsing it yourself.

   788 

   789 =item Delta_Format

   790 

   791  @str = Delta_Format($delta,$dec,@format);

   792  $str = Delta_Format($delta,$dec,@format);

   793 

   794 This is similar to the UnixDate routine except that it extracts information

   795 from a delta.  Unlike the UnixDate routine, most of the formats are 2

   796 characters instead of 1.

   797 

   798 Formats currently understood are:

   799 

   800    %Xv     : the value of the field named X

   801    %Xd     : the value of the field X, and all smaller fields, expressed in

   802              units of X

   803    %Xh     : the value of field X, and all larger fields, expressed in units

   804              of X

   805    %Xt     : the value of all fields expressed in units of X

   806 

   807    X is one of y,M,w,d,h,m,s (case sensitive).

   808 

   809    %%      : returns a "%"

   810 

   811 NOTE: Delta_Format only understands "exact" relationships, so for any delta

   812 that has a month component, there can be no mixing of the Y/M and

   813 W/D/H/MN/S segments.  In other words, the delta 1:6:1:1:1:1:1 has a month

   814 component, so asking for the total number of years (using the %yd format)

   815 will return 1.5 (which is what 1 year 6 months is).  For deltas which have

   816 NO month component, the relationship between years and days is known

   817 (365.25 is used) and all formats work as expected (except that formats with

   818 X equal to "M" are not allowed).

   819 

   820 So, the format "%hd" means the values of H, MN, and S expressed in hours.

   821 So for the delta "0:0:0:0:2:30:0", this format returns 2.5.  Similarly, the

   822 format "%yd" means the value (in years) of both the Y and M fields, or,

   823 if the month component is 0, it uses Y, W, D, H, MN, S.

   824 

   825 The format "%hh" returns the value of W, D, and H expressed in hours if

   826 the month component is non-zero, or Y, W, D, H if the month component is 0.

   827 

   828 If $dec is non-zero, the %Xd and %Xt values are formatted to contain $dec

   829 decimal places.

   830 

   831 =item ParseRecur

   832 

   833  $recur = ParseRecur($string [,$base,$date0,$date1,$flags]);

   834  @dates = ParseRecur($string [,$base,$date0,$date1,$flags]);

   835 

   836 A recurrence refers to a recurring event.  A fully specified recurrence

   837 requires (in most cases) 4 items: a recur description (describing the

   838 frequency of the event), a base date (a date when the event occurred and

   839 which other occurrences are based on), and a start and end date.  There may

   840 be one or more flags included which modify the behavior of the recur

   841 description.  The fully specified recurrence is written as:

   842 

   843   recur*flags*base*date0*date1

   844 

   845 Here, base, date0, and date1 are any strings (which must not contain any

   846 asterixes) which can be parsed by ParseDate.  flags is a comma separated

   847 list of flags (described below), and recur is a string describing a

   848 recurring event.

   849 

   850 If called in scalar context, it returns a string containing a fully

   851 specified recurrence (or as much of it as can be determined with

   852 unspecified fields left blank).  In list context, it returns a list of all

   853 dates referred to by a recurrence if enough information is given in the

   854 recurrence.  All dates returned are in the range:

   855 

   856   date0 <= date < date1

   857 

   858 The argument $string can contain any of the parts of a full recurrence.

   859 For example:

   860 

   861   recur

   862   recur*flags

   863   recur**base*date0*date1

   864 

   865 The only part which is required is the recur description.  Any values

   866 contained in $string are overridden or modified by values passed in as

   867 parameters to ParseRecur.

   868 

   869 A recur description is a string of the format Y:M:W:D:H:MN:S .  Exactly one

   870 of the colons may optionally be replaced by an asterisk, or an asterisk may

   871 be prepended to the string.

   872 

   873 Any value "N" to the left of the asterisk refers to the "Nth" one.  Any

   874 value to the right of the asterisk refers to a value as it appears on a

   875 calendar/clock.  Values to the right can be listed a single values, ranges

   876 (2 numbers separated by a dash "-"), or a comma separated list of values

   877 or ranges.  In a few cases, negative values are appropriate.

   878 

   879 This is best illustrated by example.

   880 

   881   0:0:2:1:0:0:0        every 2 weeks and 1 day

   882   0:0:0:0:5:30:0       every 5 hours and 30 minutes

   883   0:0:0:2*12:30:0      every 2 days at 12:30 (each day)

   884   3*1:0:2:12:0:0       every 3 years on Jan 2 at noon

   885   0:1*0:2:12,14:0:0    2nd of every month at 12:00 and 14:00

   886   1:0:0*45:0:0:0       45th day of every year

   887   0:1*4:2:0:0:0        4th tuesday (day 2) of every month

   888   0:1*-1:2:0:0:0       last tuesday of every month

   889   0:1:0*-2:0:0:0       2nd to last day of every month

   890   0:0:3*2:0:0:0        every 3rd tuesday (every 3 weeks on 2nd day of week)

   891   1:0*12:2:0:0:0       tuesday of the 12th week of each year

   892   *1990-1995:12:0:1:0:0:0

   893                        Dec 1 in 1990 through 1995

   894 

   895   0:1*2:0:0:0:0        the start of the 2nd week of every month (see Note 2)

   896   1*1:2:0:0:0:0        the start of the 2nd week in January each year (Note 2)

   897 

   898 I realize that this looks a bit cryptic, but after a discussion on the

   899 CALENDAR mailing list, it looked like there was no concise, flexible

   900 notation for handling recurring events.  ISO 8601 notations were very bulky

   901 and lacked the flexibility I wanted.  As a result, I developed this

   902 notation (based on crontab formats, but with much more flexibility) which

   903 fits in well with this module, and which is able to express every type of

   904 recurring event I could think of.

   905 

   906 NOTE: If a recurrence has a date0 and date1 in it AND a date0 and date1

   907 are passed in to the function, both sets of criteria apply.  If flags are

   908 passed in, they override any flags in the recurrence UNLESS the flags

   909 passed in start with a plus (+) character in which case they are appended

   910 to the flags in the recurrence.

   911 

   912 NOTE: There is no way to express the following with a single recurrence:

   913 

   914   every day at 12:30 and 1:00

   915 

   916 You have to use two recurrences to do this.

   917 

   918 NOTE: A recurrence specifying the week of a month is NOT clearly defined

   919 in common usage.  What is the 1st week in a month?  The behavior (with

   920 respect to this module) is well defined (using the FDn and FIn flags

   921 below), but in common usage, this is so ambiguous that this form should

   922 probably never be used.  It is included here solely for the sake of

   923 completeness.

   924 

   925 NOTE: Depending on whether M and W are 0 or nonzero, D means different

   926 things.  This is given in the following table.

   927 

   928   M  W  D (when right of an asterisk) refers to

   929   -  -  -------------------------------------------

   930   0  0  day of year (1-366)

   931   M  0  day of month (1-31)

   932   0  W  day of week (1-7),  W refers to the week of year

   933   M  W  the Wth (1-5 or -1 to -5) occurrence of Dth (1-7) day of week in month

   934 

   935 NOTE: Base dates are only used with some types of recurrences.  For example,

   936 

   937   0:0:3*2:0:0:0        every 3rd tuesday

   938 

   939 requires a base date.  If a base date is specified which doesn't match the

   940 criteria (for example, if a base date falling on Monday were passed in with

   941 this recurrence), the base date is moved forward to the first relevant date.

   942 

   943 Other dates do not require a base date.  For example:

   944 

   945   0:0*3:2:0:0:0        third tuesday of every month

   946 

   947 A recurrence written in the above format does NOT provide default values

   948 for base, date0, or date1.  They must be specified in order to get a list

   949 of dates.

   950 

   951 A base date is not used entirely.  It is only used to provide the parts

   952 necessary for the left part of a recurrence.  For example, the recurrence:

   953 

   954   1:3*0:4:0:0:0        every 1 year, 3 months on the 4th day of the month

   955 

   956 would only use the year and month of the base date.

   957 

   958 

   959 There are a small handful of English strings which can be parsed in place

   960 of a numerical recur description.  These include:

   961 

   962   every 2nd day [in 1997]

   963   every 2nd day in June [1997]

   964   2nd day of every month [in 1997]

   965   2nd tuesday of every month [in 1997]

   966   last tuesday of every month [in 1997]

   967   every tuesday [in 1997]

   968   every 2nd tuesday [in 1997]

   969   every 2nd tuesday in June [1997]

   970 

   971 Each of these set base, date0, and date1 to a default value (the current

   972 year with Jan 1 being the base date is the default if the year and month

   973 are missing).

   974 

   975 The following flags (case insensitive) are understood:

   976 

   977   MWn   : n is 1-7.  The first week of the month is the week

   978           which contains the first occurrence of day n (1=Monday).

   979           MW2 means that the first week contains the first Tuesday

   980           of the month.

   981   MDn   : n is 1-7.  The first week of the month contains the

   982           actual date (1st through 7th).  MD4 means that the first

   983           week of the month contains the 4th of that month.

   984 

   985   PDn   : n is 1-7.  Means the previous day n not counting today

   986   PTn   : n is 1-7.  Means the previous day n counting today

   987   NDn   : n is 1-7.  Means the next day n not counting today

   988   NTn   : n is 1-7.  Means the next day n counting today

   989 

   990   FDn   : n is any number.  Means step forward n days.

   991   BDn   : n is any number.  Means step backward n days.

   992   FWn   : n is any number.  Means step forward n workdays.

   993   BWn   : n is any number.  Means step backward n workdays.

   994 

   995   CWD   : the closest work day (using the TomorrowFirst config variable).

   996   CWN   : the closest work day (looking forward first).

   997   CWP   : the closest work day (looking backward first).

   998 

   999   NWD   : next work day counting today

  1000   PWD   : previous work day counting today

  1001   DWD   : next/previous work day (TomorrowFirst config) counting today

  1002 

  1003   EASTER: select easter for this year (the M, W, D fields are ignored

  1004           in the recur).

  1005 

  1006 NOTE: only one of MWn and MDn can be set.  If both are set, only the

  1007 last one is used.  The default is MW7 (i.e. the first week contains

  1008 the first Sunday).

  1009 

  1010 CWD, CWN, and CWP will usually return the same value, but if you are

  1011 starting at the middle day of a 3-day weekend (for example), it will return

  1012 either the first work day of the following week, or the last work day of

  1013 the previous week depending on whether it looks forward or backward first.

  1014 

  1015 All flags are applied AFTER the recurrence dates are calculated, and they

  1016 may move a date outside of the date0 to date1 range.  No check is made for

  1017 this.

  1018 

  1019 The workday flags do not act exactly the same as a business mode calculation.

  1020 For example, a date that is Saturday with a FW1 steps forward to the first

  1021 workday (i.e. Monday).

  1022 

  1023 =item Date_Cmp

  1024 

  1025  $flag = Date_Cmp($date1,$date2);

  1026 

  1027 This takes two dates and compares them.  Almost all dates can be compared

  1028 using the perl "cmp" command.  The only time this will not work is when

  1029 comparing dates in different timezones.  This routine will take that into

  1030 account.

  1031 

  1032 NOTE:  This routine currently does little more than use "cmp", but once

  1033 the internal format for storing dates is in place (where timezone information

  1034 is kept as part of the date), this routine will become more important.  You

  1035 should use this routine in prepartation for that version.

  1036 

  1037 =item DateCalc

  1038 

  1039  $d = DateCalc($d1,$d2 [,\$err] [,$mode]);

  1040 

  1041 This takes two dates, deltas, or one of each and performs the appropriate

  1042 calculation with them.  Dates must be a string that can be parsed by

  1043 &ParseDateString.  Deltas must be a string that can be parsed by

  1044 &ParseDateDelta.  Two deltas add together to form a third delta.  A date

  1045 and a delta returns a 2nd date.  Two dates return a delta (the difference

  1046 between the two dates).

  1047 

  1048 Note that in many cases, it is somewhat ambiguous what the delta actually

  1049 refers to.  Although it is ALWAYS known how many months in a year, hours in

  1050 a day, etc., it is NOT known how many days form a month.  As a result, the

  1051 part of the delta containing month/year and the part with sec/min/hr/day

  1052 must be treated separately.  For example, "Mar 31, 12:00:00" plus a delta

  1053 of 1month 2days would yield "May 2 12:00:00".  The year/month is first

  1054 handled while keeping the same date.  Mar 31 plus one month is Apr 31 (but

  1055 since Apr only has 30 days, it becomes Apr 30).  Apr 30 + 2 days is May 2.

  1056 As a result, in the case where two dates are entered, the resulting delta

  1057 can take on two different forms.  By default ($mode=0), an absolutely

  1058 correct delta (ignoring daylight savings time) is returned in days, hours,

  1059 minutes, and seconds.

  1060 

  1061 If $mode is 1, the math is done using an approximate mode where a delta is

  1062 returned using years and months as well.  The year and month part is

  1063 calculated first followed by the rest.  For example, the two dates "Mar 12

  1064 1995" and "Apr 13 1995" would have an exact delta of "31 days" but in the

  1065 approximate mode, it would be returned as "1 month 1 day".  Also, "Mar 31"

  1066 and "Apr 30" would have deltas of "30 days" or "1 month" (since Apr 31

  1067 doesn't exist, it drops down to Apr 30).  Approximate mode is a more human

  1068 way of looking at things (you'd say 1 month and 2 days more often then 33

  1069 days), but it is less meaningful in terms of absolute time.  In approximate

  1070 mode $d1 and $d2 must be dates.  If either or both is a delta, the

  1071 calculation is done in exact mode.

  1072 

  1073 If $mode is 2, a business mode is used.  That is, the calculation is done

  1074 using business days, ignoring holidays, weekends, etc.  In order to

  1075 correctly use this mode, a config file must exist which contains the

  1076 section defining holidays (see documentation on the config file below).

  1077 The config file can also define the work week and the hours of the work

  1078 day, so it is possible to have different config files for different

  1079 businesses.

  1080 

  1081 For example, if a config file defines the workday as 08:00 to 18:00, a

  1082 work week consisting of Mon-Sat, and the standard (American) holidays, then

  1083 from Tuesday at 12:00 to the following Monday at 14:00 is 5 days and 2

  1084 hours.  If the "end" of the day is reached in a calculation, it

  1085 automatically switches to the next day.  So, Tuesday at 12:00 plus 6 hours

  1086 is Wednesday at 08:00 (provided Wed is not a holiday).  Also, a date that

  1087 is not during a workday automatically becomes the start of the next

  1088 workday.  So, Sunday 12:00 and Monday at 03:00 both automatically becomes

  1089 Monday at 08:00 (provided Monday is not a holiday).  In business mode, any

  1090 combination of date and delta may be entered, but a delta should not

  1091 contain a year or month field (weeks are fine though).

  1092 

  1093 See below for some additional comments about business mode calculations.

  1094 

  1095 Note that a business week is treated the same as an exact week (i.e. from

  1096 Tuesday to Tuesday, regardless of holidays).  Because this means that the

  1097 relationship between days and weeks is NOT unambiguous, when a delta is

  1098 produced from two dates, it will be in terms of d/h/mn/s (i.e. no week

  1099 field).

  1100 

  1101 If $mode is 3 (which only applies when two dates are passed in), an exact

  1102 business mode is used.  In this case, it returns a delta as an exact number

  1103 of business days/hours/etc. between the two.  Weeks, months, and years are

  1104 ignored.

  1105 

  1106 Any other non-nil value of $mode is treated as $mode=1 (approximate mode).

  1107 

  1108 The mode can be automatically set in the dates/deltas passed by including a

  1109 key word somewhere in it.  For example, in English, if the word

  1110 "approximately" is found in either of the date/delta arguments, approximate

  1111 mode is forced.  Likewise, if the word "business" or "exactly" appears,

  1112 business/exact mode is forced (and $mode is ignored).  So, the two

  1113 following are equivalent:

  1114 

  1115    $date = DateCalc("today","+ 2 business days",\$err);

  1116    $date = DateCalc("today","+ 2 days",\$err,2);

  1117 

  1118 Note that if the keyword method is used instead of passing in $mode, it is

  1119 important that the keyword actually appear in the argument passed in to

  1120 DateCalc.  The following will NOT work:

  1121 

  1122    $delta = ParseDateDelta("+ 2 business days");

  1123    $today = ParseDate("today");

  1124    $date = DateCalc($today,$delta,\$err);

  1125 

  1126 because the mode keyword is removed from a date/delta by the parse routines,

  1127 and the mode is reset each time a parse routine is called.  Since DateCalc

  1128 parses both of its arguments, whatever mode was previously set is ignored.

  1129 

  1130 If \$err is passed in, it is set to:

  1131    1 is returned if $d1 is not a delta or date

  1132    2 is returned if $d2 is not a delta or date

  1133    3 is returned if the date is outside the years 1000 to 9999

  1134 This argument is optional, but if included, it must come before $mode.