1Date::Manip::DM5(3) User Contributed Perl Documentation Date::Manip::DM5(3)
2
6 Date::Manip::DM5 - Date manipulation routines
7
9 use Date::Manip;
10 $version = DateManipVersion;
12 Date_Init();
14 Date_Init("VAR=VAL","VAR=VAL",...);
15 @list = Date_Init();
16 @list = Date_Init("VAR=VAL","VAR=VAL",...);
17 $date = ParseDate(\@args);
19 $date = ParseDate($string);
20 $date = ParseDate(\$string);
21 @date = UnixDate($date,@format);
23 $date = UnixDate($date,@format);
24 $delta = ParseDateDelta(\@args);
26 $delta = ParseDateDelta($string);
27 $delta = ParseDateDelta(\$string);
28 @str = Delta_Format($delta,$dec,@format);
30 $str = Delta_Format($delta,$dec,@format);
31 $recur = ParseRecur($string,$base,$date0,$date1,$flags);
33 @dates = ParseRecur($string,$base,$date0,$date1,$flags);
34 $flag = Date_Cmp($date1,$date2);
36 $d = DateCalc($d1,$d2 [,$errref] [,$del]);
38 $date = Date_SetTime($date,$hr,$min,$sec);
40 $date = Date_SetTime($date,$time);
41 $date = Date_SetDateField($date,$field,$val [,$nocheck]);
43 $date = Date_GetPrev($date,$dow,$today,$hr,$min,$sec);
45 $date = Date_GetPrev($date,$dow,$today,$time);
46 $date = Date_GetNext($date,$dow,$today,$hr,$min,$sec);
48 $date = Date_GetNext($date,$dow,$today,$time);
49 $name = Date_IsHoliday($date);
51 $listref = Events_List($date);
53 $listref = Events_List($date0,$date1);
54 $date = Date_ConvTZ($date);
56 $date = Date_ConvTZ($date,$from);
57 $date = Date_ConvTZ($date,"",$to);
58 $date = Date_ConvTZ($date,$from,$to);
59 $flag = Date_IsWorkDay($date [,$flag]);
61 $date = Date_NextWorkDay($date,$off [,$flag]);
63 $date = Date_PrevWorkDay($date,$off [,$flag]);
65 $date = Date_NearestWorkDay($date [,$tomorrowfirst]);
67 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 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 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 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 $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
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 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 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 Date_Init("Language=French","DateFormat=non-US");
131 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 ParseDate
140 $date = ParseDate(\@args);
141 $date = ParseDate($string);
142 $date = ParseDate(\$string);
143 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 The real work is done in the ParseDateString routine.
155 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 mycommand -date Dec 10 1997 -arg -arg2
162 No more reading man pages to find out what date format is required
164 in a man page.
165 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 ParseDateString
176 $date = ParseDateString($string);
177 This routine is called by ParseDate, but it may also be called
179 directly to save some time (a negligible amount).
180 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 $secs = ... # seconds since Jan 1, 1970 00:00:00 GMT
188 $date = DateCalc("Jan 1, 1970 00:00:00 GMT","+ $secs");
189 Second, you can call it directly as:
191 $date = ParseDateString("epoch $secs");
193 To go backwards, just use the "%s" format of UnixDate:
195 $secs = UnixDate($date,"%s");
197 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 [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 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 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 Fractional seconds are also supported in parsing but the fractional
218 part is discarded (with NO rounding occurring).
219 Time zones always appear immediately after the time. A number of
221 different forms are supported (see the section TIME ZONES below).
222 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 Valid date formats include the ISO 8601 formats:
228 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 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 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 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 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 Additional date formats are available which may or may not be
273 common including:
274 MM/DD **
276 MM/DD/YY **
277 MM/DD/YYYY **
278 mmmDD DDmmm mmmYYYY/DD mmmYYYY
280 mmmDD/YY DDmmmYY DD/YYmmm YYYYmmmDD YYYYmmm
281 mmmDDYYYY DDmmmYYYY DDYYYYmmm YYYY/DDmmm
282 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 ** 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 Date separators are treated very flexibly (they are converted to
301 spaces), so the following dates are all equivalent:
302 12/10/1965
304 12-10 / 1965
305 12 // 10 -. 1965
306 In some cases, this may actually be TOO flexible, but no attempt is
308 made to trap this.
309 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 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 ** 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 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 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 Some things to note:
365 All strings are case insensitive. "December" and "DEceMBer" both
367 work.
368 When a part of the date is not given, defaults are used: year
370 defaults to current year; hours, minutes, seconds to 00.
371 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 Dates are always checked to make sure they are valid.
382 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 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 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 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 UnixDate
417 @date = UnixDate($date,@format);
418 $date = UnixDate($date,@format);
419 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 $date may be any string that can be parsed by ParseDateString.
426 The format options are:
428 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 %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 If a lone percent is the final character in a format, it is
503 ignored.
504 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 NOTE 1:
511 The ls format (%l) applies to date within the past OR future 6
513 months!
514 NOTE 2:
516 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 The %W and %G formats return the week-of-year and the year treating
524 weeks as starting on Monday.
525 The %U and %L formats return the week-of-year and the year treating
527 weeks as starting on Sunday.
528 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 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 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 %J returns the full ISO-8601 format (%G-W%W-%w).
551 NOTE 3:
553 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 ParseDateDelta
560 $delta = ParseDateDelta(\@args);
561 $delta = ParseDateDelta($string);
562 $delta = ParseDateDelta(\$string);
563 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 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 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 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 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 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 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 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 It is possible to include a sign for all elements that is output.
628 See the configuration variable DeltaSigns below.
629 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 Delta_Format
637 @str = Delta_Format($delta [,$mode], $dec,@format);
638 $str = Delta_Format($delta [,$mode], $dec,@format);
639 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 Formats currently understood are:
645 %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 X is one of y,M,w,d,h,m,s (case sensitive).
654 %% : returns a "%"
656 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 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 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 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 %yt = 1.5 (1 year, 6 months)
674 %Mt = 18
675 %dt = 9.5 (1 week, 2 days, 12 hours)
677 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 %dt = 557.375 (1.5 years of 365.25 days + 9.5 days)
683 If $dec is non-zero, the %Xd and %Xt values are formatted to
685 contain $dec decimal places.
686 ParseRecur
688 $recur = ParseRecur($string [,$base,$date0,$date1,$flags]);
689 @dates = ParseRecur($string [,$base,$date0,$date1,$flags]);
690 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 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 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 Third, the recurring event may have a range (a starting and ending
709 date).
710 Fourth, there may be some flags included which modify the behavior
712 of the above information.
713 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 freq*flags*base*date0*date1
719 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 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 1:2:3:4:5:6:7
732 1:2*3:4:5:6:7
733 *1:2:3:4:5:6:7
734 But the following are NOT valid because they contain 2 or more
736 asterisks:
737 1:2*3:4:5*6:7
739 1*2*3:4:5*6:7
740 *1:2:3:4:5:6*7
741 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 1:2*
747 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 If no asterisks are included, then the entire recurrence is of this
754 form. For example,
755 0:0:0:1:12:0:0
757 refers to an event that occurs every 1 day, 12 hours.
759 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 *12:0:0
765 then the recurring event occurs at 12:00:00 (noon).
767 For example:
769 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 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 Some examples are:
781 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 There is no way to express the following with a single recurrence:
790 every day at 12:30 and 1:00
792 You have to use two recurrences to do this.
794 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 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 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 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 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 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 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 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 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 1:0:0*45:0:0:0 45th day of every year
846 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 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 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 date0 <= date < date1
869 The argument $string can contain any of the parts of a full
871 recurrence. For example:
872 freq
874 freq*flags
875 freq**base*date0*date1
876 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 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 NOTE: Base dates are only used with some types of recurrences. For
888 example,
889 0:0:3*2:0:0:0 every 3rd Tuesday
891 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 Other dates do not require a base date. For example:
898 0:0*3:2:0:0:0 third Tuesday of every month
900 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 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 1:3*0:4:0:0:0 every 1 year, 3 months on the 4th day of the month
910 would only use the year and month of the base date.
912 There are a small handful of English strings which can be parsed in
914 place of a numerical recur description. These include:
915 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 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 The following flags (case insensitive) are understood:
930 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 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 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 NWD : next work day counting today
946 PWD : previous work day counting today
947 DWD : next/previous work day (TomorrowFirst config) counting today
948 EASTER: select easter for this year (the M, W, D fields are ignored
950 in the recur).
951 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 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 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 Date_Cmp
967 $flag = Date_Cmp($date1,$date2);
968 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 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 DateCalc
981 $d = DateCalc($d1,$d2 [,\$err] [,$mode]);
982 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 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 $d = DateCalc("09:00:00",$someothervalue);
999 Instead, call it as:
1001 $d = DateCalc(ParseDate("09:00:00"),$someothervalue);
1003 to force it to be a date, or:
1005 $d = DateCalc(ParseDateDelta("09:00:00"),$someothervalue);
1007 to force it to be a delta. This will avoid unexpected results.
1009 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 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 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 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 See Date::Manip::Calc for some additional comments about business
1060 mode calculations.
1061 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 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 Any other non-nil value of $mode is treated as $mode=1 (approximate
1074 mode).
1075 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 $date = DateCalc("today","+ 2 business days",\$err);
1084 $date = DateCalc("today","+ 2 days",\$err,2);
1085 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 $delta = ParseDateDelta("+ 2 business days");
1091 $today = ParseDate("today");
1092 $date = DateCalc($today,$delta,\$err);
1093 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 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 Nothing is returned if an error occurs.
1106 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 Date_SetTime
1115 $date = Date_SetTime($date,$hr,$min,$sec);
1116 $date = Date_SetTime($date,$time);
1117 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 $date = ParseDate("tomorrow");
1123 $date = Date_SetTime($date,"7:30");
1124 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 $date = Date_SetTime($date,"13:30");
1130 works, but
1132 $date = Date_SetTime($date,"1:30 PM");
1134 doesn't.
1136 Date_SetDateField
1138 $date = Date_SetDateField($date,$field,$val [,$nocheck]);
1139 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 If $nocheck is non-zero, no check is made as to the validity of the
1145 date.
1146 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 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 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 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 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 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 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 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 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 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 Similar to Date_GetPrev.
1207 Date_IsHoliday
1209 $name = Date_IsHoliday($date);
1210 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 Events_List
1216 $ref = Events_List($date);
1217 $ref = Events_List($date ,0 [,$flag]);
1218 $ref = Events_List($date0,$date1 [,$flag]);
1219 This returns a list of events. Events are defined in the Events
1221 section of the config file (discussed below).
1222 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 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 The value of $flag determines the format of the information that is
1234 returned.
1235 With $flag=0, the events are returned as a reference to a list of
1237 the form:
1238 [ date, [ list_of_events ], date, [ list_of_events ], ... ]
1240 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 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 might result in the following output:
1252 Events_List("2000-04-01")
1254 => [ 2000040100:00:00, [ Spring ] ]
1255 Events_List("2000-04-01 12:30");
1257 => [ 2000040112:30:00, [ Spring, Event3 ] ]
1258 Events_List("2000-04-01",0);
1260 => [ 2000040100:00:00, [ Spring ],
1261 2000040112:00:00, [ Spring, Event3 ],
1262 2000040113:00:00, [ Spring ] ]
1263 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 Much more complicated events can be defined using recurrences.
1271 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 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 When $flag is 2, a more complex tally with no event counted twice
1283 is returned.
1284 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 The hash contains one element for each combination of events.
1291 Date_DayOfWeek
1293 $day = Date_DayOfWeek($m,$d,$y);
1294 Returns the day of the week (1 for Monday, 7 for Sunday).
1296 All arguments must be numeric.
1298 Date_SecsSince1970
1300 $secs = Date_SecsSince1970($m,$d,$y,$h,$mn,$s);
1301 Returns the number of seconds since Jan 1, 1970 00:00 (negative if
1303 date is earlier).
1304 All arguments must be numeric.
1306 Date_SecsSince1970GMT
1308 $secs = Date_SecsSince1970GMT($m,$d,$y,$h,$mn,$s);
1309 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 All arguments must be numeric.
1316 Date_DaysSince1BC
1318 $days = Date_DaysSince1BC($m,$d,$y);
1319 Returns the number of days since Dec 31, 1BC. This includes the
1321 year 0000.
1322 All arguments must be numeric.
1324 Date_DayOfYear
1326 $day = Date_DayOfYear($m,$d,$y);
1327 Returns the day of the year (001 to 366)
1329 All arguments must be numeric.
1331 Date_NthDayOfYear
1333 ($y,$m,$d,$h,$mn,$s) = Date_NthDayOfYear($y,$n);
1334 Returns the year, month, day, hour, minutes, and decimal seconds
1336 given a floating point day of the year.
1337 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 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 Date_DaysInYear
1351 $days = Date_DaysInYear($y);
1352 Returns the number of days in the year (365 or 366)
1354 Date_DaysInMonth
1356 $days = Date_DaysInMonth($m,$y);
1357 Returns the number of days in the month.
1359 Date_WeekOfYear
1361 $wkno = Date_WeekOfYear($m,$d,$y,$first);
1362 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 All arguments must be numeric.
1368 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 Date_LeapYear
1378 $flag = Date_LeapYear($y);
1379 Returns 1 if the argument is a leap year Written by David Muir
1381 Sharnoff <muir@idiom.com>
1382 Date_DaySuffix
1384 $day = Date_DaySuffix($d);
1385 Add `st', `nd', `rd', `th' to a date (i.e. 1st, 22nd, 29th). Works
1387 for international dates.
1388 Date_TimeZone
1390 $tz = Date_TimeZone;
1391 This determines and returns the local time zone. If it is unable
1393 to determine the local time zone, the following error occurs:
1394 ERROR: Date::Manip unable to determine Time Zone.
1396 See The TIME ZONES section below for more information.
1398 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 This converts a date (which MUST be in the format returned by
1406 ParseDate) from one time zone to another.
1407 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 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 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 If Date_ConvTZ is called with both $from and $to, the date is
1424 converted from the time zone $from to $to.
1425 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 Example: To convert 2/2/96 noon PST to CST (regardless of what
1432 time zone you are in, do the following:
1433 $date = ParseDate("2/2/96 noon");
1435 $date = Date_ConvTZ($date,"PST","CST");
1436 Both time zones MUST be in one of the formats listed below in the
1438 section TIME ZONES.
1439 If an error occurs, $errlev determines what happens:
1441 0 : the program dies
1443 1 : a warning is produced and nothing is returned
1444 2 : the function silently returns nothing
1445 Date_IsWorkDay
1447 $flag = Date_IsWorkDay($date [,$flag]);
1448 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 Date_NextWorkDay
1454 $date = Date_NextWorkDay($date,$off [,$flag]);
1455 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 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 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 Date_PrevWorkDay
1467 $date = Date_PrevWorkDay($date,$off [,$flag]);
1468 Similar to Date_NextWorkDay.
1470 Date_NearestWorkDay
1472 $date = Date_NearestWorkDay($date [,$tomorrowfirst]);
1473 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 DateManipVersion
1486 $version = DateManipVersion;
1487 Returns the version of Date::Manip.
1489
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 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 The following time zone names are currently understood (and can be used
1503 in parsing dates). These are zones defined in RFC 822.
1504 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 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 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 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 The list of abbreviations available is documented in the
1556 Date::Manip::DM5abbrevs document.
1557 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 $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 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 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 US/Pacific
1579 US/Mountain
1580 US/Central
1581 US/Eastern
1582 Canada/Pacific
1583 Canada/Mountain
1584 Canada/Central
1585 Canada/Eastern
1586
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 At the top of the Manip.pm file, there is a section which contains all
1593 customization variables. These provide the default values.
1594 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 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 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 Finally, any variables passed in through Date_Init override all other
1614 values.
1615 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 VARIABLE = VALUE
1620 For example, to make the default language French, include the line:
1622 Language = French
1624 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 A line which starts with an asterisk (*) designates a new section. For
1630 example, the HOLIDAY section starts with a line:
1631 *Holiday
1633 The various sections are defined below.
1635
1637 All Date::Manip variables which can be used are described in the
1638 following section.
1639 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 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 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 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 By default, no global config file is read. Any time a global
1666 config file is read, the holidays are erased.
1667 Paths may have a tilde (~) expansion on platforms where this is
1669 supported (currently Unix and VMS).
1670 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 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 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 Paths may have a tilde (~) expansion on platforms where this is
1685 supported (currently Unix and VMS).
1686 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 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 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 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 TZ If set, this defines the local time zone. See the TIME ZONES
1719 section above for information on its format.
1720 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 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 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 YYYYMMDDHH:MN:SS
1744 It has been suggested that I remove the colons (:) to shorten this
1746 to:
1747 YYYYMMDDHHMNSS
1749 The main advantage of this is that some databases are colon
1751 delimited which makes storing a date from Date::Manip tedious.
1752 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 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 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 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 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 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 The time in both can be in any valid time format (including
1785 international formats), but seconds will be ignored.
1786 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 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 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 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 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 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 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 A better solution would be to restart the process on the two days
1842 per year where the time zone switch occurs.
1843 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 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 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
1862 The holiday section of the config file is used to define holidays.
1863 Each line is of the form:
1864 DATE = HOLIDAY
1866 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 DATE is a string which can be parsed to give a valid date in any year.
1873 It can be of the form
1874 Date
1876 Date + Delta
1877 Date - Delta
1878 Recur
1879 A valid holiday section would be:
1881 *Holiday
1883 1/1 = New Year's Day
1885 third Monday in Feb = Presidents' Day
1886 fourth Thu in Nov = Thanksgiving
1887 # The Friday after Thanksgiving is an unnamed holiday most places
1889 fourth Thu in Nov + 1 day =
1890 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 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 12/25 - 1 business day =
1901 The dates may optionally contain the year. For example, the dates
1903 1/1
1905 1/1/1999
1906 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 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 25/12/2002 = Christmas
1918 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 1*12:0:24:0:0:0*FW1 = Christmas
1925 NOTE: It was pointed out to me that using a similar type recurrence to
1927 define New Years does not work. The recurrence:
1928 1*12:0:31:0:0:0*FW1
1930 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 Use the recurrence:
1937 1*1:0:1:0:0:0*NWD
1939 instead.
1941 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 1*12:0:24:0:0:0*FW1 = Christmas
1947 1*12:0:25:0:0:0*FW1 = Boxing
1948 1*12:0:24:0:0:0*FW1 = Christmas
1950 01*12:0:24:0:0:0*FW1 = Boxing
1951 1*12:0:24:0:0:0*FW1 = Christmas
1953 1*12:0:25:0:0:0*FW1,a = Boxing
1954 The following examples will NOT work:
1956 1*12:0:24:0:0:0*FW1 = Christmas
1958 1*12:0:24:0:0:0*FW2 = Boxing
1959 1*12:0:24:0:0:0*FW1 = Christmas
1961 1*12:0:24:0:0:0*FW1 = Boxing
1962 The reasoning behind all this is as follows:
1964 Holidays go into affect the minute they are parsed. So, in the case
1966 of:
1967 1*12:0:24:0:0:0*FW1 = Christmas
1969 1*12:0:24:0:0:0*FW2 = Boxing
1970 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 An good alternative would appear to be:
1977 1*12:0:24:0:0:0*FW1 = Christmas
1979 1*12:0:24:0:0:0*FW1 = Boxing
1980 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 To fix this, make them unique with either a fake flag (which is
1987 ignored):
1988 1*12:0:24:0:0:0*FW1,a = Boxing
1990 or adding an innocuous 0 somewhere:
1992 01*12:0:24:0:0:0*FW1 = Boxing
1994 The other good alternative would be to make two completely different
1996 recurrences such as:
1997 1*12:0:24:0:0:0*FW1 = Christmas
1999 1*12:0:25:0:0:0*FW1 = Boxing
2000 At times, you may want to switch back and forth between two holiday
2002 files. This can be done by calling the following:
2003 Date_Init("EraseHolidays=1","PersonalCnf=FILE1");
2005 ...
2006 Date_Init("EraseHolidays=1","PersonalCnf=FILE2");
2007 ...
2008
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 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 Events can be based at any time of the day, and may be of any
2019 duration.
2020 Events don't affect business mode calculations
2022 Unlike holidays, events are completely ignored when doing business
2023 mode calculations.
2024 Whereas holidays were added with business mode math in mind, events
2026 were added with calendar and scheduling applications in mind.
2027 Every line in the events section is of the form:
2029 EVENT = NAME
2031 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 Date
2036 Date*
2037 Date ; Date
2039 Date ; Delta
2040 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 Both Date* and Recur* refer to an event very similar to a holiday which
2048 goes from midnight to midnight.
2049 Date and Recur refer to events which occur at the time given and with a
2051 duration of 1 hour.
2052 Events given by "Date ; Date", "Date ; Delta", and "Recur ; Delta"
2054 contain both the starting date and either ending date or duration.
2055 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
2063 The following are not bugs in Date::Manip, but they may give some
2064 people problems.
2065 Unable to determine Time Zone
2067 Perhaps the most common problem occurs when you get the error:
2068 Error: Date::Manip unable to determine Time Zone.
2070 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 Windows NT does not seem to set the time zone by default. From the
2080 Perl-Win32-Users mailing list:
2081 > 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 This might help out some NT users.
2091 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 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 When running outside the tests, Date::Manip has to rely on its
2105 other methods for determining the time zone.
2106 Missing date formats
2108 Please see the Date::Manip::Problems document for a discussion.
2109 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 $ENV{OS} = Windows_NT
2117 $ENV{OS} = Windows_95
2118 to your script before
2120 use Date::Manip
2122 Date::Manip is slow
2124 The reasons for this are covered in the SHOULD I USE DATE::MANIP
2125 section above.
2126 Some things that will definitely help:
2128 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 ISO-8601 dates are parsed first and fastest. Use them whenever
2134 possible.
2135 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 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 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 Never call Date_Init more than once. Unless you're doing something
2151 very strange, there should never be a reason to anyway.
2152 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 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 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 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 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 use Date::Manip;
2193 use Memoize;
2194 memoize('ParseDate');
2195 ...
2196 @i=sort sortDate @dates;
2197 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 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
2211 Daylight Saving Times
2212 Date::Manip does not handle daylight saving time, though it does
2213 handle time zones to a certain extent. Converting from EST to PST
2214 works fine. Going from EST to PDT is unreliable.
2215 The following examples are run in the winter of the US East coast
2217 (i.e. in the EST time zone).
2218 print UnixDate(ParseDate("6/1/97 noon"),"%u"),"\n";
2220 => Sun Jun 1 12:00:00 EST 1997
2221 June 1 EST does not exist. June 1st is during EDT. It should
2223 print:
2224 => Sun Jun 1 00:00:00 EDT 1997
2226 Even explicitly adding the time zone doesn't fix things (if
2228 anything, it makes them worse):
2229 print UnixDate(ParseDate("6/1/97 noon EDT"),"%u"),"\n";
2231 => Sun Jun 1 11:00:00 EST 1997
2232 Date::Manip converts everything to the current time zone (EST in
2234 this case).
2235 Related problems occur when trying to do date calculations over a
2237 time zone change. These calculations may be off by an hour.
2238 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 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
2248 Please refer to the Date::Manip::Problems documentation for information
2249 on submitting bug reports or questions to the author.
2250
2252 Date::Manip - main module documentation
2253
2255 This script is free software; you can redistribute it and/or modify it
2256 under the same terms as Perl itself.
2257
2259 Sullivan Beck (sbeck@cpan.org)
2260perl v5.34.1 2022-06-06 Date::Manip::DM5(3)