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