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