1Date::Manip::DM5(3)   User Contributed Perl Documentation  Date::Manip::DM5(3)
2
3
4

NAME

6       Date::Manip::DM5 - Date manipulation routines
7

SYNOPSIS

9        use Date::Manip;
10
11        $version = DateManipVersion;
12
13        Date_Init();
14        Date_Init("VAR=VAL","VAR=VAL",...);
15        @list = Date_Init();
16        @list = Date_Init("VAR=VAL","VAR=VAL",...);
17
18        $date = ParseDate(\@args);
19        $date = ParseDate($string);
20        $date = ParseDate(\$string);
21
22        @date = UnixDate($date,@format);
23        $date = UnixDate($date,@format);
24
25        $delta = ParseDateDelta(\@args);
26        $delta = ParseDateDelta($string);
27        $delta = ParseDateDelta(\$string);
28
29        @str = Delta_Format($delta,$dec,@format);
30        $str = Delta_Format($delta,$dec,@format);
31
32        $recur = ParseRecur($string,$base,$date0,$date1,$flags);
33        @dates = ParseRecur($string,$base,$date0,$date1,$flags);
34
35        $flag = Date_Cmp($date1,$date2);
36
37        $d = DateCalc($d1,$d2 [,$errref] [,$del]);
38
39        $date = Date_SetTime($date,$hr,$min,$sec);
40        $date = Date_SetTime($date,$time);
41
42        $date = Date_SetDateField($date,$field,$val [,$nocheck]);
43
44        $date = Date_GetPrev($date,$dow,$today,$hr,$min,$sec);
45        $date = Date_GetPrev($date,$dow,$today,$time);
46
47        $date = Date_GetNext($date,$dow,$today,$hr,$min,$sec);
48        $date = Date_GetNext($date,$dow,$today,$time);
49
50        $name = Date_IsHoliday($date);
51
52        $listref = Events_List($date);
53        $listref = Events_List($date0,$date1);
54
55        $date = Date_ConvTZ($date);
56        $date = Date_ConvTZ($date,$from);
57        $date = Date_ConvTZ($date,"",$to);
58        $date = Date_ConvTZ($date,$from,$to);
59
60        $flag = Date_IsWorkDay($date [,$flag]);
61
62        $date = Date_NextWorkDay($date,$off [,$flag]);
63
64        $date = Date_PrevWorkDay($date,$off [,$flag]);
65
66        $date = Date_NearestWorkDay($date [,$tomorrowfirst]);
67
68       The above routines all check to make sure that Date_Init is called.  If
69       it hasn't been, they will call it automatically.  As a result, there is
70       usually no need to call Date_Init explicitly unless you want to change
71       some of the config variables (described below).  They also do error
72       checking on the input.
73
74       The routines listed below are intended primarily for internal use by
75       other Date::Manip routines.  They do little or no error checking, and
76       do not explicitly call Date_Init.  Those functions are all done in the
77       main Date::Manip routines above.
78
79       Because they are significantly faster than the full Date::Manip
80       routines, they are available for use with a few caveats.  Since little
81       or no error checking is done, it is the responsibility of the
82       programmer to ensure that valid data (AND valid dates) are passed to
83       them.  Passing invalid data (such as a non-numeric month) or invalid
84       dates (Feb 31) will fail in unpredictable ways (possibly returning
85       erroneous results).  Also, since Date_Init is not called by these, it
86       must be called explicitly by the programmer before using these
87       routines.
88
89       In the following routines, $y may be entered as either a 2 or 4 digit
90       year (it will be converted to a 4 digit year based on the variable
91       YYtoYYYY described below).  Month and day should be numeric in all
92       cases.  Most (if not all) of the information below can be gotten from
93       UnixDate which is really the way I intended it to be gotten, but there
94       are reasons to use these (these are significantly faster).
95
96        $day = Date_DayOfWeek($m,$d,$y);
97        $secs = Date_SecsSince1970($m,$d,$y,$h,$mn,$s);
98        $secs = Date_SecsSince1970GMT($m,$d,$y,$h,$mn,$s);
99        $days = Date_DaysSince1BC($m,$d,$y);
100        $day = Date_DayOfYear($m,$d,$y);
101        ($y,$m,$d,$h,$mn,$s) = Date_NthDayOfYear($y,$n);
102        $days = Date_DaysInYear($y);
103        $days = Date_DaysInMonth($m,$y);
104        $wkno = Date_WeekOfYear($m,$d,$y,$first);
105        $flag = Date_LeapYear($y);
106        $day = Date_DaySuffix($d);
107        $tz = Date_TimeZone();
108

ROUTINES

110       Date_Init
111            Date_Init();
112            Date_Init("VAR=VAL","VAR=VAL",...);
113            @list = Date_Init();
114            @list = Date_Init("VAR=VAL","VAR=VAL",...);
115
116           Normally, it is not necessary to explicitly call Date_Init.  The
117           first time any of the other routines are called, Date_Init will be
118           called to set everything up.  If for some reason you want to change
119           the configuration of Date::Manip, you can pass the appropriate
120           string or strings into Date_Init to reinitialize things.
121
122           The strings to pass in are of the form "VAR=VAL".  Any number may
123           be included and they can come in any order.  VAR may be any
124           configuration variable.  A list of all configuration variables is
125           given in the section CUSTOMIZING DATE::MANIP below.  VAL is any
126           allowed value for that variable.  For example, to switch from
127           English to French and use non-US format (so that 12/10 is Oct 12),
128           do the following:
129
130             Date_Init("Language=French","DateFormat=non-US");
131
132           If Date_Init is called in list context, it will return a list of
133           all config variables and their values suitable for passing in to
134           Date_Init to return Date::Manip to the current state.  The only
135           possible problem is that by default, holidays will not be erased,
136           so you may need to prepend the "EraseHolidays=1" element to the
137           list.
138
139       ParseDate
140            $date = ParseDate(\@args);
141            $date = ParseDate($string);
142            $date = ParseDate(\$string);
143
144           This takes an array or a string containing a date and parses it.
145           When the date is included as an array (for example, the arguments
146           to a program) the array should contain a valid date in the first
147           one or more elements (elements after a valid date are ignored).
148           Elements containing a valid date are shifted from the array.  The
149           largest possible number of elements which can be correctly
150           interpreted as a valid date are always used.  If a string is
151           entered rather than an array, that string is tested for a valid
152           date.  The string is unmodified, even if passed in by reference.
153
154           The real work is done in the ParseDateString routine.
155
156           The ParseDate routine is primarily used to handle command line
157           arguments.  If you have a command where you want to enter a date as
158           a command line argument, you can use Date::Manip to make something
159           like the following work:
160
161             mycommand -date Dec 10 1997 -arg -arg2
162
163           No more reading man pages to find out what date format is required
164           in a man page.
165
166           Historical note: this is originally why the Date::Manip routines
167           were written (though long before they were released as the
168           Date::Manip module).  I was using a bunch of programs (primarily
169           batch queue managers) where dates and times were entered as command
170           line options and I was getting highly annoyed at the many different
171           (but not compatible) ways that they had to be entered.  Date::Manip
172           originally consisted of basically 1 routine which I could pass
173           "@ARGV" to and have it remove a date from the beginning.
174
175       ParseDateString
176            $date = ParseDateString($string);
177
178           This routine is called by ParseDate, but it may also be called
179           directly to save some time (a negligible amount).
180
181           NOTE:  One of the most frequently asked questions that I have
182           gotten is how to parse seconds since the epoch.  ParseDateString
183           cannot simply parse a number as the seconds since the epoch (it
184           conflicts with some ISO-8601 date formats).  There are two ways to
185           get this information.  First, you can do the following:
186
187               $secs = ...         # seconds since Jan 1, 1970  00:00:00 GMT
188               $date = DateCalc("Jan 1, 1970  00:00:00 GMT","+ $secs");
189
190           Second, you can call it directly as:
191
192               $date = ParseDateString("epoch $secs");
193
194           To go backwards, just use the "%s" format of UnixDate:
195
196               $secs = UnixDate($date,"%s");
197
198           A full date actually includes 2 parts: date and time.  A time must
199           include hours and minutes and can optionally include seconds,
200           fractional seconds, an am/pm type string, and a time zone.  For
201           example:
202
203                [at] HH:MN              [Zone]
204                [at] HH:MN         [am] [Zone]
205                [at] HH:MN:SS      [am] [Zone]
206                [at] HH:MN:SS.SSSS [am] [Zone]
207                [at] HH            am   [Zone]
208
209           Hours can be written using 1 or 2 digits, but the single digit form
210           may only be used when no ambiguity is introduced (i.e. when it is
211           not immediately preceded by a digit).
212
213           A time is usually entered in 24 hour mode, but 12 hour mode can be
214           used as well if AM/PM are entered (AM can be entered as AM or A.M.
215           or other variations depending on the language).
216
217           Fractional seconds are also supported in parsing but the fractional
218           part is discarded (with NO rounding occurring).
219
220           Time zones always appear immediately after the time.  A number of
221           different forms are supported (see the section TIME ZONES below).
222
223           Incidentally, the time is removed from the date before the date is
224           parsed, so the time may appear before or after the date, or between
225           any two parts of the date.
226
227           Valid date formats include the ISO 8601 formats:
228
229              YYYYMMDDHHMNSSF...
230              YYYYMMDDHHMNSS
231              YYYYMMDDHHMN
232              YYYYMMDDHH
233              YY-MMDDHHMNSSF...
234              YY-MMDDHHMNSS
235              YY-MMDDHHMN
236              YY-MMDDHH
237              YYYYMMDD
238              YYYYMM
239              YYYY
240              YY-MMDD
241              YY-MM
242              YY
243              YYYYwWWD      ex.  1965-W02-2
244              YYwWWD
245              YYYYDOY       ex.  1965-045
246              YYDOY
247
248           In the above list, YYYY and YY signify 4 or 2 digit years, MM, DD,
249           HH, MN, SS refer to two digit month, day, hour, minute, and second
250           respectively.  F...  refers to fractional seconds (any number of
251           digits) which will be ignored.  In all cases, the date and time
252           parts may be separated by the letter "T" (but this is optional), so
253              2002-12-10-12:00:00
254              2002-12-10T12:00:00 are identical.
255
256           The last 4 formats can be explained by example:  1965-w02-2 refers
257           to Tuesday (day 2) of the 2nd week of 1965.  1965-045 refers to the
258           45th day of 1965.
259
260           In all cases, parts of the date may be separated by dashes "-".  If
261           this is done, 1 or 2 digit forms of MM, DD, etc. may be used.  All
262           dashes are optional except for those given in the table above
263           (which MUST be included for that format to be correctly parsed).
264           So 19980820, 1998-0820, 1998-08-20, 1998-8-20, and 199808-20 are
265           all equivalent, but that date may NOT be written as 980820 (it must
266           be written as 98-0820).
267
268           NOTE:  Even though not allowed in the standard, the time zone for
269           an ISO-8601 date is flexible and may be any of the time zones
270           understood by Date::Manip.
271
272           Additional date formats are available which may or may not be
273           common including:
274
275             MM/DD  **
276             MM/DD/YY  **
277             MM/DD/YYYY  **
278
279             mmmDD       DDmmm                   mmmYYYY/DD     mmmYYYY
280             mmmDD/YY    DDmmmYY     DD/YYmmm    YYYYmmmDD      YYYYmmm
281             mmmDDYYYY   DDmmmYYYY   DDYYYYmmm   YYYY/DDmmm
282
283           Where mmm refers to the name of a month.  All parts of the date can
284           be separated by valid separators (space, "/", or ".").  The
285           separator "-" may be used as long as it doesn't conflict with an
286           ISO 8601 format, but this is discouraged since it is easy to
287           overlook conflicts.  For example, the format MM/DD/YY is just fine,
288           but MM-DD-YY does not work since it conflicts with YY-MM-DD.  To be
289           safe, if "-" is used as a separator in a non-ISO format, they
290           should be turned into "/" before calling the Date::Manip routines.
291           As with ISO 8601 formats, all separators are optional except for
292           those given as a "/" in the list above.
293
294           ** Note that with these formats, Americans tend to write month
295           first, but many other countries tend to write day first.  The
296           latter behavior can be obtained by setting the config variable
297           DateFormat to something other than "US" (see CUSTOMIZING
298           DATE::MANIP below).
299
300           Date separators are treated very flexibly (they are converted to
301           spaces), so the following dates are all equivalent:
302
303              12/10/1965
304              12-10 / 1965
305              12 // 10 -. 1965
306
307           In some cases, this may actually be TOO flexible, but no attempt is
308           made to trap this.
309
310           Years can be entered as 2 or 4 digits, days and months as 1 or 2
311           digits.  Both days and months must include 2 digits whenever they
312           are immediately adjacent to another numeric part of the date or
313           time.  Date separators are required if single digit forms of DD or
314           MM are used.  If separators are not used, the date will either be
315           unparsable or will get parsed incorrectly.
316
317           Miscellaneous other allowed formats are:
318             which dofw in mmm in YY      "first Sunday in June
319                                          1996 at 14:00" **
320             dofw week num YY             "Sunday week 22 1995" **
321             which dofw YY                "22nd Sunday at noon" **
322             dofw which week YY           "Sunday 22nd week in
323                                          1996" **
324             next/last dofw               "next Friday at noon"
325             next/last week/month         "next month"
326             in num days/weeks/months     "in 3 weeks at 12:00"
327             num days/weeks/months later  "3 weeks later"
328             num days/weeks/months ago    "3 weeks ago"
329             dofw in num week             "Friday in 2 weeks"
330             in num weeks dofw            "in 2 weeks on Friday"
331             dofw num week ago            "Friday 2 weeks ago"
332             num week ago dofw            "2 weeks ago Friday"
333             last day in mmm in YY        "last day of October"
334             dofw                         "Friday" (Friday of
335                                          current week)
336             Nth                          "12th", "1st" (day of
337                                          current month)
338             epoch SECS                   seconds since the epoch
339                                          (negative values are
340                                          supported)
341
342           ** Note that the formats "Sunday week 22" and "22nd Sunday" give
343           very different behaviors.  "Sunday week 22" returns the Sunday of
344           the 22nd week of the year based on how week 1 is defined.  ISO 8601
345           defines week one to contain Jan 4, so "Sunday week 1" might be the
346           first or second Sunday of the current year, or the last Sunday of
347           the previous year.  "22nd Sunday" gives the actual 22nd time Sunday
348           occurs in a given year, regardless of the definition of a week.
349
350           Note that certain words such as "in", "at", "of", etc. which
351           commonly appear in a date or time are ignored.  Also, the year is
352           always optional.
353
354           In addition, the following strings are recognized:
355             today     (exactly now OR today at a given time if a time is
356           specified)
357             now       (synonym for today)
358             yesterday (exactly 24 hours ago unless a time is specified)
359             tomorrow  (exactly 24 hours from now unless a time is specified)
360             noon      (12:00:00)
361             midnight  (00:00:00) Other languages have similar (and in some
362           cases additional) strings.
363
364           Some things to note:
365
366           All strings are case insensitive.  "December" and "DEceMBer" both
367           work.
368
369           When a part of the date is not given, defaults are used: year
370           defaults to current year; hours, minutes, seconds to 00.
371
372           The year may be entered as 2 or 4 digits.  If entered as 2 digits,
373           it will be converted to a 4 digit year.  There are several ways to
374           do this based on the value of the YYtoYYYY variable (described
375           below).  The default behavior it to force the 2 digit year to be in
376           the 100 year period CurrYear-89 to CurrYear+10.  So in 1996, the
377           range is [1907 to 2006], and the 2 digit year 05 would refer to
378           2005 but 07 would refer to 1907.  See CUSTOMIZING DATE::MANIP below
379           for information on YYtoYYYY for other methods.
380
381           Dates are always checked to make sure they are valid.
382
383           In all of the formats, the day of week ("Friday") can be entered
384           anywhere in the date and it will be checked for accuracy.  In other
385           words,
386             "Tue Jul 16 1996 13:17:00" will work but
387             "Jul 16 1996 Wednesday 13:17:00" will not (because Jul 16, 1996
388           is Tuesday, not Wednesday).  Note that depending on where the
389           weekday comes, it may give unexpected results when used in array
390           context (with ParseDate).  For example, the date
391           ("Jun","25","Sun","1990") would return June 25 of the current year
392           since Jun 25, 1990 is not Sunday.
393
394           The times "12:00 am", "12:00 pm", and "midnight" are not well
395           defined.  For good or bad, I use the following convention in
396           Date::Manip:
397             midnight = 12:00am = 00:00:00
398             noon     = 12:00pm = 12:00:00 and the day goes from 00:00:00 to
399           23:59:59.  In other words, midnight is the beginning of a day
400           rather than the end of one.  The time 24:00:00 is also allowed
401           (though it is automatically transformed to 00:00:00 of the
402           following day).
403
404           The format of the date returned is YYYYMMDDHH:MM:SS.  The advantage
405           of this time format is that two times can be compared using simple
406           string comparisons to find out which is later.  Also, it is readily
407           understood by a human.  Alternate forms can be used if that is more
408           convenient.  See Date_Init below and the config variable Internal.
409
410           NOTE: The format for the date is going to change at some point in
411           the future to YYYYMMDDHH:MN:SS+HHMN*FLAGS.  In order to maintain
412           compatibility, you should use UnixDate to extract information from
413           a date, and Date_Cmp to compare two dates.  The simple string
414           comparison will only work for dates in the same time zone.
415
416       UnixDate
417            @date = UnixDate($date,@format);
418            $date = UnixDate($date,@format);
419
420           This takes a date and a list of strings containing formats roughly
421           identical to the format strings used by the UNIX date(1) command.
422           Each format is parsed and an array of strings corresponding to each
423           format is returned.
424
425           $date may be any string that can be parsed by ParseDateString.
426
427           The format options are:
428
429            Year
430                %y     year                     - 00 to 99
431                %Y     year                     - 0001 to 9999
432            Month, Week
433                %m     month of year            - 01 to 12
434                %f     month of year            - " 1" to "12"
435                %b,%h  month abbreviation       - Jan to Dec
436                %B     month name               - January to December
437            Day
438                %j     day of the year          - 001 to 366
439                %d     day of month             - 01 to 31
440
441                %e     day of month             - " 1" to "31"
442                %v     weekday abbreviation     - " S"," M"," T"," W","Th"," F","Sa"
443                %a     weekday abbreviation     - Sun to Sat
444                %A     weekday name             - Sunday to Saturday
445                %w     day of week              - 1 (Monday) to 7 (Sunday)
446                %E     day of month with suffix - 1st, 2nd, 3rd...
447            Hour
448                %H     hour                     - 00 to 23
449                %k     hour                     - " 0" to "23"
450                %i     hour                     - " 1" to "12"
451                %I     hour                     - 01 to 12
452                %p     AM or PM
453            Minute, Second, Time zone
454                %M     minute                   - 00 to 59
455                %S     second                   - 00 to 59
456                %Z     time zone                - "EDT"
457                %z     time zone as GMT offset  - "+0100"
458            Epoch (see NOTE 3 below)
459                %s     seconds from 1/1/1970 GMT- negative if before 1/1/1970
460                %o     seconds from Jan 1, 1970
461                       in the current time zone
462            Date, Time
463                %c     %a %b %e %H:%M:%S %Y     - Fri Apr 28 17:23:15 1995
464                %C,%u  %a %b %e %H:%M:%S %z %Y  - Fri Apr 28 17:25:57 EDT 1995
465                %g     %a, %d %b %Y %H:%M:%S %z - Fri, 28 Apr 1995 17:23:15 EDT
466                %D     %m/%d/%y                 - 04/28/95
467                %x     %m/%d/%y or %d/%m/%y     - 04/28/95 or 28/04/28
468                                                  (Depends on DateFormat variable)
469                %l     date in ls(1) format (see NOTE 1 below)
470                         %b %e $H:$M            - Apr 28 17:23  (if within 6 months)
471                         %b %e  %Y              - Apr 28  1993  (otherwise)
472                %r     %I:%M:%S %p              - 05:39:55 PM
473                %R     %H:%M                    - 17:40
474                %T,%X  %H:%M:%S                 - 17:40:58
475                %V     %m%d%H%M%y               - 0428174095
476                %Q     %Y%m%d                   - 19961025
477                %q     %Y%m%d%H%M%S             - 19961025174058
478                %P     %Y%m%d%H%M%S             - 1996102517:40:58
479                %O     %Y-%m-%dT%H:%M:%S        - 1996-10-25T17:40:58
480                %F     %A, %B %e, %Y            - Sunday, January  1, 1996
481                %K     %Y-%j                    - 1997-045
482            Special Year/Week formats (see NOTE 2 below)
483                %G     year, Monday as first
484                       day of week              - 0001 to 9999
485                %W     week of year, Monday
486                       as first day of week     - 01 to 53
487                %L     year, Sunday as first
488                       day of week              - 0001 to 9999
489                %U     week of year, Sunday
490                       as first day of week     - 01 to 53
491                %J     %G-W%W-%w                - 1997-W02-2
492            Other formats
493                %n     insert a newline character
494                %t     insert a tab character
495                %%     insert a `%' character
496                %+     insert a `+' character
497            The following formats are currently unused but may be used in the future:
498                N 1234567890 !@#$^&*()_|-=\`[];',./~{}:<>?
499            They currently insert the character following the %, but may (and probably
500            will) change in the future as new formats are added.
501
502           If a lone percent is the final character in a format, it is
503           ignored.
504
505           The formats used in this routine were originally based on date.pl
506           (version 3.2) by Terry McGonigal, as well as a couple taken from
507           different versions of the Solaris date(1) command.  Also, several
508           have been added which are unique to Date::Manip.
509
510           NOTE 1:
511
512           The ls format (%l) applies to date within the past OR future 6
513           months!
514
515           NOTE 2:
516
517           The %U, %W, %L, %G, and %J formats are used to support the ISO-8601
518           format: YYYY-wWW-D.  In this format, a date is written as a year,
519           the week of the year, and the day of the week.  Technically, the
520           week may be considered to start on any day of the week, but Sunday
521           and Monday are the both common choices, so both are supported.
522
523           The %W and %G formats return the week-of-year and the year treating
524           weeks as starting on Monday.
525
526           The %U and %L formats return the week-of-year and the year treating
527           weeks as starting on Sunday.
528
529           Most of the time, the %L and %G formats returns the same value as
530           the %Y format, but there is a problem with days occurring in the
531           first or last week of the year.
532
533           The ISO-8601 representation of Jan 1, 1993 written in the YYYY-wWW-
534           D format is actually 1992-W53-5.  In other words, Jan 1 is treated
535           as being in the last week of the preceding year.  Depending on the
536           year, days in the first week of a year may belong to the previous
537           year, and days in the final week of a year may belong to the next
538           year.  The week is assigned to the year which has most of the days.
539           For example, if the week starts on Sunday, then the last week of
540           2003 is 2003-12-28 to 2004-01-03.  This week is assigned to 2003
541           since 4 of the days in it are in 2003 and only 3 of them are in
542           2004.  The first week of 2004 starts on 2004-01-04.
543
544           The %U and %W formats return a week-of-year number from 01 to 53.
545           %L and %G return the corresponding year, and to get this type of
546           information, you should always use the (%W,%G) combination or
547           (%U,%L) combination. %Y should not be used as it will yield
548           incorrect results.
549
550           %J returns the full ISO-8601 format (%G-W%W-%w).
551
552           NOTE 3:
553
554           The %s and %o formats return negative values if the date is before
555           the start of the epoch.  Other Unix utilities would return an
556           error, or a zero, so if you are going to use Date::Manip in
557           conjunction with these, be sure to check for a negative value.
558
559       ParseDateDelta
560            $delta = ParseDateDelta(\@args);
561            $delta = ParseDateDelta($string);
562            $delta = ParseDateDelta(\$string);
563
564           This takes an array and shifts a valid delta date (an amount of
565           time) from the array.  Recognized deltas are of the form:
566             +Yy +Mm +Ww +Dd +Hh +MNmn +Ss
567                 examples:
568                    +4 hours +3mn -2second
569                    + 4 hr 3 minutes -2
570                    4 hour + 3 min -2 s
571             +Y:+M:+W:+D:+H:+MN:+S
572                 examples:
573                    0:0:0:0:4:3:-2
574                    +4:3:-2
575             mixed format
576                 examples:
577                    4 hour 3:-2
578
579           A field in the format +Yy is a sign, a number, and a string
580           specifying the type of field.  The sign is "+", "-", or absent
581           (defaults to the next larger element).  The valid strings
582           specifying the field type are:
583              y:  y, yr, year, years
584              m:  m, mon, month, months
585              w:  w, wk, ws, wks, week, weeks
586              d:  d, day, days
587              h:  h, hr, hour, hours
588              mn: mn, min, minute, minutes
589              s:  s, sec, second, seconds
590
591           Also, the "s" string may be omitted.  The sign, number, and string
592           may all be separated from each other by any number of whitespace.
593
594           In the date, all fields must be given in the order: Y M W D H MN S.
595           Any number of them may be omitted provided the rest remain in the
596           correct order.  In the 2nd (colon) format, from 2 to 7 of the
597           fields may be given.  For example +D:+H:+MN:+S may be given to
598           specify only four of the fields.  In any case, both the MN and S
599           field may be present.  No spaces may be present in the colon
600           format.
601
602           Deltas may also be given as a combination of the two formats.  For
603           example, the following is valid: +Yy +D:+H:+MN:+S.  Again, all
604           fields must be given in the correct order.
605
606           The word "in" may be given (prepended in English) to the delta ("in
607           5 years") and the word "ago" may be given (appended in English) ("6
608           months ago").  The "in" is completely ignored.  The "ago" has the
609           affect of reversing all signs that appear in front of the
610           components of the delta.  I.e. "-12 yr 6 mon ago" is identical to
611           "+12yr +6mon" (don't forget that there is an implied minus sign in
612           front of the 6 because when no sign is explicitly given, it carries
613           the previously entered sign).
614
615           One thing is worth noting.  The year/month and day/hour/min/sec
616           parts are returned in a "normalized" form.  That is, the signs are
617           adjusted so as to be all positive or all negative.  For example, "+
618           2 day - 2hour" does not return "0:0:0:2:-2:0:0".  It returns
619           "+0:0:0:1:22:0:0" (1 day 22 hours which is equivalent).  I find
620           (and I think most others agree) that this is a more useful form.
621
622           Since the year/month and day/hour/min/sec parts must be normalized
623           separately there is the possibility that the sign of the two parts
624           will be different.  So, the delta "+ 2years -10 months - 2 days + 2
625           hours" produces the delta "+1:2:-0:1:22:0:0".
626
627           It is possible to include a sign for all elements that is output.
628           See the configuration variable DeltaSigns below.
629
630           NOTE: The internal format of the delta changed in version 5.30 from
631           Y:M:D:H:MN:S to Y:M:W:D:H:MN:S .  Also, it is going to change again
632           at some point in the future to Y:M:W:D:H:MN:S*FLAGS .  Use the
633           routine Delta_Format to extract information rather than parsing it
634           yourself.
635
636       Delta_Format
637            @str = Delta_Format($delta [,$mode], $dec,@format);
638            $str = Delta_Format($delta [,$mode], $dec,@format);
639
640           This is similar to the UnixDate routine except that it extracts
641           information from a delta.  Unlike the UnixDate routine, most of the
642           formats are 2 characters instead of 1.
643
644           Formats currently understood are:
645
646              %Xv     : the value of the field named X
647              %Xd     : the value of the field X, and all smaller fields, expressed in
648                        units of X
649              %Xh     : the value of field X, and all larger fields, expressed in units
650                        of X
651              %Xt     : the value of all fields expressed in units of X
652
653              X is one of y,M,w,d,h,m,s (case sensitive).
654
655              %%      : returns a "%"
656
657           So, the format "%hd" means the values of H, MN, and S expressed in
658           hours.  So for the delta "0:0:0:0:2:30:0", this format returns 2.5.
659
660           Delta_Format can operate in two modes: exact and approximate. The
661           exact mode is done by default. Approximate mode can be done by
662           passing in the string "approx" as the 2nd argument.
663
664           In exact mode, Delta_Format only understands "exact" relationships.
665           This means that there can be no mixing of the Y/M and W/D/H/MN/S
666           segments because the relationship because, depending on when the
667           delta occurs, there is no exact relation between the number of
668           years or months and the number of days.
669
670           The two sections are treated completely separate from each other.
671           So, the delta "1:6:1:2:12:0:0" would return the following values:
672
673             %yt = 1.5 (1 year, 6 months)
674             %Mt = 18
675
676             %dt = 9.5 (1 week, 2 days, 12 hours)
677
678           In approximate mode, the relationship of 1 year = 365.25 days is
679           applied (with 1 month equal to 1/12 of a year exactly). So the
680           delta "1:6:1:2:12:0:0" would return the following values:
681
682             %dt = 557.375 (1.5 years of 365.25 days + 9.5 days)
683
684           If $dec is non-zero, the %Xd and %Xt values are formatted to
685           contain $dec decimal places.
686
687       ParseRecur
688            $recur = ParseRecur($string [,$base,$date0,$date1,$flags]);
689            @dates = ParseRecur($string [,$base,$date0,$date1,$flags]);
690
691           A recurrence refers to a recurring event, and more specifically, an
692           event which occurs on a regular basis.  A fully specified recurring
693           event may requires up to four pieces of information.
694
695           First, it requires a description of the frequency of the event.
696           Examples include "the first of every month", "every other day",
697           "the 4th Thursday of each month at 2:00 PM", and "every 2 hours and
698           30 minutes".
699
700           Second, it may require a base date to work from.  This piece of
701           information is not required for every type of recurrence.  For
702           example, if the frequency is "the first of every month", no base
703           date is required.  All the information about when the event occurs
704           is included in the frequency description.  If the frequency were
705           "every other day" though, you need to know at least one day on
706           which the event occurred.
707
708           Third, the recurring event may have a range (a starting and ending
709           date).
710
711           Fourth, there may be some flags included which modify the behavior
712           of the above information.
713
714           The fully specified recurrence is written as these 5 pieces of
715           information (both a start and end date) as an asterisk separated
716           list:
717
718             freq*flags*base*date0*date1
719
720           Here, base, date0, and date1 are any strings (which must not
721           contain any asterisks) which can be parsed by ParseDate.  flags is
722           a comma separated list of flags (described below), and freq is a
723           string describing the frequency of the recurring event.
724
725           The syntax of the frequency description is a colon separated list
726           of the format Y:M:W:D:H:MN:S (which stand for year, month, week,
727           etc.).  One (and only one) of the colons may optionally be replaced
728           by an asterisk, or an asterisk may be prepended to the string.  For
729           example, the following are all valid frequency descriptions:
730
731             1:2:3:4:5:6:7
732             1:2*3:4:5:6:7
733            *1:2:3:4:5:6:7
734
735           But the following are NOT valid because they contain 2 or more
736           asterisks:
737
738             1:2*3:4:5*6:7
739             1*2*3:4:5*6:7
740            *1:2:3:4:5:6*7
741
742           If an asterisk is included, values to the left of it refer to the
743           number of times that time interval occurs between recurring events.
744           For example, if the first part of the recurrence is:
745
746             1:2*
747
748           this says that the recurring event occurs approximately every 1
749           year and 2 months.  I say approximately, because elements to the
750           right of the asterisk, as well as any flags included in the
751           recurrence will affect when the actual events occur.
752
753           If no asterisks are included, then the entire recurrence is of this
754           form.  For example,
755
756             0:0:0:1:12:0:0
757
758           refers to an event that occurs every 1 day, 12 hours.
759
760           Values that occur after an asterisk refer to a specific value for
761           that type of time element (i.e. exactly as it would appear on a
762           calendar or a clock).  For example, if the recurrence ends with:
763
764             *12:0:0
765
766           then the recurring event occurs at 12:00:00 (noon).
767
768           For example:
769
770             0:0:2:1:0:0:0        every 2 weeks and 1 day
771             0:0:0:0:5:30:0       every 5 hours and 30 minutes
772             0:0:0:2*12:30:0      every 2 days at 12:30 (each day)
773
774           Values to the right of the asterisk can be listed a single values,
775           ranges (2 numbers separated by a dash "-"), or a comma separated
776           list of values or ranges.  In most cases, negative values are
777           appropriate for the week or day values. -1 stands for the last
778           possible value, -2 for the second to the last, etc.
779
780           Some examples are:
781
782             0:0:0:1*2,4,6:0:0    every day at at 2:00, 4:00, and 6:00
783             0:0:0:2*12-13:0,30:0 every other day at 12:00, 12:30, 13:00,
784                                  and 13:30
785             0:1:0*-1:0:0:0       the last day of every month
786             *1990-1995:12:0:1:0:0:0
787                                  Dec 1 in 1990 through 1995
788
789           There is no way to express the following with a single recurrence:
790
791             every day at 12:30 and 1:00
792
793           You have to use two recurrences to do this.
794
795           When a non-zero day element occurs to the right of the asterisk, it
796           can take on multiple meanings, depending on the value of the month
797           and week elements.  It can refer to the day of the week, day of the
798           month, or day of the year.  Similarly, if a non-zero week element
799           occurs to the right of the asterisk, it actually refers to the nth
800           time a certain day of the week occurs, either in the month or in
801           the year.
802
803           If the week element is non-zero and the day element is non-zero
804           (and to the right of the asterisk), the day element refers to the
805           day of the week. It can be any value from 1 to 7 (negative values
806           -1 to -7 are also allowed). If you use the ISO 8601 convention, the
807           first day of the week is Monday (though Date::Manip can use any day
808           as the start of the week by setting the FirstDay config variable).
809           So, assuming that you are using the ISO 8601 convention, the
810           following examples illustrate day-of-week recurrences:
811
812             0:1*4:2:0:0:0        4th Tuesday (day 2) of every month
813             0:1*-1:2:0:0:0       last Tuesday of every month
814             0:0:3*2:0:0:0        every 3rd Tuesday (every 3 weeks
815                                  on 2nd day of week)
816             1:0*12:2:0:0:0       the 12th Tuesday of each year
817
818           If the week element is non-zero, and the day element is zero, the
819           day defaults to 1 (i.e. the first day of the week).
820
821             0:1*2:0:0:0:0        the 2nd occurrence of FirstDay
822                                  in the year (typically Monday)
823             0:1*2:1:0:0:0        the same
824
825           If the week element is zero and the month element is non-zero, the
826           day value is the day of the month (it can be from 1 to 31 or -1 to
827           -31 counting from the end of the month). If a value of 0 is given,
828           it defaults to 1.
829
830             3*1:0:2:12:0:0       every 3 years on Jan 2 at noon
831             0:1*0:2:12,14:0:0    2nd of every month at 12:00 and 14:00
832             0:1:0*-2:0:0:0       2nd to last day of every month
833
834           If the day given refers to the 29th, 30th, or 31st, in a month that
835           does not have that number of days, it is ignored. For example, if
836           you ask for the 31st of every month, it will return dates in Jan,
837           Mar, May, Jul, etc.  Months with fewer than 31 days will be
838           ignored.
839
840           If both the month and week elements are zero, and the year element
841           is non-zero, the day value is the day of the year (1 to 365 or 366
842           -- or the negative numbers to count backwards from the end of the
843           year).
844
845             1:0:0*45:0:0:0       45th day of every year
846
847           Specifying a day that doesn't occur in that year silently ignores
848           that year. The only result of this is that specifying +366 or -366
849           will ignore all years except leap years.
850
851           I realize that this looks a bit cryptic, but after a discussion on
852           the CALENDAR mailing list, it appeared like there was no concise,
853           flexible notation for handling recurring events.  ISO 8601
854           notations were very bulky and lacked the flexibility I wanted.  As
855           a result, I developed this notation (based on crontab formats, but
856           with much more flexibility) which fits in well with this module.
857           Even better, it is able to express every type of recurring event I
858           could think of that is used in common life in (what I believe to
859           be) a very concise and elegant way.
860
861           If ParseRecur is called in scalar context, it returns a string
862           containing a fully specified recurrence (or as much of it as can be
863           determined with unspecified fields left blank).  In list context,
864           it returns a list of all dates referred to by a recurrence if
865           enough information is given in the recurrence.  All dates returned
866           are in the range:
867
868             date0 <= date < date1
869
870           The argument $string can contain any of the parts of a full
871           recurrence.  For example:
872
873             freq
874             freq*flags
875             freq**base*date0*date1
876
877           The only part which is required is the frequency description.  Any
878           values contained in $string are overridden or modified by values
879           passed in as parameters to ParseRecur.
880
881           NOTE: If a recurrence has a date0 and date1 in it AND a date0 and
882           date1 are passed in to the function, both sets of criteria apply.
883           If flags are passed in, they override any flags in the recurrence
884           UNLESS the flags passed in start with a plus (+) character in which
885           case they are appended to the flags in the recurrence.
886
887           NOTE: Base dates are only used with some types of recurrences.  For
888           example,
889
890             0:0:3*2:0:0:0        every 3rd Tuesday
891
892           requires a base date.  If a base date is specified which doesn't
893           match the criteria (for example, if a base date falling on Monday
894           were passed in with this recurrence), the base date is moved
895           forward to the first relevant date.
896
897           Other dates do not require a base date.  For example:
898
899             0:0*3:2:0:0:0        third Tuesday of every month
900
901           A recurrence written in the above format does NOT provide default
902           values for base, date0, or date1.  They must be specified in order
903           to get a list of dates.
904
905           A base date is not used entirely.  It is only used to provide the
906           parts necessary for the left part of a recurrence.  For example,
907           the recurrence:
908
909             1:3*0:4:0:0:0        every 1 year, 3 months on the 4th day of the month
910
911           would only use the year and month of the base date.
912
913           There are a small handful of English strings which can be parsed in
914           place of a numerical recur description.  These include:
915
916             every 2nd day [in 1997]
917             every 2nd day in June [1997]
918             2nd day of every month [in 1997]
919             2nd Tuesday of every month [in 1997]
920             last Tuesday of every month [in 1997]
921             every Tuesday [in 1997]
922             every 2nd Tuesday [in 1997]
923             every 2nd Tuesday in June [1997]
924
925           Each of these set base, date0, and date1 to a default value (the
926           current year with Jan 1 being the base date is the default if the
927           year and month are missing).
928
929           The following flags (case insensitive) are understood:
930
931             PDn   : n is 1-7.  Means the previous day n not counting today
932             PTn   : n is 1-7.  Means the previous day n counting today
933             NDn   : n is 1-7.  Means the next day n not counting today
934             NTn   : n is 1-7.  Means the next day n counting today
935
936             FDn   : n is any number.  Means step forward n days.
937             BDn   : n is any number.  Means step backward n days.
938             FWn   : n is any number.  Means step forward n workdays.
939             BWn   : n is any number.  Means step backward n workdays.
940
941             CWD   : the closest work day (using the TomorrowFirst config variable).
942             CWN   : the closest work day (looking forward first).
943             CWP   : the closest work day (looking backward first).
944
945             NWD   : next work day counting today
946             PWD   : previous work day counting today
947             DWD   : next/previous work day (TomorrowFirst config) counting today
948
949             EASTER: select easter for this year (the M, W, D fields are ignored
950                     in the recur).
951
952           CWD, CWN, and CWP will usually return the same value, but if you
953           are starting at the middle day of a 3-day weekend (for example), it
954           will return either the first work day of the following week, or the
955           last work day of the previous week depending on whether it looks
956           forward or backward first.
957
958           All flags are applied AFTER the recurrence dates are calculated,
959           and they may move a date outside of the date0 to date1 range.  No
960           check is made for this.
961
962           The workday flags do not act exactly the same as a business mode
963           calculation.  For example, a date that is Saturday with a FW1 steps
964           forward to the first workday (i.e. Monday).
965
966       Date_Cmp
967            $flag = Date_Cmp($date1,$date2);
968
969           This takes two dates and compares them.  Almost all dates can be
970           compared using the Perl "cmp" command.  The only time this will not
971           work is when comparing dates in different time zones.  This routine
972           will take that into account.
973
974           NOTE:  This routine currently does little more than use "cmp", but
975           once the internal format for storing dates is in place (where time
976           zone information is kept as part of the date), this routine will
977           become more important.  You should use this routine in preparation
978           for that version.
979
980       DateCalc
981            $d = DateCalc($d1,$d2 [,\$err] [,$mode]);
982
983           This takes two dates, deltas, or one of each and performs the
984           appropriate calculation with them.  Dates must be a string that can
985           be parsed by ParseDateString.  Deltas must be a string that can be
986           parsed by ParseDateDelta.  Two deltas add together to form a third
987           delta.  A date and a delta returns a 2nd date.  Two dates return a
988           delta (the difference between the two dates).
989
990           Since the two items can be interpreted as either dates or deltas,
991           and since many types of dates can be interpreted as deltas (and
992           vice versa), it is a good idea to pass the input through ParseDate
993           or ParseDateDelta as appropriate. For example, the string
994           "09:00:00" can be interpreted either as a date (today at 9:00:00)
995           or a delta (9 hours). To avoid unexpected results, avoid calling
996           DateCalc as:
997
998             $d = DateCalc("09:00:00",$someothervalue);
999
1000           Instead, call it as:
1001
1002             $d = DateCalc(ParseDate("09:00:00"),$someothervalue);
1003
1004           to force it to be a date, or:
1005
1006             $d = DateCalc(ParseDateDelta("09:00:00"),$someothervalue);
1007
1008           to force it to be a delta. This will avoid unexpected results.
1009
1010           Note that in many cases, it is somewhat ambiguous what the delta
1011           actually refers to.  Although it is ALWAYS known how many months in
1012           a year, hours in a day, etc., it is NOT known (in the generals
1013           case) how many days are in a month.  As a result, the part of the
1014           delta containing month/year and the part with sec/min/hr/day must
1015           be treated separately.  For example, "Mar 31, 12:00:00" plus a
1016           delta of 1month 2days would yield "May 2 12:00:00".  The year/month
1017           is first handled while keeping the same date.  Mar 31 plus one
1018           month is Apr 31 (but since Apr only has 30 days, it becomes Apr
1019           30).  Apr 30 + 2 days is May 2.  As a result, in the case where two
1020           dates are entered, the resulting delta can take on two different
1021           forms.  By default ($mode=0), an absolutely correct delta (ignoring
1022           daylight saving time) is returned in weeks, days, hours, minutes,
1023           and seconds.
1024
1025           If $mode is 1, the math is done using an approximate mode where a
1026           delta is returned using years and months as well.  The year and
1027           month part is calculated first followed by the rest.  For example,
1028           the two dates "Mar 12 1995" and "Apr 13 1995" would have an exact
1029           delta of "31 days" but in the approximate mode, it would be
1030           returned as "1 month 1 day".  Also, "Mar 31" and "Apr 30" would
1031           have deltas of "30 days" or "1 month" (since Apr 31 doesn't exist,
1032           it drops down to Apr 30).  Approximate mode is a more human way of
1033           looking at things (you'd say 1 month and 2 days more often then 33
1034           days), but it is less meaningful in terms of absolute time.  In
1035           approximate mode $d1 and $d2 must be dates.  If either or both is a
1036           delta, the calculation is done in exact mode.
1037
1038           If $mode is 2, a business mode is used.  That is, the calculation
1039           is done using business days, ignoring holidays, weekends, etc.  In
1040           order to correctly use this mode, a config file must exist which
1041           contains the section defining holidays (see documentation on the
1042           config file below).  The config file can also define the work week
1043           and the hours of the work day, so it is possible to have different
1044           config files for different businesses.
1045
1046           For example, if a config file defines the workday as 08:00 to
1047           18:00, a work week consisting of Mon-Sat, and the standard
1048           (American) holidays, then from Tuesday at 12:00 to the following
1049           Monday at 14:00 is 5 days and 2 hours.  If the "end" of the day is
1050           reached in a calculation, it automatically switches to the next
1051           day.  So, Tuesday at 12:00 plus 6 hours is Wednesday at 08:00
1052           (provided Wed is not a holiday).  Also, a date that is not during a
1053           workday automatically becomes the start of the next workday.  So,
1054           Sunday 12:00 and Monday at 03:00 both automatically becomes Monday
1055           at 08:00 (provided Monday is not a holiday).  In business mode, any
1056           combination of date and delta may be entered, but a delta should
1057           not contain a year or month field (weeks are fine though).
1058
1059           See Date::Manip::Calc for some additional comments about business
1060           mode calculations.
1061
1062           Note that a business week is treated the same as an exact week
1063           (i.e. from Tuesday to Tuesday, regardless of holidays).  Because
1064           this means that the relationship between days and weeks is NOT
1065           unambiguous, when a delta is produced from two dates, it will be in
1066           terms of d/h/mn/s (i.e. no week field).
1067
1068           If $mode is 3 (which only applies when two dates are passed in), an
1069           exact business mode is used.  In this case, it returns a delta as
1070           an exact number of business days/hours/etc. between the two.
1071           Weeks, months, and years are ignored.
1072
1073           Any other non-nil value of $mode is treated as $mode=1 (approximate
1074           mode).
1075
1076           The mode can be automatically set in the dates/deltas passed by
1077           including a key word somewhere in it.  For example, in English, if
1078           the word "approximately" is found in either of the date/delta
1079           arguments, approximate mode is forced.  Likewise, if the word
1080           "business" or "exactly" appears, business/exact mode is forced (and
1081           $mode is ignored).  So, the two following are equivalent:
1082
1083              $date = DateCalc("today","+ 2 business days",\$err);
1084              $date = DateCalc("today","+ 2 days",\$err,2);
1085
1086           Note that if the keyword method is used instead of passing in
1087           $mode, it is important that the keyword actually appear in the
1088           argument passed in to DateCalc.  The following will NOT work:
1089
1090              $delta = ParseDateDelta("+ 2 business days");
1091              $today = ParseDate("today");
1092              $date = DateCalc($today,$delta,\$err);
1093
1094           because the mode keyword is removed from a date/delta by the parse
1095           routines, and the mode is reset each time a parse routine is
1096           called.  Since DateCalc parses both of its arguments, whatever mode
1097           was previously set is ignored.
1098
1099           If \$err is passed in, it is set to:
1100              1 is returned if $d1 is not a delta or date
1101              2 is returned if $d2 is not a delta or date
1102              3 is returned if the date is outside the years 1000 to 9999 This
1103           argument is optional, but if included, it must come before $mode.
1104
1105           Nothing is returned if an error occurs.
1106
1107           When a delta is returned, the signs such that it is strictly
1108           positive or strictly negative ("1 day - 2 hours" would never be
1109           returned for example).  The only time when this cannot be enforced
1110           is when two deltas with a year/month component are entered.  In
1111           this case, only the signs on the day/hour/min/sec part are
1112           standardized.
1113
1114       Date_SetTime
1115            $date = Date_SetTime($date,$hr,$min,$sec);
1116            $date = Date_SetTime($date,$time);
1117
1118           This takes a date (any string that may be parsed by
1119           ParseDateString) and sets the time in that date.  For example, one
1120           way to get the time for 7:30 tomorrow would be to use the lines:
1121
1122              $date = ParseDate("tomorrow");
1123              $date = Date_SetTime($date,"7:30");
1124
1125           Note that in this routine (as well as the other routines below
1126           which use a time argument), no real parsing is done on the times.
1127           As a result,
1128
1129              $date = Date_SetTime($date,"13:30");
1130
1131           works, but
1132
1133              $date = Date_SetTime($date,"1:30 PM");
1134
1135           doesn't.
1136
1137       Date_SetDateField
1138            $date = Date_SetDateField($date,$field,$val [,$nocheck]);
1139
1140           This takes a date and sets one of its fields to a new value.
1141           $field is any of the strings "y", "m", "d", "h", "mn", "s" (case
1142           insensitive) and $val is the new value.
1143
1144           If $nocheck is non-zero, no check is made as to the validity of the
1145           date.
1146
1147       Date_GetPrev
1148            $date = Date_GetPrev($date,$dow, $curr [,$hr,$min,$sec]);
1149            $date = Date_GetPrev($date,$dow, $curr [,$time]);
1150            $date = Date_GetPrev($date,undef,$curr,$hr,$min,$sec);
1151            $date = Date_GetPrev($date,undef,$curr,$time);
1152
1153           This takes a date (any string that may be parsed by
1154           ParseDateString) and finds the previous occurrence of either a day
1155           of the week, or a certain time of day.
1156
1157           If $dow is defined, the previous occurrence of the day of week is
1158           returned.  $dow may either be a string (such as "Fri" or "Friday")
1159           or a number (between 1 and 7).  The date of the previous $dow is
1160           returned.
1161
1162           If $date falls on the day of week given by $dow, the date returned
1163           depends on $curr.  If $curr is 0, the date returned is a week
1164           before $date.  If $curr is 1, the date returned is the same as
1165           $date.  If $curr is 2, the date returned (including the time
1166           information) is required to be before $date.
1167
1168           If a time is passed in (either as separate hours, minutes, seconds
1169           or as a time in HH:MM:SS or HH:MM format), the time on this date is
1170           set to it.  The following examples should illustrate the use of
1171           Date_GetPrev:
1172
1173               date                   dow    curr  time            returns
1174               Fri Nov 22 18:15:00    Thu    any   12:30           Thu Nov 21 12:30:00
1175               Fri Nov 22 18:15:00    Fri    0     12:30           Fri Nov 15 12:30:00
1176               Fri Nov 22 18:15:00    Fri    1/2   12:30           Fri Nov 22 12:30:00
1177
1178               Fri Nov 22 18:15:00    Fri    1     18:30           Fri Nov 22 18:30:00
1179               Fri Nov 22 18:15:00    Fri    2     18:30           Fri Nov 15 18:30:00
1180
1181           If $dow is undefined, then a time must be entered, and the date
1182           returned is the previous occurrence of this time.  If $curr is non-
1183           zero, the current time is returned if it matches the criteria
1184           passed in.  In other words, the time returned is the last time that
1185           a digital clock (in 24 hour mode) would have displayed the time you
1186           passed in.  If you define hours, minutes and seconds default to 0
1187           and you might jump back as much as an entire day.  If hours are
1188           undefined, you are looking for the last time the minutes/seconds
1189           appeared on the digital clock, so at most, the time will jump back
1190           one hour.
1191
1192               date               curr  hr     min    sec      returns
1193               Nov 22 18:15:00    0/1   18     undef  undef    Nov 22 18:00:00
1194               Nov 22 18:15:00    0/1   18     30     0        Nov 21 18:30:00
1195               Nov 22 18:15:00    0     18     15     undef    Nov 21 18:15:00
1196               Nov 22 18:15:00    1     18     15     undef    Nov 22 18:15:00
1197               Nov 22 18:15:00    0     undef  15     undef    Nov 22 17:15:00
1198               Nov 22 18:15:00    1     undef  15     undef    Nov 22 18:15:00
1199
1200       Date_GetNext
1201            $date = Date_GetNext($date,$dow, $curr [,$hr,$min,$sec]);
1202            $date = Date_GetNext($date,$dow, $curr [,$time]);
1203            $date = Date_GetNext($date,undef,$curr,$hr,$min,$sec);
1204            $date = Date_GetNext($date,undef,$curr,$time);
1205
1206           Similar to Date_GetPrev.
1207
1208       Date_IsHoliday
1209            $name = Date_IsHoliday($date);
1210
1211           This returns undef if $date is not a holiday, or a string
1212           containing the name of the holiday otherwise.  An empty string is
1213           returned for an unnamed holiday.
1214
1215       Events_List
1216            $ref = Events_List($date);
1217            $ref = Events_List($date ,0      [,$flag]);
1218            $ref = Events_List($date0,$date1 [,$flag]);
1219
1220           This returns a list of events.  Events are defined in the Events
1221           section of the config file (discussed below).
1222
1223           In the first form (a single argument), $date is any string
1224           containing a date.  A list of events active at that precise time
1225           will be returned.  The format is similar to when $flag=0, except
1226           only a single time will be returned.
1227
1228           In all other cases, a range of times will be used.  If the 2nd
1229           argument evaluates to 0, the range of times will be the 24 hour
1230           period from midnight to midnight containing $date.  Otherwise, the
1231           range is given by the two dates.
1232
1233           The value of $flag determines the format of the information that is
1234           returned.
1235
1236           With $flag=0, the events are returned as a reference to a list of
1237           the form:
1238
1239             [ date, [ list_of_events ], date, [ list_of_events ], ... ]
1240
1241           For example, if the following events are defined (using the syntax
1242           discussed below in the description of the Event section of the
1243           config file):
1244
1245             2000-01-01 ; 2000-03-21  = Winter
1246             2000-03-22 ; 2000-06-21  = Spring
1247             2000-02-01               = Event1
1248             2000-05-01               = Event2
1249             2000-04-01-12:00:00      = Event3
1250
1251           might result in the following output:
1252
1253             Events_List("2000-04-01")
1254              => [ 2000040100:00:00, [ Spring ] ]
1255
1256             Events_List("2000-04-01 12:30");
1257              => [ 2000040112:30:00, [ Spring, Event3 ] ]
1258
1259             Events_List("2000-04-01",0);
1260              => [ 2000040100:00:00, [ Spring ],
1261                   2000040112:00:00, [ Spring, Event3 ],
1262                   2000040113:00:00, [ Spring ] ]
1263
1264             Events_List("2000-03-15","2000-04-10");
1265              => [ 2000031500:00:00, [ Winter ],
1266                   2000032200:00:00, [ Spring ]
1267                   2000040112:00:00, [ Spring, Event3 ]
1268                   2000040113:00:00, [ Spring ] ]
1269
1270           Much more complicated events can be defined using recurrences.
1271
1272           When $flag is non-zero, the format of the output is changed.  If
1273           $flag is 1, then a tally of the amount of time given to each event
1274           is returned.  Time for which two or more events apply is counted
1275           for both.
1276
1277             Events_List("2000-03-15","2000-04-10",1);
1278              => { Winter => +0:0:1:0:0:0:0,
1279                   Spring => +0:0:2:5:0:0:0,
1280                   Event3 => +0:0:0:0:1:0:0 }
1281
1282           When $flag is 2, a more complex tally with no event counted twice
1283           is returned.
1284
1285             Events_List("2000-03-15","2000-04-10",2);
1286              => { Winter => +0:0:1:0:0:0:0,
1287                   Spring => +0:0:2:4:23:0:0,
1288                   Event3+Spring => +0:0:0:0:1:0:0 }
1289
1290           The hash contains one element for each combination of events.
1291
1292       Date_DayOfWeek
1293            $day = Date_DayOfWeek($m,$d,$y);
1294
1295           Returns the day of the week (1 for Monday, 7 for Sunday).
1296
1297           All arguments must be numeric.
1298
1299       Date_SecsSince1970
1300            $secs = Date_SecsSince1970($m,$d,$y,$h,$mn,$s);
1301
1302           Returns the number of seconds since Jan 1, 1970 00:00 (negative if
1303           date is earlier).
1304
1305           All arguments must be numeric.
1306
1307       Date_SecsSince1970GMT
1308            $secs = Date_SecsSince1970GMT($m,$d,$y,$h,$mn,$s);
1309
1310           Returns the number of seconds since Jan 1, 1970 00:00 GMT (negative
1311           if date is earlier).  If CurrTZ is "IGNORE", the number will be
1312           identical to Date_SecsSince1970 (i.e. the date given will be
1313           treated as being in GMT).
1314
1315           All arguments must be numeric.
1316
1317       Date_DaysSince1BC
1318            $days = Date_DaysSince1BC($m,$d,$y);
1319
1320           Returns the number of days since Dec 31, 1BC.  This includes the
1321           year 0000.
1322
1323           All arguments must be numeric.
1324
1325       Date_DayOfYear
1326            $day = Date_DayOfYear($m,$d,$y);
1327
1328           Returns the day of the year (001 to 366)
1329
1330           All arguments must be numeric.
1331
1332       Date_NthDayOfYear
1333            ($y,$m,$d,$h,$mn,$s) = Date_NthDayOfYear($y,$n);
1334
1335           Returns the year, month, day, hour, minutes, and decimal seconds
1336           given a floating point day of the year.
1337
1338           All arguments must be numeric.  $n must be greater than or equal to
1339           1 and less than 366 on non-leap years and 367 on leap years.
1340
1341           NOTE: When $n is a decimal number, the results are non-intuitive
1342           perhaps.  Day 1 is Jan 01 00:00.  Day 2 is Jan 02 00:00.
1343           Intuitively, you might think of day 1.5 as being 1.5 days after Jan
1344           01 00:00, but this would mean that Day 1.5 was Jan 02 12:00 (which
1345           is later than Day 2).  The best way to think of this function is a
1346           time line starting at 1 and ending at 366 (in a non-leap year).  In
1347           terms of a delta, think of $n as the number of days after Dec 31
1348           00:00 of the previous year.
1349
1350       Date_DaysInYear
1351            $days = Date_DaysInYear($y);
1352
1353           Returns the number of days in the year (365 or 366)
1354
1355       Date_DaysInMonth
1356            $days = Date_DaysInMonth($m,$y);
1357
1358           Returns the number of days in the month.
1359
1360       Date_WeekOfYear
1361            $wkno = Date_WeekOfYear($m,$d,$y,$first);
1362
1363           Figure out week number.  $first is the first day of the week which
1364           is usually 1 (Monday) or 7 (Sunday), but could be any number
1365           between 1 and 7 in practice.
1366
1367           All arguments must be numeric.
1368
1369           NOTE: This routine should only be called in rare cases.  Use
1370           UnixDate with the %W, %U, %J, %L formats instead.  This routine
1371           returns a week between 0 and 53 which must then be "fixed" to get
1372           into the ISO-8601 weeks from 1 to 53.  A date which returns a week
1373           of 0 actually belongs to the last week of the previous year.  A
1374           date which returns a week of 53 may belong to the first week of the
1375           next year.
1376
1377       Date_LeapYear
1378            $flag = Date_LeapYear($y);
1379
1380           Returns 1 if the argument is a leap year Written by David Muir
1381           Sharnoff <muir@idiom.com>
1382
1383       Date_DaySuffix
1384            $day = Date_DaySuffix($d);
1385
1386           Add `st', `nd', `rd', `th' to a date (i.e. 1st, 22nd, 29th).  Works
1387           for international dates.
1388
1389       Date_TimeZone
1390            $tz = Date_TimeZone;
1391
1392           This determines and returns the local time zone.  If it is unable
1393           to determine the local time zone, the following error occurs:
1394
1395              ERROR: Date::Manip unable to determine Time Zone.
1396
1397           See The TIME ZONES section below for more information.
1398
1399       Date_ConvTZ
1400            $date = Date_ConvTZ($date);
1401            $date = Date_ConvTZ($date,$from);
1402            $date = Date_ConvTZ($date,"",$to [,$errlev]);
1403            $date = Date_ConvTZ($date,$from,$to [,$errlev]);
1404
1405           This converts a date (which MUST be in the format returned by
1406           ParseDate) from one time zone to another.
1407
1408           If it is called with no arguments, the date is converted from the
1409           local time zone to the time zone specified by the config variable
1410           ConvTZ (see documentation on ConvTZ below).  If ConvTZ is set to
1411           "IGNORE", no conversion is done.
1412
1413           If called with $from but no $to, the time zone is converted from
1414           the time zone in $from to ConvTZ (of TZ if ConvTZ is not set).
1415           Again, no conversion is done if ConvTZ is set to "IGNORE".
1416
1417           If called with $to but no $from, $from defaults to ConvTZ (if set)
1418           or the local time zone otherwise.  Although this does not seem
1419           immediately obvious, it actually makes sense.  By default, all
1420           dates that are parsed are converted to ConvTZ, so most of the dates
1421           being worked with will be stored in that time zone.
1422
1423           If Date_ConvTZ is called with both $from and $to, the date is
1424           converted from the time zone $from to $to.
1425
1426           NOTE: As in all other cases, the $date returned from Date_ConvTZ
1427           has no time zone information included as part of it, so calling
1428           UnixDate with the "%z" format will return the time zone that
1429           Date::Manip is working in (usually the local time zone).
1430
1431           Example:  To convert 2/2/96 noon PST to CST (regardless of what
1432           time zone you are in, do the following:
1433
1434            $date = ParseDate("2/2/96 noon");
1435            $date = Date_ConvTZ($date,"PST","CST");
1436
1437           Both time zones MUST be in one of the formats listed below in the
1438           section TIME ZONES.
1439
1440           If an error occurs, $errlev determines what happens:
1441
1442             0   : the program dies
1443             1   : a warning is produced and nothing is returned
1444             2   : the function silently returns nothing
1445
1446       Date_IsWorkDay
1447             $flag = Date_IsWorkDay($date [,$flag]);
1448
1449           This returns 1 if $date is a work day.  If $flag is non-zero, the
1450           time is checked to see if it falls within work hours.  It returns
1451           an empty string if $date is not valid.
1452
1453       Date_NextWorkDay
1454             $date = Date_NextWorkDay($date,$off [,$flag]);
1455
1456           Finds the day $off work days from now.  If $flag is non-zero, we
1457           must also take into account the time of day.
1458
1459           If $flag is zero, day 0 is today (if today is a workday) or the
1460           next work day if it isn't.  In any case, the time of day is
1461           unaffected.
1462
1463           If $flag is non-zero, day 0 is now (if now is part of a workday) or
1464           the start of the very next work day.
1465
1466       Date_PrevWorkDay
1467             $date = Date_PrevWorkDay($date,$off [,$flag]);
1468
1469           Similar to Date_NextWorkDay.
1470
1471       Date_NearestWorkDay
1472             $date = Date_NearestWorkDay($date [,$tomorrowfirst]);
1473
1474           This looks for the work day nearest to $date.  If $date is a work
1475           day, it is returned.  Otherwise, it will look forward or backwards
1476           in time 1 day at a time until a work day is found.  If
1477           $tomorrowfirst is non-zero (or if it is omitted and the config
1478           variable TomorrowFirst is non-zero), we look to the future first.
1479           Otherwise, we look in the past first.  In other words, in a normal
1480           week, if $date is Wednesday, $date is returned.  If $date is
1481           Saturday, Friday is returned.  If $date is Sunday, Monday is
1482           returned.  If Wednesday is a holiday, Thursday is returned if
1483           $tomorrowfirst is non-nil or Tuesday otherwise.
1484
1485       DateManipVersion
1486             $version = DateManipVersion;
1487
1488           Returns the version of Date::Manip.
1489

TIME ZONES

1491       With the release of Date::Manip 6.00, time zones and daylight saving
1492       time are now fully supported in Date::Manip. 6.00 uses information from
1493       several standards (most importantly the Olson zoneinfo database) to get
1494       a list of all known time zones.
1495
1496       Unfortunately, 6.00 requires a newer version of perl, so I will
1497       continue to support the 5.xx release for a while. However, the way I
1498       will support time zones in 5.xx has changed. Previously, new time zones
1499       would be added on request. That is no longer the case. Time zones for
1500       5.xx are now generated automatically from those available in 6.00.
1501
1502       The following time zone names are currently understood (and can be used
1503       in parsing dates).  These are zones defined in RFC 822.
1504
1505           Universal:  GMT, UT
1506           US zones :  EST, EDT, CST, CDT, MST, MDT, PST, PDT
1507           Military :  A to Z (except J)
1508           Other    :  +HHMM or -HHMM
1509           ISO 8601 :  +HH:MM, +HH, -HH:MM, -HH
1510
1511       In addition, the following time zone abbreviations are also accepted.
1512       These do not come from a standard, but were included in previous
1513       releases of Date::Manip 5.xx and are preserved here for backward
1514       compatibility:
1515
1516          IDLW    -1200    International Date Line West
1517          NT      -1100    Nome
1518          SAT     -0400    Chile
1519          CLDT    -0300    Chile Daylight
1520          AT      -0200    Azores
1521          MEWT    +0100    Middle European Winter
1522          MEZ     +0100    Middle European
1523          FWT     +0100    French Winter
1524          GB      +0100    GMT with daylight savings
1525          SWT     +0100    Swedish Winter
1526          MESZ    +0200    Middle European Summer
1527          FST     +0200    French Summer
1528          METDST  +0200    An alias for MEST used by HP-UX
1529          EETDST  +0300    An alias for eest used by HP-UX
1530          EETEDT  +0300    Eastern Europe, USSR Zone 1
1531          BT      +0300    Baghdad, USSR Zone 2
1532          IT      +0330    Iran
1533          ZP4     +0400    USSR Zone 3
1534          ZP5     +0500    USSR Zone 4
1535          IST     +0530    Indian Standard
1536          ZP6     +0600    USSR Zone 5
1537          AWST    +0800    Australian Western Standard
1538          ROK     +0900    Republic of Korea
1539          AEST    +1000    Australian Eastern Standard
1540          ACDT    +1030    Australian Central Daylight
1541          CADT    +1030    Central Australian Daylight
1542          AEDT    +1100    Australian Eastern Daylight
1543          EADT    +1100    Eastern Australian Daylight
1544          NZT     +1200    New Zealand
1545          IDLE    +1200    International Date Line East
1546
1547       All other time zone abbreviations come from the standards. In many
1548       cases, an abbreviation may be used for multiple time zones. For
1549       example, NST stands for Newfoundland Standard -0330 and North Sumatra
1550       +0630.  In these cases, only 1 of the two is available. I have tried to
1551       use the most recent definition, and of those (if multiple time zones
1552       use the abbreviation), the most commonly used. I don't claim that I'm
1553       correct in all cases, but I've done the best I could.
1554
1555       The list of abbreviations available is documented in the
1556       Date::Manip::DM5abbrevs document.
1557
1558       Date::Manip must be able to determine the time zone the user is in.  It
1559       does this by looking in the following places:
1560
1561          $Date::Manip::TZ (set with Date_Init or in Manip.pm)
1562          $ENV{TZ}
1563          the Unix `date` command (if available)
1564          $main::TZ
1565          /etc/TIMEZONE
1566          /etc/time zone
1567
1568       At least one of these should contain a time zone in one of the
1569       supported forms.  If none do by default, the TZ variable must be set
1570       with Date_Init.
1571
1572       The time zone may be in the STD#DST format (in which case both
1573       abbreviations must be in the table above) or any of the formats
1574       described above.  The STD#DST format is NOT available when parsing a
1575       date however.  The following forms are also available and are treated
1576       similar to the STD#DST forms:
1577
1578             US/Pacific
1579             US/Mountain
1580             US/Central
1581             US/Eastern
1582             Canada/Pacific
1583             Canada/Mountain
1584             Canada/Central
1585             Canada/Eastern
1586

CUSTOMIZING DATE::MANIP

1588       There are a number of variables which can be used to customize the way
1589       Date::Manip behaves.  There are also several ways to set these
1590       variables.
1591
1592       At the top of the Manip.pm file, there is a section which contains all
1593       customization variables.  These provide the default values.
1594
1595       These can be overridden in a global config file if one is present (this
1596       file is optional).  If the GlobalCnf variable is set in the Manip.pm
1597       file, it contains the full path to a config file.  If the file exists,
1598       its values will override those set in the Manip.pm file.  A sample
1599       config file is included with the Date::Manip distribution.  Modify it
1600       as appropriate and copy it to some appropriate directory and set the
1601       GlobalCnf variable in the Manip.pm file.
1602
1603       Each user can have a personal config file which is of the same form as
1604       the global config file.  The variables PersonalCnf and PersonalCnfPath
1605       set the name and search path for the personal config file.  This file
1606       is also optional.  If present, it overrides any values set in the
1607       global file.
1608
1609       NOTE: if you use business mode calculations, you must have a config
1610       file (either global or personal) since this is the only place where you
1611       can define holidays.
1612
1613       Finally, any variables passed in through Date_Init override all other
1614       values.
1615
1616       A config file can be composed of several sections.  The first section
1617       sets configuration variables.  Lines in this section are of the form:
1618
1619          VARIABLE = VALUE
1620
1621       For example, to make the default language French, include the line:
1622
1623          Language = French
1624
1625       Only variables described below may be used.  Blank lines and lines
1626       beginning with a pound sign (#) are ignored.  All spaces are optional
1627       and strings are case insensitive.
1628
1629       A line which starts with an asterisk (*) designates a new section.  For
1630       example, the HOLIDAY section starts with a line:
1631
1632          *Holiday
1633
1634       The various sections are defined below.
1635

DATE::MANIP VARIABLES

1637       All Date::Manip variables which can be used are described in the
1638       following section.
1639
1640       IgnoreGlobalCnf
1641           If this variable is used (any value is ignored), the global config
1642           file is not read.  It must be present in the initial call to
1643           Date_Init or the global config file will be read.
1644
1645       EraseHolidays
1646           If this variable is used (any value is ignored), the current list
1647           of defined holidays is erased.  A new set will be set the next time
1648           a config file is read in.  This can be set in either the global
1649           config file or as a Date_Init argument (in which case holidays can
1650           be read in from both the global and personal config files) or in
1651           the personal config file (in which case, only holidays in the
1652           personal config file are counted).
1653
1654       PathSep
1655           This is a regular expression used to separate multiple paths.  For
1656           example, on Unix, it defaults to a colon (:) so that multiple paths
1657           can be written PATH1:PATH2 .  For Win32 platforms, it defaults to a
1658           semicolon (;) so that paths such as "c:\;d:\" will work.
1659
1660       GlobalCnf
1661           This variable can be passed into Date_Init to point to a global
1662           configuration file.  The value must be the complete path to a
1663           config file.
1664
1665           By default, no global config file is read.  Any time a global
1666           config file is read, the holidays are erased.
1667
1668           Paths may have a tilde (~) expansion on platforms where this is
1669           supported (currently Unix and VMS).
1670
1671       PersonalCnf
1672           This variable can be passed into Date_Init or set in a global
1673           config file to set the name of the personal configuration file.
1674
1675           The default name for the config file is .DateManip.cnf on all Unix
1676           platforms and Manip.cnf on all non-Unix platforms (because some of
1677           them insist on 8.3 character filenames :-).
1678
1679       PersonalCnfPath
1680           This is a list of paths separated by the separator specified by the
1681           PathSep variable.  These paths are each checked for the PersonalCnf
1682           config file.
1683
1684           Paths may have a tilde (~) expansion on platforms where this is
1685           supported (currently Unix and VMS).
1686
1687       Language
1688           Date::Manip can be used to parse dates in many different languages.
1689           Currently, it is configured to read  the following languages (the
1690           version in which they added is included for historical interest):
1691
1692             English      (default)
1693             French       (5.02)
1694             Swedish      (5.05)
1695             German       (5.31)
1696             Dutch        (5.32)     aka Nederlands
1697             Polish       (5.32)
1698             Spanish      (5.33)
1699             Portuguese   (5.34)
1700             Romanian     (5.35)
1701             Italian      (5.35)
1702             Russian      (5.41)
1703             Turkish      (5.41)
1704             Danish       (5.41)
1705
1706           Others can be added easily.  Language is set to the language used
1707           to parse dates.  If you are interested in providing a translation
1708           for a new language, email me (see the AUTHOR section below) and
1709           I'll send you a list of things that I need.
1710
1711       DateFormat
1712           Different countries look at the date 12/10 as Dec 10 or Oct 12.  In
1713           the United States, the first is most common, but this certainly
1714           doesn't hold true for other countries.  Setting DateFormat to "US"
1715           forces the first behavior (Dec 10).  Setting DateFormat to anything
1716           else forces the second behavior (Oct 12).
1717
1718       TZ  If set, this defines the local time zone.  See the TIME ZONES
1719           section above for information on its format.
1720
1721       ConvTZ
1722           All date comparisons and calculations must be done in a single time
1723           zone in order for them to work correctly.  So, when a date is
1724           parsed, it should be converted to a specific time zone.  This
1725           allows dates to easily be compared and manipulated as if they are
1726           all in a single time zone.
1727
1728           The ConvTZ variable determines which time zone should be used to
1729           store dates in.  If it is left blank, all dates are converted to
1730           the local time zone (see the TZ variable above).  If it is set to
1731           one of the time zones listed above, all dates are converted to this
1732           time zone.  Finally, if it is set to the string "IGNORE", all time
1733           zone information is ignored as the dates are read in (in this case,
1734           the two dates "1/1/96 12:00 GMT" and "1/1/96 12:00 EST" would be
1735           treated as identical).
1736
1737       Internal
1738           When a date is parsed using ParseDate, that date is stored in an
1739           internal format which is understood by the Date::Manip routines
1740           UnixDate and DateCalc.  Originally, the format used to store the
1741           date internally was:
1742
1743              YYYYMMDDHH:MN:SS
1744
1745           It has been suggested that I remove the colons (:) to shorten this
1746           to:
1747
1748              YYYYMMDDHHMNSS
1749
1750           The main advantage of this is that some databases are colon
1751           delimited which makes storing a date from Date::Manip tedious.
1752
1753           In order to maintain backwards compatibility, the Internal variable
1754           was introduced.  Set it to 0 (to use the old format) or 1 (to use
1755           the new format).
1756
1757       FirstDay
1758           It is sometimes necessary to know what day of week is regarded as
1759           first.  By default, this is set to Monday, but many countries and
1760           people will prefer Sunday (and in a few cases, a different day may
1761           be desired).  Set the FirstDay variable to be the first day of the
1762           week (1=Monday, 7=Sunday) Monday should be chosen to to comply with
1763           ISO 8601.
1764
1765       WorkWeekBeg, WorkWeekEnd
1766           The first and last days of the work week.  By default, Monday and
1767           Friday.  WorkWeekBeg must come before WorkWeekEnd numerically.  The
1768           days are numbered from 1 (Monday) to 7 (Sunday).
1769
1770           There is no way to handle an odd work week of Thu to Mon for
1771           example or 10 days on, 4 days off.
1772
1773       WorkDay24Hr
1774           If this is non-nil, a work day is treated as being 24 hours long.
1775           The WorkDayBeg and WorkDayEnd variables are ignored in this case.
1776
1777       WorkDayBeg, WorkDayEnd
1778           The times when the work day starts and ends.  WorkDayBeg must come
1779           before WorkDayEnd (i.e. there is no way to handle the night shift
1780           where the work day starts one day and ends another).  Also, the
1781           workday MUST be more than one hour long (of course, if this isn't
1782           the case, let me know... I want a job there!).
1783
1784           The time in both can be in any valid time format (including
1785           international formats), but seconds will be ignored.
1786
1787       TomorrowFirst
1788           Periodically, if a day is not a business day, we need to find the
1789           nearest business day to it.  By default, we'll look to "tomorrow"
1790           first, but if this variable is set to 0, we'll look to "yesterday"
1791           first.  This is only used in the Date_NearestWorkDay and is easily
1792           overridden (see documentation for that function).
1793
1794       DeltaSigns
1795           Prior to Date::Manip version 5.07, a negative delta would put
1796           negative signs in front of every component (i.e. "0:0:-1:-3:0:-4").
1797           By default, 5.07 changes this behavior to print only 1 or two signs
1798           in front of the year and day elements (even if these elements might
1799           be zero) and the sign for year/month and day/hour/minute/second are
1800           the same.  Setting this variable to non-zero forces deltas to be
1801           stored with a sign in front of every element (including elements
1802           equal to 0).
1803
1804       Jan1Week1
1805           ISO 8601 states that the first week of the year is the one which
1806           contains Jan 4 (i.e. it is the first week in which most of the days
1807           in that week fall in that year).  This means that the first 3 days
1808           of the year may be treated as belonging to the last week of the
1809           previous year.  If this is set to non-nil, the ISO 8601 standard
1810           will be ignored and the first week of the year contains Jan 1.
1811
1812       YYtoYYYY
1813           By default, a 2 digit year is treated as falling in the 100 year
1814           period of CURR-89 to CURR+10.  YYtoYYYY may be set to any integer N
1815           to force a 2 digit year into the period CURR-N to CURR+(99-N).  A
1816           value of 0 forces the year to be the current year or later.  A
1817           value of 99 forces the year to be the current year or earlier.
1818           Since I do no checking on the value of YYtoYYYY, you can actually
1819           have it any positive or negative value to force it into any century
1820           you want.
1821
1822           YYtoYYYY can also be set to "C" to force it into the current
1823           century, or to "C##" to force it into a specific century.  So, in
1824           1998, "C" forces 2 digit years to be 1900-1999 and "C18" would
1825           force it to be 1800-1899.
1826
1827           It can also be set to the form "C####" to force it into a specific
1828           100 year period.  C1950 refers to 1950-2049.
1829
1830       UpdateCurrTZ
1831           If a script is running over a long period of time, the time zone
1832           may change during the course of running it (i.e. when daylight
1833           saving time starts or ends).  As a result, parsing dates may start
1834           putting them in the wrong time zone.  Since a lot of overhead can
1835           be saved if we don't have to check the current time zone every time
1836           a date is parsed, by default checking is turned off.  Setting this
1837           to non-nil will force time zone checking to be done every time a
1838           date is parsed... but this will result in a considerable
1839           performance penalty.
1840
1841           A better solution would be to restart the process on the two days
1842           per year where the time zone switch occurs.
1843
1844       IntCharSet
1845           If set to 0, use the US character set (7-bit ASCII) to return
1846           strings such as the month name.  If set to 1, use the appropriate
1847           international character set.  For example, If you want your French
1848           representation of December to have the accent over the first "e",
1849           you'll want to set this to 1.
1850
1851       ForceDate
1852           This variable can be set to a date in the format:
1853           YYYY-MM-DD-HH:MN:SS to force the current date to be interpreted as
1854           this date.  Since the current date is used in parsing, this string
1855           will not be parsed and MUST be in the format given above.
1856
1857       TodayIsMidnight
1858           If set to a true value (e.g. 1), then "today" will mean the same as
1859           "midnight today"; otherwise it will mean the same as "now".
1860

HOLIDAY SECTION

1862       The holiday section of the config file is used to define holidays.
1863       Each line is of the form:
1864
1865          DATE = HOLIDAY
1866
1867       HOLIDAY is the name of the holiday (or it can be blank in which case
1868       the day will still be treated as a holiday... for example the day after
1869       Thanksgiving or Christmas is often a work holiday though neither are
1870       named).
1871
1872       DATE is a string which can be parsed to give a valid date in any year.
1873       It can be of the form
1874
1875          Date
1876          Date + Delta
1877          Date - Delta
1878          Recur
1879
1880       A valid holiday section would be:
1881
1882          *Holiday
1883
1884          1/1                             = New Year's Day
1885          third Monday in Feb             = Presidents' Day
1886          fourth Thu in Nov               = Thanksgiving
1887
1888          # The Friday after Thanksgiving is an unnamed holiday most places
1889          fourth Thu in Nov + 1 day       =
1890
1891          1*0:0:0:0:0:0*EASTER            = Easter
1892          1*11:0:11:0:0:0*DWD             = Veteran's Day (observed)
1893          1*0:0:0:0:0:0*EASTER,PD5        = Good Friday
1894
1895       In a Date + Delta or Date - Delta string, you can use business mode by
1896       including the appropriate string (see documentation on DateCalc) in the
1897       Date or Delta.  So (in English), the first workday before Christmas
1898       could be defined as:
1899
1900          12/25 - 1 business day          =
1901
1902       The dates may optionally contain the year.  For example, the dates
1903
1904         1/1
1905         1/1/1999
1906
1907       refers to Jan 1 in any year or in only 1999 respectively.  For dates
1908       that refer to any year, the date must be written such that by simply
1909       appending the year (separated by spaces) it can be correctly
1910       interpreted.  This will work for everything except ISO 8601 dates, so
1911       ISO 8601 dates may not be used in this case.
1912
1913       Note that the dates are specified in whatever format is set using the
1914       Date_Init options, so if the standard parsing is D/M/YYYY, you would
1915       need to specify it as:
1916
1917          25/12/2002           = Christmas
1918
1919       In cases where you are interested in business type calculations, you'll
1920       want to define most holidays using recurrences, since they can define
1921       when a holiday is celebrated in the financial world.  For example,
1922       Christmas should be defined as:
1923
1924          1*12:0:24:0:0:0*FW1  = Christmas
1925
1926       NOTE: It was pointed out to me that using a similar type recurrence to
1927       define New Years does not work.  The recurrence:
1928
1929          1*12:0:31:0:0:0*FW1
1930
1931       fails (worse, it goes into an infinite loop).  The problem is that each
1932       holiday definition is applied to a specific year and it expects to find
1933       the holiday for that year.  When this recurrence is applied to the year
1934       1995, it returns the holiday for 1996 and fails.
1935
1936       Use the recurrence:
1937
1938          1*1:0:1:0:0:0*NWD
1939
1940       instead.
1941
1942       If you wanted to define both Christmas and Boxing days (Boxing is the
1943       day after Christmas, and is celebrated in some parts of the world), you
1944       could do it in one of the following ways:
1945
1946          1*12:0:24:0:0:0*FW1  = Christmas
1947          1*12:0:25:0:0:0*FW1  = Boxing
1948
1949           1*12:0:24:0:0:0*FW1 = Christmas
1950          01*12:0:24:0:0:0*FW1 = Boxing
1951
1952          1*12:0:24:0:0:0*FW1   = Christmas
1953          1*12:0:25:0:0:0*FW1,a = Boxing
1954
1955       The following examples will NOT work:
1956
1957          1*12:0:24:0:0:0*FW1  = Christmas
1958          1*12:0:24:0:0:0*FW2  = Boxing
1959
1960          1*12:0:24:0:0:0*FW1  = Christmas
1961          1*12:0:24:0:0:0*FW1  = Boxing
1962
1963       The reasoning behind all this is as follows:
1964
1965       Holidays go into affect the minute they are parsed.  So, in the case
1966       of:
1967
1968          1*12:0:24:0:0:0*FW1  = Christmas
1969          1*12:0:24:0:0:0*FW2  = Boxing
1970
1971       the minute the first line is parsed, Christmas is defined as a holiday.
1972       The second line then steps forward 2 work days (skipping Christmas
1973       since that's no longer a work day) and define the work day two days
1974       after Christmas, NOT the day after Christmas.
1975
1976       An good alternative would appear to be:
1977
1978          1*12:0:24:0:0:0*FW1  = Christmas
1979          1*12:0:24:0:0:0*FW1  = Boxing
1980
1981       This unfortunately fails because the recurrences are currently stored
1982       in a hash.  Since these two recurrences are identical, they fail (the
1983       first one is overwritten by the second and in essence, Christmas is
1984       never defined).
1985
1986       To fix this, make them unique with either a fake flag (which is
1987       ignored):
1988
1989          1*12:0:24:0:0:0*FW1,a  = Boxing
1990
1991       or adding an innocuous 0 somewhere:
1992
1993          01*12:0:24:0:0:0*FW1   = Boxing
1994
1995       The other good alternative would be to make two completely different
1996       recurrences such as:
1997
1998          1*12:0:24:0:0:0*FW1  = Christmas
1999          1*12:0:25:0:0:0*FW1  = Boxing
2000
2001       At times, you may want to switch back and forth between two holiday
2002       files.  This can be done by calling the following:
2003
2004         Date_Init("EraseHolidays=1","PersonalCnf=FILE1");
2005         ...
2006         Date_Init("EraseHolidays=1","PersonalCnf=FILE2");
2007         ...
2008

EVENTS SECTION

2010       The Events section of the config file is similar to the Holiday
2011       section.  It is used to name certain days or times, but there are a few
2012       important differences:
2013
2014       Events can be assigned to any time and duration
2015           All holidays are exactly 1 day long.  They are assigned to a period
2016           of time from midnight to midnight.
2017
2018           Events can be based at any time of the day, and may be of any
2019           duration.
2020
2021       Events don't affect business mode calculations
2022           Unlike holidays, events are completely ignored when doing business
2023           mode calculations.
2024
2025       Whereas holidays were added with business mode math in mind, events
2026       were added with calendar and scheduling applications in mind.
2027
2028       Every line in the events section is of the form:
2029
2030          EVENT = NAME
2031
2032       where NAME is the name of the event, and EVENT defines when it occurs
2033       and its duration.  An EVENT can be defined in the following ways:
2034
2035          Date
2036          Date*
2037
2038          Date  ; Date
2039          Date  ; Delta
2040
2041       Here, Date* refers to a string containing a Date with NO TIME fields
2042       (Jan 12, 1/1/2000, 2010-01-01) while Date does contain time fields.
2043       Similarly, Recur* stands for a recurrence with the time fields all
2044       equal to 0) while Recur stands for a recurrence with at least one non-
2045       zero time field.
2046
2047       Both Date* and Recur* refer to an event very similar to a holiday which
2048       goes from midnight to midnight.
2049
2050       Date and Recur refer to events which occur at the time given and with a
2051       duration of 1 hour.
2052
2053       Events given by "Date ; Date", "Date ; Delta", and "Recur ; Delta"
2054       contain both the starting date and either ending date or duration.
2055
2056       Events given as three elements "Date ; Delta ; Delta" or "Recur ; Delta
2057       ; Delta" take a date and add both deltas to it to give the starting and
2058       ending time of the event.  The order and sign of the deltas is
2059       unimportant (and both can be the same sign to give a range of times
2060       which does not contain the base date).
2061

KNOWN PROBLEMS

2063       The following are not bugs in Date::Manip, but they may give some
2064       people problems.
2065
2066       Unable to determine Time Zone
2067           Perhaps the most common problem occurs when you get the error:
2068
2069              Error: Date::Manip unable to determine Time Zone.
2070
2071           Date::Manip tries hard to determine the local time zone, but on
2072           some machines, it cannot do this (especially non-Unix systems).  To
2073           fix this, just set the TZ variable, either at the top of the
2074           Manip.pm file, in the DateManip.cnf file, or in a call to
2075           Date_Init.  I suggest using the form "EST5EDT" so you don't have to
2076           change it every 6 months when going to or from daylight saving
2077           time.
2078
2079           Windows NT does not seem to set the time zone by default.  From the
2080           Perl-Win32-Users mailing list:
2081
2082              > How do I get the TimeZone on my NT?
2083              >
2084              >      $time_zone = $ENV{'TZ'};
2085              >
2086              You have to set the variable before, WinNT doesn't set it by
2087              default.  Open the properties of "My Computer" and set a SYSTEM
2088              variable TZ to your time zone.   Jenda@Krynicky.cz
2089
2090           This might help out some NT users.
2091
2092           A minor (false) assumption that some users might make is that since
2093           Date::Manip passed all of its tests at install time, this should
2094           not occur and are surprised when it does.
2095
2096           Some of the tests are time zone dependent.  Since the tests all
2097           include input and expected output, I needed to know in advance what
2098           time zone they would be run in.  So, the tests all explicitly set
2099           the time zone using the TZ configuration variable passed into
2100           Date_Init.  Since this overrides any other method of determining
2101           the time zone, Date::Manip uses this and doesn't have to look
2102           elsewhere for the time zone.
2103
2104           When running outside the tests, Date::Manip has to rely on its
2105           other methods for determining the time zone.
2106
2107       Missing date formats
2108           Please see the Date::Manip::Problems document for a discussion.
2109
2110       Complaining about getpwnam/getpwuid
2111           Another problem is when running on Micro$oft OS's.  I have added
2112           many tests to catch them, but they still slip through occasionally.
2113           If any ever complain about getpwnam/getpwuid, simply add one of the
2114           lines:
2115
2116             $ENV{OS} = Windows_NT
2117             $ENV{OS} = Windows_95
2118
2119           to your script before
2120
2121             use Date::Manip
2122
2123       Date::Manip is slow
2124           The reasons for this are covered in the SHOULD I USE DATE::MANIP
2125           section above.
2126
2127           Some things that will definitely help:
2128
2129           Version 5.21 does run noticeably faster than earlier versions due
2130           to rethinking some of the initialization, so at the very least,
2131           make sure you are running this version or later.
2132
2133           ISO-8601 dates are parsed first and fastest.  Use them whenever
2134           possible.
2135
2136           Avoid parsing dates that are referenced against the current time
2137           (in 2 days, today at noon, etc.).  These take a lot longer to
2138           parse.
2139
2140              Example:  parsing 1065 dates with version 5.11 took 48.6 seconds, 36.2
2141              seconds with version 5.21, and parsing 1065 ISO-8601 dates with version
2142              5.21 took 29.1 seconds (these were run on a slow, overloaded computer with
2143              little memory... but the ratios should be reliable on a faster computer).
2144
2145           Business date calculations are extremely slow.  You should consider
2146           alternatives if possible (i.e. doing the calculation in exact mode
2147           and then multiplying by 5/7).  Who needs a business date more
2148           accurate than "6 to 8 weeks" anyway, right :-)
2149
2150           Never call Date_Init more than once.  Unless you're doing something
2151           very strange, there should never be a reason to anyway.
2152
2153       Sorting Problems
2154           If you use Date::Manip to sort a number of dates, you must call
2155           Date_Init either explicitly, or by way of some other Date::Manip
2156           routine before it is used in the sort.  For example, the following
2157           code fails:
2158
2159              use Date::Manip;
2160              # Date_Init;
2161              sub sortDate {
2162                  my($date1, $date2);
2163                  $date1 = ParseDate($a);
2164                  $date2 = ParseDate($b);
2165                  return (Date_Cmp($date1,$date2));
2166              }
2167              @dates = ("Fri 16 Aug 96",
2168                       "Mon 19 Aug 96",
2169                       "Thu 15 Aug 96");
2170              @i=sort sortDate @dates;
2171
2172           but if you uncomment the Date_Init line, it works.  The reason for
2173           this is that the first time you call Date_Init, it initializes a
2174           number of items used by Date::Manip.  Some of these have to be
2175           sorted (regular expressions sorted by length to ensure the longest
2176           match).  It turns out that Perl has a bug in it which does not
2177           allow a sort within a sort.  At some point, this should be fixed,
2178           but for now, the best thing to do is to call Date_Init explicitly.
2179           The bug exists in all versions up to 5.005 (I haven't tested 5.6.0
2180           yet).
2181
2182           NOTE: This is an EXTREMELY inefficient way to sort data (but read
2183           the 2nd note below for an easy way to correct this).  Instead, you
2184           should parse the dates with ParseDate, sort them using a normal
2185           string comparison, and then convert them back to the format desired
2186           using UnixDate.
2187
2188           NOTE: It has been reported to me that you can still use ParseDate
2189           to sort dates in this way, and be quite efficient through the use
2190           of Memoize.  Just add the following lines to your code:
2191
2192              use Date::Manip;
2193              use Memoize;
2194              memoize('ParseDate');
2195              ...
2196              @i=sort sortDate @dates;
2197
2198           Since sortDate would call ParseDate with the same data over and
2199           over, this is a perfect application for the Memoize module.  So,
2200           sorting with ParseDate is no longer slow for sorting.
2201
2202       RCS Control
2203           If you try to put Date::Manip under RCS control, you are going to
2204           have problems.  Apparently, RCS replaces strings of the form
2205           "$Date...$" with the current date.  This form occurs all over in
2206           Date::Manip.  To prevent the RCS keyword expansion, checkout files
2207           using "co -ko".  Since very few people will ever have a desire to
2208           do this (and I don't use RCS), I have not worried about it.
2209

KNOWN BUGS

2211       Daylight Saving Times
2212           Date::Manip 5.xx does not handle daylight saving time, though it
2213           does handle time zones to a certain extent.  Converting from EST to
2214           PST works fine.  Going from EST to PDT is unreliable.
2215
2216           The following examples are run in the winter of the US East coast
2217           (i.e.  in the EST time zone).
2218
2219                   print UnixDate(ParseDate("6/1/97 noon"),"%u"),"\n";
2220                   => Sun Jun  1 12:00:00 EST 1997
2221
2222           June 1 EST does not exist.  June 1st is during EDT.  It should
2223           print:
2224
2225                   => Sun Jun  1 00:00:00 EDT 1997
2226
2227           Even explicitly adding the time zone doesn't fix things (if
2228           anything, it makes them worse):
2229
2230                   print UnixDate(ParseDate("6/1/97 noon EDT"),"%u"),"\n";
2231                   => Sun Jun  1 11:00:00 EST 1997
2232
2233           Date::Manip converts everything to the current time zone (EST in
2234           this case).
2235
2236           Related problems occur when trying to do date calculations over a
2237           time zone change.  These calculations may be off by an hour.
2238
2239           Also, if you are running a script which uses Date::Manip over a
2240           period of time which starts in one time zone and ends in another
2241           (i.e. it switches form Daylight Saving Time to Standard Time or
2242           vice versa), many things may be wrong (especially elapsed time).
2243
2244           These problems will not be fixed in Date::Manip 5.xx. Date::Manip
2245           6.xx has full support for time zones and daylight saving time.
2246

BUGS AND QUESTIONS

2248       Please refer to the Date::Manip::Problems documentation for information
2249       on submitting bug reports or questions to the author.
2250

SEE ALSO

2252       Date::Manip        - main module documentation
2253

LICENSE

2255       This script is free software; you can redistribute it and/or modify it
2256       under the same terms as Perl itself.
2257

AUTHOR

2259       Sullivan Beck (sbeck@cpan.org)
2260
2261
2262
2263perl v5.38.0                      2023-07-20               Date::Manip::DM5(3)
Impressum