1Manip(3) User Contributed Perl Documentation Manip(3)
2
6 Date::Manip - date manipulation routines
7
9 use Date::Manip;
10 $version = DateManipVersion;
12 $date = ParseDate(\@args);
14 $date = ParseDate($string);
15 $date = ParseDate(\$string);
16 @date = UnixDate($date,@format);
18 $date = UnixDate($date,@format);
19 $delta = ParseDateDelta(\@args);
21 $delta = ParseDateDelta($string);
22 $delta = ParseDateDelta(\$string);
23 @str = Delta_Format($delta,$dec,@format);
25 $str = Delta_Format($delta,$dec,@format);
26 $recur = ParseRecur($string,$base,$date0,$date1,$flags);
28 @dates = ParseRecur($string,$base,$date0,$date1,$flags);
29 $flag = Date_Cmp($date1,$date2);
31 $d = DateCalc($d1,$d2 [,$errref] [,$del]);
33 $date = Date_SetTime($date,$hr,$min,$sec);
35 $date = Date_SetTime($date,$time);
36 $date = Date_SetDateField($date,$field,$val [,$nocheck]);
38 $date = Date_GetPrev($date,$dow,$today,$hr,$min,$sec);
40 $date = Date_GetPrev($date,$dow,$today,$time);
41 $date = Date_GetNext($date,$dow,$today,$hr,$min,$sec);
43 $date = Date_GetNext($date,$dow,$today,$time);
44 $name = Date_IsHoliday($date);
46 $listref = Events_List($date);
48 $listref = Events_List($date0,$date1);
49 $date = Date_ConvTZ($date);
51 $date = Date_ConvTZ($date,$from);
52 $date = Date_ConvTZ($date,"",$to);
53 $date = Date_ConvTZ($date,$from,$to);
54 $flag = Date_IsWorkDay($date [,$flag]);
56 $date = Date_NextWorkDay($date,$off [,$time]);
58 $date = Date_PrevWorkDay($date,$off [,$time]);
60 $date = Date_NearestWorkDay($date [,$tomorrowfirst]);
62 &Date_Init();
64 &Date_Init("VAR=VAL","VAR=VAL",...);
65 @list = Date_Init();
66 @list = Date_Init("VAR=VAL","VAR=VAL",...);
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 explicitely 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 explicitely 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 rou‐
80 tines, they are available for use with a few caveats. Since little or
81 no error checking is done, it is the responsibility of the programmer
82 to ensure that valid data (AND valid dates) are passed to them. Pass‐
83 ing invalid data (such as a non-numeric month) or invalid dates (Feb
84 31) will fail in unpredictable ways (possibly returning erroneous
85 results). Also, since Date_Init is not called by these, it must be
86 called explicitely by the programmer before using these routines.
87 In the following routines, $y may be entered as either a 2 or 4 digit
89 year (it will be converted to a 4 digit year based on the variable
90 YYtoYYYY described below). Month and day should be numeric in all
91 cases. Most (if not all) of the information below can be gotten from
92 UnixDate which is really the way I intended it to be gotten, but there
93 are reasons to use these (these are significantly faster).
94 $day = Date_DayOfWeek($m,$d,$y);
96 $secs = Date_SecsSince1970($m,$d,$y,$h,$mn,$s);
97 $secs = Date_SecsSince1970GMT($m,$d,$y,$h,$mn,$s);
98 $days = Date_DaysSince1BC($m,$d,$y);
99 $day = Date_DayOfYear($m,$d,$y);
100 ($y,$m,$d,$h,$mn,$s) = Date_NthDayOfYear($y,$n);
101 $days = Date_DaysInYear($y);
102 $days = Date_DaysInMonth($m,$y);
103 $wkno = Date_WeekOfYear($m,$d,$y,$first);
104 $flag = Date_LeapYear($y);
105 $day = Date_DaySuffix($d);
106 $tz = Date_TimeZone();
107
109 This is a set of routines designed to make any common date/time manipu‐
110 lation easy to do. Operations such as comparing two times, calculating
111 a time a given amount of time from another, or parsing international
112 times are all easily done. From the very beginning, the main focus of
113 Date::Manip has been to be able to do ANY desired date/time operation
114 easily, not necessarily quickly. Also, it is definitely oriented
115 towards the type of operations we (as people) tend to think of rather
116 than those operations used routinely by computers. There are other
117 modules that can do a subset of the operations available in Date::Manip
118 much quicker than those presented here, so be sure to read the section
119 SHOULD I USE DATE::MANIP below before deciding which of the Date and
120 Time modules from CPAN is for you.
121 Date::Manip deals with time as it is presented the Gregorian calendar
123 (the one currently in use). The Julian calendar defined leap years as
124 every 4th year. The Gregorian calendar improved this by making every
125 100th year NOT a leap year, unless it was also the 400th year. The
126 Gregorian calendar has been extrapolated back to the year 0000 AD and
127 forward to the year 9999 AD. Note that in historical context, the
128 Julian calendar was in use until 1582 when the Gregorian calendar was
129 adopted by the Catholic church. Protestant countries did not accept it
130 until later; Germany and Netherlands in 1698, British Empire in 1752,
131 Russia in 1918. Note that the Gregorian calendar is itself imperfect
132 and at some point will need to be corrected. No attempt is made to
133 correct for that, and my great great great grandchildren will be long
134 dead before this even occurs, so it's not an immediate concern. Yes,
135 this is the same type of attitute that caused the great Y2K problem...
136 but I have an excuse: I don't know what the correction will be, so I
137 can't possible implement it. Nobody doubted that the year after 1999
138 would be known as 2000 :-).
139 Date::Manip is therefore not equipped to truly deal with historical
141 dates, but should be able to perform (virtually) any operation dealing
142 with a modern time and date.
143 Date::Manip has (or will have) functionality to work with several fun‐
145 damental types of data.
146 DATE
148 Although the word date is used extensively here, it is actually
149 somewhat misleading. Date::Manip works with the full date AND time
150 (year, month, day, hour, minute, second and weeks when appropri‐
151 ate). It doesn't work with fractional seconds. Timezones are also
152 supported to some extent.
153 NOTE: Much better support for timezones (including Daylight Sav‐
155 ings Time) is planned for the future.
156 DELTA
158 This refers to a duration or elapsed time. One thing to note is
159 that, as used in this module, a delta refers only to the amount of
160 time elapsed. It includes no information about a starting or end‐
161 ing time.
162 RECURRENCE
164 A recurrence is simply a notation for defining when a recurring
165 event occurs. For example, if an event occurs every other Friday
166 or every 4 hours, this can be defined as a recurrence. With a
167 recurrence and a starting and ending date, you can get a list of
168 dates in that period when a recurring event occurs.
169 GRAIN
171 The granularity of a time basically refers to how accurate you wish
172 to treat a date. For example, if you want to compare two dates to
173 see if they are identical at a granularity of days, then they only
174 have to occur on the same day. At a granularity of an hour, they
175 have to occur within an hour of each other, etc.
176 NOTE: Support for this does not exist, but may be added in the
178 future.
179 HOLIDAYS and EVENTS
181 These are basically a named time. Holidays are used in business
182 mode calculations. Events allow things like calendar and schedul‐
183 ing applications to be designed much more easily.
184 Among other things, Date::Manip allow you to:
186 1. Enter a date and be able to choose any format convenient
188 2. Compare two dates, entered in widely different formats
190 to determine which is earlier
191 3. Extract any information you want from ANY date using a
193 format string similar to the Unix date command
194 4. Determine the amount of time between two dates
196 5. Add a time offset to a date to get a second date (i.e.
198 determine the date 132 days ago or 2 years and 3 months
199 after Jan 2, 1992)
200 6. Work with dates with dates using international formats
202 (foreign month names, 12/10/95 referring to October
203 rather than December, etc.).
204 7. To find a list of dates where a recurring event happens.
206 Each of these tasks is trivial (one or two lines at most) with this
208 package.
209
211 In the documentation below, US formats are used, but in most (if not
212 all) cases, a non-English equivalent will work equally well.
213 1. Parsing a date from any convenient format
215 $date = ParseDate("today");
217 $date = ParseDate("1st thursday in June 1992");
218 $date = ParseDate("05/10/93");
219 $date = ParseDate("12:30 Dec 12th 1880");
220 $date = ParseDate("8:00pm december tenth");
221 if (! $date) {
222 # Error in the date
223 }
224 2. Compare two dates
226 $date1 = ParseDate($string1);
228 $date2 = ParseDate($string2);
229 $flag = Date_Cmp($date1,$date2);
230 if ($flag<0) {
231 # date1 is earlier
232 } elsif ($flag==0) {
233 # the two dates are identical
234 } else {
235 # date2 is earlier
236 }
237 3. Extract information from a date.
239 print &UnixDate("today","It is now %T on %b %e, %Y.");
241 => "It is now 13:24:08 on Feb 3, 1996."
242 4. The amount of time between two dates.
244 $date1 = ParseDate($string1);
246 $date2 = ParseDate($string2);
247 $delta = DateCalc($date1,$date2,\$err);
248 => 0:0:WK:DD:HH:MM:SS the weeks, days, hours, minutes,
249 and seconds between the two
250 $delta = DateCalc($date1,$date2,\$err,1);
251 => YY:MM:WK:DD:HH:MM:SS the years, months, etc. between
252 the two
253 Read the documentation below for an explanation of the
255 difference.
256 5. To determine a date a given offset from another.
258 $date = DateCalc("today","+ 3hours 12minutes 6 seconds",\$err);
260 $date = DateCalc("12 hours ago","12:30 6Jan90",\$err);
261 It even works with business days:
263 $date = DateCalc("today","+ 3 business days",\$err);
265 6. To work with dates in another language.
267 &Date_Init("Language=French","DateFormat=non-US");
269 $date = ParseDate("1er decembre 1990");
270 7. To find a list of dates where a recurring event happens
272 (including quite complex ones).
273 # To find the 2nd tuesday of every month
275 @date = ParseRecur("0:1*2:2:0:0:0",$base,$start,$stop);
276 # To find the Monday after easter in 1997-1999.
278 @date = ParseRecur("*1997-1999:0:0:0:0:0:0*EASTER,ND1");
279 NOTE: Some date forms do not work as well in languages other than Eng‐
281 lish, but this is not because Date::Manip is incapable of doing so
282 (almost nothing in this module is language dependent). It is simply
283 that I do not have the correct translation available for some words.
284 If there is a date form that works in English but does not work in a
285 language you need, let me know and if you can provide me the transla‐
286 tion, I will fix Date::Manip.
287
289 If you look in CPAN, you'll find that there are a number of Date and
290 Time packages. Is Date::Manip the one you should be using? In my
291 opinion, the answer is no most of the time. This sounds odd coming
292 from the author of the software, but read on.
293 Date::Manip is written entirely in perl. It's the most powerful of the
295 date modules. It's also the biggest and slowest.
296 Since Date::Manip is written entirely in perl, and depends on no other
298 module not in a standard perl distribution, Date::Manip has no depen‐
299 dancies to meet. Other modules have dependancies on a C compiler or
300 other perl modules. Since it is fairly easy to satisfy these dependan‐
301 cies for anyone who is reasonably familiar with perl modules, this is
302 not a huge advantage that Date::Manip has.
303 On the other hand, simpler perl modules tend to be faster than
305 Date::Manip, and modules written in C are significantly faster than
306 their perl counterparts (at least if they're done right). The TimeDate
307 and Time-modules modules are written in perl, but are much simpler (and
308 hence, faster) than Date::Manip. The Date::Calc module is written in C
309 and is a good module for doing many date calculations much faster than
310 Date::Manip. Between these three, most of your common date operations
311 can be done.
312 It should be noted that using the Memoize module in conjunction with
314 Date::Manip can have a huge impact on it's performance, depending on
315 the types of operations you do. Your mileage may vary though.
316 Date::Manip is certainly the most powerful of the Date modules. To the
318 best of my knowledge, it will do everything that any other date module
319 will do (not just the ones I listed above), and there are a number of
320 features that Date::Manip has that none of the other modules have.
321 Date::Manip is the "Swiss Army Knife" of Date modules. I'm trying to
322 build a library which can do _EVERY_ conceivable date/time manipulation
323 that you'll run into in everyday life.
324 Although I am working on making Date::Manip faster, it will never be as
326 fast as other modules. And before anyone asks, Date::Manip will never
327 be translated to C (at least by me). I write C because I have to. I
328 write perl because I like to. Date::Manip is something I do because it
329 interests me, not something I'm paid for.
330 Date::Manip is also big. The last time I looked, it's one of the
332 largest CPAN modules there is. If you ignore modules like Tk, LWP,
333 etc. which are actually packages of modules, it may be the largest.
334 It's true that Date::Manip will do almost every date operation you
335 could imagine... but you rarely need all that power. I'm working on
336 reducing the footprint of Date::Manip, but even at it's slimmest, it'll
337 outweigh the other modules by a good bit.
338 If you are going to be using the module in cases where performance is
340 an important factor (started up in a CGI program being run by your web
341 server 5,000 times a second), you should check out one of the other
342 Date or Time modules in CPAN. If you're only doing fairly simple date
343 operations (parsing common date formats, finding the difference between
344 two dates, etc.), the other modules will almost certainly suffice. If
345 you're doing one operation very repetitively (parsing 10,000 dates from
346 a database), you are probably better off writing your own functions
347 (perhaps bypassing all date modules entirely) designed specifically for
348 your needs.
349 On the other hand, if you want one solution for all your date needs,
351 don't need peak speed, or are trying to do more exotic date operations,
352 Date::Manip is for you. Operations on things like business dates, for‐
353 eign language dates, holidays and other recurring events, etc. are
354 available more-or-less exclusively in Date::Manip.
355
357 ParseDate
358 $date = ParseDate(\@args);
359 $date = ParseDate($string);
360 $date = ParseDate(\$string);
361 This takes an array or a string containing a date and parses it.
363 When the date is included as an array (for example, the arguments
364 to a program) the array should contain a valid date in the first
365 one or more elements (elements after a valid date are ignored).
366 Elements containing a valid date are shifted from the array. The
367 largest possible number of elements which can be correctly inter‐
368 preted as a valid date are always used. If a string is entered
369 rather than an array, that string is tested for a valid date. The
370 string is unmodified, even if passed in by reference.
371 The real work is done in the ParseDateString routine.
373 The ParseDate routine is primarily used to handle command line
375 arguments. If you have a command where you want to enter a date as
376 a command line argument, you can use Date::Manip to make something
377 like the following work:
378 mycommand -date Dec 10 1997 -arg -arg2
380 No more reading man pages to find out what date format is required
382 in a man page.
383 Historical note: this is originally why the Date::Manip routines
385 were written (though long before they were released as the
386 Date::Manip module). I was using a bunch of programs (primarily
387 batch queue managers) where dates and times were entered as command
388 line options and I was getting highly annoyed at the many different
389 (but not compatible) ways that they had to be entered. Date::Manip
390 originally consisted of basically 1 routine which I could pass
391 "@ARGV" to and have it remove a date from the beginning.
392 ParseDateString
394 $date = ParseDateString($string);
395 This routine is called by ParseDate, but it may also be called
397 directly to save some time (a negligable amount).
398 NOTE: One of the most frequently asked questions that I have got‐
400 ten is how to parse seconds since the epoch. ParseDateString can‐
401 not simply parse a number as the seconds since the epoch (it con‐
402 flicts with some ISO-8601 date formats). There are two ways to get
403 this information. First, you can do the following:
404 $secs = ... # seconds since Jan 1, 1970 00:00:00 GMT
406 $date = &DateCalc("Jan 1, 1970 00:00:00 GMT",$secs);
407 Second, you can call it directly as:
409 $date = &ParseDateString("epoch $secs");
411 To go backwards, just use the "%s" format of UnixDate:
413 $secs = &UnixDate($date,"%s");
415 A full date actually includes 2 parts: date and time. A time must
417 include hours and minutes and can optionally include seconds, frac‐
418 tional seconds, an am/pm type string, and a timezone. For example:
419 [at] HH:MN [Zone]
421 [at] HH:MN [am] [Zone]
422 [at] HH:MN:SS [am] [Zone]
423 [at] HH:MN:SS.SSSS [am] [Zone]
424 [at] HH am [Zone]
425 Hours can be written using 1 or 2 digits, but the single digit form
427 may only be used when no ambiguity is introduced (i.e. when it is
428 not immediately preceded by a digit).
429 A time is usually entered in 24 hour mode, but 12 hour mode can be
431 used as well if AM/PM are entered (AM can be entered as AM or A.M.
432 or other variations depending on the language).
433 Fractional seconds are also supported in parsing but the fractional
435 part is discarded (with NO rounding ocurring).
436 Timezones always appear immediately after the time. A number of
438 different forms are supported (see the section TIMEZONEs below).
439 Incidentally, the time is removed from the date before the date is
441 parsed, so the time may appear before or after the date, or between
442 any two parts of the date.
443 Valid date formats include the ISO 8601 formats:
445 YYYYMMDDHHMNSSF...
447 YYYYMMDDHHMNSS
448 YYYYMMDDHHMN
449 YYYYMMDDHH
450 YY-MMDDHHMNSSF...
451 YY-MMDDHHMNSS
452 YY-MMDDHHMN
453 YY-MMDDHH
454 YYYYMMDD
455 YYYYMM
456 YYYY
457 YY-MMDD
458 YY-MM
459 YY
460 YYYYwWWD ex. 1965-W02-2
461 YYwWWD
462 YYYYDOY ex. 1965-045
463 YYDOY
464 In the above list, YYYY and YY signify 4 or 2 digit years, MM, DD,
466 HH, MN, SS refer to two digit month, day, hour, minute, and second
467 respectively. F... refers to fractional seconds (any number of
468 digits) which will be ignored. In all cases, the date and time
469 parts may be separated by the letter "T" (but this is optional), so
470 2002-12-10-12:00:00
471 2002-12-10T12:00:00 are identical.
472 The last 4 formats can be explained by example: 1965-w02-2 refers
474 to Tuesday (day 2) of the 2nd week of 1965. 1965-045 refers to the
475 45th day of 1965.
476 In all cases, parts of the date may be separated by dashes "-". If
478 this is done, 1 or 2 digit forms of MM, DD, etc. may be used. All
479 dashes are optional except for those given in the table above
480 (which MUST be included for that format to be correctly parsed).
481 So 19980820, 1998-0820, 1998-08-20, 1998-8-20, and 199808-20 are
482 all equivalent, but that date may NOT be written as 980820 (it must
483 be written as 98-0820).
484 NOTE: Even though not allowed in the standard, the timezone for an
486 ISO-8601 date is flexible and may be any of the timezones under‐
487 stood by Date::Manip.
488 Additional date formats are available which may or may not be com‐
490 mon including:
491 MM/DD **
493 MM/DD/YY **
494 MM/DD/YYYY **
495 mmmDD DDmmm mmmYYYY/DD mmmYYYY
497 mmmDD/YY DDmmmYY DD/YYmmm YYYYmmmDD YYYYmmm
498 mmmDDYYYY DDmmmYYYY DDYYYYmmm YYYY/DDmmm
499 Where mmm refers to the name of a month. All parts of the date can
501 be separated by valid separators (space, "/", or "."). The separa‐
502 tor "-" may be used as long as it doesn't conflict with an ISO 8601
503 format, but this is discouraged since it is easy to overlook con‐
504 flicts. For example, the format MM/DD/YY is just fine, but MM-DD-
505 YY does not work since it conflicts with YY-MM-DD. To be safe, if
506 "-" is used as a separator in a non-ISO format, they should be
507 turned into "/" before calling the Date::Manip routines. As with
508 ISO 8601 formats, all separators are optional except for those
509 given as a "/" in the list above.
510 ** Note that with these formats, Americans tend to write month
512 first, but many other countries tend to write day first. The lat‐
513 ter behavior can be obtained by setting the config variable Date‐
514 Format to something other than "US" (see CUSTOMIZING DATE::MANIP
515 below).
516 Date separators are treated very flexibly (they are converted to
518 spaces), so the following dates are all equivalent:
519 12/10/1965
521 12-10 / 1965
522 12 // 10 -. 1965
523 In some cases, this may actually be TOO flexible, but no attempt is
525 made to trap this.
526 Years can be entered as 2 or 4 digits, days and months as 1 or 2
528 digits. Both days and months must include 2 digits whenever they
529 are immediately adjacent to another numeric part of the date or
530 time. Date separators are required if single digit forms of DD or
531 MM are used. If separators are not used, the date will either be
532 unparsable or will get parsed incorrectly.
533 Miscellaneous other allowed formats are:
535 which dofw in mmm in YY "first sunday in june
536 1996 at 14:00" **
537 dofw week num YY "sunday week 22 1995" **
538 which dofw YY "22nd sunday at noon" **
539 dofw which week YY "sunday 22nd week in
540 1996" **
541 next/last dofw "next friday at noon"
542 next/last week/month "next month"
543 in num days/weeks/months "in 3 weeks at 12:00"
544 num days/weeks/months later "3 weeks later"
545 num days/weeks/months ago "3 weeks ago"
546 dofw in num week "Friday in 2 weeks"
547 in num weeks dofw "in 2 weeks on friday"
548 dofw num week ago "Friday 2 weeks ago"
549 num week ago dofw "2 weeks ago friday"
550 last day in mmm in YY "last day of October"
551 dofw "Friday" (Friday of
552 current week)
553 Nth "12th", "1st" (day of
554 current month)
555 epoch SECS seconds since the epoch
556 (negative values are
557 supported)
558 ** Note that the formats "sunday week 22" and "22nd sunday" give
560 very different bahaviors. "sunday week 22" returns the sunday of
561 the 22nd week of the year based on how week 1 is defined. ISO 8601
562 defines week one to contain Jan 4, so "sunday week 1" might be the
563 first or second sunday of the current year, or the last sunday of
564 the previous year. "22nd sunday" gives the actual 22nd time sunday
565 occurs in a given year, regardless of the definition of a week.
566 Note that certain words such as "in", "at", "of", etc. which com‐
568 monly appear in a date or time are ignored. Also, the year is
569 always optional.
570 In addition, the following strings are recognized:
572 today (exactly now OR today at a given time if a time is
573 specified)
574 now (synonym for today)
575 yesterday (exactly 24 hours ago unless a time is specified)
576 tomorrow (exactly 24 hours from now unless a time is specifed)
577 noon (12:00:00)
578 midnight (00:00:00) Other languages have similar (and in some
579 cases additional) strings.
580 Some things to note:
582 All strings are case insensitive. "December" and "DEceMBer" both
584 work.
585 When a part of the date is not given, defaults are used: year
587 defaults to current year; hours, minutes, seconds to 00.
588 The year may be entered as 2 or 4 digits. If entered as 2 digits,
590 it will be converted to a 4 digit year. There are several ways to
591 do this based on the value of the YYtoYYYY variable (described
592 below). The default behavior it to force the 2 digit year to be in
593 the 100 year period CurrYear-89 to CurrYear+10. So in 1996, the
594 range is [1907 to 2006], and the 2 digit year 05 would refer to
595 2005 but 07 would refer to 1907. See CUSTOMIZING DATE::MANIP below
596 for information on YYtoYYYY for other methods.
597 Dates are always checked to make sure they are valid.
599 In all of the formats, the day of week ("Friday") can be entered
601 anywhere in the date and it will be checked for accuracy. In other
602 words,
603 "Tue Jul 16 1996 13:17:00" will work but
604 "Jul 16 1996 Wednesday 13:17:00" will not (because Jul 16, 1996
605 is Tuesday, not Wednesday). Note that depending on where the week‐
606 day comes, it may give unexpected results when used in array con‐
607 text (with ParseDate). For example, the date
608 ("Jun","25","Sun","1990") would return June 25 of the current year
609 since Jun 25, 1990 is not Sunday.
610 The times "12:00 am", "12:00 pm", and "midnight" are not well
612 defined. For good or bad, I use the following convention in
613 Date::Manip:
614 midnight = 12:00am = 00:00:00
615 noon = 12:00pm = 12:00:00 and the day goes from 00:00:00 to
616 23:59:59. In other words, midnight is the beginning of a day
617 rather than the end of one. The time 24:00:00 is also allowed
618 (though it is automatically transformed to 00:00:00 of the follow‐
619 ing day).
620 The format of the date returned is YYYYMMDDHH:MM:SS. The advantage
622 of this time format is that two times can be compared using simple
623 string comparisons to find out which is later. Also, it is readily
624 understood by a human. Alternate forms can be used if that is more
625 convenient. See Date_Init below and the config variable Internal.
626 NOTE: The format for the date is going to change at some point in
628 the future to YYYYMMDDHH:MN:SS+HHMN*FLAGS. In order to maintain
629 compatibility, you should use UnixDate to extract information from
630 a date, and Date_Cmp to compare two dates. The simple string com‐
631 parison will only work for dates in the same timezone.
632 UnixDate
634 @date = UnixDate($date,@format);
635 $date = UnixDate($date,@format);
636 This takes a date and a list of strings containing formats roughly
638 identical to the format strings used by the UNIX date(1) command.
639 Each format is parsed and an array of strings corresponding to each
640 format is returned.
641 $date may be any string that can be parsed by ParseDateString.
643 The format options are:
645 Year
647 %y year - 00 to 99
648 %Y year - 0001 to 9999
649 %G year, Sunday as first
650 day of week - 0001 to 9999 (see below)
651 %L year, Monday as first
652 day of week - 0001 to 9999 (see below)
653 Month, Week
654 %m month of year - 01 to 12
655 %f month of year - " 1" to "12"
656 %b,%h month abbreviation - Jan to Dec
657 %B month name - January to December
658 %U week of year, Sunday
659 as first day of week - 01 to 53 (see below)
660 %W week of year, Monday
661 as first day of week - 01 to 53 (see below)
662 Day
663 %j day of the year - 001 to 366
664 %d day of month - 01 to 31
665 %e day of month - " 1" to "31"
667 %v weekday abbreviation - " S"," M"," T"," W","Th"," F","Sa"
668 %a weekday abbreviation - Sun to Sat
669 %A weekday name - Sunday to Saturday
670 %w day of week - 1 (Monday) to 7 (Sunday)
671 %E day of month with suffix - 1st, 2nd, 3rd...
672 Hour
673 %H hour - 00 to 23
674 %k hour - " 0" to "23"
675 %i hour - " 1" to "12"
676 %I hour - 01 to 12
677 %p AM or PM
678 Minute, Second, Timezone
679 %M minute - 00 to 59
680 %S second - 00 to 59
681 %s seconds from 1/1/1970 GMT- negative if before 1/1/1970
682 %o seconds from Jan 1, 1970
683 in the current time zone
684 %Z timezone - "EDT"
685 %z timezone as GMT offset - "+0100"
686 Date, Time
687 %c %a %b %e %H:%M:%S %Y - Fri Apr 28 17:23:15 1995
688 %C,%u %a %b %e %H:%M:%S %z %Y - Fri Apr 28 17:25:57 EDT 1995
689 %g %a, %d %b %Y %H:%M:%S %z - Fri, 28 Apr 1995 17:23:15 EDT
690 %D %m/%d/%y - 04/28/95
691 %x %m/%d/%y or %d/%m/%y - 04/28/95 or 28/04/28
692 (Depends on DateFormat variable)
693 %l date in ls(1) format
694 %b %e $H:$M - Apr 28 17:23 (if within 6 months)
695 %b %e %Y - Apr 28 1993 (otherwise)
696 %r %I:%M:%S %p - 05:39:55 PM
697 %R %H:%M - 17:40
698 %T,%X %H:%M:%S - 17:40:58
699 %V %m%d%H%M%y - 0428174095
700 %Q %Y%m%d - 19961025
701 %q %Y%m%d%H%M%S - 19961025174058
702 %P %Y%m%d%H%M%S - 1996102517:40:58
703 %O %Y-%m-%dT%H:%M:%S - 1996-10-25T17:40:58
704 %F %A, %B %e, %Y - Sunday, January 1, 1996
705 %J %G-W%W-%w - 1997-W02-2
706 %K %Y-%j - 1997-045
707 Other formats
708 %n insert a newline character
709 %t insert a tab character
710 %% insert a `%' character
711 %+ insert a `+' character
712 The following formats are currently unused but may be used in the future:
713 N 1234567890 !@#$^&*()_⎪-=\`[];',./~{}:<>?
714 They currently insert the character following the %, but may (and probably
715 will) change in the future as new formats are added.
716 If a lone percent is the final character in a format, it is
718 ignored.
719 Note that the ls format (%l) applies to date within the past OR
721 future 6 months!
722 The %U, %W, %L, and %G formats are used to support the ISO-8601
724 format: YYYY-wWW-D. In this format, a date is written as a year,
725 the week of the year, and the day of the week. Technically, the
726 week may be considered to start on any day of the week, but Sunday
727 and Monday are the both common choices, so both are supported.
728 The %W and %G formats return the week-of-year and the year treating
730 weeks as starting on Monday.
731 The %U and %L formats return the week-of-year and the year treating
733 weeks as starting on Sunday.
734 Most of the time, the %L and %G formats returns the same value as
736 the %Y format, but there is a problem with days occuring in the
737 first or last week of the year.
738 The ISO-8601 representation of Jan 1, 1993 written in the YYYY-wWW-
740 D format is actually 1992-W53-5. In other words, Jan 1 is treates
741 as being in the last week of the preceding year. Depending on the
742 year, days in the first week of a year may belong to the previous
743 year, and days in the final week of a year may belong to the next
744 year. The week is assigned to the year which has most of the days.
745 For example, if the week starts on Sunday, then the last week of
746 2003 is 2003-12-28 to 2004-01-03. This week is assigned to 2003
747 since 4 of the days in it are in 2003 and only 3 of them are in
748 2004. The first week of 2004 starts on 2004-01-04.
749 The %U and %W formats return a week-of-year number from 01 to 53.
751 %J returns the full ISO-8601 format (%G-W%W-%w).
753 The %s and %o formats return negative values if the date is before
755 the start of the epoch. Other unix utilities would return an
756 error, or a zero, so if you are going to use Date::Manip in conjuc‐
757 tion with these, be sure to check for a negative value.
758 The formats used in this routine were originally based on date.pl
760 (version 3.2) by Terry McGonigal, as well as a couple taken from
761 different versions of the Solaris date(1) command. Also, several
762 have been added which are unique to Date::Manip.
763 ParseDateDelta
765 $delta = ParseDateDelta(\@args);
766 $delta = ParseDateDelta($string);
767 $delta = ParseDateDelta(\$string);
768 This takes an array and shifts a valid delta date (an amount of
770 time) from the array. Recognized deltas are of the form:
771 +Yy +Mm +Ww +Dd +Hh +MNmn +Ss
772 examples:
773 +4 hours +3mn -2second
774 + 4 hr 3 minutes -2
775 4 hour + 3 min -2 s
776 +Y:+M:+W:+D:+H:+MN:+S
777 examples:
778 0:0:0:0:4:3:-2
779 +4:3:-2
780 mixed format
781 examples:
782 4 hour 3:-2
783 A field in the format +Yy is a sign, a number, and a string speci‐
785 fying the type of field. The sign is "+", "-", or absent (defaults
786 to the next larger element). The valid strings specifying the
787 field type are:
788 y: y, yr, year, years
789 m: m, mon, month, months
790 w: w, wk, ws, wks, week, weeks
791 d: d, day, days
792 h: h, hr, hour, hours
793 mn: mn, min, minute, minutes
794 s: s, sec, second, seconds
795 Also, the "s" string may be omitted. The sign, number, and string
797 may all be separated from each other by any number of whitespaces.
798 In the date, all fields must be given in the order: Y M W D H MN S.
800 Any number of them may be omitted provided the rest remain in the
801 correct order. In the 2nd (colon) format, from 2 to 7 of the
802 fields may be given. For example +D:+H:+MN:+S may be given to
803 specify only four of the fields. In any case, both the MN and S
804 field may be present. No spaces may be present in the colon for‐
805 mat.
806 Deltas may also be given as a combination of the two formats. For
808 example, the following is valid: +Yy +D:+H:+MN:+S. Again, all
809 fields must be given in the correct order.
810 The word "in" may be given (prepended in English) to the delta ("in
812 5 years") and the word "ago" may be given (appended in English) ("6
813 months ago"). The "in" is completely ignored. The "ago" has the
814 affect of reversing all signs that appear in front of the compo‐
815 nents of the delta. I.e. "-12 yr 6 mon ago" is identical to "+12yr
816 +6mon" (don't forget that there is an implied minus sign in front
817 of the 6 because when no sign is explicitly given, it carries the
818 previously entered sign).
819 One thing is worth noting. The year/month and day/hour/min/sec
821 parts are returned in a "normalized" form. That is, the signs are
822 adjusted so as to be all positive or all negative. For example, "+
823 2 day - 2hour" does not return "0:0:0:2:-2:0:0". It returns
824 "+0:0:0:1:22:0:0" (1 day 22 hours which is equivalent). I find
825 (and I think most others agree) that this is a more useful form.
826 Since the year/month and day/hour/min/sec parts must be normalized
828 separately there is the possibility that the sign of the two parts
829 will be different. So, the delta "+ 2years -10 months - 2 days + 2
830 hours" produces the delta "+1:2:-0:1:22:0:0".
831 It is possible to include a sign for all elements that is output.
833 See the configuration variable DeltaSigns below.
834 NOTE: The internal format of the delta changed in version 5.30 from
836 Y:M:D:H:MN:S to Y:M:W:D:H:MN:S . Also, it is going to change again
837 at some point in the future to Y:M:W:D:H:MN:S*FLAGS . Use the rou‐
838 tine Delta_Format to extract information rather than parsing it
839 yourself.
840 Delta_Format
842 @str = Delta_Format($delta [,$mode], $dec,@format);
843 $str = Delta_Format($delta [,$mode], $dec,@format);
844 This is similar to the UnixDate routine except that it extracts
846 information from a delta. Unlike the UnixDate routine, most of the
847 formats are 2 characters instead of 1.
848 Formats currently understood are:
850 %Xv : the value of the field named X
852 %Xd : the value of the field X, and all smaller fields, expressed in
853 units of X
854 %Xh : the value of field X, and all larger fields, expressed in units
855 of X
856 %Xt : the value of all fields expressed in units of X
857 X is one of y,M,w,d,h,m,s (case sensitive).
859 %% : returns a "%"
861 So, the format "%hd" means the values of H, MN, and S expressed in
863 hours. So for the delta "0:0:0:0:2:30:0", this format returns 2.5.
864 Delta_Format can operate in two modes: exact and approximate. The
866 exact mode is done by default. Approximate mode can be done by
867 passing in the string "approx" as the 2nd argument.
868 In exact mode, Delta_Format only understands "exact" relationships.
870 This means that there can be no mixing of the Y/M and W/D/H/MN/S
871 segments because the relationship because, depending on when the
872 delta occurs, there is no exact relation between the number of
873 years or months and the number of days.
874 The two sections are treated completely separate from each other.
876 So, the delta "1:6:1:2:12:0:0" would return the following values:
877 %yt = 1.5 (1 year, 6 months)
879 %Mt = 18
880 %dt = 9.5 (1 week, 2 days, 12 hours)
882 In approximate mode, the relationship of 1 year = 365.25 days is
884 applied (with 1 month equal to 1/12 of a year exactly). So the
885 delta "1:6:1:2:12:0:0" would return the following values:
886 %dt = 557.375 (1.5 years of 365.25 days + 9.5 days)
888 If $dec is non-zero, the %Xd and %Xt values are formatted to con‐
890 tain $dec decimal places.
891 ParseRecur
893 $recur = ParseRecur($string [,$base,$date0,$date1,$flags]);
894 @dates = ParseRecur($string [,$base,$date0,$date1,$flags]);
895 A recurrence refers to a recurring event, and more specifically, an
897 event which occurs on a regular basis. A fully specified recurring
898 event may requires up to four pieces of information.
899 First, it requires a decription of the frequency of the event.
901 Examples include "the first of every month", "every other day",
902 "the 4th Thursday of each month at 2:00 PM", and "every 2 hours and
903 30 minutes".
904 Second, it may require a base date to work from. This piece of
906 information is not required for every type of recurrence. For
907 example, if the frequency is "the first of every month", no base
908 date is required. All the information about when the event occurs
909 is included in the frequency description. If the frequency were
910 "every other day" though, you need to know at least one day on
911 which the event occured.
912 Third, the recurring event may have a range (a starting and ending
914 date).
915 Fourth, there may be some flags included which modify the behavior
917 of the above information.
918 The fully specified recurrence is written as these 5 pieces of
920 information (both a start and end date) as an asterix separated
921 list:
922 freq*flags*base*date0*date1
924 Here, base, date0, and date1 are any strings (which must not con‐
926 tain any asterixes) which can be parsed by ParseDate. flags is a
927 comma separated list of flags (described below), and freq is a
928 string describing the frequency of the recurring event.
929 The syntax of the frequency description is a colon separated list
931 of the format Y:M:W:D:H:MN:S (which stand for year, month, week,
932 etc.). One (and only one) of the colons may optionally be replaced
933 by an asterisk, or an asterisk may be prepended to the string. For
934 example, the following are all valid frequency descriptions:
935 1:2:3:4:5:6:7
937 1:2*3:4:5:6:7
938 *1:2:3:4:5:6:7
939 But the following are NOT valid because they contain 2 or more
941 asterixes:
942 1:2*3:4:5*6:7
944 1*2*3:4:5*6:7
945 *1:2:3:4:5:6*7
946 If an asterix is included, values to the left of it refer to the
948 number of times that time interval occurs between recurring events.
949 For example, if the first part of the recurrence is:
950 1:2*
952 this says that the recurring event occurs approximately every 1
954 year and 2 months. I say approximately, because elements to the
955 right of the asterix, as well as any flags included in the recur‐
956 rence will affect when the actual events occur.
957 If no asterixes are included, then the entire recurrence is of this
959 form. For example,
960 0:0:0:1:12:0:0
962 refers to an event that occurs every 1 day, 12 hours.
964 Values that occur after an asterix refer to a specific value for
966 that type of time element (i.e. exactly as it would appear on a
967 calendar or a clock). For example, if the recurrence ends with:
968 *12:0:0
970 then the recurring event occurs at 12:00:00 (noon).
972 For example:
974 0:0:2:1:0:0:0 every 2 weeks and 1 day
976 0:0:0:0:5:30:0 every 5 hours and 30 minutes
977 0:0:0:2*12:30:0 every 2 days at 12:30 (each day)
978 Values to the right of the asterix can be listed a single values,
980 ranges (2 numbers separated by a dash "-"), or a comma separated
981 list of values or ranges. In most cases, negative values are
982 appropriate for the week or day values. -1 stands for the last pos‐
983 sible value, -2 for the second to the last, etc.
984 Some examples are:
986 0:0:0:1*2,4,6:0:0 every day at at 2:00, 4:00, and 6:00
988 0:0:0:2*12-13:0,30:0 every other day at 12:00, 12:30, 13:00,
989 and 13:30
990 0:1:0*-1:0:0:0 the last day of every month
991 *1990-1995:12:0:1:0:0:0
992 Dec 1 in 1990 through 1995
993 When the day element occurs to the right of the asterix, it can
995 take on multiple meanings, depending on the value of the month and
996 week elements. It can refer to the day of the week, day of the
997 month, or day of the year. Similarily, if the week element occurs
998 to the right of the asterix, it actually refers to the n'th time a
999 certain day of the week occurs, either in the month or in the year.
1000 If the week element is non-zero and the day element is non-zero, it
1002 refers to the day of the week. It can be any value from 1 to 7
1003 (negative values -1 to -7 are also allowed). If you use the ISO
1004 8601 convention, the first day of the week is Monday (though
1005 Date::Manip can use any day as the start of the week by setting the
1006 FirstDay config variable). So, assuming that you are using the ISO
1007 8601 convention, the following examples illustrate day-of-week
1008 recurrences:
1009 0:1*4:2:0:0:0 4th Tuesday (day 2) of every month
1011 0:1*-1:2:0:0:0 last tuesday of every month
1012 0:0:3*2:0:0:0 every 3rd tuesday (every 3 weeks on 2nd day of week)
1013 1:0*12:2:0:0:0 the 12th tuesday of each year
1014 If the week element is non-zero, and the day element is zero, the
1016 day defaults to 1 (i.e. the first day of the week).
1017 0:1*2:0:0:0:0 the 2nd occurence of FirstDay
1019 in the year (typically Monday)
1020 0:1*2:1:0:0:0 the same
1021 If the week element is zero and the month element is non-zero, the
1023 day value is the day of the month (it can be from 1 to 31 or -1 to
1024 -31 counting from the end of the month). If a value of 0 is given,
1025 it defaults to 1.
1026 3*1:0:2:12:0:0 every 3 years on Jan 2 at noon
1028 0:1*0:2:12,14:0:0 2nd of every month at 12:00 and 14:00
1029 0:1:0*-2:0:0:0 2nd to last day of every month
1030 If the day given refers to the 29th, 30th, or 31st, in a month that
1032 does not have that number of days, it is ignored. For example, if
1033 you ask for the 31st of every month, it will return dates in Jan,
1034 Mar, May, Jul, etc. Months with fewer than 31 days will be
1035 ignored.
1036 If both the month and week elements are zero, and the year element
1038 is non-zero, the day value is the day of the year (1 to 365 or 366
1039 -- or the negative numbers to count backwards from the end of the
1040 year).
1041 1:0:0*45:0:0:0 45th day of every year
1043 Specifying a day that doesn't occur in that year silently ignores
1045 that year. The only result of this is that specifying +366 or -366
1046 will ignore all years except leap years.
1047 There is no way to express the following with a single recurrence:
1049 every day at 12:30 and 1:00
1051 You have to use two recurrences to do this.
1053 I realize that this looks a bit cryptic, but after a discussion on
1055 the CALENDAR mailing list, it appeared like there was no concise,
1056 flexible notation for handling recurring events. ISO 8601 nota‐
1057 tions were very bulky and lacked the flexibility I wanted. As a
1058 result, I developed this notation (based on crontab formats, but
1059 with much more flexibility) which fits in well with this module.
1060 Even better, it is able to express every type of recurring event I
1061 could think of that is used in common life in (what I believe to
1062 be) a very concise and elegant way.
1063 If ParseRecur is called in scalar context, it returns a string con‐
1065 taining a fully specified recurrence (or as much of it as can be
1066 determined with unspecified fields left blank). In list context,
1067 it returns a list of all dates referred to by a recurrence if
1068 enough information is given in the recurrence. All dates returned
1069 are in the range:
1070 date0 <= date < date1
1072 The argument $string can contain any of the parts of a full recur‐
1074 rence. For example:
1075 freq
1077 freq*flags
1078 freq**base*date0*date1
1079 The only part which is required is the frequency description. Any
1081 values contained in $string are overridden or modified by values
1082 passed in as parameters to ParseRecur.
1083 NOTE: If a recurrence has a date0 and date1 in it AND a date0 and
1085 date1 are passed in to the function, both sets of criteria apply.
1086 If flags are passed in, they override any flags in the recurrence
1087 UNLESS the flags passed in start with a plus (+) character in which
1088 case they are appended to the flags in the recurrence.
1089 NOTE: Base dates are only used with some types of recurrences. For
1091 example,
1092 0:0:3*2:0:0:0 every 3rd tuesday
1094 requires a base date. If a base date is specified which doesn't
1096 match the criteria (for example, if a base date falling on Monday
1097 were passed in with this recurrence), the base date is moved for‐
1098 ward to the first relevant date.
1099 Other dates do not require a base date. For example:
1101 0:0*3:2:0:0:0 third tuesday of every month
1103 A recurrence written in the above format does NOT provide default
1105 values for base, date0, or date1. They must be specified in order
1106 to get a list of dates.
1107 A base date is not used entirely. It is only used to provide the
1109 parts necessary for the left part of a recurrence. For example,
1110 the recurrence:
1111 1:3*0:4:0:0:0 every 1 year, 3 months on the 4th day of the month
1113 would only use the year and month of the base date.
1115 There are a small handful of English strings which can be parsed in
1117 place of a numerical recur description. These include:
1118 every 2nd day [in 1997]
1120 every 2nd day in June [1997]
1121 2nd day of every month [in 1997]
1122 2nd tuesday of every month [in 1997]
1123 last tuesday of every month [in 1997]
1124 every tuesday [in 1997]
1125 every 2nd tuesday [in 1997]
1126 every 2nd tuesday in June [1997]
1127 Each of these set base, date0, and date1 to a default value (the
1129 current year with Jan 1 being the base date is the default if the
1130 year and month are missing).
1131 The following flags (case insensitive) are understood:
1133 PDn : n is 1-7. Means the previous day n not counting today
1135 PTn : n is 1-7. Means the previous day n counting today
1136 NDn : n is 1-7. Means the next day n not counting today
1137 NTn : n is 1-7. Means the next day n counting today
1138 FDn : n is any number. Means step forward n days.
1140 BDn : n is any number. Means step backward n days.
1141 FWn : n is any number. Means step forward n workdays.
1142 BWn : n is any number. Means step backward n workdays.
1143 CWD : the closest work day (using the TomorrowFirst config variable).
1145 CWN : the closest work day (looking forward first).
1146 CWP : the closest work day (looking backward first).
1147 NWD : next work day counting today
1149 PWD : previous work day counting today
1150 DWD : next/previous work day (TomorrowFirst config) counting today
1151 EASTER: select easter for this year (the M, W, D fields are ignored
1153 in the recur).
1154 CWD, CWN, and CWP will usually return the same value, but if you
1156 are starting at the middle day of a 3-day weekend (for example), it
1157 will return either the first work day of the following week, or the
1158 last work day of the previous week depending on whether it looks
1159 forward or backward first.
1160 All flags are applied AFTER the recurrence dates are calculated,
1162 and they may move a date outside of the date0 to date1 range. No
1163 check is made for this.
1164 The workday flags do not act exactly the same as a business mode
1166 calculation. For example, a date that is Saturday with a FW1 steps
1167 forward to the first workday (i.e. Monday).
1168 Date_Cmp
1170 $flag = Date_Cmp($date1,$date2);
1171 This takes two dates and compares them. Almost all dates can be
1173 compared using the perl "cmp" command. The only time this will not
1174 work is when comparing dates in different timezones. This routine
1175 will take that into account.
1176 NOTE: This routine currently does little more than use "cmp", but
1178 once the internal format for storing dates is in place (where time‐
1179 zone information is kept as part of the date), this routine will
1180 become more important. You should use this routine in prepartation
1181 for that version.
1182 DateCalc
1184 $d = DateCalc($d1,$d2 [,\$err] [,$mode]);
1185 This takes two dates, deltas, or one of each and performs the
1187 appropriate calculation with them. Dates must be a string that can
1188 be parsed by &ParseDateString. Deltas must be a string that can be
1189 parsed by &ParseDateDelta. Two deltas add together to form a third
1190 delta. A date and a delta returns a 2nd date. Two dates return a
1191 delta (the difference between the two dates).
1192 Note that in many cases, it is somewhat ambiguous what the delta
1194 actually refers to. Although it is ALWAYS known how many months in
1195 a year, hours in a day, etc., it is NOT known how many days form a
1196 month. As a result, the part of the delta containing month/year
1197 and the part with sec/min/hr/day must be treated separately. For
1198 example, "Mar 31, 12:00:00" plus a delta of 1month 2days would
1199 yield "May 2 12:00:00". The year/month is first handled while
1200 keeping the same date. Mar 31 plus one month is Apr 31 (but since
1201 Apr only has 30 days, it becomes Apr 30). Apr 30 + 2 days is May
1202 2. As a result, in the case where two dates are entered, the
1203 resulting delta can take on two different forms. By default
1204 ($mode=0), an absolutely correct delta (ignoring daylight savings
1205 time) is returned in weeks, days, hours, minutes, and seconds.
1206 If $mode is 1, the math is done using an approximate mode where a
1208 delta is returned using years and months as well. The year and
1209 month part is calculated first followed by the rest. For example,
1210 the two dates "Mar 12 1995" and "Apr 13 1995" would have an exact
1211 delta of "31 days" but in the approximate mode, it would be
1212 returned as "1 month 1 day". Also, "Mar 31" and "Apr 30" would
1213 have deltas of "30 days" or "1 month" (since Apr 31 doesn't exist,
1214 it drops down to Apr 30). Approximate mode is a more human way of
1215 looking at things (you'd say 1 month and 2 days more often then 33
1216 days), but it is less meaningful in terms of absolute time. In
1217 approximate mode $d1 and $d2 must be dates. If either or both is a
1218 delta, the calculation is done in exact mode.
1219 If $mode is 2, a business mode is used. That is, the calculation
1221 is done using business days, ignoring holidays, weekends, etc. In
1222 order to correctly use this mode, a config file must exist which
1223 contains the section defining holidays (see documentation on the
1224 config file below). The config file can also define the work week
1225 and the hours of the work day, so it is possible to have different
1226 config files for different businesses.
1227 For example, if a config file defines the workday as 08:00 to
1229 18:00, a work week consisting of Mon-Sat, and the standard (Ameri‐
1230 can) holidays, then from Tuesday at 12:00 to the following Monday
1231 at 14:00 is 5 days and 2 hours. If the "end" of the day is reached
1232 in a calculation, it automatically switches to the next day. So,
1233 Tuesday at 12:00 plus 6 hours is Wednesday at 08:00 (provided Wed
1234 is not a holiday). Also, a date that is not during a workday auto‐
1235 matically becomes the start of the next workday. So, Sunday 12:00
1236 and Monday at 03:00 both automatically becomes Monday at 08:00
1237 (provided Monday is not a holiday). In business mode, any combina‐
1238 tion of date and delta may be entered, but a delta should not con‐
1239 tain a year or month field (weeks are fine though).
1240 See below for some additional comments about business mode calcula‐
1242 tions.
1243 Note that a business week is treated the same as an exact week
1245 (i.e. from Tuesday to Tuesday, regardless of holidays). Because
1246 this means that the relationship between days and weeks is NOT
1247 unambiguous, when a delta is produced from two dates, it will be in
1248 terms of d/h/mn/s (i.e. no week field).
1249 If $mode is 3 (which only applies when two dates are passed in), an
1251 exact business mode is used. In this case, it returns a delta as
1252 an exact number of business days/hours/etc. between the two.
1253 Weeks, months, and years are ignored.
1254 Any other non-nil value of $mode is treated as $mode=1 (approximate
1256 mode).
1257 The mode can be automatically set in the dates/deltas passed by
1259 including a key word somewhere in it. For example, in English, if
1260 the word "approximately" is found in either of the date/delta argu‐
1261 ments, approximate mode is forced. Likewise, if the word "busi‐
1262 ness" or "exactly" appears, business/exact mode is forced (and
1263 $mode is ignored). So, the two following are equivalent:
1264 $date = DateCalc("today","+ 2 business days",\$err);
1266 $date = DateCalc("today","+ 2 days",\$err,2);
1267 Note that if the keyword method is used instead of passing in
1269 $mode, it is important that the keyword actually appear in the
1270 argument passed in to DateCalc. The following will NOT work:
1271 $delta = ParseDateDelta("+ 2 business days");
1273 $today = ParseDate("today");
1274 $date = DateCalc($today,$delta,\$err);
1275 because the mode keyword is removed from a date/delta by the parse
1277 routines, and the mode is reset each time a parse routine is
1278 called. Since DateCalc parses both of its arguments, whatever mode
1279 was previously set is ignored.
1280 If \$err is passed in, it is set to:
1282 1 is returned if $d1 is not a delta or date
1283 2 is returned if $d2 is not a delta or date
1284 3 is returned if the date is outside the years 1000 to 9999 This
1285 argument is optional, but if included, it must come before $mode.
1286 Nothing is returned if an error occurs.
1288 When a delta is returned, the signs such that it is strictly posi‐
1290 tive or strictly negative ("1 day - 2 hours" would never be
1291 returned for example). The only time when this cannot be enforced
1292 is when two deltas with a year/month component are entered. In
1293 this case, only the signs on the day/hour/min/sec part are stan‐
1294 dardized.
1295 Date_SetTime
1297 $date = Date_SetTime($date,$hr,$min,$sec);
1298 $date = Date_SetTime($date,$time);
1299 This takes a date (any string that may be parsed by ParseDat‐
1301 eString) and sets the time in that date. For example, one way to
1302 get the time for 7:30 tomorrow would be to use the lines:
1303 $date = ParseDate("tomorrow");
1305 $date = Date_SetTime($date,"7:30");
1306 Note that in this routine (as well as the other routines below
1308 which use a time argument), no real parsing is done on the times.
1309 As a result,
1310 $date = Date_SetTime($date,"13:30");
1312 works, but
1314 $date = Date_SetTime($date,"1:30 PM");
1316 doesn't.
1318 Date_SetDateField
1320 $date = Date_SetDateField($date,$field,$val [,$nocheck]);
1321 This takes a date and sets one of it's fields to a new value.
1323 $field is any of the strings "y", "m", "d", "h", "mn", "s" (case
1324 insensitive) and $val is the new value.
1325 If $nocheck is non-zero, no check is made as to the validity of the
1327 date.
1328 Date_GetPrev
1330 $date = Date_GetPrev($date,$dow, $curr [,$hr,$min,$sec]);
1331 $date = Date_GetPrev($date,$dow, $curr [,$time]);
1332 $date = Date_GetPrev($date,undef,$curr,$hr,$min,$sec);
1333 $date = Date_GetPrev($date,undef,$curr,$time);
1334 This takes a date (any string that may be parsed by ParseDat‐
1336 eString) and finds the previous occurrence of either a day of the
1337 week, or a certain time of day.
1338 If $dow is defined, the previous occurrence of the day of week is
1340 returned. $dow may either be a string (such as "Fri" or "Friday")
1341 or a number (between 1 and 7). The date of the previous $dow is
1342 returned.
1343 If $date falls on the day of week given by $dow, the date returned
1345 depends on $curr. If $curr is 0, the date returned is a week
1346 before $date. If $curr is 1, the date returned is the same as
1347 $date. If $curr is 2, the date returned (including the time infor‐
1348 mation) is required to be before $date.
1349 If a time is passed in (either as separate hours, minutes, seconds
1351 or as a time in HH:MM:SS or HH:MM format), the time on this date is
1352 set to it. The following examples should illustrate the use of
1353 Date_GetPrev:
1354 date dow curr time returns
1356 Fri Nov 22 18:15:00 Thu any 12:30 Thu Nov 21 12:30:00
1357 Fri Nov 22 18:15:00 Fri 0 12:30 Fri Nov 15 12:30:00
1358 Fri Nov 22 18:15:00 Fri 1/2 12:30 Fri Nov 22 12:30:00
1359 Fri Nov 22 18:15:00 Fri 1 18:30 Fri Nov 22 18:30:00
1361 Fri Nov 22 18:15:00 Fri 2 18:30 Fri Nov 15 18:30:00
1362 If $dow is undefined, then a time must be entered, and the date
1364 returned is the previous occurrence of this time. If $curr is
1365 non-zero, the current time is returned if it matches the criteria
1366 passed in. In other words, the time returned is the last time that
1367 a digital clock (in 24 hour mode) would have displayed the time you
1368 passed in. If you define hours, minutes and seconds default to 0
1369 and you might jump back as much as an entire day. If hours are
1370 undefined, you are looking for the last time the minutes/seconds
1371 appeared on the digital clock, so at most, the time will jump back
1372 one hour.
1373 date curr hr min sec returns
1375 Nov 22 18:15:00 0/1 18 undef undef Nov 22 18:00:00
1376 Nov 22 18:15:00 0/1 18 30 0 Nov 21 18:30:00
1377 Nov 22 18:15:00 0 18 15 undef Nov 21 18:15:00
1378 Nov 22 18:15:00 1 18 15 undef Nov 22 18:15:00
1379 Nov 22 18:15:00 0 undef 15 undef Nov 22 17:15:00
1380 Nov 22 18:15:00 1 undef 15 undef Nov 22 18:15:00
1381 Date_GetNext
1383 $date = Date_GetNext($date,$dow, $curr [,$hr,$min,$sec]);
1384 $date = Date_GetNext($date,$dow, $curr [,$time]);
1385 $date = Date_GetNext($date,undef,$curr,$hr,$min,$sec);
1386 $date = Date_GetNext($date,undef,$curr,$time);
1387 Similar to Date_GetPrev.
1389 Date_IsHoliday
1391 $name = Date_IsHoliday($date);
1392 This returns undef if $date is not a holiday, or a string contain‐
1394 ing the name of the holiday otherwise. An empty string is returned
1395 for an unnamed holiday.
1396 Events_List
1398 $ref = Events_List($date);
1399 $ref = Events_List($date ,0 [,$flag]);
1400 $ref = Events_List($date0,$date1 [,$flag]);
1401 This returns a list of events. Events are defined in the Events
1403 section of the config file (discussed below).
1404 In the first form (a single argument), $date is any string contain‐
1406 ing a date. A list of events active at that precise time will be
1407 returned. The format is similar to when $flag=0, except only a
1408 single time will be returned.
1409 In all other cases, a range of times will be used. If the 2nd
1411 argument evaluates to 0, the range of times will be the 24 hour
1412 period from midnight to midnight containing $date. Otherwise, the
1413 range is given by the two dates.
1414 The value of $flag determines the format of the information that is
1416 returned.
1417 With $flag=0, the events are returned as a reference to a list of
1419 the form:
1420 [ date, [ list_of_events ], date, [ list_of_events ], ... ]
1422 For example, if the following events are defined (using the syntax
1424 discussed below in the description of the Event section of the con‐
1425 fig file):
1426 2000-01-01 ; 2000-03-21 = Winter
1428 2000-03-22 ; 2000-06-21 = Spring
1429 2000-02-01 = Event1
1430 2000-05-01 = Event2
1431 2000-04-01-12:00:00 = Event3
1432 might result in the following output:
1434 &Events_List("2000-04-01")
1436 => [ 2000040100:00:00, [ Spring ] ]
1437 &Events_List("2000-04-01 12:30");
1439 => [ 2000040112:30:00, [ Spring, Event3 ] ]
1440 &Events_List("2000-04-01",0);
1442 => [ 2000040100:00:00, [ Spring ],
1443 2000040112:00:00, [ Spring, Event3 ],
1444 2000040113:00:00, [ Spring ] ]
1445 &Events_List("2000-03-15","2000-04-10");
1447 => [ 2000031500:00:00, [ Winter ],
1448 2000032200:00:00, [ Spring ]
1449 2000040112:00:00, [ Spring, Event3 ]
1450 2000040113:00:00, [ Spring ] ]
1451 Much more complicated events can be defined using recurrences.
1453 When $flag is non-zero, the format of the output is changed. If
1455 $flag is 1, then a tally of the amount of time given to each event
1456 is returned. Time for which two or more events apply is counted
1457 for both.
1458 &Events_List("2000-03-15","2000-04-10",1);
1460 => { Winter => +0:0:1:0:0:0:0,
1461 Spring => +0:0:2:5:0:0:0,
1462 Event3 => +0:0:0:0:1:0:0 }
1463 When $flag is 2, a more complex tally with no event counted twice
1465 is returned.
1466 &Events_List("2000-03-15","2000-04-10",2);
1468 => { Winter => +0:0:1:0:0:0:0,
1469 Spring => +0:0:2:4:23:0:0,
1470 Event3+Spring => +0:0:0:0:1:0:0 }
1471 The hash contains one element for each combination of events.
1473 Date_DayOfWeek
1475 $day = Date_DayOfWeek($m,$d,$y);
1476 Returns the day of the week (1 for Monday, 7 for Sunday).
1478 All arguments must be numeric.
1480 Date_SecsSince1970
1482 $secs = Date_SecsSince1970($m,$d,$y,$h,$mn,$s);
1483 Returns the number of seconds since Jan 1, 1970 00:00 (negative if
1485 date is earlier).
1486 All arguments must be numeric.
1488 Date_SecsSince1970GMT
1490 $secs = Date_SecsSince1970GMT($m,$d,$y,$h,$mn,$s);
1491 Returns the number of seconds since Jan 1, 1970 00:00 GMT (negative
1493 if date is earlier). If CurrTZ is "IGNORE", the number will be
1494 identical to Date_SecsSince1970 (i.e. the date given will be
1495 treated as being in GMT).
1496 All arguments must be numeric.
1498 Date_DaysSince1BC
1500 $days = Date_DaysSince1BC($m,$d,$y);
1501 Returns the number of days since Dec 31, 1BC. This includes the
1503 year 0000.
1504 All arguments must be numeric.
1506 Date_DayOfYear
1508 $day = Date_DayOfYear($m,$d,$y);
1509 Returns the day of the year (001 to 366)
1511 All arguments must be numeric.
1513 Date_NthDayOfYear
1515 ($y,$m,$d,$h,$mn,$s) = Date_NthDayOfYear($y,$n);
1516 Returns the year, month, day, hour, minutes, and decimal seconds
1518 given a floating point day of the year.
1519 All arguments must be numeric. $n must be greater than or equal to
1521 1 and less than 366 on non-leap years and 367 on leap years.
1522 NOTE: When $n is a decimal number, the results are non-intuitive
1524 perhaps. Day 1 is Jan 01 00:00. Day 2 is Jan 02 00:00. Intu‐
1525 itively, you might think of day 1.5 as being 1.5 days after Jan 01
1526 00:00, but this would mean that Day 1.5 was Jan 02 12:00 (which is
1527 later than Day 2). The best way to think of this function is a
1528 timeline starting at 1 and ending at 366 (in a non-leap year). In
1529 terms of a delta, think of $n as the number of days after Dec 31
1530 00:00 of the previous year.
1531 Date_DaysInYear
1533 $days = Date_DaysInYear($y);
1534 Returns the number of days in the year (365 or 366)
1536 Date_DaysInMonth
1538 $days = Date_DaysInMonth($m,$y);
1539 Returns the number of days in the month.
1541 Date_WeekOfYear
1543 $wkno = Date_WeekOfYear($m,$d,$y,$first);
1544 Figure out week number. $first is the first day of the week which
1546 is usually 1 (Monday) or 7 (Sunday), but could be any number
1547 between 1 and 7 in practice.
1548 All arguments must be numeric.
1550 NOTE: This routine should only be called in rare cases. Use Unix‐
1552 Date with the %W, %U, %J, %L formats instead. This routine returns
1553 a week between 0 and 53 which must then be "fixed" to get into the
1554 ISO-8601 weeks from 1 to 53. A date which returns a week of 0
1555 actually belongs to the last week of the previous year. A date
1556 which returns a week of 53 may belong to the first week of the next
1557 year.
1558 Date_LeapYear
1560 $flag = Date_LeapYear($y);
1561 Returns 1 if the argument is a leap year Written by David Muir
1563 Sharnoff <muir@idiom.com>
1564 Date_DaySuffix
1566 $day = Date_DaySuffix($d);
1567 Add `st', `nd', `rd', `th' to a date (ie 1st, 22nd, 29th). Works
1569 for international dates.
1570 Date_TimeZone
1572 $tz = Date_TimeZone;
1573 This determines and returns the local timezone. If it is unable to
1575 determine the local timezone, the following error occurs:
1576 ERROR: Date::Manip unable to determine TimeZone.
1578 See The TIMEZONES section below for more information.
1580 Date_ConvTZ
1582 $date = Date_ConvTZ($date);
1583 $date = Date_ConvTZ($date,$from);
1584 $date = Date_ConvTZ($date,"",$to [,$errlev]);
1585 $date = Date_ConvTZ($date,$from,$to [,$errlev]);
1586 This converts a date (which MUST be in the format returned by
1588 ParseDate) from one timezone to another.
1589 If it is called with no arguments, the date is converted from the
1591 local timezone to the timezone specified by the config variable
1592 ConvTZ (see documentation on ConvTZ below). If ConvTZ is set to
1593 "IGNORE", no conversion is done.
1594 If called with $from but no $to, the timezone is converted from the
1596 timezone in $from to ConvTZ (of TZ if ConvTZ is not set). Again,
1597 no conversion is done if ConvTZ is set to "IGNORE".
1598 If called with $to but no $from, $from defaults to ConvTZ (if set)
1600 or the local timezone otherwise. Although this does not seem imme‐
1601 diately obvious, it actually makes sense. By default, all dates
1602 that are parsed are converted to ConvTZ, so most of the dates being
1603 worked with will be stored in that timezone.
1604 If Date_ConvTZ is called with both $from and $to, the date is con‐
1606 verted from the timezone $from to $to.
1607 NOTE: As in all other cases, the $date returned from Date_ConvTZ
1609 has no timezone information included as part of it, so calling
1610 UnixDate with the "%z" format will return the timezone that
1611 Date::Manip is working in (usually the local timezone).
1612 Example: To convert 2/2/96 noon PST to CST (regardless of what
1614 timezone you are in, do the following:
1615 $date = ParseDate("2/2/96 noon");
1617 $date = Date_ConvTZ($date,"PST","CST");
1618 Both timezones MUST be in one of the formats listed below in the
1620 section TIMEZONES.
1621 If an error occurs, $errlev determines what happens:
1623 0 : the program dies
1625 1 : a warning is produced and nothing is returned
1626 2 : the function silently returns nothing
1627 Date_Init
1629 &Date_Init();
1630 &Date_Init("VAR=VAL","VAR=VAL",...);
1631 @list = Date_Init();
1632 @list = Date_Init("VAR=VAL","VAR=VAL",...);
1633 Normally, it is not necessary to explicitly call Date_Init. The
1635 first time any of the other routines are called, Date_Init will be
1636 called to set everything up. If for some reason you want to change
1637 the configuration of Date::Manip, you can pass the appropriate
1638 string or strings into Date_Init to reinitialize things.
1639 The strings to pass in are of the form "VAR=VAL". Any number may
1641 be included and they can come in any order. VAR may be any config‐
1642 uration variable. A list of all configuration variables is given
1643 in the section CUSTOMIZING DATE::MANIP below. VAL is any allowed
1644 value for that variable. For example, to switch from English to
1645 French and use non-US format (so that 12/10 is Oct 12), do the fol‐
1646 lowing:
1647 &Date_Init("Language=French","DateFormat=non-US");
1649 If Date_Init is called in list context, it will return a list of
1651 all config variables and their values suitable for passing in to
1652 Date_Init to return Date::Manip to the current state. The only
1653 possible problem is that by default, holidays will not be erased,
1654 so you may need to prepend the "EraseHolidays=1" element to the
1655 list.
1656 Date_IsWorkDay
1658 $flag = Date_IsWorkDay($date [,$flag]);
1659 This returns 1 if $date is a work day. If $flag is non-zero, the
1661 time is checked to see if it falls within work hours. It returns
1662 an empty string if $date is not valid.
1663 Date_NextWorkDay
1665 $date = Date_NextWorkDay($date,$off [,$time]);
1666 Finds the day $off work days from now. If $time is passed in, we
1668 must also take into account the time of day.
1669 If $time is not passed in, day 0 is today (if today is a workday)
1671 or the next work day if it isn't. In any case, the time of day is
1672 unaffected.
1673 If $time is passed in, day 0 is now (if now is part of a workday)
1675 or the start of the very next work day.
1676 Date_PrevWorkDay
1678 $date = Date_PrevWorkDay($date,$off [,$time]);
1679 Similar to Date_NextWorkDay.
1681 Date_NearestWorkDay
1683 $date = Date_NearestWorkDay($date [,$tomorrowfirst]);
1684 This looks for the work day nearest to $date. If $date is a work
1686 day, it is returned. Otherwise, it will look forward or backwards
1687 in time 1 day at a time until a work day is found. If $tomorrow‐
1688 first is non-zero (or if it is omitted and the config variable
1689 TomorrowFirst is non-zero), we look to the future first. Other‐
1690 wise, we look in the past first. In other words, in a normal week,
1691 if $date is Wednesday, $date is returned. If $date is Saturday,
1692 Friday is returned. If $date is Sunday, Monday is returned. If
1693 Wednesday is a holiday, Thursday is returned if $tomorrowfirst is
1694 non-nil or Tuesday otherwise.
1695 DateManipVersion
1697 $version = DateManipVersion;
1698 Returns the version of Date::Manip.
1700
1702 The following timezone names are currently understood (and can be used
1703 in parsing dates). These are zones defined in RFC 822.
1704 Universal: GMT, UT
1706 US zones : EST, EDT, CST, CDT, MST, MDT, PST, PDT
1707 Military : A to Z (except J)
1708 Other : +HHMM or -HHMM
1709 ISO 8601 : +HH:MM, +HH, -HH:MM, -HH
1710 In addition, the following timezone abbreviations are also accepted.
1712 In a few cases, the same abbreviation is used for two different time‐
1713 zones (for example, NST stands for Newfoundland Standard -0330 and
1714 North Sumatra +0630). In these cases, only 1 of the two is available.
1715 The one preceded by a "#" sign is NOT available but is documented here
1716 for completeness. This list of zones comes in part from the Time::Zone
1717 module by Graham Barr, David Muir Sharnoff, and Paul Foley (with sev‐
1718 eral additions by myself).
1719 IDLW -1200 International Date Line West
1721 NT -1100 Nome
1722 HST -1000 Hawaii Standard
1723 CAT -1000 Central Alaska
1724 AHST -1000 Alaska-Hawaii Standard
1725 AKST -0900 Alaska Standard
1726 YST -0900 Yukon Standard
1727 HDT -0900 Hawaii Daylight
1728 AKDT -0800 Alaska Daylight
1729 YDT -0800 Yukon Daylight
1730 PST -0800 Pacific Standard
1731 PDT -0700 Pacific Daylight
1732 MST -0700 Mountain Standard
1733 MDT -0600 Mountain Daylight
1734 CST -0600 Central Standard
1735 CDT -0500 Central Daylight
1736 EST -0500 Eastern Standard
1737 ACT -0500 Brazil, Acre
1738 SAT -0400 Chile
1739 CLST -0400 Chile Standard
1740 BOT -0400 Bolivia
1741 EDT -0400 Eastern Daylight
1742 AST -0400 Atlantic Standard
1743 AMT -0400 Brazil, Amazon
1744 ACST -0400 Brazil, Acre Daylight
1745 #NST -0330 Newfoundland Standard nst=North Sumatra +0630
1746 NFT -0330 Newfoundland
1747 CLDT -0300 Chile Daylight
1748 #GST -0300 Greenland Standard gst=Guam Standard +1000
1749 #BST -0300 Brazil Standard bst=British Summer +0100
1750 #BRST -0300 Brazil Standard
1751 BRT -0300 Brazil Standard
1752 AMST -0300 Brazil, Amazon Daylight
1753 ADT -0300 Atlantic Daylight
1754 ART -0300 Argentina
1755 UYT -0300 Uruguay
1756 NDT -0230 Newfoundland Daylight
1757 AT -0200 Azores
1758 BRST -0200 Brazil Daylight (official time)
1759 FNT -0200 Brazil, Fernando de Noronha
1760 WAT -0100 West Africa
1761 FNST -0100 Brazil, Fernando de Noronha Daylight
1762 GMT +0000 Greenwich Mean
1763 UT +0000 Universal (Coordinated)
1764 UTC +0000 Universal (Coordinated)
1765 WET +0000 Western European
1766 CET +0100 Central European
1767 FWT +0100 French Winter
1768 MET +0100 Middle European
1769 MEZ +0100 Middle European
1770 MEWT +0100 Middle European Winter
1771 SWT +0100 Swedish Winter
1772 BST +0100 British Summer bst=Brazil standard -0300
1773 GB +0100 GMT with daylight savings
1774 WEST +0000 Western European Daylight
1775 CEST +0200 Central European Summer
1776 EET +0200 Eastern Europe, USSR Zone 1
1777 FST +0200 French Summer
1778 MEST +0200 Middle European Summer
1779 MESZ +0200 Middle European Summer
1780 METDST +0200 An alias for MEST used by HP-UX
1781 SAST +0200 South African Standard
1782 SST +0200 Swedish Summer sst=South Sumatra +0700
1783 EEST +0300 Eastern Europe Summer
1784 BT +0300 Baghdad, USSR Zone 2
1785 MSK +0300 Moscow
1786 EAT +0300 East Africa
1787 IT +0330 Iran
1788 ZP4 +0400 USSR Zone 3
1789 MSD +0300 Moscow Daylight
1790 ZP5 +0500 USSR Zone 4
1791 IST +0530 Indian Standard
1792 ZP6 +0600 USSR Zone 5
1793 NOVST +0600 Novosibirsk time zone, Russia
1794 NST +0630 North Sumatra nst=Newfoundland Std -0330
1795 #SST +0700 South Sumatra, USSR Zone 6 sst=Swedish Summer +0200
1796 JAVT +0700 Java
1797 ICT +0700 Indo China Time
1798 KRAT +0700 Krasnoyarsk, Russia
1799 CCT +0800 China Coast, USSR Zone 7
1800 KRAST +0800 Krasnoyarsk, Russia Daylight
1801 AWST +0800 Australian Western Standard
1802 WST +0800 West Australian Standard
1803 PHT +0800 Asia Manila
1804 JST +0900 Japan Standard, USSR Zone 8
1805 ROK +0900 Republic of Korea
1806 ACST +0930 Australian Central Standard
1807 CAST +0930 Central Australian Standard
1808 AEST +1000 Australian Eastern Standard
1809 EAST +1000 Eastern Australian Standard
1810 GST +1000 Guam Standard, USSR Zone 9 gst=Greenland Std -0300
1811 CHST +1000 Guam Standard, USSR Zone 9 gst=Greenland Std -0300
1812 ACDT +1030 Australian Central Daylight
1813 CADT +1030 Central Australian Daylight
1814 AEDT +1100 Australian Eastern Daylight
1815 EADT +1100 Eastern Australian Daylight
1816 IDLE +1200 International Date Line East
1817 NZST +1200 New Zealand Standard
1818 NZT +1200 New Zealand
1819 NZDT +1300 New Zealand Daylight
1820 Others can be added in the future upon request.
1822 Date::Manip must be able to determine the timezone the user is in. It
1824 does this by looking in the following places:
1825 $Date::Manip::TZ (set with Date_Init or in Manip.pm)
1827 $ENV{TZ}
1828 the unix `date` command (if available)
1829 $main::TZ
1830 /etc/TIMEZONE
1831 /etc/timezone
1832 At least one of these should contain a timezone in one of the supported
1834 forms. If none do by default, the TZ variable must be set with
1835 Date_Init.
1836 The timezone may be in the STD#DST format (in which case both abbrevia‐
1838 tions must be in the table above) or any of the formats described
1839 above. The STD#DST format is NOT available when parsing a date how‐
1840 ever. The following forms are also available and are treated similar
1841 to the STD#DST forms:
1842 US/Pacific
1844 US/Mountain
1845 US/Central
1846 US/Eastern
1847 Canada/Pacific
1848 Canada/Mountain
1849 Canada/Central
1850 Canada/Eastern
1851
1853 Anyone using business mode is going to notice a few quirks about it
1854 which should be explained. When I designed business mode, I had in
1855 mind what UPS tells me when they say 2 day delivery, or what the local
1856 business which promises 1 business day turnaround really means.
1857 If you do a business day calculation (with the workday set to
1859 9:00-5:00), you will get the following:
1860 Saturday at noon + 1 business day = Tuesday at 9:00
1862 Saturday at noon - 1 business day = Friday at 9:00
1863 What does this mean?
1865 We have a business that works 9-5 and they have a drop box so I can
1867 drop things off over the weekend and they promise 1 business day turn‐
1868 around. If I drop something off Friday night, Saturday, or Sunday, it
1869 doesn't matter. They're going to get started on it Monday morning.
1870 It'll be 1 business day to finish the job, so the earliest I can expect
1871 it to be done is around 17:00 Monday or 9:00 Tuesday morning. Unfortu‐
1872 nately, there is some ambiguity as to what day 17:00 really falls on,
1873 similar to the ambiguity that occurs when you ask what day midnight
1874 falls on. Although it's not the only answer, Date::Manip treats mid‐
1875 night as the beginning of a day rather than the end of one. In the
1876 same way, 17:00 is equivalent to 9:00 the next day and any time the
1877 date calculations encounter 17:00, it automatically switch to 9:00 the
1878 next day. Although this introduces some quirks, I think this is justi‐
1879 fied. You just have to treat 17:00/9:00 as being ambiguous (in the
1880 same way you treat midnight as being ambiguous).
1881 Equivalently, if I want a job to be finished on Saturday (despite the
1883 fact that I cannot pick it up since the business is closed), I have to
1884 drop it off no later than Friday at 9:00. That gives them a full busi‐
1885 ness day to finish it off. Of course, I could just as easily drop it
1886 off at 17:00 Thursday, or any time between then and 9:00 Friday.
1887 Again, it's a matter of treating 9:00 as ambiguous.
1888 So, in case the business date calculations ever produce results that
1890 you find confusing, I believe the solution is to write a wrapper which,
1891 whenever it sees a date with the time of exactly 9:00, it treats it
1892 specially (depending on what you want).
1893 So Saturday + 1 business day = Tuesday at 9:00 (which means anything
1895 from Monday 17:00 to Tuesday 9:00), but Monday at 9:01 + 1 business day
1896 = Tuesday at 9:01 which is exact.
1897 If this is not exactly what you have in mind, don't use the DateCalc
1899 routine. You can probably get whatever behavior you want using the
1900 routines Date_IsWorkDay, Date_NextWorkDay, and Date_PrevWorkDay
1901 described above.
1902
1904 There are a number of variables which can be used to customize the way
1905 Date::Manip behaves. There are also several ways to set these vari‐
1906 ables.
1907 At the top of the Manip.pm file, there is a section which contains all
1909 customization variables. These provide the default values.
1910 These can be overridden in a global config file if one is present (this
1912 file is optional). If the GlobalCnf variable is set in the Manip.pm
1913 file, it contains the full path to a config file. If the file exists,
1914 it's values will override those set in the Manip.pm file. A sample
1915 config file is included with the Date::Manip distribution. Modify it
1916 as appropriate and copy it to some appropriate directory and set the
1917 GlobalCnf variable in the Manip.pm file.
1918 Each user can have a personal config file which is of the same form as
1920 the global config file. The variables PersonalCnf and PersonalCnfPath
1921 set the name and search path for the personal config file. This file
1922 is also optional. If present, it overrides any values set in the
1923 global file.
1924 NOTE: if you use business mode calculations, you must have a config
1926 file (either global or personal) since this is the only place where you
1927 can define holidays.
1928 Finally, any variables passed in through Date_Init override all other
1930 values.
1931 A config file can be composed of several sections. The first section
1933 sets configuration variables. Lines in this section are of the form:
1934 VARIABLE = VALUE
1936 For example, to make the default language French, include the line:
1938 Language = French
1940 Only variables described below may be used. Blank lines and lines
1942 beginning with a pound sign (#) are ignored. All spaces are optional
1943 and strings are case insensitive.
1944 A line which starts with an asterisk (*) designates a new section. For
1946 example, the HOLIDAY section starts with a line:
1947 *Holiday
1949 The various sections are defined below.
1951
1953 All Date::Manip variables which can be used are described in the fol‐
1954 lowing section.
1955 IgnoreGlobalCnf
1957 If this variable is used (any value is ignored), the global config
1958 file is not read. It must be present in the initial call to
1959 Date_Init or the global config file will be read.
1960 EraseHolidays
1962 If this variable is used (any value is ignored), the current list
1963 of defined holidays is erased. A new set will be set the next time
1964 a config file is read in. This can be set in either the global
1965 config file or as a Date_Init argument (in which case holidays can
1966 be read in from both the global and personal config files) or in
1967 the personal config file (in which case, only holidays in the per‐
1968 sonal config file are counted).
1969 PathSep
1971 This is a regular expression used to separate multiple paths. For
1972 example, on Unix, it defaults to a colon (:) so that multiple paths
1973 can be written PATH1:PATH2 . For Win32 platforms, it defaults to a
1974 semicolon (;) so that paths such as "c:\;d:\" will work.
1975 GlobalCnf
1977 This variable can be passed into Date_Init to point to a global
1978 configuration file. The value must be the complete path to a con‐
1979 fig file.
1980 By default, no global config file is read. Any time a global con‐
1982 fig file is read, the holidays are erased.
1983 Paths may have a tilde (~) expansion on platforms where this is
1985 supported (currently Unix and VMS).
1986 PersonalCnf
1988 This variable can be passed into Date_Init or set in a global con‐
1989 fig file to set the name of the personal configuration file.
1990 The default name for the config file is .DateManip.cnf on all Unix
1992 platforms and Manip.cnf on all non-Unix platforms (because some of
1993 them insist on 8.3 character filenames :-).
1994 PersonalCnfPath
1996 This is a list of paths separated by the separator specified by the
1997 PathSep variable. These paths are each checked for the PersonalCnf
1998 config file.
1999 Paths may have a tilde (~) expansion on platforms where this is
2001 supported (currently Unix and VMS).
2002 Language
2004 Date::Manip can be used to parse dates in many different languages.
2005 Currently, it is configured to read the following languages (the
2006 version in which they added is included for historical interest):
2007 English (default)
2009 French (5.02)
2010 Swedish (5.05)
2011 German (5.31)
2012 Dutch (5.32) aka Nederlands
2013 Polish (5.32)
2014 Spanish (5.33)
2015 Portuguese (5.34)
2016 Romanian (5.35)
2017 Italian (5.35)
2018 Russian (5.41)
2019 Turkish (5.41)
2020 Danish (5.41)
2021 Others can be added easily. Language is set to the language used
2023 to parse dates. If you are interested in providing a translation
2024 for a new language, email me (see the AUTHOR section below) and
2025 I'll send you a list of things that I need.
2026 DateFormat
2028 Different countries look at the date 12/10 as Dec 10 or Oct 12. In
2029 the United States, the first is most common, but this certainly
2030 doesn't hold true for other countries. Setting DateFormat to "US"
2031 forces the first behavior (Dec 10). Setting DateFormat to anything
2032 else forces the second behavior (Oct 12).
2033 TZ If set, this defines the local timezone. See the TIMEZONES section
2035 above for information on it's format.
2036 ConvTZ
2038 All date comparisons and calculations must be done in a single time
2039 zone in order for them to work correctly. So, when a date is
2040 parsed, it should be converted to a specific timezone. This allows
2041 dates to easily be compared and manipulated as if they are all in a
2042 single timezone.
2043 The ConvTZ variable determines which timezone should be used to
2045 store dates in. If it is left blank, all dates are converted to
2046 the local timezone (see the TZ variable above). If it is set to
2047 one of the timezones listed above, all dates are converted to this
2048 timezone. Finally, if it is set to the string "IGNORE", all time‐
2049 zone information is ignored as the dates are read in (in this case,
2050 the two dates "1/1/96 12:00 GMT" and "1/1/96 12:00 EST" would be
2051 treated as identical).
2052 Internal
2054 When a date is parsed using ParseDate, that date is stored in an
2055 internal format which is understood by the Date::Manip routines
2056 UnixDate and DateCalc. Originally, the format used to store the
2057 date internally was:
2058 YYYYMMDDHH:MN:SS
2060 It has been suggested that I remove the colons (:) to shorten this
2062 to:
2063 YYYYMMDDHHMNSS
2065 The main advantage of this is that some databases are colon delim‐
2067 ited which makes storing a date from Date::Manip tedious.
2068 In order to maintain backwards compatibility, the Internal variable
2070 was introduced. Set it to 0 (to use the old format) or 1 (to use
2071 the new format).
2072 FirstDay
2074 It is sometimes necessary to know what day of week is regarded as
2075 first. By default, this is set to Monday, but many countries and
2076 people will prefer Sunday (and in a few cases, a different day may
2077 be desired). Set the FirstDay variable to be the first day of the
2078 week (1=Monday, 7=Sunday) Monday should be chosen to to comply with
2079 ISO 8601.
2080 WorkWeekBeg, WorkWeekEnd
2082 The first and last days of the work week. By default, Monday and
2083 Friday. WorkWeekBeg must come before WorkWeekEnd numerically. The
2084 days are numbered from 1 (Monday) to 7 (Sunday).
2085 There is no way to handle an odd work week of Thu to Mon for exam‐
2087 ple or 10 days on, 4 days off.
2088 WorkDay24Hr
2090 If this is non-nil, a work day is treated as being 24 hours long.
2091 The WorkDayBeg and WorkDayEnd variables are ignored in this case.
2092 WorkDayBeg, WorkDayEnd
2094 The times when the work day starts and ends. WorkDayBeg must come
2095 before WorkDayEnd (i.e. there is no way to handle the night shift
2096 where the work day starts one day and ends another). Also, the
2097 workday MUST be more than one hour long (of course, if this isn't
2098 the case, let me know... I want a job there!).
2099 The time in both can be in any valid time format (including inter‐
2101 national formats), but seconds will be ignored.
2102 TomorrowFirst
2104 Periodically, if a day is not a business day, we need to find the
2105 nearest business day to it. By default, we'll look to "tomorrow"
2106 first, but if this variable is set to 0, we'll look to "yesterday"
2107 first. This is only used in the Date_NearestWorkDay and is easily
2108 overridden (see documentation for that function).
2109 DeltaSigns
2111 Prior to Date::Manip version 5.07, a negative delta would put nega‐
2112 tive signs in front of every component (i.e. "0:0:-1:-3:0:-4"). By
2113 default, 5.07 changes this behavior to print only 1 or two signs in
2114 front of the year and day elements (even if these elements might be
2115 zero) and the sign for year/month and day/hour/minute/second are
2116 the same. Setting this variable to non-zero forces deltas to be
2117 stored with a sign in front of every element (including elements
2118 equal to 0).
2119 Jan1Week1
2121 ISO 8601 states that the first week of the year is the one which
2122 contains Jan 4 (i.e. it is the first week in which most of the days
2123 in that week fall in that year). This means that the first 3 days
2124 of the year may be treated as belonging to the last week of the
2125 previous year. If this is set to non-nil, the ISO 8601 standard
2126 will be ignored and the first week of the year contains Jan 1.
2127 YYtoYYYY
2129 By default, a 2 digit year is treated as falling in the 100 year
2130 period of CURR-89 to CURR+10. YYtoYYYY may be set to any integer N
2131 to force a 2 digit year into the period CURR-N to CURR+(99-N). A
2132 value of 0 forces the year to be the current year or later. A
2133 value of 99 forces the year to be the current year or earlier.
2134 Since I do no checking on the value of YYtoYYYY, you can actually
2135 have it any positive or negative value to force it into any century
2136 you want.
2137 YYtoYYYY can also be set to "C" to force it into the current cen‐
2139 tury, or to "C##" to force it into a specific century. So, no
2140 (1998), "C" forces 2 digit years to be 1900-1999 and "C18" would
2141 force it to be 1800-1899.
2142 It can also be set to the form "C####" to force it into a specific
2144 100 year period. C1950 refers to 1950-2049.
2145 UpdateCurrTZ
2147 If a script is running over a long period of time, the timezone may
2148 change during the course of running it (i.e. when daylight savings
2149 time starts or ends). As a result, parsing dates may start putting
2150 them in the wrong time zone. Since a lot of overhead can be saved
2151 if we don't have to check the current timezone every time a date is
2152 parsed, by default checking is turned off. Setting this to non-nil
2153 will force timezone checking to be done every time a date is
2154 parsed... but this will result in a considerable performance
2155 penalty.
2156 A better solution would be to restart the process on the two days
2158 per year where the timezone switch occurs.
2159 IntCharSet
2161 If set to 0, use the US character set (7-bit ASCII) to return
2162 strings such as the month name. If set to 1, use the appropriate
2163 international character set. For example, If you want your French
2164 representation of Decemeber to have the accent over the first "e",
2165 you'll want to set this to 1.
2166 ForceDate
2168 This variable can be set to a date in the format:
2169 YYYY-MM-DD-HH:MN:SS to force the current date to be interpreted as
2170 this date. Since the current date is used in parsing, this string
2171 will not be parsed and MUST be in the format given above.
2172 TodayIsMidnight
2174 If set to a true value (e.g. 1), then "today" will mean the same as
2175 "midnight today"; otherwise it will mean the same as "now".
2176
2178 The holiday section of the config file is used to define holidays.
2179 Each line is of the form:
2180 DATE = HOLIDAY
2182 HOLIDAY is the name of the holiday (or it can be blank in which case
2184 the day will still be treated as a holiday... for example the day after
2185 Thanksgiving or Christmas is often a work holiday though neither are
2186 named).
2187 DATE is a string which can be parsed to give a valid date in any year.
2189 It can be of the form
2190 Date
2192 Date + Delta
2193 Date - Delta
2194 Recur
2195 A valid holiday section would be:
2197 *Holiday
2199 1/1 = New Year's Day
2201 third Monday in Feb = Presidents' Day
2202 fourth Thu in Nov = Thanksgiving
2203 # The Friday after Thanksgiving is an unnamed holiday most places
2205 fourth Thu in Nov + 1 day =
2206 1*0:0:0:0:0:0*EASTER = Easter
2208 1*11:0:11:0:0:0*CWD = Veteran's Day (observed)
2209 1*0:0:0:0:0:0*EASTER,PD5 = Good Friday
2210 In a Date + Delta or Date - Delta string, you can use business mode by
2212 including the appropriate string (see documentation on DateCalc) in the
2213 Date or Delta. So (in English), the first workday before Christmas
2214 could be defined as:
2215 12/25 - 1 business day =
2217 The date's may optionally contain the year. For example, the dates
2219 1/1
2221 1/1/1999
2222 refers to Jan 1 in any year or in only 1999 respectively. For dates
2224 that refer to any year, the date must be written such that by simply
2225 appending the year (separated by spaces) it can be correctly inter‐
2226 preted. This will work for everything except ISO 8601 dates, so ISO
2227 8601 dates may not be used in this case.
2228 In cases where you are interested in business type calculations, you'll
2230 want to define most holidays using recurrences, since they can define
2231 when a holiday is celebrated in the financial world. For example,
2232 Christmas should be defined as:
2233 1*12:0:24:0:0:0*FW1 = Christmas
2235 NOTE: It was pointed out to me that using a similar type recurrence to
2237 define New Years does not work. The recurrence:
2238 1*12:0:31:0:0:0*FW1
2240 fails (worse, it goes into an infinite loop). The problem is that each
2242 holiday definition is applied to a specific year and it expects to find
2243 the holiday for that year. When this recurrence is applied to the year
2244 1995, it returns the holiday for 1996 and fails.
2245 Use the recurrence:
2247 1*1:0:1:0:0:0*NWD
2249 instead.
2251 If you wanted to define both Christmas and Boxing days (Boxing is the
2253 day after Christmas, and is celebrated in some parts of the world), you
2254 could do it in one of the following ways:
2255 1*12:0:24:0:0:0*FW1 = Christmas
2257 1*12:0:25:0:0:0*FW1 = Boxing
2258 1*12:0:24:0:0:0*FW1 = Christmas
2260 01*12:0:24:0:0:0*FW1 = Boxing
2261 1*12:0:24:0:0:0*FW1 = Christmas
2263 1*12:0:25:0:0:0*FW1,a = Boxing
2264 The following examples will NOT work:
2266 1*12:0:24:0:0:0*FW1 = Christmas
2268 1*12:0:24:0:0:0*FW2 = Boxing
2269 1*12:0:24:0:0:0*FW1 = Christmas
2271 1*12:0:24:0:0:0*FW1 = Boxing
2272 The reasoning behind all this is as follows:
2274 Holidays go into affect the minute they are parsed. So, in the case
2276 of:
2277 1*12:0:24:0:0:0*FW1 = Christmas
2279 1*12:0:24:0:0:0*FW2 = Boxing
2280 the minute the first line is parsed, Christmas is defined as a holiday.
2282 The second line then steps forward 2 work days (skipping Christmas
2283 since that's no longer a work day) and define the work day two days
2284 after Christmas, NOT the day after Christmas.
2285 An good alternative would appear to be:
2287 1*12:0:24:0:0:0*FW1 = Christmas
2289 1*12:0:24:0:0:0*FW1 = Boxing
2290 This unfortunately fails because the recurrences are currently stored
2292 in a hash. Since these two recurrences are identical, they fail (the
2293 first one is overwritten by the second and in essense, Christmas is
2294 never defined).
2295 To fix this, make them unique with either a fake flag (which is
2297 ignored):
2298 1*12:0:24:0:0:0*FW1,a = Boxing
2300 or adding an innocuous 0 somewhere:
2302 01*12:0:24:0:0:0*FW1 = Boxing
2304 The other good alternative would be to make two completely different
2306 recurrences such as:
2307 1*12:0:24:0:0:0*FW1 = Christmas
2309 1*12:0:25:0:0:0*FW1 = Boxing
2310 At times, you may want to switch back and forth between two holiday
2312 files. This can be done by calling the following:
2313 &Date_Init("EraseHolidays=1","PersonalCnf=FILE1");
2315 ...
2316 &Date_Init("EraseHolidays=1","PersonalCnf=FILE2");
2317 ...
2318
2320 The Events section of the config file is similar to the Holiday sec‐
2321 tion. It is used to name certain days or times, but there are a few
2322 important differences:
2323 Events can be assigned to any time and duration
2325 All holidays are exactly 1 day long. They are assigned to a period
2326 of time from midnight to midnight.
2327 Events can be based at any time of the day, and may be of any dura‐
2329 tion.
2330 Events don't affect business mode calculations
2332 Unlike holidays, events are completely ignored when doing business
2333 mode calculations.
2334 Whereas holidays were added with business mode math in mind, events
2336 were added with calendar and scheduling applications in mind.
2337 Every line in the events section is of the form:
2339 EVENT = NAME
2341 where NAME is the name of the event, and EVENT defines when it occurs
2343 and it's duration. An EVENT can be defined in the following ways:
2344 Date
2346 Date*
2347 Recur [NYI]
2348 Recur* [NYI]
2349 Date ; Date
2351 Date ; Delta
2352 Recur ; Delta [NYI]
2353 Date ; Delta ; Delta [NYI]
2355 Recur ; Delta ; Delta [NYI]
2356 Here, Date* refers to a string containing a Date with NO TIME fields
2358 (Jan 12, 1/1/2000, 2010-01-01) while Date does contain time fields.
2359 Similarily, Recur* stands for a recurrence with the time fields all
2360 equal to 0) while Recur stands for a recurrence with at least one non-
2361 zero time field.
2362 Both Date* and Recur* refer to an event very similar to a holiday which
2364 goes from midnight to midnight.
2365 Date and Recur refer to events which occur at the time given and with a
2367 duration of 1 hour.
2368 Events given by "Date ; Date", "Date ; Delta", and "Recur ; Delta" con‐
2370 tain both the starting date and either ending date or duration.
2371 Events given as three elements "Date ; Delta ; Delta" or "Recur ; Delta
2373 ; Delta" take a date and add both deltas to it to give the starting and
2374 ending time of the event. The order and sign of the deltas is unimpor‐
2375 tant (and both can be the same sign to give a range of times which does
2376 not contain the base date).
2377 Items marked with [NYI] are not yet implemented but will be by the time
2379 this is released.
2380
2382 For the most part, Date::Manip has remained backward compatible at
2383 every release. There have been a few minor incompatibilities intro‐
2384 duced at various stages. Major differences are marked with bullets.
2385 VERSION 5.44
2387 * Recurrences revisited
2388 The behavior of some elements of recurrences changed. These
2389 included making the week element (N) refer to the Nth occurence
2390 of a day of the week in the week, month, or year. It is now
2391 possible to look at the 3rd Friday of every month for example.
2392 Changed %x format in UnixDate
2394 The %x format used to be equivalent to %D (%m/%d/%y), but it
2395 has been modified to use the DateFormat config varible, so it
2396 may return %d/%m/%y if a non-US DateFormat is specified.
2397 VERSION 5.41
2399 Changed path separator for VMS
2400 Since ":" is used in some VMS paths, it should not have been
2401 used as the path separator. It has been changed to a newline
2402 ("\n") character.
2403 Delta_Format behavior changed
2405 The entire delta is exact if no month component is present
2406 (previously, no year or month component could be present).
2407 VERSION 5.38
2409 Removed Date_DaysSince999
2410 The Date_DaysSince999 function (deprecated in 5.35) has been
2411 removed.
2412 VERSION 5.35
2414 Deprected Date_DaysSince999
2415 In fixing support for the years 0000-0999, I rewrote
2416 Date_DaysSince999 to be Date_DaysSince1BC. The
2417 Date_DaysSince999 function will be removed.
2418 * Added PathSep variable
2420 In order to better support Win32 platforms, I added the PathSep
2421 config variable. This will allow the use of paths such as
2422 "c:\date" on Win32 platforms. Old config files on Win32 plat‐
2423 forms (which were not working correctly in many cases) may not
2424 work if they contain path information to the personal config
2425 file.
2426 VERSION 5.34
2428 * All Date::Manip variables are no longer accessible
2429 Previously, Date::Manip variables were declared using a full
2430 package name. Now, they are declared with the my() function.
2431 This means that internal variables are no longer accessible
2432 outside of the module.
2433 Week interpretation in business mode deltas
2435 A business mode delta containing a week value used to be
2436 treated as 7 days. A much more likely interpretation of a week
2437 is Monday to Monday, regardless of holidays, so this is now the
2438 behavior.
2439 %z UnixDate format
2441 The %z UnixDate format used to return the Timezone abbrevia‐
2442 tion. It now returns it as a GMT offset (i.e. -0500). %Z
2443 still returns the Timezone abbreviation.
2444 Formats "22nd sunday" returns the intuitive value
2446 The date "22nd sunday" used to return the Sunday of the 22nd
2447 week of the year (which could be the 21st, 22nd, or 23rd Sunday
2448 of the year depending on how weeks were defined). Now, it
2449 returns the 22nd Sunday of the year regardless.
2450 Separator in DD/YYmmm and mmmDD/YY formats no longer optional
2452 Previously, the date "Dec1065" would return Dec 10, 1965.
2453 After adding the YYYYmmm and mmmYYYY formats, this was no
2454 longer possible. The separator between DD and YY is no longer
2455 optional, so
2456 Dec1065 returns December 1, 1065
2458 Dec10/65 returns December 10, 1965
2459 * Date_Cmp added
2461 This is not a backwards incompatibility... but is added to help
2462 prepare for a future incompatibility. In one of the next ver‐
2463 sions of Date::Manip, the internal format of the date will
2464 change to include timezone information. All date comparisons
2465 should be made using Date_Cmp (which currently does nothing
2466 more than call the perl "cmp" command, but which will important
2467 when comparing dates that include the timezone).
2468 VERSION 5.32
2470 Date_Init arguments
2471 The old style Date_Init arguments that were deprecated in ver‐
2472 sion 5.07 have been removed.
2473 * DateManip.cnf change
2475 Changed .DateManip.cnf to Manip.cnf (to get rid of problems on
2476 OS's that insist on 8.3 filenames) for all non-Unix platforms
2477 (Wintel, VMS, Mac). For all Unix platforms, it's still .Date‐
2478 Manip.cnf . It will only look in the user's home directory on
2479 VMS and Unix.
2480 VERSION 5.30
2482 * Delta format changed
2483 A week field has been added to the internal format of the
2484 delta. It now reads "Y:M:W:D:H:MN:S" instead of
2485 "Y:M:D:H:MN:S".
2486 VERSION 5.21
2488 Long running processes may give incorrect timezone
2489 A process that runs during a timezone change (Daylight Saving
2490 Time specifically) may report the wrong timezone. See the
2491 UpdateCurrTZ variable for more information.
2492 UnixDate "%J", "%W", and "%U" formats fixed
2494 The %J, %W, and %U will no longer report a week 0 or a week 53
2495 if it should really be week 1 of the following year. They now
2496 report the correct week number according to ISO 8601.
2497 VERSION 5.20
2499 * ParseDate formats removed (ISO 8601 compatibility)
2500 Full support for ISO 8601 formats was added. As a result, some
2501 formats which previously worked may no longer be parsed since
2502 they conflict with an ISO 8601 format. These include MM-DD-YY
2503 (conflicts with YY-MM-DD) and YYMMDD (conflicts with YYYYMM).
2504 MM/DD/YY still works, so the first form can be kept easily by
2505 changing "-" to "/". YYMMDD can be changed to YY-MM-DD before
2506 being parsed. Whenever parsing dates using dashes as separa‐
2507 tors, they will be treated as ISO 8601 dates. You can get
2508 around this by converting all dashes to slashes.
2509 * Week day numbering
2511 The day numbering was changed from 0-6 (sun-sat) to 1-7
2512 (mon-sun) to be ISO 8601 compatible. Weeks start on Monday
2513 (though this can be overridden using the FirstDay config vari‐
2514 able) and the 1st week of the year contains Jan 4 (though it
2515 can be forced to contain Jan 1 with the Jan1Week1 config vari‐
2516 able).
2517 VERSION 5.07
2519 UnixDate "%s" format
2520 Used to return the number of seconds since 1/1/1970 in the cur‐
2521 rent timezone. It now returns the number of seconds since
2522 1/1/1970 GMT. The "%o" format was added which returns what
2523 "%s" previously did.
2524 Internal format of delta
2526 The format for the deltas returned by ParseDateDelta changed.
2527 Previously, each element of a delta had a sign attached to it
2528 (+1:+2:+3:+4:+5:+6). The new format removes all unnecessary
2529 signs by default (+1:2:3:4:5:6). Also, because of the way
2530 deltas are normalized (see documentation on ParseDateDelta), at
2531 most two signs are included. For backwards compatibility, the
2532 config variable DeltaSigns was added. If set to 1, all deltas
2533 include all 6 signs.
2534 Date_Init arguments
2536 The format of the Date_Init calling arguments changed. The old
2537 method
2538 &Date_Init($language,$format,$tz,$convtz);
2540 is still supported , but this support will likely disappear in
2542 the future. Use the new calling format instead:
2543 &Date_Init("var=val","var=val",...);
2545 NOTE: The old format is no longer supported as of version 5.32
2547 .
2548
2550 The following are not bugs in Date::Manip, but they may give some peo‐
2551 ple problems.
2552 Unable to determine TimeZone
2554 Perhaps the most common problem occurs when you get the error:
2555 Error: Date::Manip unable to determine TimeZone.
2557 Date::Manip tries hard to determine the local timezone, but on some
2559 machines, it cannot do this (especially non-unix systems). To fix
2560 this, just set the TZ variable, either at the top of the Manip.pm
2561 file,, in the DateManip.cnf file, or in a call to Date_Init. I
2562 suggest using the form "EST5EDT" so you don't have to change it
2563 every 6 months when going to or from daylight savings time.
2564 Windows NT does not seem to set the TimeZone by default. From the
2566 Perl-Win32-Users mailing list:
2567 > How do I get the TimeZone on my NT?
2569 >
2570 > $time_zone = $ENV{'TZ'};
2571 >
2572 You have to set the variable before, WinNT doesn't set it by
2573 default. Open the properties of "My Computer" and set a SYSTEM
2574 variable TZ to your timezone. Jenda@Krynicky.cz
2575 This might help out some NT users.
2577 A minor (false) assumption that some users might make is that since
2579 Date::Manip passed all of it's tests at install time, this should
2580 not occur and are surprised when it does.
2581 Some of the tests are timezone dependent. Since the tests all
2583 include input and expected output, I needed to know in advance what
2584 timezone they would be run in. So, the tests all explicitly set
2585 the timezone using the TZ configuration variable passed into
2586 Date_Init. Since this overrides any other method of determining
2587 the timezone, Date::Manip uses this and doesn't have to look else‐
2588 where for the timezone.
2589 When running outside the tests, Date::Manip has to rely on it's
2591 other methods for determining the timezone.
2592 Complaining about getpwnam/getpwuid
2594 Another problem is when running on Micro$oft OS'es. I have added
2595 many tests to catch them, but they still slip through occasionally.
2596 If any ever complain about getpwnam/getpwuid, simply add one of the
2597 lines:
2598 $ENV{OS} = Windows_NT
2600 $ENV{OS} = Windows_95
2601 to your script before
2603 use Date::Manip
2605 Date::Manip is slow
2607 The reasons for this are covered in the SHOULD I USE DATE::MANIP
2608 section above.
2609 Some things that will definitely help:
2611 Version 5.21 does run noticeably faster than earlier versions due
2613 to rethinking some of the initialization, so at the very least,
2614 make sure you are running this version or later.
2615 ISO-8601 dates are parsed first and fastest. Use them whenever
2617 possible.
2618 Avoid parsing dates that are referenced against the current time
2620 (in 2 days, today at noon, etc.). These take a lot longer to
2621 parse.
2622 Example: parsing 1065 dates with version 5.11 took 48.6 seconds, 36.2
2624 seconds with version 5.21, and parsing 1065 ISO-8601 dates with version
2625 5.21 took 29.1 seconds (these were run on a slow, overloaded computer with
2626 little memory... but the ratios should be reliable on a faster computer).
2627 Business date calculations are extremely slow. You should consider
2629 alternatives if possible (i.e. doing the calculation in exact mode
2630 and then multiplying by 5/7). There will be an approximate busi‐
2631 ness mode in one of the next versions which will be much faster
2632 (though less accurate) which will do something like this. Whenever
2633 possible, use this mode. And who needs a business date more accu‐
2634 rate than "6 to 8 weeks" anyway huh :-)
2635 Never call Date_Init more than once. Unless you're doing something
2637 very strange, there should never be a reason to anyway.
2638 Sorting Problems
2640 If you use Date::Manip to sort a number of dates, you must call
2641 Date_Init either explicitly, or by way of some other Date::Manip
2642 routine before it is used in the sort. For example, the following
2643 code fails:
2644 use Date::Manip;
2646 # &Date_Init;
2647 sub sortDate {
2648 my($date1, $date2);
2649 $date1 = &ParseDate($a);
2650 $date2 = &ParseDate($b);
2651 return (&Date_Cmp($date1,$date2));
2652 }
2653 @dates = ("Fri 16 Aug 96",
2654 "Mon 19 Aug 96",
2655 "Thu 15 Aug 96");
2656 @i=sort sortDate @dates;
2657 but if you uncomment the Date_Init line, it works. The reason for
2659 this is that the first time you call Date_Init, it initializes a
2660 number of items used by Date::Manip. Some of these have to be
2661 sorted (regular expressions sorted by length to ensure the longest
2662 match). It turns out that perl has a bug in it which does not
2663 allow a sort within a sort. At some point, this should be fixed,
2664 but for now, the best thing to do is to call Date_Init explicitly.
2665 The bug exists in all versions up to 5.005 (I haven't tested 5.6.0
2666 yet).
2667 NOTE: This is an EXTREMELY inefficient way to sort data (but read
2669 the 2nd note below for an easy way to correct this). Instead, you
2670 should parse the dates with ParseDate, sort them using a normal
2671 string comparison, and then convert them back to the format desired
2672 using UnixDate.
2673 2nd NOTE: It has been reported to me that you can still use Parse‐
2675 Date to sort dates in this way, and be quite efficient through the
2676 use of Memoize. Just add the following lines to your code:
2677 use Date::Manip;
2679 use Memoize;
2680 memoize('ParseDate');
2681 ...
2682 @i=sort sortDate @dates;
2683 Since sortDate would call ParseDate with the same data over and
2685 over, this is a perfect application for the Memoize module. So,
2686 sorting with ParseDate is no longer slow for sorting.
2687 RCS Control
2689 If you try to put Date::Manip under RCS control, you are going to
2690 have problems. Apparently, RCS replaces strings of the form
2691 "$Date...$" with the current date. This form occurs all over in
2692 Date::Manip. To prevent the RCS keyword expansion, checkout files
2693 using "co -ko". Since very few people will ever have a desire to
2694 do this (and I don't use RCS), I have not worried about it.
2695
2697 Daylight Savings Times
2698 Date::Manip does not handle daylight savings time, though it does
2699 handle timezones to a certain extent. Converting from EST to PST
2700 works fine. Going from EST to PDT is unreliable.
2701 The following examples are run in the winter of the US East coast
2703 (i.e. in the EST timezone).
2704 print UnixDate(ParseDate("6/1/97 noon"),"%u"),"\n";
2706 => Sun Jun 1 12:00:00 EST 1997
2707 June 1 EST does not exist. June 1st is during EDT. It should
2709 print:
2710 => Sun Jun 1 00:00:00 EDT 1997
2712 Even explicitly adding the timezone doesn't fix things (if any‐
2714 thing, it makes them worse):
2715 print UnixDate(ParseDate("6/1/97 noon EDT"),"%u"),"\n";
2717 => Sun Jun 1 11:00:00 EST 1997
2718 Date::Manip converts everything to the current timezone (EST in
2720 this case).
2721 Related problems occur when trying to do date calculations over a
2723 timezone change. These calculations may be off by an hour.
2724 Also, if you are running a script which uses Date::Manip over a
2726 period of time which starts in one time zone and ends in another
2727 (i.e. it switches form Daylight Savings Time to Standard Time or
2728 vice versa), many things may be wrong (especially elapsed time).
2729 I hope to fix these problems in a future release so that it would
2731 convert everything to the current zones (EST or EDT).
2732
2734 If you find a bug in Date::Manip, please send it directly to me (see
2735 the AUTHOR section below) rather than posting it to one of the news‐
2736 groups. Although I try to keep up with the comp.lang.perl.* groups,
2737 all too often I miss news (flaky news server, articles expiring before
2738 I caught them, 1200 articles to wade through and I missed one that I
2739 was interested in, etc.).
2740 When filing a bug report, please include the following information:
2742 o The version of Date::Manip you are using. You can get this by using
2744 the script:
2745 use Date::Manip;
2747 print &DateManipVersion(),"\n";
2748 o The output from "perl -V"
2750 If you have a problem using Date::Manip that perhaps isn't a bug (can't
2752 figure out the syntax, etc.), you're in the right place. Go right back
2753 to the top of this man page and start reading. If this still doesn't
2754 answer your question, mail me (again, please mail me rather than post
2755 to the newsgroup).
2756
2758 In hindsight, the fact that I've only been asked once (so far) if
2759 Date::Manip is year 2000 compliant surprises me a bit. Still, as 2000
2760 approaches and this buzzword starts flying around more and more franti‐
2761 cally, other's might follow suit, so this section answers the question.
2762 Is Date::Manip year 2000 compliant?
2764 This question is largely meaningless. Date::Manip is basically just a
2766 parser. You give it a date and it'll manipulate it. Date::Manip does
2767 store the date internally as a 4 digit year, and performs all opera‐
2768 tions using this internal representation, so I will state that
2769 Date::Manip is CAPABLE of writing Y2K compliant code.
2770 But Date::Manip is simply a library. If you use it correctly, your
2772 code can be Y2K compliant. If you don't, your code may not be Y2K com‐
2773 pliant.
2774 The bottom line is this:
2776 Date::Manip is a library that is capable of being used to write Y2K
2778 compliant code. It may also be used to write non-Y2K compliant code.
2779 If your code is NOT Y2K compliant, it is NOT due to any deficiency in
2781 Date::Manip. Rather, it is due to poor programming on the part of the
2782 person using Date::Manip.
2783 For an excellent treatment of the Y2K problem, see the article by Tom
2785 Christiansen at:
2786 http://language.perl.com/news/y2k.html
2788 A slightly better question is "Is Perl year 2000 compliant"? This is
2790 covered in the perl FAQ (section 4) and in the article by Tom Crhis‐
2791 tiansen.
2792 The best question is "For what dates is Date::Manip useful?" It defi‐
2794 nitely can't handle BC dates, or dates past Dec 31, 9999. So
2795 Date::Manip works during the years 1000 to 9999.
2796 In practical terms however, Date::Manip deals with the Gregorian calen‐
2798 dar, and is therefore useful in the period that that calendar has been,
2799 or will be, in effect. The Gregorian calendar was first adopted by the
2800 Catholic church in 1582, but some countries were still using the Julian
2801 calendar as late as the early part of the 20th century. Also, at some
2802 point (probably no earlier than the year 3000 and possibly much later),
2803 the Gregorian system is going to have to be modified slightly since the
2804 current system of leap years is off by a few seconds a year. So... in
2805 practical terms, Date::Manip is _probably_ useful from 1900 to 3000.
2806 One other note is that Date::Manip will NOT handle 3 digit years. So,
2808 if you store the year as an offset from 1900 (which is 2 digits now,
2809 but will become 3 digits in 2000), these will NOT be parsable by
2810 Date::Manip.
2811
2813 A note about version numbers.
2814 Prior to version 5.00, Date::Manip was distributed as a perl4 library.
2816 There were no numbering conventions in place, so I used a simple
2817 MAJOR.MINOR numbering scheme.
2818 With version 5.00, I switched to a perl5 module and at that time
2820 switched to the perl5 numbering convention of a major version followed
2821 by a 2 digit minor version.
2822 As of 5.41/5.42, all versions released to CPAN will be even numbered.
2824 Odd numbered will be development versions available from my web site.
2825 For example, after 5.40 was released, I started making changes, and
2826 called the development version 5.41. When released to CPAN, it was
2827 called 5.42. I may add a third digit to development versions (i.e.
2828 5.41.9) to keep track of important changes in the development version.
2829
2831 There are many people who have contributed to Date::Manip over the
2832 years that I'd like to thank. The most important contributions have
2833 come in the form of suggestions and bug reports by users. I have tried
2834 to include the name of every person who first suggested each improve‐
2835 ment or first reported each bug. These are included in the HISTORY
2836 file in the Date::Manip distribution in the order the changes are made.
2837 The list is simply too long to appear here, but I appreciate their
2838 help.
2839 A number of people have made suggestions or reported bugs which are not
2841 mentioned in the HISTORY file. These include suggestions which have
2842 not been implemented and people who have made a suggestion or bug
2843 report which has already been suggested/reported by someone else. For
2844 those who's suggestions have not yet been implemented, they will be
2845 added to the HISTORY file when (if) their suggestions are implemented.
2846 For everyone else, thank you too. I'd much rather have a suggestion
2847 made twice than not at all.
2848 Thanks to Alan Cezar and Greg Schiedler for paying me to implement the
2850 Events_List routine. They gave me the idea, and were then willing to
2851 pay me for my time to get it implemented quickly.
2852 I'd also like a couple of authors. Date::Manip has recently been get‐
2854 ting some really good press in a couple of books. Since no one's pay‐
2855 ing me to write Date::Manip, seeing my module get a good review in a
2856 book written by someone else really makes my day. My thanks to Nate
2857 Padwardhan and Clay Irving (Programming with Perl Modules -- part of
2858 the O'Reilly Perl Resource Kit); and Tom Christiansen and Nathan Tork‐
2859 ington (The Perl Cookbook). Also, thanks to any other authors who've
2860 written about Date::Manip who's books I haven't seen.
2861
2863 Sullivan Beck (sbeck@cpan.org)
2864 You can always get the newest beta version of Date::Manip (which may
2866 fix problems in the current CPAN version... and may add others) from my
2867 home page:
2868 http://www.cise.ufl.edu/~sbeck/
2870perl v5.8.8 2008-03-26 Manip(3)