Commit | Line | Data |
---|---|---|
86530b38 AT |
1 | |
2 | =head1 NAME | |
3 | ||
4 | Date::Calc - Gregorian calendar date calculations | |
5 | ||
6 | =head1 MOTTO | |
7 | ||
8 | Keep it small, fast and simple | |
9 | ||
10 | =head1 PREFACE | |
11 | ||
12 | This package consists of a C library and a Perl module (which uses | |
13 | the C library, internally) for all kinds of date calculations based | |
14 | on the Gregorian calendar (the one used in all western countries today), | |
15 | thereby complying with all relevant norms and standards: S<ISO/R 2015-1971>, | |
16 | S<DIN 1355> and, to some extent, S<ISO 8601> (where applicable). | |
17 | ||
18 | (See also http://www.engelschall.com/u/sb/download/Date-Calc/DIN1355/ | |
19 | for a scan of part of the "S<DIN 1355>" document (in German)). | |
20 | ||
21 | The module of course handles year numbers of 2000 and above correctly | |
22 | ("Year 2000" or "Y2K" compliance) -- actually all year numbers from 1 | |
23 | to the largest positive integer representable on your system (which | |
24 | is at least 32767) can be dealt with. | |
25 | ||
26 | This is not true, however, for the import/export functions in this | |
27 | package which are an interface to the internal POSIX date and time | |
28 | functions of your system, which can only cover dates in the following | |
29 | ranges: | |
30 | ||
31 | 01-Jan-1970 00:00:00 GMT .. 19-Jan-2038 03:14:07 GMT [Unix etc.] | |
32 | 01-Jan-1904 00:00:00 LT .. 06-Feb-2040 06:28:15 LT [MacOS Classic] | |
33 | (LT = local time) | |
34 | ||
35 | Note that this package projects the Gregorian calendar back until the | |
36 | year S<1 A.D.> -- even though the Gregorian calendar was only adopted | |
37 | in 1582, mostly by the Catholic European countries, in obedience to the | |
38 | corresponding decree of Pope S<Gregory XIII> in that year. | |
39 | ||
40 | Some (mainly protestant) countries continued to use the Julian calendar | |
41 | (used until then) until as late as the beginning of the 20th century. | |
42 | ||
43 | Finally, note that this package is not intended to do everything you could | |
44 | ever imagine automagically for you; it is rather intended to serve as a | |
45 | toolbox (in the best of UNIX spirit and traditions) which should, however, | |
46 | always get you where you want to go. | |
47 | ||
48 | See the section "RECIPES" at the bottom of this document for solutions | |
49 | to common problems! | |
50 | ||
51 | If nevertheless you can't figure out how to solve a particular problem, | |
52 | please let me know! (See e-mail address at the end of this document.) | |
53 | ||
54 | =head1 SYNOPSIS | |
55 | ||
56 | use Date::Calc qw( | |
57 | Days_in_Year | |
58 | Days_in_Month | |
59 | Weeks_in_Year | |
60 | leap_year | |
61 | check_date | |
62 | check_time | |
63 | check_business_date | |
64 | Day_of_Year | |
65 | Date_to_Days | |
66 | Day_of_Week | |
67 | Week_Number | |
68 | Week_of_Year | |
69 | Monday_of_Week | |
70 | Nth_Weekday_of_Month_Year | |
71 | Standard_to_Business | |
72 | Business_to_Standard | |
73 | Delta_Days | |
74 | Delta_DHMS | |
75 | Delta_YMD | |
76 | Delta_YMDHMS | |
77 | Normalize_DHMS | |
78 | Add_Delta_Days | |
79 | Add_Delta_DHMS | |
80 | Add_Delta_YM | |
81 | Add_Delta_YMD | |
82 | Add_Delta_YMDHMS | |
83 | System_Clock | |
84 | Today | |
85 | Now | |
86 | Today_and_Now | |
87 | This_Year | |
88 | Gmtime | |
89 | Localtime | |
90 | Mktime | |
91 | Timezone | |
92 | Date_to_Time | |
93 | Time_to_Date | |
94 | Easter_Sunday | |
95 | Decode_Month | |
96 | Decode_Day_of_Week | |
97 | Decode_Language | |
98 | Decode_Date_EU | |
99 | Decode_Date_US | |
100 | Fixed_Window | |
101 | Moving_Window | |
102 | Compress | |
103 | Uncompress | |
104 | check_compressed | |
105 | Compressed_to_Text | |
106 | Date_to_Text | |
107 | Date_to_Text_Long | |
108 | English_Ordinal | |
109 | Calendar | |
110 | Month_to_Text | |
111 | Day_of_Week_to_Text | |
112 | Day_of_Week_Abbreviation | |
113 | Language_to_Text | |
114 | Language | |
115 | Languages | |
116 | Decode_Date_EU2 | |
117 | Decode_Date_US2 | |
118 | Parse_Date | |
119 | ISO_LC | |
120 | ISO_UC | |
121 | ); | |
122 | ||
123 | use Date::Calc qw(:all); | |
124 | ||
125 | Days_in_Year | |
126 | $days = Days_in_Year($year,$month); | |
127 | ||
128 | Days_in_Month | |
129 | $days = Days_in_Month($year,$month); | |
130 | ||
131 | Weeks_in_Year | |
132 | $weeks = Weeks_in_Year($year); | |
133 | ||
134 | leap_year | |
135 | if (leap_year($year)) | |
136 | ||
137 | check_date | |
138 | if (check_date($year,$month,$day)) | |
139 | ||
140 | check_time | |
141 | if (check_time($hour,$min,$sec)) | |
142 | ||
143 | check_business_date | |
144 | if (check_business_date($year,$week,$dow)) | |
145 | ||
146 | Day_of_Year | |
147 | $doy = Day_of_Year($year,$month,$day); | |
148 | ||
149 | Date_to_Days | |
150 | $days = Date_to_Days($year,$month,$day); | |
151 | ||
152 | Day_of_Week | |
153 | $dow = Day_of_Week($year,$month,$day); | |
154 | ||
155 | Week_Number | |
156 | $week = Week_Number($year,$month,$day); # DEPRECATED | |
157 | ||
158 | Week_of_Year | |
159 | ($week,$year) = Week_of_Year($year,$month,$day); # RECOMMENDED | |
160 | $week = Week_of_Year($year,$month,$day); # DANGEROUS | |
161 | ||
162 | Monday_of_Week | |
163 | ($year,$month,$day) = Monday_of_Week($week,$year); | |
164 | ||
165 | Nth_Weekday_of_Month_Year | |
166 | if (($year,$month,$day) = | |
167 | Nth_Weekday_of_Month_Year($year,$month,$dow,$n)) | |
168 | ||
169 | Standard_to_Business | |
170 | ($year,$week,$dow) = | |
171 | Standard_to_Business($year,$month,$day); | |
172 | ||
173 | Business_to_Standard | |
174 | ($year,$month,$day) = | |
175 | Business_to_Standard($year,$week,$dow); | |
176 | ||
177 | Delta_Days | |
178 | $Dd = Delta_Days($year1,$month1,$day1, | |
179 | $year2,$month2,$day2); | |
180 | ||
181 | Delta_DHMS | |
182 | ($Dd,$Dh,$Dm,$Ds) = | |
183 | Delta_DHMS($year1,$month1,$day1, $hour1,$min1,$sec1, | |
184 | $year2,$month2,$day2, $hour2,$min2,$sec2); | |
185 | ||
186 | Delta_YMD | |
187 | ($Dy,$Dm,$Dd) = | |
188 | Delta_YMD($year1,$month1,$day1, | |
189 | $year2,$month2,$day2); | |
190 | ||
191 | Delta_YMDHMS | |
192 | ($D_y,$D_m,$D_d, $Dh,$Dm,$Ds) = | |
193 | Delta_YMDHMS($year1,$month1,$day1, $hour1,$min1,$sec1, | |
194 | $year2,$month2,$day2, $hour2,$min2,$sec2); | |
195 | ||
196 | Normalize_DHMS | |
197 | ($Dd,$Dh,$Dm,$Ds) = | |
198 | Normalize_DHMS($Dd,$Dh,$Dm,$Ds); | |
199 | ||
200 | Add_Delta_Days | |
201 | ($year,$month,$day) = | |
202 | Add_Delta_Days($year,$month,$day, | |
203 | $Dd); | |
204 | ||
205 | Add_Delta_DHMS | |
206 | ($year,$month,$day, $hour,$min,$sec) = | |
207 | Add_Delta_DHMS($year,$month,$day, $hour,$min,$sec, | |
208 | $Dd,$Dh,$Dm,$Ds); | |
209 | ||
210 | Add_Delta_YM | |
211 | ($year,$month,$day) = | |
212 | Add_Delta_YM($year,$month,$day, | |
213 | $Dy,$Dm); | |
214 | ||
215 | Add_Delta_YMD | |
216 | ($year,$month,$day) = | |
217 | Add_Delta_YMD($year,$month,$day, | |
218 | $Dy,$Dm,$Dd); | |
219 | ||
220 | Add_Delta_YMDHMS | |
221 | ($year,$month,$day, $hour,$min,$sec) = | |
222 | Add_Delta_YMDHMS($year,$month,$day, $hour,$min,$sec, | |
223 | $D_y,$D_m,$D_d, $Dh,$Dm,$Ds); | |
224 | ||
225 | System_Clock | |
226 | ($year,$month,$day, $hour,$min,$sec, $doy,$dow,$dst) = | |
227 | System_Clock([$gmt]); | |
228 | ||
229 | Today | |
230 | ($year,$month,$day) = Today([$gmt]); | |
231 | ||
232 | Now | |
233 | ($hour,$min,$sec) = Now([$gmt]); | |
234 | ||
235 | Today_and_Now | |
236 | ($year,$month,$day, $hour,$min,$sec) = Today_and_Now([$gmt]); | |
237 | ||
238 | This_Year | |
239 | $year = This_Year([$gmt]); | |
240 | ||
241 | Gmtime | |
242 | ($year,$month,$day, $hour,$min,$sec, $doy,$dow,$dst) = | |
243 | Gmtime([time]); | |
244 | ||
245 | Localtime | |
246 | ($year,$month,$day, $hour,$min,$sec, $doy,$dow,$dst) = | |
247 | Localtime([time]); | |
248 | ||
249 | Mktime | |
250 | $time = Mktime($year,$month,$day, $hour,$min,$sec); | |
251 | ||
252 | Timezone | |
253 | ($D_y,$D_m,$D_d, $Dh,$Dm,$Ds, $dst) = Timezone([time]); | |
254 | ||
255 | Date_to_Time | |
256 | $time = Date_to_Time($year,$month,$day, $hour,$min,$sec); | |
257 | ||
258 | Time_to_Date | |
259 | ($year,$month,$day, $hour,$min,$sec) = Time_to_Date([time]); | |
260 | ||
261 | Easter_Sunday | |
262 | ($year,$month,$day) = Easter_Sunday($year); | |
263 | ||
264 | Decode_Month | |
265 | if ($month = Decode_Month($string)) | |
266 | ||
267 | Decode_Day_of_Week | |
268 | if ($dow = Decode_Day_of_Week($string)) | |
269 | ||
270 | Decode_Language | |
271 | if ($lang = Decode_Language($string)) | |
272 | ||
273 | Decode_Date_EU | |
274 | if (($year,$month,$day) = Decode_Date_EU($string)) | |
275 | ||
276 | Decode_Date_US | |
277 | if (($year,$month,$day) = Decode_Date_US($string)) | |
278 | ||
279 | Fixed_Window | |
280 | $year = Fixed_Window($yy); | |
281 | ||
282 | Moving_Window | |
283 | $year = Moving_Window($yy); | |
284 | ||
285 | Compress | |
286 | $date = Compress($year,$month,$day); | |
287 | ||
288 | Uncompress | |
289 | if (($century,$year,$month,$day) = Uncompress($date)) | |
290 | ||
291 | check_compressed | |
292 | if (check_compressed($date)) | |
293 | ||
294 | Compressed_to_Text | |
295 | $string = Compressed_to_Text($date); | |
296 | ||
297 | Date_to_Text | |
298 | $string = Date_to_Text($year,$month,$day); | |
299 | ||
300 | Date_to_Text_Long | |
301 | $string = Date_to_Text_Long($year,$month,$day); | |
302 | ||
303 | English_Ordinal | |
304 | $string = English_Ordinal($number); | |
305 | ||
306 | Calendar | |
307 | $string = Calendar($year,$month[,$orthodox]); | |
308 | ||
309 | Month_to_Text | |
310 | $string = Month_to_Text($month); | |
311 | ||
312 | Day_of_Week_to_Text | |
313 | $string = Day_of_Week_to_Text($dow); | |
314 | ||
315 | Day_of_Week_Abbreviation | |
316 | $string = Day_of_Week_Abbreviation($dow); | |
317 | ||
318 | Language_to_Text | |
319 | $string = Language_to_Text($lang); | |
320 | ||
321 | Language | |
322 | $lang = Language(); | |
323 | Language($lang); | |
324 | $oldlang = Language($newlang); | |
325 | ||
326 | Languages | |
327 | $max_lang = Languages(); | |
328 | ||
329 | Decode_Date_EU2 | |
330 | if (($year,$month,$day) = Decode_Date_EU2($string)) | |
331 | ||
332 | Decode_Date_US2 | |
333 | if (($year,$month,$day) = Decode_Date_US2($string)) | |
334 | ||
335 | Parse_Date | |
336 | if (($year,$month,$day) = Parse_Date($string)) | |
337 | ||
338 | ISO_LC | |
339 | $lower = ISO_LC($string); | |
340 | ||
341 | ISO_UC | |
342 | $upper = ISO_UC($string); | |
343 | ||
344 | Version | |
345 | $string = Date::Calc::Version(); | |
346 | ||
347 | =head1 IMPORTANT NOTES | |
348 | ||
349 | (See the section "RECIPES" at the bottom of this document for | |
350 | solutions to common problems!) | |
351 | ||
352 | =over 2 | |
353 | ||
354 | =item * | |
355 | ||
356 | "Year 2000" ("Y2K") compliance | |
357 | ||
358 | The upper limit for any year number in this module is only given | |
359 | by the size of the largest positive integer that can be represented | |
360 | in a variable of the C type "int" on your system, which is at least | |
361 | 32767, according to the ANSI C standard (exceptions see below). | |
362 | ||
363 | In order to simplify calculations, this module projects the gregorian | |
364 | calendar back until the year S<1 A.D.> -- i.e., back B<BEYOND> the | |
365 | year 1582 when this calendar was first decreed by the Catholic Pope | |
366 | S<Gregory XIII>! | |
367 | ||
368 | Therefore, B<BE SURE TO ALWAYS SPECIFY "1998" WHEN YOU MEAN "1998">, | |
369 | for instance, and B<DO NOT WRITE "98" INSTEAD>, because this will | |
370 | in fact perform a calculation based on the year "98" A.D. and | |
371 | B<NOT> "1998"! | |
372 | ||
373 | An exception from this rule are the functions which contain the | |
374 | word "compress" in their names (which can only handle years between | |
375 | 1970 and 2069 and also accept the abbreviations "00" to "99"), and | |
376 | the functions whose names begin with "Decode_Date_" (which translate | |
377 | year numbers below 100 using a technique known as "moving window"). | |
378 | ||
379 | If you want to convert a two-digit year number into a full-fledged, | |
380 | four-digit (at least for some years to come C<;-)>) year number, | |
381 | use the two functions "Fixed_Window()" and "Moving_Window()" | |
382 | (see their description further below). | |
383 | ||
384 | Note also that the following import/export functions (which are | |
385 | interfaces to the POSIX functions "time()", "gmtime()", "localtime()" | |
386 | and "mktime()" or (the last two) substitutes for the BSD function | |
387 | "timegm()" and the POSIX function "gmtime()") have a very limited | |
388 | range of representable dates (in contrast to all other functions | |
389 | in this package, which cover virtually any date including and | |
390 | after S<January 1st 1 A.D.>): | |
391 | ||
392 | System_Clock() | |
393 | Today() | |
394 | Now() | |
395 | Today_and_Now() | |
396 | This_Year() | |
397 | Gmtime() | |
398 | Localtime() | |
399 | Mktime() | |
400 | Timezone() | |
401 | Date_to_Time() | |
402 | Time_to_Date() | |
403 | ||
404 | These functions can only deal with dates in the range from | |
405 | S<01-Jan-1970 00:00:00 GMT> to S<19-Jan-2038 03:14:07 GMT> | |
406 | (the latter limit is only authoritative on S<32 bit> systems, | |
407 | however, and can (in principle, through a few code changes) | |
408 | be extended somewhat C<:-)> on S<64 bit> systems). | |
409 | ||
410 | On MacOS Classic, the valid range of dates is between | |
411 | (both included) S<01-Jan-1904 00:00:00> (local time) | |
412 | to S<06-Feb-2040 06:28:15> (local time). | |
413 | ||
414 | Note further that the function "Easter_Sunday()" can only | |
415 | be used for years in the range 1583 to 2299. | |
416 | ||
417 | =item * | |
418 | ||
419 | First index | |
420 | ||
421 | B<ALL> ranges in this module start with "C<1>", B<NOT> "C<0>"! | |
422 | ||
423 | I.e., the day of month, day of week, day of year, month of year, | |
424 | week of year, first valid year number and language B<ALL> start | |
425 | counting at one, B<NOT> zero! | |
426 | ||
427 | The only exception is the function "C<Week_Number()>", which may | |
428 | in fact return "C<0>" when the given date actually lies in the | |
429 | last week of the B<PREVIOUS> year, and of course the numbers for | |
430 | hours (C<0..23>), minutes (C<0..59>) and seconds (C<0..59>). | |
431 | ||
432 | =item * | |
433 | ||
434 | Function naming conventions | |
435 | ||
436 | Function names completely in lower case indicate a boolean return value. | |
437 | ||
438 | =item * | |
439 | ||
440 | Boolean values | |
441 | ||
442 | Boolean values in this module are always a numeric zero ("C<0>") for | |
443 | "false" and a numeric one ("C<1>") for "true". | |
444 | ||
445 | =item * | |
446 | ||
447 | Exception handling | |
448 | ||
449 | The functions in this module will usually die with a corresponding error | |
450 | message if their input parameters, intermediate results or output values | |
451 | are out of range. | |
452 | ||
453 | The following functions handle errors differently: | |
454 | ||
455 | - check_date() | |
456 | - check_time() | |
457 | - check_business_date() | |
458 | - check_compressed() | |
459 | ||
460 | (which return a "false" return value when the given input does not represent | |
461 | a valid date or time), | |
462 | ||
463 | - Nth_Weekday_of_Month_Year() | |
464 | ||
465 | (which returns an empty list if the requested 5th day of week does not exist), | |
466 | ||
467 | - Decode_Month() | |
468 | - Decode_Day_of_Week() | |
469 | - Decode_Language() | |
470 | - Fixed_Window() | |
471 | - Moving_Window() | |
472 | - Compress() | |
473 | ||
474 | (which return "C<0>" upon failure or invalid input), and | |
475 | ||
476 | - Decode_Date_EU() | |
477 | - Decode_Date_US() | |
478 | - Decode_Date_EU2() | |
479 | - Decode_Date_US2() | |
480 | - Parse_Date() | |
481 | - Uncompress() | |
482 | ||
483 | (which return an empty list upon failure or invalid input). | |
484 | ||
485 | Note that you can always catch an exception thrown by any of the functions | |
486 | in this module and handle it yourself by enclosing the function call in an | |
487 | "C<eval>" with curly brackets and checking the special variable "C<$@>" | |
488 | (see L<perlfunc(1)/eval> for details). | |
489 | ||
490 | =back | |
491 | ||
492 | =head1 DESCRIPTION | |
493 | ||
494 | =over 2 | |
495 | ||
496 | =item * | |
497 | ||
498 | C<use Date::Calc qw( Days_in_Year Days_in_Month ... );> | |
499 | ||
500 | =item * | |
501 | ||
502 | C<use Date::Calc qw(:all);> | |
503 | ||
504 | You can either specify the functions you want to import explicitly by | |
505 | enumerating them between the parentheses of the "C<qw()>" operator, or | |
506 | you can use the "C<:all>" tag instead to import B<ALL> available functions. | |
507 | ||
508 | =item * | |
509 | ||
510 | C<$days = Days_in_Year($year,$month);> | |
511 | ||
512 | This function returns the sum of the number of days in the months starting | |
513 | with January up to and including "C<$month>" in the given year "C<$year>". | |
514 | ||
515 | I.e., "C<Days_in_Year(1998,1)>" returns "C<31>", "C<Days_in_Year(1998,2)>" | |
516 | returns "C<59>", "C<Days_in_Year(1998,3)>" returns "C<90>", and so on. | |
517 | ||
518 | Note that "C<Days_in_Year($year,12)>" returns the number of days in the | |
519 | given year "C<$year>", i.e., either "C<365>" or "C<366>". | |
520 | ||
521 | =item * | |
522 | ||
523 | C<$days = Days_in_Month($year,$month);> | |
524 | ||
525 | This function returns the number of days in the given month "C<$month>" of | |
526 | the given year "C<$year>". | |
527 | ||
528 | The year must always be supplied, even though it is only needed when the | |
529 | month is February, in order to determine whether it is a leap year or not. | |
530 | ||
531 | I.e., "C<Days_in_Month(1998,1)>" returns "C<31>", "C<Days_in_Month(1998,2)>" | |
532 | returns "C<28>", "C<Days_in_Month(2000,2)>" returns "C<29>", | |
533 | "C<Days_in_Month(1998,3)>" returns "C<31>", and so on. | |
534 | ||
535 | =item * | |
536 | ||
537 | C<$weeks = Weeks_in_Year($year);> | |
538 | ||
539 | This function returns the number of weeks in the given year "C<$year>", | |
540 | i.e., either "C<52>" or "C<53>". | |
541 | ||
542 | =item * | |
543 | ||
544 | C<if (leap_year($year))> | |
545 | ||
546 | This function returns "true" ("C<1>") if the given year "C<$year>" is | |
547 | a leap year and "false" ("C<0>") otherwise. | |
548 | ||
549 | =item * | |
550 | ||
551 | C<if (check_date($year,$month,$day))> | |
552 | ||
553 | This function returns "true" ("C<1>") if the given three numerical | |
554 | values "C<$year>", "C<$month>" and "C<$day>" constitute a valid date, | |
555 | and "false" ("C<0>") otherwise. | |
556 | ||
557 | =item * | |
558 | ||
559 | C<if (check_time($hour,$min,$sec))> | |
560 | ||
561 | This function returns "true" ("C<1>") if the given three numerical | |
562 | values "C<$hour>", "C<$min>" and "C<$sec>" constitute a valid time | |
563 | (C<0 E<lt>= $hour E<lt> 24>, C<0 E<lt>= $min E<lt> 60> and | |
564 | C<0 E<lt>= $sec E<lt> 60>), and "false" ("C<0>") otherwise. | |
565 | ||
566 | =item * | |
567 | ||
568 | C<if (check_business_date($year,$week,$dow))> | |
569 | ||
570 | This function returns "true" ("C<1>") if the given three numerical | |
571 | values "C<$year>", "C<$week>" and "C<$dow>" constitute a valid date | |
572 | in business format, and "false" ("C<0>") otherwise. | |
573 | ||
574 | B<Beware> that this function does B<NOT> compute whether a given date | |
575 | is a business day (i.e., Monday to Friday)! | |
576 | ||
577 | To do so, use "C<(Day_of_Week($year,$month,$day) E<lt> 6)>" instead. | |
578 | ||
579 | =item * | |
580 | ||
581 | C<$doy = Day_of_Year($year,$month,$day);> | |
582 | ||
583 | This function returns the (relative) number of the day of the given date | |
584 | in the given year. | |
585 | ||
586 | E.g., "C<Day_of_Year($year,1,1)>" returns "C<1>", | |
587 | "C<Day_of_Year($year,2,1)>" returns "C<32>", and | |
588 | "C<Day_of_Year($year,12,31)>" returns either "C<365>" or "C<366>". | |
589 | ||
590 | =item * | |
591 | ||
592 | C<$days = Date_to_Days($year,$month,$day);> | |
593 | ||
594 | This function returns the (absolute) number of the day of the given date, | |
595 | where counting starts at the 1st of January of the year S<1 A.D.> | |
596 | ||
597 | I.e., "C<Date_to_Days(1,1,1)>" returns "C<1>", "C<Date_to_Days(1,12,31)>" | |
598 | returns "C<365>", "C<Date_to_Days(2,1,1)>" returns "C<366>", | |
599 | "C<Date_to_Days(1998,5,1)>" returns "C<729510>", and so on. | |
600 | ||
601 | This is sometimes also referred to (not quite correctly) as the Julian | |
602 | date (or day). This may cause confusion, because also the number of the | |
603 | day in a year (from 1 to 365 or 366) is frequently called the "Julian date". | |
604 | ||
605 | In fact the calendar that was used B<BEFORE> the Gregorian calendar | |
606 | was the Julian calendar - named after famous Julius Caesar, who had | |
607 | instituted it in Roman times. The Julian calendar was less precise | |
608 | because it had too many leap years compared to the true mean length | |
609 | of a year, and because rulers often changed it arbitrarily, in order | |
610 | to lengthen their own reign, for instance. | |
611 | ||
612 | In order to convert the number returned by this function back into | |
613 | a date, use the function "C<Add_Delta_Days()>" (described further | |
614 | below), as follows: | |
615 | ||
616 | $days = Date_to_Days($year,$month,$day); | |
617 | ($year,$month,$day) = Add_Delta_Days(1,1,1, $days - 1); | |
618 | ||
619 | =item * | |
620 | ||
621 | C<$dow = Day_of_Week($year,$month,$day);> | |
622 | ||
623 | This function returns the number of the day of week of the given date. | |
624 | ||
625 | The function returns "C<1>" for Monday, "C<2>" for Tuesday and so on | |
626 | until "C<7>" for Sunday. | |
627 | ||
628 | Note that in the Hebrew calendar (on which the Christian calendar is based), | |
629 | the week starts with Sunday and ends with the Sabbath or Saturday (where | |
630 | according to the Genesis (as described in the Bible) the Lord rested from | |
631 | creating the world). | |
632 | ||
633 | In medieval times, Catholic Popes have decreed the Sunday to be the official | |
634 | day of rest, in order to dissociate the Christian from the Hebrew belief. | |
635 | ||
636 | Nowadays, the Sunday B<AND> the Saturday are commonly considered (and | |
637 | used as) days of rest, usually referred to as the "week-end". | |
638 | ||
639 | Consistent with this practice, current norms and standards (such as | |
640 | S<ISO/R 2015-1971>, S<DIN 1355> and S<ISO 8601>) define the Monday | |
641 | as the first day of the week. | |
642 | ||
643 | =item * | |
644 | ||
645 | C<$week = Week_Number($year,$month,$day);> | |
646 | ||
647 | This function returns the number of the week the given date lies in. | |
648 | ||
649 | If the given date lies in the B<LAST> week of the B<PREVIOUS> year, | |
650 | "C<0>" is returned. | |
651 | ||
652 | If the given date lies in the B<FIRST> week of the B<NEXT> year, | |
653 | "C<Weeks_in_Year($year) + 1>" is returned. | |
654 | ||
655 | =item * | |
656 | ||
657 | C<($week,$year) = Week_of_Year($year,$month,$day);> | |
658 | ||
659 | This function returns the number of the week the given date lies in, | |
660 | as well as the year that week belongs to. | |
661 | ||
662 | I.e., if the given date lies in the B<LAST> week of the B<PREVIOUS> year, | |
663 | "C<(Weeks_in_Year($year-1), $year-1)>" is returned. | |
664 | ||
665 | If the given date lies in the B<FIRST> week of the B<NEXT> year, | |
666 | "C<(1, $year+1)>" is returned. | |
667 | ||
668 | Otherwise, "C<(Week_Number($year,$month,$day), $year)>" is returned. | |
669 | ||
670 | =item * | |
671 | ||
672 | C<$week = Week_of_Year($year,$month,$day);> | |
673 | ||
674 | In scalar context, this function returns just the week number. This | |
675 | allows you to write "C<$week = Week_of_Year($year,$month,$day);>" | |
676 | instead of "C<($week) = Week_of_Year($year,$month,$day);>" (note | |
677 | the parentheses around "C<$week>"). | |
678 | ||
679 | If the given date lies in the B<LAST> week of the B<PREVIOUS> year, | |
680 | "C<Weeks_in_Year($year-1)>" is returned. | |
681 | ||
682 | If the given date lies in the B<FIRST> week of the B<NEXT> year, | |
683 | "C<1>" is returned. | |
684 | ||
685 | Otherwise the return value is identical with that of | |
686 | "C<Week_Number($year,$month,$day)>". | |
687 | ||
688 | B<BEWARE> that using this function in scalar context is a B<DANGEROUS> | |
689 | feature, because without knowing which year the week belongs to, you | |
690 | might inadvertently assume the wrong one! | |
691 | ||
692 | If for instance you are iterating through an interval of dates, you might | |
693 | assume that the week always belongs to the same year as the given date, | |
694 | which unfortunately is B<WRONG> in some cases! | |
695 | ||
696 | In many years, the 31st of December for instance belongs to week number | |
697 | one of the B<FOLLOWING> year. Assuming that the year is the same as your | |
698 | date (31st of December, in this example), sends you back to the first week | |
699 | of the B<CURRENT> year - the Monday of which, by the way, in case of bad | |
700 | luck, might actually lie in the year B<BEFORE> the current year! | |
701 | ||
702 | This actually happens in 2002, for example. | |
703 | ||
704 | So you always need to provide the correct corresponding year number | |
705 | by other means, keeping track of it yourself. | |
706 | ||
707 | In case you do not understand this, never mind, but then simply | |
708 | B<DO NOT USE> this function in scalar context! | |
709 | ||
710 | =item * | |
711 | ||
712 | C<($year,$month,$day) = Monday_of_Week($week,$year);> | |
713 | ||
714 | This function returns the date of the first day of the given week, i.e., | |
715 | the Monday. | |
716 | ||
717 | "C<$year>" must be greater than or equal to "C<1>", and "C<$week>" must | |
718 | lie in the range "C<1>" to "C<Weeks_in_Year($year)>". | |
719 | ||
720 | Note that you can write | |
721 | "C<($year,$month,$day) = Monday_of_Week(Week_of_Year($year,$month,$day));>" | |
722 | in order to calculate the date of the Monday of the same week as the | |
723 | given date. | |
724 | ||
725 | If you want to calculate any other day of week in the same week as a | |
726 | given date, use | |
727 | ||
728 | @date = Add_Delta_Days(Monday_of_Week(Week_of_Year(@date)),$offset); | |
729 | ||
730 | where C<$offset = 1> for Tuesday, C<2> for Wednesday etc. | |
731 | ||
732 | =item * | |
733 | ||
734 | C<if (($year,$month,$day) = Nth_Weekday_of_Month_Year($year,$month,$dow,$n))> | |
735 | ||
736 | This function calculates the date of the "C<$n>"th day of week "C<$dow>" | |
737 | in the given month "C<$month>" and year "C<$year>"; such as, for example, | |
738 | the 3rd Thursday of a given month and year. | |
739 | ||
740 | This can be used to send a notification mail to the members of a group | |
741 | which meets regularly on every 3rd Thursday of a month, for instance. | |
742 | ||
743 | (See the section "RECIPES" near the end of this document for a code | |
744 | snippet to actually do so.) | |
745 | ||
746 | "C<$year>" must be greater than or equal to "C<1>", "C<$month>" must lie | |
747 | in the range "C<1>" to "C<12>", "C<$dow>" must lie in the range "C<1>" | |
748 | to "C<7>" and "C<$n>" must lie in the range "C<1>" to "C<5>", or a fatal | |
749 | error (with appropriate error message) occurs. | |
750 | ||
751 | The function returns an empty list when the 5th of a given day of week | |
752 | does not exist in the given month and year. | |
753 | ||
754 | =item * | |
755 | ||
756 | C<($year,$week,$dow) = Standard_to_Business($year,$month,$day);> | |
757 | ||
758 | This function converts a given date from standard notation (year, | |
759 | month, day (of month)) to business notation (year, week, day of week). | |
760 | ||
761 | =item * | |
762 | ||
763 | C<($year,$month,$day) = Business_to_Standard($year,$week,$dow);> | |
764 | ||
765 | This function converts a given date from business notation (year, | |
766 | week, day of week) to standard notation (year, month, day (of month)). | |
767 | ||
768 | =item * | |
769 | ||
770 | C<$Dd = Delta_Days($year1,$month1,$day1, $year2,$month2,$day2);> | |
771 | ||
772 | This function returns the difference in days between the two given | |
773 | dates. | |
774 | ||
775 | The result is positive if the two dates are in chronological order, | |
776 | i.e., if date #1 comes chronologically B<BEFORE> date #2, and negative | |
777 | if the order of the two dates is reversed. | |
778 | ||
779 | The result is zero if the two dates are identical. | |
780 | ||
781 | =item * | |
782 | ||
783 | C<($Dd,$Dh,$Dm,$Ds) = Delta_DHMS($year1,$month1,$day1, $hour1,$min1,$sec1, $year2,$month2,$day2, $hour2,$min2,$sec2);> | |
784 | ||
785 | This function returns the difference in days, hours, minutes and seconds | |
786 | between the two given dates with times. | |
787 | ||
788 | All four return values will be positive if the two dates are in chronological | |
789 | order, i.e., if date #1 comes chronologically B<BEFORE> date #2, and negative | |
790 | (in all four return values!) if the order of the two dates is reversed. | |
791 | ||
792 | This is so that the two functions "C<Delta_DHMS()>" and "C<Add_Delta_DHMS()>" | |
793 | (description see further below) are complementary, i.e., mutually inverse: | |
794 | ||
795 | Add_Delta_DHMS(@date1,@time1, Delta_DHMS(@date1,@time1, @date2,@time2)) | |
796 | ||
797 | yields "C<(@date2,@time2)>" again, whereas | |
798 | ||
799 | Add_Delta_DHMS(@date2,@time2, | |
800 | map(-$_, Delta_DHMS(@date1,@time1, @date2,@time2))) | |
801 | ||
802 | yields "C<(@date1,@time1)>", and | |
803 | ||
804 | Delta_DHMS(@date1,@time1, Add_Delta_DHMS(@date1,@time1, @delta)) | |
805 | ||
806 | yields "C<@delta>" again. | |
807 | ||
808 | The result is zero (in all four return values) if the two dates and times | |
809 | are identical. | |
810 | ||
811 | =item * | |
812 | ||
813 | C<($Dy,$Dm,$Dd) = Delta_YMD($year1,$month1,$day1, $year2,$month2,$day2);> | |
814 | ||
815 | This function returns the vector | |
816 | ||
817 | ( $year2 - $year1, $month2 - $month1, $day2 - $day1 ) | |
818 | ||
819 | An error occurs if any of the two dates is invalid. | |
820 | ||
821 | =item * | |
822 | ||
823 | C<($D_y,$D_m,$D_d, $Dh,$Dm,$Ds) = Delta_YMDHMS($year1,$month1,$day1, $hour1,$min1,$sec1, $year2,$month2,$day2, $hour2,$min2,$sec2);> | |
824 | ||
825 | This function is based on the function "Delta_YMD()" above but additionally | |
826 | calculates the time difference. When a carry over from the time difference | |
827 | occurs, the value of "C<$D_d>" is adjusted accordingly, thus giving the | |
828 | correct total date/time difference. | |
829 | ||
830 | Arguments are expected to be in chronological order to yield a (usually) | |
831 | positive result. | |
832 | ||
833 | In any case, adding the result of this function to the first date/time value | |
834 | (C<$year1,$month1,$day1,> C<$hour1,$min1,$sec1>) always gives the second | |
835 | date/time value (C<$year2,$month2,$day2,> C<$hour2,$min2,$sec2>) again, | |
836 | and adding the negative result (all elements of the result vector negated) | |
837 | to the second date/time value gives the first date/time value. | |
838 | ||
839 | See the function "Add_Delta_YMDHMS()" further below for adding a date/time | |
840 | value and a date/time difference. | |
841 | ||
842 | An error occurs if any of the two date/time values is invalid. | |
843 | ||
844 | =item * | |
845 | ||
846 | C<($Dd,$Dh,$Dm,$Ds) = Normalize_DHMS($Dd,$Dh,$Dm,$Ds);> | |
847 | ||
848 | This function takes four arbitrary values for days, hours, minutes | |
849 | and seconds (which may have different signs) and renormalizes them | |
850 | so that the values for hours, minutes and seconds will lie in the | |
851 | ranges C<[-23..23]>, C<[-59..59]> and C<[-59..59]>, respectively, | |
852 | and so that all four values have the same sign (or are zero). | |
853 | ||
854 | The given values are left untouched, i.e., unchanged. | |
855 | ||
856 | =item * | |
857 | ||
858 | C<($year,$month,$day) = Add_Delta_Days($year,$month,$day, $Dd);> | |
859 | ||
860 | This function has two principal uses: | |
861 | ||
862 | First, it can be used to calculate a new date, given an initial date and | |
863 | an offset (which may be positive or negative) in days, in order to answer | |
864 | questions like "today plus 90 days -- which date gives that?". | |
865 | ||
866 | (In order to add a weeks offset, simply multiply the weeks offset with | |
867 | "C<7>" and use that as your days offset.) | |
868 | ||
869 | Second, it can be used to convert the canonical representation of a date, | |
870 | i.e., the number of that day (where counting starts at the 1st of January | |
871 | in S<1 A.D.>), back into a date given as year, month and day. | |
872 | ||
873 | Because counting starts at "C<1>", you will actually have to subtract "C<1>" | |
874 | from the canonical date in order to get back the original date: | |
875 | ||
876 | $canonical = Date_to_Days($year,$month,$day); | |
877 | ||
878 | ($year,$month,$day) = Add_Delta_Days(1,1,1, $canonical - 1); | |
879 | ||
880 | Moreover, this function is the inverse of the function "C<Delta_Days()>": | |
881 | ||
882 | Add_Delta_Days(@date1, Delta_Days(@date1, @date2)) | |
883 | ||
884 | yields "C<@date2>" again, whereas | |
885 | ||
886 | Add_Delta_Days(@date2, -Delta_Days(@date1, @date2)) | |
887 | ||
888 | yields "C<@date1>", and | |
889 | ||
890 | Delta_Days(@date1, Add_Delta_Days(@date1, $delta)) | |
891 | ||
892 | yields "C<$delta>" again. | |
893 | ||
894 | =item * | |
895 | ||
896 | C<($year,$month,$day, $hour,$min,$sec) = Add_Delta_DHMS($year,$month,$day, $hour,$min,$sec, $Dd,$Dh,$Dm,$Ds);> | |
897 | ||
898 | This function serves to add a days, hours, minutes and seconds offset to a | |
899 | given date and time, in order to answer questions like "today and now plus | |
900 | 7 days but minus 5 hours and then plus 30 minutes, what date and time gives | |
901 | that?": | |
902 | ||
903 | ($y,$m,$d,$H,$M,$S) = Add_Delta_DHMS(Today_and_Now(), +7,-5,+30,0); | |
904 | ||
905 | =item * | |
906 | ||
907 | C<($year,$month,$day) = Add_Delta_YM($year,$month,$day, $Dy,$Dm);> | |
908 | ||
909 | This function can be used to add a year and/or month offset to a given | |
910 | date. | |
911 | ||
912 | In contrast to the function described immediately below | |
913 | ("C<Add_Delta_YMD()>"), this function does no "wrapping" into | |
914 | the next month if the day happens to lie outside the valid range | |
915 | for the resulting year and month (after adding the year and month | |
916 | offsets). Instead, it simply truncates the day to the last possible | |
917 | day of the resulting month. | |
918 | ||
919 | Examples: | |
920 | ||
921 | Adding an offset of 0 years, 1 month to the date (1999,1,31) would result | |
922 | in the (invalid) date (1999,2,31). The function replaces this result by | |
923 | the (valid) date (1999,2,28). | |
924 | ||
925 | Adding an offset of 1 year, 1 month to the same date (1999,1,31) as above | |
926 | would result in the (still invalid) date (2000,2,31). The function replaces | |
927 | this result by the valid date (2000,2,29) (because 2000 is a leap year). | |
928 | ||
929 | Note that the year and month offsets can be negative, and that they can | |
930 | have different signs. | |
931 | ||
932 | If you want to additionally add a days offset, use the function | |
933 | "C<Add_Delta_Days()>" before or after calling "C<Add_Delta_YM()>": | |
934 | ||
935 | @date2 = Add_Delta_Days( Add_Delta_YM(@date1, $Dy,$Dm), $Dd ); | |
936 | @date2 = Add_Delta_YM( Add_Delta_Days(@date1, $Dd), $Dy,$Dm ); | |
937 | ||
938 | Note that your result may depend on the order in which you call | |
939 | these two functions! | |
940 | ||
941 | Consider the date (1999,2,28) and the offsets 0 years, 1 month | |
942 | and 1 day: | |
943 | ||
944 | (1999,2,28) plus one month is (1999,3,28), plus one day is | |
945 | (1999,3,29). (1999,2,28) plus one day is (1999,3,1), plus | |
946 | one month is (1999,4,1). | |
947 | ||
948 | (Which is also the reason why the "C<Add_Delta_YM()>" function | |
949 | does not allow to add a days offset, because this would actually | |
950 | require TWO functions: One for adding the days offset BEFORE and | |
951 | one for adding it AFTER applying the year/month offsets.) | |
952 | ||
953 | An error occurs if the initial date is not valid. | |
954 | ||
955 | Note that "C<Add_Delta_YM( Add_Delta_YM(@date, $Dy,$Dm), -$Dy,-$Dm );>" | |
956 | will not, in general, return the original date "C<@date>" (consider | |
957 | the examples given above!). | |
958 | ||
959 | =item * | |
960 | ||
961 | C<($year,$month,$day) = Add_Delta_YMD($year,$month,$day, $Dy,$Dm,$Dd);> | |
962 | ||
963 | This function serves to add a years, months and days offset to a given date. | |
964 | ||
965 | (In order to add a weeks offset, simply multiply the weeks offset with "C<7>" | |
966 | and add this number to your days offset.) | |
967 | ||
968 | Note that the three offsets for years, months and days are applied | |
969 | independently from each other. This also allows them to have | |
970 | different signs. | |
971 | ||
972 | The years and months offsets are applied first, and the days offset | |
973 | is applied last. | |
974 | ||
975 | If the resulting date happens to fall on a day after the end of the | |
976 | resulting month, like the 32nd of April or the 30th of February, then | |
977 | the date is simply counted forward into the next month (possibly also | |
978 | into the next year) by the number of excessive days (e.g., the 32nd of | |
979 | April will become the 2nd of May). | |
980 | ||
981 | B<BEWARE> that this behaviour differs from that of previous versions | |
982 | of this module! In previous versions, the day was simply truncated to | |
983 | the maximum number of days in the resulting month. | |
984 | ||
985 | If you want the previous behaviour, use the new function "C<Add_Delta_YM()>" | |
986 | (described immediately above) plus the function "C<Add_Delta_Days()>" | |
987 | instead. | |
988 | ||
989 | B<BEWARE> also that because a year and a month offset is not equivalent | |
990 | to a fixed number of days, the transformation performed by this function | |
991 | is B<NOT ALWAYS REVERSIBLE>! | |
992 | ||
993 | This is in contrast to the functions "C<Add_Delta_Days()>" and | |
994 | "C<Add_Delta_DHMS()>", which are fully and truly reversible (with | |
995 | the help of the functions "C<Delta_Days()>" and "C<Delta_DHMS()>", | |
996 | for instance). | |
997 | ||
998 | Note that for this same reason, | |
999 | ||
1000 | @date = Add_Delta_YMD( | |
1001 | Add_Delta_YMD(@date, $Dy,$Dm,$Dd), -$Dy,-$Dm,-$Dd); | |
1002 | ||
1003 | will in general B<NOT> return the initial date "C<@date>". | |
1004 | ||
1005 | Note that this is B<NOT> a program bug but B<NECESSARILY> so | |
1006 | because of the variable lengths of years and months! | |
1007 | ||
1008 | =item * | |
1009 | ||
1010 | C<($year,$month,$day, $hour,$min,$sec) = Add_Delta_YMDHMS($year,$month,$day, $hour,$min,$sec, $D_y,$D_m,$D_d, $Dh,$Dm,$Ds);> | |
1011 | ||
1012 | Same as the function above, except that a time offset may be given in | |
1013 | addition to the year, month and day offset. | |
1014 | ||
1015 | =item * | |
1016 | ||
1017 | C<($year,$month,$day, $hour,$min,$sec, $doy,$dow,$dst) = System_Clock([$gmt]);> | |
1018 | ||
1019 | If your operating system supports the corresponding system calls | |
1020 | ("C<time()>" and "C<localtime()>" or "C<gmtime()>"), this function | |
1021 | will return the information provided by your system clock, i.e., | |
1022 | the current date and time, the number of the day of year, the number | |
1023 | of the day of week and a flag signaling whether daylight savings time | |
1024 | is currently in effect or not. | |
1025 | ||
1026 | The ranges of values returned (and their meanings) are as follows: | |
1027 | ||
1028 | $year : 1970..2038 (or more) [Unix etc.] | |
1029 | $year : 1904..2040 [MacOS Classic] | |
1030 | ||
1031 | $month : 1..12 | |
1032 | $day : 1..31 | |
1033 | $hour : 0..23 | |
1034 | $min : 0..59 | |
1035 | $sec : 0..59 (0..61 on some systems) | |
1036 | $doy : 1..366 | |
1037 | $dow : 1..7 | |
1038 | $dst : -1..1 | |
1039 | ||
1040 | "C<$doy>" is the day of year, sometimes also referred to as the | |
1041 | "julian date", which starts at "C<1>" and goes up to the number | |
1042 | of days in that year. | |
1043 | ||
1044 | The day of week ("C<$dow>") will be "C<1>" for Monday, "C<2>" for | |
1045 | Tuesday and so on until "C<7>" for Sunday. | |
1046 | ||
1047 | The daylight savings time flag ("C<$dst>") will be "C<-1>" if this | |
1048 | information is not available on your system, "C<0>" for no daylight | |
1049 | savings time (i.e., winter time) and "C<1>" when daylight savings | |
1050 | time is in effect. | |
1051 | ||
1052 | If your operating system does not provide the necessary system calls, | |
1053 | calling this function will result in a fatal "not available on this | |
1054 | system" error message. | |
1055 | ||
1056 | If you want to handle this exception yourself, use "C<eval>" as follows: | |
1057 | ||
1058 | eval { ($year,$month,$day, $hour,$min,$sec, $doy,$dow,$dst) = | |
1059 | System_Clock(); }; | |
1060 | ||
1061 | if ($@) | |
1062 | { | |
1063 | # Handle missing system clock | |
1064 | # (For instance, ask user to enter this information manually) | |
1065 | } | |
1066 | ||
1067 | Note that curlies ("{" and "}") are used here to delimit the statement to | |
1068 | be "eval"ed (which is the way to catch exceptions in Perl), and not quotes | |
1069 | (which is a way to evaluate Perl expressions at runtime). | |
1070 | ||
1071 | If the optional (boolean) input parameter "C<$gmt>" is given, a "true" | |
1072 | value ("C<1>") will cause "C<gmtime()>" to be used instead of "C<localtime()>", | |
1073 | internally, thus returning Greenwich Mean Time (GMT, or UTC) instead of | |
1074 | local time. | |
1075 | ||
1076 | =item * | |
1077 | ||
1078 | C<($year,$month,$day) = Today([$gmt]);> | |
1079 | ||
1080 | This function returns a subset of the values returned by the function | |
1081 | "C<System_Clock()>" (see above for details), namely the current year, | |
1082 | month and day. | |
1083 | ||
1084 | A fatal "not available on this system" error message will appear if the | |
1085 | corresponding system calls are not supported by your current operating | |
1086 | system. | |
1087 | ||
1088 | If the optional (boolean) input parameter "C<$gmt>" is given, a "true" | |
1089 | value ("C<1>") will cause "C<gmtime()>" to be used instead of "C<localtime()>", | |
1090 | internally, thus returning Greenwich Mean Time (GMT, or UTC) instead of | |
1091 | local time. | |
1092 | ||
1093 | =item * | |
1094 | ||
1095 | C<($hour,$min,$sec) = Now([$gmt]);> | |
1096 | ||
1097 | This function returns a subset of the values returned by the function | |
1098 | "C<System_Clock()>" (see above for details), namely the current time | |
1099 | (hours, minutes and full seconds). | |
1100 | ||
1101 | A fatal "not available on this system" error message will appear if the | |
1102 | corresponding system calls are not supported by your current operating | |
1103 | system. | |
1104 | ||
1105 | If the optional (boolean) input parameter "C<$gmt>" is given, a "true" | |
1106 | value ("C<1>") will cause "C<gmtime()>" to be used instead of "C<localtime()>", | |
1107 | internally, thus returning Greenwich Mean Time (GMT, or UTC) instead of | |
1108 | local time. | |
1109 | ||
1110 | =item * | |
1111 | ||
1112 | C<($year,$month,$day, $hour,$min,$sec) = Today_and_Now([$gmt]);> | |
1113 | ||
1114 | This function returns a subset of the values returned by the function | |
1115 | "C<System_Clock()>" (see above for details), namely the current date | |
1116 | (year, month, day) and time (hours, minutes and full seconds). | |
1117 | ||
1118 | A fatal "not available on this system" error message will appear if the | |
1119 | corresponding system calls are not supported by your current operating | |
1120 | system. | |
1121 | ||
1122 | If the optional (boolean) input parameter "C<$gmt>" is given, a "true" | |
1123 | value ("C<1>") will cause "C<gmtime()>" to be used instead of "C<localtime()>", | |
1124 | internally, thus returning Greenwich Mean Time (GMT, or UTC) instead of | |
1125 | local time. | |
1126 | ||
1127 | =item * | |
1128 | ||
1129 | C<$year = This_Year([$gmt]);> | |
1130 | ||
1131 | This function returns the current year, according to local time. | |
1132 | ||
1133 | A fatal "not available on this system" error message will appear if the | |
1134 | corresponding system calls are not supported by your current operating | |
1135 | system. | |
1136 | ||
1137 | If the optional (boolean) input parameter "C<$gmt>" is given, a "true" | |
1138 | value ("C<1>") will cause "C<gmtime()>" to be used instead of "C<localtime()>", | |
1139 | internally, thus returning Greenwich Mean Time (GMT, or UTC) instead of | |
1140 | local time. However, this will only make a difference within a few hours | |
1141 | around New Year (unless you are on a Pacific island, where this can | |
1142 | be almost 24 hours). | |
1143 | ||
1144 | =item * | |
1145 | ||
1146 | C<($year,$month,$day, $hour,$min,$sec, $doy,$dow,$dst) = Gmtime([time]);> | |
1147 | ||
1148 | This is Date::Calc's equivalent of Perl's built-in "gmtime()" function. | |
1149 | See also L<perlfunc/gmtime>. | |
1150 | ||
1151 | The ranges of values returned (and their meanings) are as follows: | |
1152 | ||
1153 | $year : 1970..2038 (or more) [Unix etc.] | |
1154 | $year : 1904..2040 [MacOS Classic] | |
1155 | ||
1156 | $month : 1..12 | |
1157 | $day : 1..31 | |
1158 | $hour : 0..23 | |
1159 | $min : 0..59 | |
1160 | $sec : 0..59 | |
1161 | $doy : 1..366 | |
1162 | $dow : 1..7 | |
1163 | $dst : -1..1 | |
1164 | ||
1165 | "C<$doy>" is the day of year, sometimes also referred to as the | |
1166 | "julian date", which starts at "C<1>" and goes up to the number | |
1167 | of days in that year. | |
1168 | ||
1169 | The day of week ("C<$dow>") will be "C<1>" for Monday, "C<2>" for | |
1170 | Tuesday and so on until "C<7>" for Sunday. | |
1171 | ||
1172 | The daylight savings time flag ("C<$dst>") will be "C<-1>" if this | |
1173 | information is not available on your system, "C<0>" for no daylight | |
1174 | savings time (i.e., winter time) and "C<1>" when daylight savings | |
1175 | time is in effect. | |
1176 | ||
1177 | A fatal "time out of range" error will occur if the given time value | |
1178 | is out of range C<[0..(~0E<gt>E<gt>1)]>. | |
1179 | ||
1180 | If the time value is omitted, the "time()" function is called instead, | |
1181 | internally. | |
1182 | ||
1183 | =item * | |
1184 | ||
1185 | C<($year,$month,$day, $hour,$min,$sec, $doy,$dow,$dst) = Localtime([time]);> | |
1186 | ||
1187 | This is Date::Calc's equivalent of Perl's built-in "localtime()" function. | |
1188 | See also L<perlfunc/localtime>. | |
1189 | ||
1190 | The ranges of values returned (and their meanings) are as follows: | |
1191 | ||
1192 | $year : 1970..2038 (or more) [Unix etc.] | |
1193 | $year : 1904..2040 [MacOS Classic] | |
1194 | ||
1195 | $month : 1..12 | |
1196 | $day : 1..31 | |
1197 | $hour : 0..23 | |
1198 | $min : 0..59 | |
1199 | $sec : 0..59 | |
1200 | $doy : 1..366 | |
1201 | $dow : 1..7 | |
1202 | $dst : -1..1 | |
1203 | ||
1204 | "C<$doy>" is the day of year, sometimes also referred to as the | |
1205 | "julian date", which starts at "C<1>" and goes up to the number | |
1206 | of days in that year. | |
1207 | ||
1208 | The day of week ("C<$dow>") will be "C<1>" for Monday, "C<2>" for | |
1209 | Tuesday and so on until "C<7>" for Sunday. | |
1210 | ||
1211 | The daylight savings time flag ("C<$dst>") will be "C<-1>" if this | |
1212 | information is not available on your system, "C<0>" for no daylight | |
1213 | savings time (i.e., winter time) and "C<1>" when daylight savings | |
1214 | time is in effect. | |
1215 | ||
1216 | A fatal "time out of range" error will occur if the given time value is | |
1217 | out of range C<[0..(~0E<gt>E<gt>1)]>. | |
1218 | ||
1219 | If the time value is omitted, the "time()" function is called instead, | |
1220 | internally. | |
1221 | ||
1222 | =item * | |
1223 | ||
1224 | C<$time = Mktime($year,$month,$day, $hour,$min,$sec);> | |
1225 | ||
1226 | This function converts a date into a time value, i.e., into the number | |
1227 | of seconds since whatever moment in time your system considers to be | |
1228 | the "epoch". On Unix and most other systems this is the number of seconds | |
1229 | since January 1st 1970 at midnight (GMT). On MacOS Classic this is the | |
1230 | number of seconds since January 1st 1904 at midnight (local time). | |
1231 | ||
1232 | The function is similar to the "POSIX::mktime()" function (see L<POSIX/mktime> | |
1233 | for more details), but in contrast to the latter, it expects dates in the | |
1234 | usual ranges used throughout this module: The year 2001 stays year 2001, | |
1235 | and months are numbered from 1 to 12. | |
1236 | ||
1237 | A fatal "date out of range" error will occur if the given date cannot | |
1238 | be expressed in terms of seconds since the epoch (this happens for | |
1239 | instance when the date lies before the epoch, or if it is later than | |
1240 | S<19-Jan-2038 03:14:07 GMT> on S<32 bit> Unix systems, or later than | |
1241 | S<06-Feb-2040 06:28:15> (local time) on a Macintosh with MacOS Classic). | |
1242 | ||
1243 | Just like the "POSIX::mktime()" function, this function uses the | |
1244 | "mktime()" system call, internally. | |
1245 | ||
1246 | This means that the given date and time is considered to be in local time, | |
1247 | and that the value returned by this function will depend on your machine's | |
1248 | local settings such as the time zone, whether daylight savings time is | |
1249 | (or was, at the time) in effect, and the system clock itself. | |
1250 | ||
1251 | B<BEWARE> that "mktime()" does not always return the same time value | |
1252 | as fed into "localtime()", when you feed the output of "localtime()" | |
1253 | back into "mktime()", on some systems! | |
1254 | ||
1255 | I.e., "C<Mktime((Localtime($time))[0..5])>" will not always return | |
1256 | the same value as given in "C<$time>"! | |
1257 | ||
1258 | =item * | |
1259 | ||
1260 | C<($D_y,$D_m,$D_d, $Dh,$Dm,$Ds, $dst) = Timezone([time]);> | |
1261 | ||
1262 | This function returns the difference between "C<localtime(time)>" and | |
1263 | "C<gmtime(time)>", which is the timezone offset in effect for the current | |
1264 | location and the given "C<time>". | |
1265 | ||
1266 | This offset is positive if you are located to the east of Greenwich, | |
1267 | and is usually negative (except during daylight savings time, in some | |
1268 | locations) if you are located to the west of Greenwich. | |
1269 | ||
1270 | Note that this offset is influenced by all of the relevant system | |
1271 | settings and parameters on your machine; such as locales, environment | |
1272 | variables (e.g. "C<TZ>") and the system clock itself. See the | |
1273 | relevant documentation on your system for more details. | |
1274 | ||
1275 | If the "C<time>" is omitted, the "C<time()>" function will | |
1276 | be called automatically, internally (similar to the built-in | |
1277 | functions "C<localtime()>" and "C<gmtime()>" in Perl). | |
1278 | ||
1279 | A fatal "time out of range" error will occur if the given time value | |
1280 | is out of range C<[0..(~0E<gt>E<gt>1)]>. | |
1281 | ||
1282 | The last item of the returned list is a flag which indicates whether | |
1283 | daylight savings time is currently in effect. This flag is negative | |
1284 | (-1) if this information is not available on your system. It is zero | |
1285 | (0) when daylight savings time is off, and positive (+1) when daylight | |
1286 | savings time is on. | |
1287 | ||
1288 | Thus you can check very quickly whether daylight savings time is | |
1289 | currently in effect by evaluating this function in scalar context | |
1290 | (in scalar context, Perl returns the last item of a list): | |
1291 | ||
1292 | if (scalar Timezone > 0) { # yes, daylight savings time | |
1293 | ||
1294 | However, a slightly more efficient way would be this: | |
1295 | ||
1296 | if (scalar System_Clock > 0) { # yes, daylight savings time | |
1297 | ||
1298 | =item * | |
1299 | ||
1300 | C<$time = Date_to_Time($year,$month,$day, $hour,$min,$sec);> | |
1301 | ||
1302 | This function is a replacement for the BSD function "timegm()" | |
1303 | (which is not available on all Unix systems), which converts | |
1304 | a given date and time into a time value, i.e., into the number | |
1305 | of seconds since whatever moment in time your system considers to be | |
1306 | the "epoch". On Unix and most other systems this is the number of seconds | |
1307 | since January 1st 1970 at midnight (GMT). On MacOS Classic this is the | |
1308 | number of seconds since January 1st 1904 at midnight (local time). | |
1309 | ||
1310 | Under Unix, the date and time are considered to be in UTC | |
1311 | ("Universal Time Coordinated", and so is the resulting time value. | |
1312 | ||
1313 | UTC is almost the same as GMT (or "Greenwich Mean Time"), except | |
1314 | that UTC has leap seconds (in order to account for small variations | |
1315 | in the rotation of the earth, for instance), whereas GMT does not. | |
1316 | ||
1317 | Under MacOS Classic, however, both input and output are | |
1318 | considered to be in local time. | |
1319 | ||
1320 | The ranges of year and month follow the same rules as throughout | |
1321 | the rest of this module (and not the contorted rules of its Unix | |
1322 | equivalent), i.e., the year "2001" stays "2001" and the month | |
1323 | ranges from 1 to 12. | |
1324 | ||
1325 | A fatal "date out of range" error will occur if the given date cannot | |
1326 | be expressed in terms of seconds since the epoch (this happens for | |
1327 | instance when the date lies before the epoch, or if it is later than | |
1328 | S<19-Jan-2038 03:14:07 GMT> on S<32 bit> Unix systems, or later than | |
1329 | S<06-Feb-2040 06:28:15> (local time) on a Macintosh with MacOS Classic). | |
1330 | ||
1331 | This function should be very fast, because it is implemented in | |
1332 | a very straightforward manner and doesn't use any internal system | |
1333 | calls. | |
1334 | ||
1335 | Moreover, the functions "Date_to_Time()" and "Time_to_Date()" | |
1336 | are guaranteed to be complementary, i.e., that | |
1337 | "C<Date_to_Time(Time_to_Date($time))>" and | |
1338 | "C<Time_to_Date(Date_to_Time($year,$month,$day, $hour,$min,$sec))>" | |
1339 | will always return the initial values. | |
1340 | ||
1341 | =item * | |
1342 | ||
1343 | C<($year,$month,$day, $hour,$min,$sec) = Time_to_Date([time]);> | |
1344 | ||
1345 | This function is an alternative to the POSIX "gmtime()" function | |
1346 | (and its built-in Perl equivalent), which converts a given time | |
1347 | value into the corresponding date and time. The given time value | |
1348 | must be the number of seconds since whatever moment in time your | |
1349 | system considers to be the "epoch". On Unix and most other systems | |
1350 | this is the number of seconds since January 1st 1970 at midnight | |
1351 | (GMT). On MacOS Classic this is the number of seconds since | |
1352 | January 1st 1904 at midnight (local time). | |
1353 | ||
1354 | Under Unix, the given time value is considered to be in UTC | |
1355 | ("Universal Time Coordinated", and so is the resulting date | |
1356 | and time. | |
1357 | ||
1358 | UTC is almost the same as GMT (or "Greenwich Mean Time"), except | |
1359 | that UTC has leap seconds (in order to account for small variations | |
1360 | in the rotation of the earth, for instance), whereas GMT does not. | |
1361 | ||
1362 | Under MacOS Classic, however, both input and output | |
1363 | are considered to be in local time. | |
1364 | ||
1365 | If the input value "C<time>" is omitted, the "C<time()>" function | |
1366 | will be called automatically, internally (similar to the built-in | |
1367 | functions "C<localtime()>" and "C<gmtime()>" in Perl). | |
1368 | ||
1369 | A fatal "time out of range" error will occur if the given time | |
1370 | value is negative. | |
1371 | ||
1372 | This function should be very fast, because it is implemented in | |
1373 | a very straightforward manner and doesn't use any internal system | |
1374 | calls (except for "time()", if the input value is omitted). | |
1375 | ||
1376 | Moreover, the functions "Date_to_Time()" and "Time_to_Date()" | |
1377 | are guaranteed to be complementary, i.e., that | |
1378 | "C<Date_to_Time(Time_to_Date($time))>" and | |
1379 | "C<Time_to_Date(Date_to_Time($year,$month,$day, $hour,$min,$sec))>" | |
1380 | will always return the initial values. | |
1381 | ||
1382 | =item * | |
1383 | ||
1384 | C<($year,$month,$day) = Easter_Sunday($year);> | |
1385 | ||
1386 | This function calculates the date of Easter Sunday for all years in the | |
1387 | range from 1583 to 2299 (all other year numbers will result in a fatal | |
1388 | "year out of range" error message) using the method known as the "Gaussian | |
1389 | Rule". | |
1390 | ||
1391 | Some related christian feast days which depend on the date of Easter Sunday: | |
1392 | ||
1393 | Carnival Monday / Rosenmontag / Veille du Mardi Gras = -48 days | |
1394 | Mardi Gras / Karnevalsdienstag / Mardi Gras = -47 days | |
1395 | Ash Wednesday / Aschermittwoch / Mercredi des Cendres = -46 days | |
1396 | Palm Sunday / Palmsonntag / Dimanche des Rameaux = -7 days | |
1397 | Easter Friday / Karfreitag / Vendredi Saint = -2 days | |
1398 | Easter Saturday / Ostersamstag / Samedi de Paques = -1 day | |
1399 | Easter Monday / Ostermontag / Lundi de Paques = +1 day | |
1400 | Ascension of Christ / Christi Himmelfahrt / Ascension = +39 days | |
1401 | Whitsunday / Pfingstsonntag / Dimanche de Pentecote = +49 days | |
1402 | Whitmonday / Pfingstmontag / Lundi de Pentecote = +50 days | |
1403 | Feast of Corpus Christi / Fronleichnam / Fete-Dieu = +60 days | |
1404 | ||
1405 | Use the offsets shown above to calculate the date of the corresponding | |
1406 | feast day as follows: | |
1407 | ||
1408 | ($year,$month,$day) = Add_Delta_Days(Easter_Sunday($year), $offset)); | |
1409 | ||
1410 | =item * | |
1411 | ||
1412 | C<if ($month = Decode_Month($string))> | |
1413 | ||
1414 | This function takes a string as its argument, which should contain the | |
1415 | name of a month B<IN THE CURRENTLY SELECTED LANGUAGE> (see further below | |
1416 | for details about the multi-language support of this package), or any uniquely | |
1417 | identifying abbreviation of a month's name (i.e., the first few letters), | |
1418 | and returns the corresponding number (1..12) upon a successful match, or | |
1419 | "C<0>" otherwise (therefore, the return value can also be used as the | |
1420 | conditional expression in an "if" statement). | |
1421 | ||
1422 | Note that the input string may not contain any other characters which do not | |
1423 | pertain to the month's name, especially no leading or trailing whitespace. | |
1424 | ||
1425 | Note also that matching is performed in a case-insensitive manner (this may | |
1426 | depend on the "locale" setting on your current system, though!) | |
1427 | ||
1428 | With "English" as the currently selected language (which is the default), | |
1429 | the following examples will all return the value "C<9>": | |
1430 | ||
1431 | $month = Decode_Month("s"); | |
1432 | $month = Decode_Month("Sep"); | |
1433 | $month = Decode_Month("septemb"); | |
1434 | $month = Decode_Month("September"); | |
1435 | ||
1436 | =item * | |
1437 | ||
1438 | C<if ($dow = Decode_Day_of_Week($string))> | |
1439 | ||
1440 | This function takes a string as its argument, which should contain the | |
1441 | name of a day of week B<IN THE CURRENTLY SELECTED LANGUAGE> (see further | |
1442 | below for details about the multi-language support of this package), or any | |
1443 | uniquely identifying abbreviation of the name of a day of week (i.e., the | |
1444 | first few letters), and returns the corresponding number (1..7) upon a | |
1445 | successful match, or "C<0>" otherwise (therefore, the return value can | |
1446 | also be used as the conditional expression in an "if" statement). | |
1447 | ||
1448 | Note that the input string may not contain any other characters which | |
1449 | do not pertain to the name of the day of week, especially no leading | |
1450 | or trailing whitespace. | |
1451 | ||
1452 | Note also that matching is performed in a case-insensitive manner (this may | |
1453 | depend on the "locale" setting on your current system, though!) | |
1454 | ||
1455 | With "English" as the currently selected language (which is the default), | |
1456 | the following examples will all return the value "C<3>": | |
1457 | ||
1458 | $dow = Decode_Day_of_Week("w"); | |
1459 | $dow = Decode_Day_of_Week("Wed"); | |
1460 | $dow = Decode_Day_of_Week("wednes"); | |
1461 | $dow = Decode_Day_of_Week("Wednesday"); | |
1462 | ||
1463 | =item * | |
1464 | ||
1465 | C<if ($lang = Decode_Language($string))> | |
1466 | ||
1467 | This function takes a string as its argument, which should contain the | |
1468 | name of one of the languages supported by this package (B<IN THIS VERY | |
1469 | LANGUAGE ITSELF>), or any uniquely identifying abbreviation of the name | |
1470 | of a language (i.e., the first few letters), and returns its corresponding | |
1471 | internal number (1..13 in the original distribution) upon a successful match, | |
1472 | or "C<0>" otherwise (therefore, the return value can also be used as the | |
1473 | conditional expression in an "if" statement). | |
1474 | ||
1475 | Note that the input string may not contain any other characters which do | |
1476 | not pertain to the name of a language, especially no leading or trailing | |
1477 | whitespace. | |
1478 | ||
1479 | Note also that matching is performed in a case-insensitive manner (this may | |
1480 | depend on the "locale" setting on your current system, though!) | |
1481 | ||
1482 | The original distribution supports the following thirteen languages: | |
1483 | ||
1484 | English ==> 1 (default) | |
1485 |