1Date::Calc(3) User Contributed Perl Documentation Date::Calc(3)
2
6 Date::Calc - Gregorian calendar date calculations
7
9 Keep it small, fast and simple
10
12 This package consists of a C library and a Perl module (which uses the
13 C library, internally) for all kinds of date calculations based on the
14 Gregorian calendar (the one used in all western countries today),
15 thereby complying with all relevant norms and standards:
16 ISO/RÂ 2015-1971, DINÂ 1355 and, to some extent, ISOÂ 8601 (where
17 applicable).
18 (See also http://www.engelschall.com/u/sb/download/Date-Calc/DIN1355/
20 for a scan of part of the "DINÂ 1355" document (in German)).
21 The module of course handles year numbers of 2000 and above correctly
23 ("Year 2000" or "Y2K" compliance) -- actually all year numbers from 1
24 to the largest positive integer representable on your system (which is
25 at least 32767) can be dealt with.
26 This is not true, however, for the import/export functions in this
28 package which are an interface to the internal POSIX date and time
29 functions of your system, which can only cover dates in the following
30 ranges:
31 01-Jan-1970 00:00:00 GMT .. 19-Jan-2038 03:14:07 GMT [Unix etc.]
33 01-Jan-1904 00:00:00 LT .. 06-Feb-2040 06:28:15 LT [MacOS Classic]
34 (LT = local time)
35 Note that this package projects the Gregorian calendar back until the
37 year 1Â A.D. -- even though the Gregorian calendar was only adopted in
38 1582, mostly by the Catholic European countries, in obedience to the
39 corresponding decree of Pope Gregory XIII in that year.
40 Some (mainly protestant) countries continued to use the Julian calendar
42 (used until then) until as late as the beginning of the 20th century.
43 Finally, note that this package is not intended to do everything you
45 could ever imagine automagically for you; it is rather intended to
46 serve as a toolbox (in the best of UNIX spirit and traditions) which
47 should, however, always get you where you want to go.
48 See the section "RECIPES" at the bottom of this document for solutions
50 to common problems!
51 If nevertheless you can't figure out how to solve a particular problem,
53 please let me know! (See e-mail address at the end of this document.)
54
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 N_Delta_YMD
78 N_Delta_YMDHMS
79 Normalize_DHMS
80 Add_Delta_Days
81 Add_Delta_DHMS
82 Add_Delta_YM
83 Add_Delta_YMD
84 Add_Delta_YMDHMS
85 Add_N_Delta_YMD
86 Add_N_Delta_YMDHMS
87 System_Clock
88 Today
89 Now
90 Today_and_Now
91 This_Year
92 Gmtime
93 Localtime
94 Mktime
95 Timezone
96 Date_to_Time
97 Time_to_Date
98 Easter_Sunday
99 Decode_Month
100 Decode_Day_of_Week
101 Decode_Language
102 Decode_Date_EU
103 Decode_Date_US
104 Fixed_Window
105 Moving_Window
106 Compress
107 Uncompress
108 check_compressed
109 Compressed_to_Text
110 Date_to_Text
111 Date_to_Text_Long
112 English_Ordinal
113 Calendar
114 Month_to_Text
115 Day_of_Week_to_Text
116 Day_of_Week_Abbreviation
117 Language_to_Text
118 Language
119 Languages
120 Decode_Date_EU2
121 Decode_Date_US2
122 Parse_Date
123 ISO_LC
124 ISO_UC
125 );
126 use Date::Calc qw(:all);
128 Days_in_Year
130 $days = Days_in_Year($year,$month);
131 Days_in_Month
133 $days = Days_in_Month($year,$month);
134 Weeks_in_Year
136 $weeks = Weeks_in_Year($year);
137 leap_year
139 if (leap_year($year))
140 check_date
142 if (check_date($year,$month,$day))
143 check_time
145 if (check_time($hour,$min,$sec))
146 check_business_date
148 if (check_business_date($year,$week,$dow))
149 Day_of_Year
151 $doy = Day_of_Year($year,$month,$day);
152 Date_to_Days
154 $days = Date_to_Days($year,$month,$day);
155 Day_of_Week
157 $dow = Day_of_Week($year,$month,$day);
158 Week_Number
160 $week = Week_Number($year,$month,$day); # DEPRECATED
161 Week_of_Year
163 ($week,$year) = Week_of_Year($year,$month,$day); # RECOMMENDED
164 $week = Week_of_Year($year,$month,$day); # DANGEROUS
165 Monday_of_Week
167 ($year,$month,$day) = Monday_of_Week($week,$year);
168 Nth_Weekday_of_Month_Year
170 if (($year,$month,$day) =
171 Nth_Weekday_of_Month_Year($year,$month,$dow,$n))
172 Standard_to_Business
174 ($year,$week,$dow) =
175 Standard_to_Business($year,$month,$day);
176 Business_to_Standard
178 ($year,$month,$day) =
179 Business_to_Standard($year,$week,$dow);
180 Delta_Days
182 $Dd = Delta_Days($year1,$month1,$day1,
183 $year2,$month2,$day2);
184 Delta_DHMS
186 ($Dd,$Dh,$Dm,$Ds) =
187 Delta_DHMS($year1,$month1,$day1, $hour1,$min1,$sec1,
188 $year2,$month2,$day2, $hour2,$min2,$sec2);
189 Delta_YMD
191 ($Dy,$Dm,$Dd) =
192 Delta_YMD($year1,$month1,$day1,
193 $year2,$month2,$day2);
194 Delta_YMDHMS
196 ($D_y,$D_m,$D_d, $Dh,$Dm,$Ds) =
197 Delta_YMDHMS($year1,$month1,$day1, $hour1,$min1,$sec1,
198 $year2,$month2,$day2, $hour2,$min2,$sec2);
199 N_Delta_YMD
201 ($Dy,$Dm,$Dd) =
202 N_Delta_YMD($year1,$month1,$day1,
203 $year2,$month2,$day2);
204 N_Delta_YMDHMS
206 ($D_y,$D_m,$D_d, $Dhh,$Dmm,$Dss) =
207 N_Delta_YMDHMS($year1,$month1,$day1, $hour1,$min1,$sec1,
208 $year2,$month2,$day2, $hour2,$min2,$sec2);
209 Normalize_DHMS
211 ($Dd,$Dh,$Dm,$Ds) =
212 Normalize_DHMS($Dd,$Dh,$Dm,$Ds);
213 Add_Delta_Days
215 ($year,$month,$day) =
216 Add_Delta_Days($year,$month,$day,
217 $Dd);
218 Add_Delta_DHMS
220 ($year,$month,$day, $hour,$min,$sec) =
221 Add_Delta_DHMS($year,$month,$day, $hour,$min,$sec,
222 $Dd,$Dh,$Dm,$Ds);
223 Add_Delta_YM
225 ($year,$month,$day) =
226 Add_Delta_YM($year,$month,$day,
227 $Dy,$Dm);
228 Add_Delta_YMD
230 ($year,$month,$day) =
231 Add_Delta_YMD($year,$month,$day,
232 $Dy,$Dm,$Dd);
233 Add_Delta_YMDHMS
235 ($year,$month,$day, $hour,$min,$sec) =
236 Add_Delta_YMDHMS($year,$month,$day, $hour,$min,$sec,
237 $D_y,$D_m,$D_d, $Dh,$Dm,$Ds);
238 Add_N_Delta_YMD
240 ($year,$month,$day) =
241 Add_N_Delta_YMD($year,$month,$day,
242 $Dy,$Dm,$Dd);
243 Add_N_Delta_YMDHMS
245 ($year,$month,$day, $hour,$min,$sec) =
246 Add_N_Delta_YMDHMS($year,$month,$day, $hour,$min,$sec,
247 $D_y,$D_m,$D_d, $Dhh,$Dmm,$Dss);
248 System_Clock
250 ($year,$month,$day, $hour,$min,$sec, $doy,$dow,$dst) =
251 System_Clock([$gmt]);
252 Today
254 ($year,$month,$day) = Today([$gmt]);
255 Now
257 ($hour,$min,$sec) = Now([$gmt]);
258 Today_and_Now
260 ($year,$month,$day, $hour,$min,$sec) = Today_and_Now([$gmt]);
261 This_Year
263 $year = This_Year([$gmt]);
264 Gmtime
266 ($year,$month,$day, $hour,$min,$sec, $doy,$dow,$dst) =
267 Gmtime([time]);
268 Localtime
270 ($year,$month,$day, $hour,$min,$sec, $doy,$dow,$dst) =
271 Localtime([time]);
272 Mktime
274 $time = Mktime($year,$month,$day, $hour,$min,$sec);
275 Timezone
277 ($D_y,$D_m,$D_d, $Dh,$Dm,$Ds, $dst) = Timezone([time]);
278 Date_to_Time
280 $time = Date_to_Time($year,$month,$day, $hour,$min,$sec);
281 Time_to_Date
283 ($year,$month,$day, $hour,$min,$sec) = Time_to_Date([time]);
284 Easter_Sunday
286 ($year,$month,$day) = Easter_Sunday($year);
287 Decode_Month
289 if ($month = Decode_Month($string[,$lang]))
290 Decode_Day_of_Week
292 if ($dow = Decode_Day_of_Week($string[,$lang]))
293 Decode_Language
295 if ($lang = Decode_Language($string))
296 Decode_Date_EU
298 if (($year,$month,$day) = Decode_Date_EU($string[,$lang]))
299 Decode_Date_US
301 if (($year,$month,$day) = Decode_Date_US($string[,$lang]))
302 Fixed_Window
304 $year = Fixed_Window($yy);
305 Moving_Window
307 $year = Moving_Window($yy);
308 Compress
310 $date = Compress($year,$month,$day);
311 Uncompress
313 if (($century,$year,$month,$day) = Uncompress($date))
314 check_compressed
316 if (check_compressed($date))
317 Compressed_to_Text
319 $string = Compressed_to_Text($date[,$lang]);
320 Date_to_Text
322 $string = Date_to_Text($year,$month,$day[,$lang]);
323 Date_to_Text_Long
325 $string = Date_to_Text_Long($year,$month,$day[,$lang]);
326 English_Ordinal
328 $string = English_Ordinal($number);
329 Calendar
331 $string = Calendar($year,$month[,$orthodox[,$lang]]);
332 Month_to_Text
334 $string = Month_to_Text($month[,$lang]);
335 Day_of_Week_to_Text
337 $string = Day_of_Week_to_Text($dow[,$lang]);
338 Day_of_Week_Abbreviation
340 $string = Day_of_Week_Abbreviation($dow[,$lang]);
341 Language_to_Text
343 $string = Language_to_Text($lang);
344 Language
346 $lang = Language();
347 Language($lang); # DEPRECATED
348 $oldlang = Language($newlang); # DEPRECATED
349 Languages
351 $max_lang = Languages();
352 Decode_Date_EU2
354 if (($year,$month,$day) = Decode_Date_EU2($string[,$lang]))
355 Decode_Date_US2
357 if (($year,$month,$day) = Decode_Date_US2($string[,$lang]))
358 Parse_Date
360 if (($year,$month,$day) = Parse_Date($string[,$lang]))
361 ISO_LC
363 $lower = ISO_LC($string);
364 ISO_UC
366 $upper = ISO_UC($string);
367 Version
369 $string = Date::Calc::Version();
370
372 (See the section "RECIPES" at the bottom of this document for solutions
373 to common problems!)
374 · "Year 2000" ("Y2K") compliance
376 The upper limit for any year number in this module is only given by
378 the size of the largest positive integer that can be represented in a
379 variable of the C type "int" on your system, which is at least 32767,
380 according to the ANSI C standard (exceptions see below).
381 In order to simplify calculations, this module projects the gregorian
383 calendar back until the year 1Â A.D. -- i.e., back BEYOND the year
384 1582 when this calendar was first decreed by the Catholic Pope
385 Gregory XIII!
386 Therefore, BE SURE TO ALWAYS SPECIFY "1998" WHEN YOU MEAN "1998", for
388 instance, and DO NOT WRITE "98" INSTEAD, because this will in fact
389 perform a calculation based on the year "98" A.D. and NOT "1998"!
390 An exception from this rule are the functions which contain the word
392 "compress" in their names (which can only handle years between 1970
393 and 2069 and also accept the abbreviations "00" to "99"), and the
394 functions whose names begin with "Decode_Date_" (which translate year
395 numbers below 100 using a technique known as "moving window").
396 If you want to convert a two-digit year number into a full-fledged,
398 four-digit (at least for some years to come ";-)") year number, use
399 the two functions "Fixed_Window()" and "Moving_Window()" (see their
400 description further below).
401 Note also that the following import/export functions (which are
403 interfaces to the POSIX functions "time()", "gmtime()", "localtime()"
404 and "mktime()" or (the last two) substitutes for the BSD function
405 "timegm()" and the POSIX function "gmtime()") have a very limited
406 range of representable dates (in contrast to all other functions in
407 this package, which cover virtually any date including and after
408 January 1st 1 A.D.):
409 System_Clock()
411 Today()
412 Now()
413 Today_and_Now()
414 This_Year()
415 Gmtime()
416 Localtime()
417 Mktime()
418 Timezone()
419 Date_to_Time()
420 Time_to_Date()
421 These functions can only deal with dates in the range from
423 01-Jan-1970Â 00:00:00Â GMT to 19-Jan-2038Â 03:14:07Â GMT (the latter
424 limit is only authoritative on 32Â bit systems, however, and can (in
425 principle, through a few code changes) be extended somewhat ":-)" on
426 64Â bit systems).
427 On MacOS Classic, the valid range of dates is between (both included)
429 01-Jan-1904Â 00:00:00 (local time) to 06-Feb-2040Â 06:28:15 (local
430 time).
431 Note further that the function "Easter_Sunday()" can only be used for
433 years in the range 1583 to 2299.
434 · POSIX functions
436 Note that the following functions
438 Gmtime()
440 Localtime()
441 Mktime()
442 Timezone()
443 are actually wrappers around or based upon the corresponding POSIX
445 functions "time()", "gmtime()", "localtime()" and "mktime()".
446 As such, they depend on local settings of the underlying machine such
448 as e.g. the system clock, the time zone and the locale.
449 Their results can therefore sometimes be unexpected or counter-
451 intuitive.
452 Therefore, no support can be provided for these functions.
454 They are supplied "as is", purely for the sake of interoperability.
456 Use at your own risk. (You have been warned!)
458 · First index
460 ALL ranges in this module start with "1", NOT "0"!
462 I.e., the day of month, day of week, day of year, month of year, week
464 of year, first valid year number and language ALL start counting at
465 one, NOT zero!
466 The only exception is the function ""Week_Number()"", which may in
468 fact return "0" when the given date actually lies in the last week of
469 the PREVIOUS year, and of course the numbers for hours (0..23),
470 minutes (0..59) and seconds (0..59).
471 · Function naming conventions
473 Function names completely in lower case indicate a boolean return
475 value.
476 · Boolean values
478 Boolean values returned from functions in this module are always a
480 numeric zero ("0") for "false" and a numeric one ("1") for "true".
481 · Exception handling
483 The functions in this module will usually die with a corresponding
485 error message if their input parameters, intermediate results or
486 output values are out of range.
487 The following functions handle errors differently:
489 - check_date()
491 - check_time()
492 - check_business_date()
493 - check_compressed()
494 (which return a "false" return value when the given input does not
496 represent a valid date or time),
497 - Nth_Weekday_of_Month_Year()
499 (which returns an empty list if the requested 5th day of week does
501 not exist),
502 - Decode_Month()
504 - Decode_Day_of_Week()
505 - Decode_Language()
506 - Fixed_Window()
507 - Moving_Window()
508 - Compress()
509 (which return "0" upon failure or invalid input), and
511 - Decode_Date_EU()
513 - Decode_Date_US()
514 - Decode_Date_EU2()
515 - Decode_Date_US2()
516 - Parse_Date()
517 - Uncompress()
518 (which return an empty list upon failure or invalid input).
520 Note that you can always catch an exception thrown by any of the
522 functions in this module and handle it yourself by enclosing the
523 function call in an ""eval"" with curly brackets and checking the
524 special variable "$@" (see "eval" in perlfunc(1) for details).
525
527 · "use Date::Calc qw( Days_in_Year Days_in_Month ... );"
528 · "use Date::Calc qw(:all);"
530 You can either specify the functions you want to import explicitly by
532 enumerating them between the parentheses of the ""qw()"" operator, or
533 you can use the "":all"" tag instead to import ALL available
534 functions.
535 · "$days = Days_in_Year($year,$month);"
537 This function returns the sum of the number of days in the months
539 starting with January up to and including "$month" in the given year
540 "$year".
541 I.e., ""Days_in_Year(1998,1)"" returns "31", ""Days_in_Year(1998,2)""
543 returns "59", ""Days_in_Year(1998,3)"" returns "90", and so on.
544 Note that ""Days_in_Year($year,12)"" returns the number of days in
546 the given year "$year", i.e., either "365" or "366".
547 · "$days = Days_in_Month($year,$month);"
549 This function returns the number of days in the given month "$month"
551 of the given year "$year".
552 The year must always be supplied, even though it is only needed when
554 the month is February, in order to determine whether it is a leap
555 year or not.
556 I.e., ""Days_in_Month(1998,1)"" returns "31",
558 ""Days_in_Month(1998,2)"" returns "28", ""Days_in_Month(2000,2)""
559 returns "29", ""Days_in_Month(1998,3)"" returns "31", and so on.
560 · "$weeks = Weeks_in_Year($year);"
562 This function returns the number of weeks in the given year "$year",
564 i.e., either "52" or "53".
565 · "if (leap_year($year))"
567 This function returns "true" ("1") if the given year "$year" is a
569 leap year and "false" ("0") otherwise.
570 · "if (check_date($year,$month,$day))"
572 This function returns "true" ("1") if the given three numerical
574 values "$year", "$month" and "$day" constitute a valid date, and
575 "false" ("0") otherwise.
576 · "if (check_time($hour,$min,$sec))"
578 This function returns "true" ("1") if the given three numerical
580 values "$hour", "$min" and "$sec" constitute a valid time ("0 <=
581 $hour < 24", "0 <= $min < 60" and "0 <= $sec < 60"), and "false"
582 ("0") otherwise.
583 · "if (check_business_date($year,$week,$dow))"
585 This function returns "true" ("1") if the given three numerical
587 values "$year", "$week" and "$dow" constitute a valid date in
588 business format, and "false" ("0") otherwise.
589 Beware that this function does NOT compute whether a given date is a
591 business day (i.e., Monday to Friday)!
592 To do so, use ""(Day_of_Week($year,$month,$day) < 6)"" instead.
594 · "$doy = Day_of_Year($year,$month,$day);"
596 This function returns the (relative) number of the day of the given
598 date in the given year.
599 E.g., ""Day_of_Year($year,1,1)"" returns "1",
601 ""Day_of_Year($year,2,1)"" returns "32", and
602 ""Day_of_Year($year,12,31)"" returns either "365" or "366".
603 The day of year is sometimes also referred to as the Julian day (or
605 date), although it has nothing to do with the Julian calendar, the
606 calendar which was used before the Gregorian calendar.
607 In order to convert the number returned by this function back into a
609 date, use the function ""Add_Delta_Days()"" (described further
610 below), as follows:
611 $doy = Day_of_Year($year,$month,$day);
613 ($year,$month,$day) = Add_Delta_Days($year,1,1, $doy - 1);
614 · "$days = Date_to_Days($year,$month,$day);"
616 This function returns the (absolute) number of the day of the given
618 date, where counting starts at the 1st of January of the year 1Â A.D.
619 I.e., ""Date_to_Days(1,1,1)"" returns "1", ""Date_to_Days(1,12,31)""
621 returns "365", ""Date_to_Days(2,1,1)"" returns "366",
622 ""Date_to_Days(1998,5,1)"" returns "729510", and so on.
623 This is sometimes also referred to (not quite correctly) as the
625 Julian date (or day). This may cause confusion, because also the
626 number of the day in a year (from 1 to 365 or 366) is frequently
627 called the "Julian day".
628 More confusing still, this has nothing to do with the Julian
630 calendar, which was used BEFORE the Gregorian calendar.
631 The Julian calendar was named after famous Julius Caesar, who had
633 instituted it in Roman times. The Julian calendar is less precise
634 than the Gregorian calendar because it has too many leap years
635 compared to the true mean length of a year (but the Gregorian
636 calendar also still has one day too much every 5000 years). Anyway,
637 the Julian calendar was better than what existed before, because
638 rulers had often changed the calendar used until then in arbitrary
639 ways, in order to lengthen their own reign, for instance.
640 In order to convert the number returned by this function back into a
642 date, use the function ""Add_Delta_Days()"" (described further
643 below), as follows:
644 $days = Date_to_Days($year,$month,$day);
646 ($year,$month,$day) = Add_Delta_Days(1,1,1, $days - 1);
647 · "$dow = Day_of_Week($year,$month,$day);"
649 This function returns the number of the day of week of the given
651 date.
652 The function returns "1" for Monday, "2" for Tuesday and so on until
654 "7" for Sunday.
655 Note that in the Hebrew calendar (on which the Christian calendar is
657 based), the week starts with Sunday and ends with the Sabbath or
658 Saturday (where according to the Genesis (as described in the Bible)
659 the Lord rested from creating the world).
660 In medieval times, Catholic Popes have decreed the Sunday to be the
662 official day of rest, in order to dissociate the Christian from the
663 Hebrew belief.
664 It appears that this actually happened with the Emperor Constantin,
666 who converted to Christianity but still worshipped the Sun god and
667 therefore moved the Christian sabbath to the day of the Sun.
668 Nowadays, the Sunday AND the Saturday are commonly considered (and
670 used as) days of rest, usually referred to as the "week-end".
671 Consistent with this practice, current norms and standards (such as
673 ISO/RÂ 2015-1971, DINÂ 1355 and ISOÂ 8601) define the Monday as the
674 first day of the week.
675 · "$week = Week_Number($year,$month,$day);"
677 This function returns the number of the week the given date lies in.
679 If the given date lies in the LAST week of the PREVIOUS year, "0" is
681 returned.
682 If the given date lies in the FIRST week of the NEXT year,
684 ""Weeks_in_Year($year) + 1"" is returned.
685 · "($week,$year) = Week_of_Year($year,$month,$day);"
687 This function returns the number of the week the given date lies in,
689 as well as the year that week belongs to.
690 I.e., if the given date lies in the LAST week of the PREVIOUS year,
692 ""(Weeks_in_Year($year-1), $year-1)"" is returned.
693 If the given date lies in the FIRST week of the NEXT year, ""(1,
695 $year+1)"" is returned.
696 Otherwise, ""(Week_Number($year,$month,$day), $year)"" is returned.
698 · "$week = Week_of_Year($year,$month,$day);"
700 In scalar context, this function returns just the week number. This
702 allows you to write ""$week = Week_of_Year($year,$month,$day);""
703 instead of ""($week) = Week_of_Year($year,$month,$day);"" (note the
704 parentheses around "$week").
705 If the given date lies in the LAST week of the PREVIOUS year,
707 ""Weeks_in_Year($year-1)"" is returned.
708 If the given date lies in the FIRST week of the NEXT year, "1" is
710 returned.
711 Otherwise the return value is identical with that of
713 ""Week_Number($year,$month,$day)"".
714 BEWARE that using this function in scalar context is a DANGEROUS
716 feature, because without knowing which year the week belongs to, you
717 might inadvertently assume the wrong one!
718 If for instance you are iterating through an interval of dates, you
720 might assume that the week always belongs to the same year as the
721 given date, which unfortunately is WRONG in some cases!
722 In many years, the 31st of December for instance belongs to week
724 number one of the FOLLOWING year. Assuming that the year is the same
725 as your date (31st of December, in this example), sends you back to
726 the first week of the CURRENT year - the Monday of which, by the way,
727 in case of bad luck, might actually lie in the year BEFORE the
728 current year!
729 This actually happens in 2002, for example.
731 So you always need to provide the correct corresponding year number
733 by other means, keeping track of it yourself.
734 In case you do not understand this, never mind, but then simply DO
736 NOT USE this function in scalar context!
737 · "($year,$month,$day) = Monday_of_Week($week,$year);"
739 This function returns the date of the first day of the given week,
741 i.e., the Monday.
742 "$year" must be greater than or equal to "1", and "$week" must lie in
744 the range "1" to ""Weeks_in_Year($year)"".
745 Note that you can write ""($year,$month,$day) =
747 Monday_of_Week(Week_of_Year($year,$month,$day));"" in order to
748 calculate the date of the Monday of the same week as the given date.
749 If you want to calculate any other day of week in the same week as a
751 given date, use
752 @date = Add_Delta_Days(Monday_of_Week(Week_of_Year(@date)),$offset);
754 where "$offset = 1" for Tuesday, 2 for Wednesday etc.
756 · "if (($year,$month,$day) =
758 Nth_Weekday_of_Month_Year($year,$month,$dow,$n))"
759 This function calculates the date of the "$n"th day of week "$dow" in
761 the given month "$month" and year "$year"; such as, for example, the
762 3rd Thursday of a given month and year.
763 This can be used to send a notification mail to the members of a
765 group which meets regularly on every 3rd Thursday of a month, for
766 instance.
767 (See the section "RECIPES" near the end of this document for a code
769 snippet to actually do so.)
770 "$year" must be greater than or equal to "1", "$month" must lie in
772 the range "1" to "12", "$dow" must lie in the range "1" to "7" and
773 "$n" must lie in the range "1" to "5", or a fatal error (with
774 appropriate error message) occurs.
775 The function returns an empty list when the 5th of a given day of
777 week does not exist in the given month and year.
778 · "($year,$week,$dow) = Standard_to_Business($year,$month,$day);"
780 This function converts a given date from standard notation (year,
782 month, day (of month)) to business notation (year, week, day of
783 week).
784 · "($year,$month,$day) = Business_to_Standard($year,$week,$dow);"
786 This function converts a given date from business notation (year,
788 week, day of week) to standard notation (year, month, day (of
789 month)).
790 · "$Dd = Delta_Days($year1,$month1,$day1, $year2,$month2,$day2);"
792 This function returns the difference in days between the two given
794 dates.
795 The result is positive if the two dates are in chronological order,
797 i.e., if date #1 comes chronologically BEFORE date #2, and negative
798 if the order of the two dates is reversed.
799 The result is zero if the two dates are identical.
801 · "($Dd,$Dh,$Dm,$Ds) = Delta_DHMS($year1,$month1,$day1,
803 $hour1,$min1,$sec1, $year2,$month2,$day2, $hour2,$min2,$sec2);"
804 This function returns the difference in days, hours, minutes and
806 seconds between the two given dates with times.
807 All four return values will be positive if the two dates are in
809 chronological order, i.e., if date #1 comes chronologically BEFORE
810 date #2, and negative (in all four return values!) if the order of
811 the two dates is reversed.
812 This is so that the two functions ""Delta_DHMS()"" and
814 ""Add_Delta_DHMS()"" (description see further below) are
815 complementary, i.e., mutually inverse:
816 Add_Delta_DHMS(@date1,@time1, Delta_DHMS(@date1,@time1, @date2,@time2))
818 yields ""(@date2,@time2)"" again, whereas
820 Add_Delta_DHMS(@date2,@time2,
822 map(-$_, Delta_DHMS(@date1,@time1, @date2,@time2)))
823 yields ""(@date1,@time1)"", and
825 Delta_DHMS(@date1,@time1, Add_Delta_DHMS(@date1,@time1, @delta))
827 yields "@delta" again.
829 The result is zero (in all four return values) if the two dates and
831 times are identical.
832 · "($Dy,$Dm,$Dd) = Delta_YMD($year1,$month1,$day1,
834 $year2,$month2,$day2);"
835 This function returns the vector
837 ( $year2 - $year1, $month2 - $month1, $day2 - $day1 )
839 This is called the "one-by-one" semantics.
841 Adding the result of this function to the first date always yields
843 the second date again, and adding the negative result (where the
844 signs of all elements of the result vector have been flipped) to the
845 second date gives the first date. See also the description of the
846 function "Add_Delta_YMD()" further below.
847 Example:
849 (6,2,-30) == Delta_YMD(1996,1,31, 2002,3,1]);
851 [1996,1,31] + ( 6, 2,-30) = [2002,3, 1]
853 [2002,3, 1] + (-6,-2, 30) = [1996,1,31]
854 An error occurs if any of the two given dates is invalid.
856 · "($D_y,$D_m,$D_d, $Dh,$Dm,$Ds) = Delta_YMDHMS($year1,$month1,$day1,
858 $hour1,$min1,$sec1, $year2,$month2,$day2, $hour2,$min2,$sec2);"
859 This function is based on the function "Delta_YMD()" above but
861 additionally calculates the time difference. When a carry over from
862 the time difference occurs, the value of "$D_d" is adjusted
863 accordingly, thus giving the correct total date/time difference.
864 Arguments are expected to be in chronological order to yield a
866 (usually) positive result.
867 In any case, adding the result of this function to the first
869 date/time value ("$year1,$month1,$day1," "$hour1,$min1,$sec1") always
870 gives the second date/time value ("$year2,$month2,$day2,"
871 "$hour2,$min2,$sec2") again, and adding the negative result (with the
872 signs of all elements of the result vector flipped) to the second
873 date/time value gives the first date/time value.
874 See the function "Add_Delta_YMDHMS()" further below for adding a
876 date/time value and a date/time difference.
877 An error occurs if any of the given two date/time values is invalid.
879 · "($Dy,$Dm,$Dd) = N_Delta_YMD($year1,$month1,$day1,
881 $year2,$month2,$day2);"
882 This function returns the difference between the two given dates in a
884 more intuitive way (as far as possible - more on that see a bit
885 further below) than the function "Delta_YMD()" described above.
886 The "N" which precedes its name is meant to signify "new" or
888 "normalized".
889 This function is loosely based on recipe #17 b) (see the section
891 "RECIPES" below near the end of this document).
892 However, the code of recipe #17 b) actually does not treat positive
894 and negative values symmetrically and consistently.
895 This new routine does.
897 The return values of this function are guaranteed to all have the
899 same sign (or to be zero). This is why this function is called
900 "normalized".
901 Moreover, the results are guaranteed to be "minimal", in the sense
903 that "|$Dm| < 12" and "|$Dd| < 31" (which is equivalent to $Dm lying
904 in the range "[-11..+11]" and $Dd lying in the range "[-30..+30]").
905 When the results are applied (i.e., added) to the first given date in
907 a left-to-right order, the second given date is guaranteed to be
908 obtained, provided that intermediary results are truncated, as done
909 by the function "Add_Delta_YM()" (see further below), i.e., that
910 invalid intermediate dates such as e.g. [2009,2,31] will
911 automatically be transformed into [2009,2,28] (and not "wrapped" into
912 the next month, e.g. to [2009,3,3]).
913 This is called the "left-to-right with truncation" semantics.
915 Note that reversing the order of the given dates and reversing the
917 sign of each of the result values will not always add up.
918 Consider the dates [2008,2,29] and [2009,2,1]: their difference is
920 (0,11,3) ([2008,2,29] plus 11 months is [2009,1,29], which plus 3
921 days is [2009,2,1]), but the difference between [2009,2,1] and
922 [2008,2,29] is (0,-11,-1), and not (0,-11,-3) ([2009,2,1] minus 11
923 months is [2008,3,1], which minus one day is [2008,2,29]).
924 Another example: The difference between [1996,2,29] and [1997,2,28]
926 is (1,0,0) (observe the truncation of the invalid date [1997,2,29] to
927 [1997,2,28] here!), whereas the difference between [1997,2,28] and
928 [1996,2,29] is (0,-11,-28) ([1997,2,28] minus 11 months is
929 [1996,3,28], which minus 28 days is not [1996,3,0] but of course
930 [1996,2,29]).
931 "Benign" examples such as for instance the difference between
933 [1964,1,3] and [2009,9,10] are completely symmetrical: The difference
934 in this example is (45,8,7), whereas the difference between
935 [2009,9,10] and [1964,1,3] is (-45,-8,-7), as would normally be
936 expected. In this example, the result is also the same as the one
937 returned by "Delta_YMD()".
938 All these counter-intuitive effects are due to the fact that months
940 (and due to leap years, also years) do not correspond to a fixed
941 number of days, so the semantics of "plus one month" or "plus one
942 year" are in fact undefined.
943 The present function is an attempt to provide a definition which is
945 intuitive most of the time, and at least consistent the rest of the
946 time.
947 Other definitions are of course possible, but most often lead to
949 contradictions (e.g., the results and the given first date do not add
950 up to the second given date).
951 See the file "datecalc.pl" in the "examples" subdirectory of this
953 distribution for a way to play around with this function, or go to
954 http://www.engelschall.com/u/sb/datecalc/ for the online version.
955 An error occurs if any of the two given dates is invalid, or if any
957 intermediate result leads to an invalid date (this does not apply to
958 truncation, however, as explained above).
959 · "($D_y,$D_m,$D_d, $Dhh,$Dmm,$Dss) =
961 N_Delta_YMDHMS($year1,$month1,$day1, $hour1,$min1,$sec1,
962 $year2,$month2,$day2, $hour2,$min2,$sec2);"
963 This function essentially does the same as the function
965 "N_Delta_YMD()" described immediately above, except that also the
966 difference in hours, minutes and seconds is taken into account.
967 This function is loosely based on recipe #17 a) (see the section
969 "RECIPES" below near the end of this document).
970 However, the code of recipe #17 a) actually does not treat positive
972 and negative values symmetrically and consistently.
973 This new routine does.
975 The return values of this function (including the time differences)
977 are guaranteed to all have the same sign (or to be zero). This is the
978 reason for the "N" that precedes the name of this function, which is
979 intended to mean "normalized" (or "new").
980 Moreover, the results are guaranteed to be "minimal", in the sense
982 that "|$D_m| < 12", "|$D_d| < 31", "|$Dhh| < 24", "|$Dmm| < 60" and
983 "|$Dss| < 60" (which is equivalent to $D_m lying in the range
984 "[-11..+11]", $D_d lying in the range "[-30..+30]", $Dhh lying in the
985 range "[-23..+23]", and $Dmm and $Dss both lying in the range
986 "[-59..+59]").
987 · "($Dd,$Dh,$Dm,$Ds) = Normalize_DHMS($Dd,$Dh,$Dm,$Ds);"
989 This function takes four arbitrary values for days, hours, minutes
991 and seconds (which may have different signs) and renormalizes them so
992 that the values for hours, minutes and seconds will lie in the ranges
993 "[-23..23]", "[-59..59]" and "[-59..59]", respectively, and so that
994 all four values have the same sign (or are zero).
995 The given values are left untouched, i.e., unchanged.
997 · "($year,$month,$day) = Add_Delta_Days($year,$month,$day, $Dd);"
999 This function has two principal uses:
1001 First, it can be used to calculate a new date, given an initial date
1003 and an offset (which may be positive or negative) in days, in order
1004 to answer questions like "today plus 90 days -- which date gives
1005 that?".
1006 (In order to add a weeks offset, simply multiply the weeks offset
1008 with "7" and use that as your days offset.)
1009 Second, it can be used to convert the canonical representation of a
1011 date, i.e., the number of that day (where counting starts at the 1st
1012 of January in 1Â A.D.), back into a date given as year, month and
1013 day.
1014 Because counting starts at "1", you will actually have to subtract
1016 "1" from the canonical date in order to get back the original date:
1017 $canonical = Date_to_Days($year,$month,$day);
1019 ($year,$month,$day) = Add_Delta_Days(1,1,1, $canonical - 1);
1021 Moreover, this function is the inverse of the function
1023 ""Delta_Days()"":
1024 Add_Delta_Days(@date1, Delta_Days(@date1, @date2))
1026 yields "@date2" again, whereas
1028 Add_Delta_Days(@date2, -Delta_Days(@date1, @date2))
1030 yields "@date1", and
1032 Delta_Days(@date1, Add_Delta_Days(@date1, $delta))
1034 yields "$delta" again.
1036 · "($year,$month,$day, $hour,$min,$sec) =
1038 Add_Delta_DHMS($year,$month,$day, $hour,$min,$sec, $Dd,$Dh,$Dm,$Ds);"
1039 This function serves to add a days, hours, minutes and seconds offset
1041 to a given date and time, in order to answer questions like "today
1042 and now plus 7 days but minus 5 hours and then plus 30 minutes, what
1043 date and time gives that?":
1044 ($y,$m,$d,$H,$M,$S) = Add_Delta_DHMS(Today_and_Now(), +7,-5,+30,0);
1046 · "($year,$month,$day) = Add_Delta_YM($year,$month,$day, $Dy,$Dm);"
1048 This function can be used to add a year and/or month offset to a
1050 given date.
1051 In contrast to the function described immediately below
1053 (""Add_Delta_YMD()""), this function does no "wrapping" into the next
1054 month if the day happens to lie outside the valid range for the
1055 resulting year and month (after adding the year and month offsets).
1056 Instead, it simply truncates the day to the last possible day of the
1057 resulting month.
1058 Examples:
1060 Adding an offset of 0 years, 1 month to the date [1999,1,31] would
1062 result in the (invalid) date [1999,2,31]. The function replaces this
1063 result by the (valid) date [1999,2,28].
1064 Adding an offset of 1 year, 1 month to the same date [1999,1,31] as
1066 above would result in the (still invalid) date [2000,2,31]. The
1067 function replaces this result by the valid date [2000,2,29] (because
1068 2000 is a leap year).
1069 Note that the year and month offsets can be negative, and that they
1071 can have different signs.
1072 If you want to additionally add a days offset, use the function
1074 ""Add_Delta_Days()"" before or after calling ""Add_Delta_YM()"":
1075 @date2 = Add_Delta_Days( Add_Delta_YM(@date1, $Dy,$Dm), $Dd );
1077 @date2 = Add_Delta_YM( Add_Delta_Days(@date1, $Dd), $Dy,$Dm );
1078 Note that your result may depend on the order in which you call these
1080 two functions!
1081 Consider the date [1999,2,28] and the offsets 0 years, 1 month and 1
1083 day:
1084 [1999,2,28] plus one month is [1999,3,28], plus one day is
1086 [1999,3,29]. [1999,2,28] plus one day is [1999,3,1], plus one month
1087 is [1999,4,1].
1088 (Which is also the reason why the ""Add_Delta_YM()"" function does
1090 not allow to add a days offset, because this would actually require
1091 TWO functions: One for adding the days offset BEFORE and one for
1092 adding it AFTER applying the year/month offsets.)
1093 An error occurs if the initial date is not valid.
1095 Note that ""Add_Delta_YM( Add_Delta_YM(@date, $Dy,$Dm), -$Dy,-$Dm
1097 );"" will not, in general, return the original date "@date" (consider
1098 the examples given above!).
1099 · "($year,$month,$day) = Add_Delta_YMD($year,$month,$day,
1101 $Dy,$Dm,$Dd);"
1102 This function serves to add a years, months and days offset to a
1104 given date.
1105 (In order to add a weeks offset, simply multiply the weeks offset
1107 with "7" and add this number to your days offset.)
1108 Note that the three offsets for years, months and days are applied
1110 independently from each other. This also allows them to have
1111 different signs.
1112 The years and months offsets are applied first, and the days offset
1114 is applied last.
1115 If the resulting date happens to fall on a day after the end of the
1117 resulting month, like the 32nd of April or the 30th of February, then
1118 the date is simply counted forward into the next month (possibly also
1119 into the next year) by the number of excessive days (e.g., the 32nd
1120 of April will become the 2nd of May).
1121 BEWARE that this behaviour differs from that of previous versions of
1123 this module! In previous versions, the day was simply truncated to
1124 the maximum number of days in the resulting month.
1125 If you want the previous behaviour, use the new function
1127 ""Add_Delta_YM()"" (described immediately above) plus the function
1128 ""Add_Delta_Days()"" instead.
1129 BEWARE also that because a year and a month offset is not equivalent
1131 to a fixed number of days, the transformation performed by this
1132 function is NOT ALWAYS REVERSIBLE!
1133 This is in contrast to the functions ""Add_Delta_Days()"" and
1135 ""Add_Delta_DHMS()"", which are fully and truly reversible (with the
1136 help of the functions ""Delta_Days()"" and ""Delta_DHMS()"", for
1137 instance).
1138 Note that for this same reason,
1140 @date = Add_Delta_YMD(
1142 Add_Delta_YMD(@date, $Dy,$Dm,$Dd), -$Dy,-$Dm,-$Dd);
1143 will in general NOT return the initial date "@date", even though
1145 @date2 = Add_Delta_YMD( @date1, Delta_YMD(@date1, @date2) );
1147 will always return the second date "@date2", and
1149 @date1 = Add_Delta_YMD( @date2, map(-$_, Delta_YMD(@date1, @date2)) );
1151 which is the same as
1153 @date1 = Add_Delta_YMD( @date2, Delta_YMD(@date2, @date1) );
1155 will always return the first date "@date1".
1157 Examples:
1159 [1996,1,31] + ( 6, 1,-2) = [2002,3,1]
1161 [2002,3, 1] + (-6,-1, 2) = [1996,2,3] # EXPECTED: [1996,1,31]
1162 (6,2,-30) == Delta_YMD(1996,1,31, 2002,3,1);
1164 [1996,1,31] + ( 6, 2,-30) = [2002,3, 1]
1166 [2002,3, 1] + (-6,-2, 30) = [1996,1,31] # OK
1167 (6,1,-2) == Delta_YMD(1996,2,3, 2002,3,1);
1169 [1996,2,3] + ( 6, 1,-2) = [2002,3,1]
1171 [2002,3,1] + (-6,-1, 2) = [1996,2,3] # OK
1172 Note that this is NOT a program bug but NECESSARILY so, because of
1174 the variable lengths of years and months, and hence because of the
1175 ambiguity of the difference between two dates in terms of years,
1176 months and days, i.e., the fact that the difference between two dates
1177 can be expressed in more than one way:
1178 [1996,1,31] + (6,1, -2) = [2002,3,1]
1180 [1996,1,31] + (6,2,-30) = [2002,3,1]
1181 · "($year,$month,$day, $hour,$min,$sec) =
1183 Add_Delta_YMDHMS($year,$month,$day, $hour,$min,$sec, $D_y,$D_m,$D_d,
1184 $Dh,$Dm,$Ds);"
1185 Same as the function above, except that a time offset may be given in
1187 addition to the year, month and day offset.
1188 · "($year,$month,$day) = Add_N_Delta_YMD($year,$month,$day,
1190 $Dy,$Dm,$Dd);"
1191 This function is actually a shortcut for applying the function
1193 "Add_Delta_YM()" first, followed by the function "Add_Delta_Days()",
1194 i.e., this function does exactly the same as
1195 ($year,$month,$day) = Add_Delta_Days( Add_Delta_YM($year,$month,$day,$Dy,$Dm), $Dd );
1197 Beware that, if necessary, the function "Add_Delta_YM()" truncates
1199 the resulting day of the month to the largest allowable value for
1200 that month, i.e., the (invalid) result [2009,2,31] is automatically
1201 transformed into [2009,2,28].
1202 For more details on this truncation, see the description of the
1204 function "Add_Delta_YM()" further above.
1205 This function is meant to be complementary with the function
1207 "N_Delta_YMD()" described further above.
1208 This means that it is guaranteed that the result returned by
1210 Add_N_Delta_YMD( @date1, N_Delta_YMD(@date1, @date2) );
1212 is always identical with the given date "@date2".
1214 Note however that unlike with function "Add_Delta_YMD()", the reverse
1216 is not true here, i.e.,
1217 ($Dy,$Dm,$Dd) = N_Delta_YMD(@date1,@date2);
1219 @date = Add_N_Delta_YMD(@date2, -$Dy,-$Dm,-$Dd);
1220 will NOT always return the initial date "@date1".
1222 Example:
1224 (0,11,3) == N_Delta_YMD(2008,2,29, 2009,2,1);
1226 [2008,2,29] + (0, 11, 3) = [2009,2, 1]
1228 [2009,2, 1] + (0,-11,-3) = [2008,2,27] # EXPECTED: [2008,2,29]
1229 · "($year,$month,$day, $hour,$min,$sec) =
1231 Add_N_Delta_YMDHMS($year,$month,$day, $hour,$min,$sec,
1232 $D_y,$D_m,$D_d, $Dhh,$Dmm,$Dss);"
1233 This function essentially does the same as the function
1235 "Add_N_Delta_YMD()" described immediately above, except that also the
1236 difference in hours, minutes and seconds is taken into account.
1237 · "($year,$month,$day, $hour,$min,$sec, $doy,$dow,$dst) =
1239 System_Clock([$gmt]);"
1240 If your operating system supports the corresponding system calls
1242 (""time()"" and ""localtime()"" or ""gmtime()""), this function will
1243 return the information provided by your system clock, i.e., the
1244 current date and time, the number of the day of year, the number of
1245 the day of week and a flag signaling whether daylight savings time is
1246 currently in effect or not.
1247 The ranges of values returned (and their meanings) are as follows:
1249 $year : 1970..2038 (or more) [Unix etc.]
1251 $year : 1904..2040 [MacOS Classic]
1252 $month : 1..12
1254 $day : 1..31
1255 $hour : 0..23
1256 $min : 0..59
1257 $sec : 0..59 (0..61 on some systems)
1258 $doy : 1..366
1259 $dow : 1..7
1260 $dst : -1..1
1261 "$doy" is the day of year, sometimes also referred to as the "julian
1263 date", which starts at "1" and goes up to the number of days in that
1264 year.
1265 The day of week ("$dow") will be "1" for Monday, "2" for Tuesday and
1267 so on until "7" for Sunday.
1268 The daylight savings time flag ("$dst") will be ""-1"" if this
1270 information is not available on your system, "0" for no daylight
1271 savings time (i.e., winter time) and "1" when daylight savings time
1272 is in effect.
1273 If your operating system does not provide the necessary system calls,
1275 calling this function will result in a fatal "not available on this
1276 system" error message.
1277 If you want to handle this exception yourself, use ""eval"" as
1279 follows:
1280 eval { ($year,$month,$day, $hour,$min,$sec, $doy,$dow,$dst) =
1282 System_Clock(); };
1283 if ($@)
1285 {
1286 # Handle missing system clock
1287 # (For instance, ask user to enter this information manually)
1288 }
1289 Note that curlies ("{" and "}") are used here to delimit the
1291 statement to be "eval"ed (which is the way to catch exceptions in
1292 Perl), and not quotes (which is a way to evaluate Perl expressions at
1293 runtime).
1294 If the optional (boolean) input parameter "$gmt" is given, a "true"
1296 value ("1") will cause ""gmtime()"" to be used instead of
1297 ""localtime()"", internally, thus returning Greenwich Mean Time (GMT,
1298 or UTC) instead of local time.
1299 · "($year,$month,$day) = Today([$gmt]);"
1301 This function returns a subset of the values returned by the function
1303 ""System_Clock()"" (see above for details), namely the current year,
1304 month and day.
1305 A fatal "not available on this system" error message will appear if
1307 the corresponding system calls are not supported by your current
1308 operating system.
1309 If the optional (boolean) input parameter "$gmt" is given, a "true"
1311 value ("1") will cause ""gmtime()"" to be used instead of
1312 ""localtime()"", internally, thus returning Greenwich Mean Time (GMT,
1313 or UTC) instead of local time.
1314 · "($hour,$min,$sec) = Now([$gmt]);"
1316 This function returns a subset of the values returned by the function
1318 ""System_Clock()"" (see above for details), namely the current time
1319 (hours, minutes and full seconds).
1320 A fatal "not available on this system" error message will appear if
1322 the corresponding system calls are not supported by your current
1323 operating system.
1324 If the optional (boolean) input parameter "$gmt" is given, a "true"
1326 value ("1") will cause ""gmtime()"" to be used instead of
1327 ""localtime()"", internally, thus returning Greenwich Mean Time (GMT,
1328 or UTC) instead of local time.
1329 · "($year,$month,$day, $hour,$min,$sec) = Today_and_Now([$gmt]);"
1331 This function returns a subset of the values returned by the function
1333 ""System_Clock()"" (see above for details), namely the current date
1334 (year, month, day) and time (hours, minutes and full seconds).
1335 A fatal "not available on this system" error message will appear if
1337 the corresponding system calls are not supported by your current
1338 operating system.
1339 If the optional (boolean) input parameter "$gmt" is given, a "true"
1341 value ("1") will cause ""gmtime()"" to be used instead of
1342 ""localtime()"", internally, thus returning Greenwich Mean Time (GMT,
1343 or UTC) instead of local time.
1344 · "$year = This_Year([$gmt]);"
1346 This function returns the current year, according to local time.
1348 A fatal "not available on this system" error message will appear if
1350 the corresponding system calls are not supported by your current
1351 operating system.
1352 If the optional (boolean) input parameter "$gmt" is given, a "true"
1354 value ("1") will cause ""gmtime()"" to be used instead of
1355 ""localtime()"", internally, thus returning Greenwich Mean Time (GMT,
1356 or UTC) instead of local time. However, this will only make a
1357 difference within a few hours around New Year (unless you are on a
1358 Pacific island, where this can be almost 24 hours).
1359 · "($year,$month,$day, $hour,$min,$sec, $doy,$dow,$dst) =
1361 Gmtime([time]);"
1362 This is Date::Calc's equivalent of Perl's built-in "gmtime()"
1364 function. See also "gmtime" in perlfunc(1).
1365 With the optional argument "time" (i.e., seconds since the epoch),
1367 this function will return the corresponding values for that
1368 particular time (instead of the current time when this parameter is
1369 omitted).
1370 The ranges of values returned (and their meanings) are as follows:
1372 $year : 1970..2038 (or more) [Unix etc.]
1374 $year : 1904..2040 [MacOS Classic]
1375 $month : 1..12
1377 $day : 1..31
1378 $hour : 0..23
1379 $min : 0..59
1380 $sec : 0..59
1381 $doy : 1..366
1382 $dow : 1..7
1383 $dst : -1..1
1384 "$doy" is the day of year, sometimes also referred to as the "julian
1386 date", which starts at "1" and goes up to the number of days in that
1387 year.
1388 The day of week ("$dow") will be "1" for Monday, "2" for Tuesday and
1390 so on until "7" for Sunday.
1391 The daylight savings time flag ("$dst") will be ""-1"" if this
1393 information is not available on your system, "0" for no daylight
1394 savings time (i.e., winter time) and "1" when daylight savings time
1395 is in effect.
1396 A fatal "time out of range" error will occur if the given time value
1398 is out of range "[0..(~0>>1)]".
1399 If the time value is omitted, the "time()" function is called
1401 instead, internally.
1402 · "($year,$month,$day, $hour,$min,$sec, $doy,$dow,$dst) =
1404 Localtime([time]);"
1405 This is Date::Calc's equivalent of Perl's built-in "localtime()"
1407 function. See also "localtime" in perlfunc(1).
1408 The ranges of values returned (and their meanings) are as follows:
1410 $year : 1970..2038 (or more) [Unix etc.]
1412 $year : 1904..2040 [MacOS Classic]
1413 $month : 1..12
1415 $day : 1..31
1416 $hour : 0..23
1417 $min : 0..59
1418 $sec : 0..59
1419 $doy : 1..366
1420 $dow : 1..7
1421 $dst : -1..1
1422 "$doy" is the day of year, sometimes also referred to as the "julian
1424 date", which starts at "1" and goes up to the number of days in that
1425 year.
1426 The day of week ("$dow") will be "1" for Monday, "2" for Tuesday and
1428 so on until "7" for Sunday.
1429 The daylight savings time flag ("$dst") will be ""-1"" if this
1431 information is not available on your system, "0" for no daylight
1432 savings time (i.e., winter time) and "1" when daylight savings time
1433 is in effect.
1434 A fatal "time out of range" error will occur if the given time value
1436 is out of range "[0..(~0>>1)]".
1437 If the time value is omitted, the "time()" function is called
1439 instead, internally.
1440 · "$time = Mktime($year,$month,$day, $hour,$min,$sec);"
1442 This function converts a date into a time value, i.e., into the
1444 number of seconds since whatever moment in time your system considers
1445 to be the "epoch". On Unix and most other systems this is the number
1446 of seconds since January 1st 1970 at midnight (GMT). On MacOS Classic
1447 this is the number of seconds since January 1st 1904 at midnight
1448 (local time).
1449 The function is similar to the "POSIX::mktime()" function (see
1451 "mktime" in POSIX(1) for more details), but in contrast to the
1452 latter, it expects dates in the usual ranges used throughout this
1453 module: The year 2001 stays year 2001, and months are numbered from 1
1454 to 12.
1455 A fatal "date out of range" error will occur if the given date cannot
1457 be expressed in terms of seconds since the epoch (this happens for
1458 instance when the date lies before the epoch, or if it is later than
1459 19-Jan-2038Â 03:14:07Â GMT on 32Â bit Unix systems, or later than
1460 06-Feb-2040Â 06:28:15 (local time) on a Macintosh with MacOS
1461 Classic).
1462 Just like the "POSIX::mktime()" function, this function uses the
1464 "mktime()" system call, internally.
1465 This means that the given date and time is considered to be in local
1467 time, and that the value returned by this function will depend on
1468 your machine's local settings such as the time zone, whether daylight
1469 savings time is (or was, at the time) in effect, and the system clock
1470 itself.
1471 BEWARE that "mktime()" does not always return the same time value as
1473 fed into "localtime()", when you feed the output of "localtime()"
1474 back into "mktime()", on some systems!
1475 I.e., ""Mktime((Localtime($time))[0..5])"" will not always return the
1477 same value as given in "$time"!
1478 · "($D_y,$D_m,$D_d, $Dh,$Dm,$Ds, $dst) = Timezone([time]);"
1480 This function returns the difference between ""localtime(time)"" and
1482 ""gmtime(time)"", which is the timezone offset in effect for the
1483 current location and the given ""time"".
1484 This offset is positive if you are located to the east of Greenwich,
1486 and is usually negative (except during daylight savings time, in some
1487 locations) if you are located to the west of Greenwich.
1488 Note that this offset is influenced by all of the relevant system
1490 settings and parameters on your machine; such as locales, environment
1491 variables (e.g. ""TZ"") and the system clock itself. See the relevant
1492 documentation on your system for more details.
1493 If the ""time"" is omitted, the ""time()"" function will be called
1495 automatically, internally (similar to the built-in functions
1496 ""localtime()"" and ""gmtime()"" in Perl).
1497 A fatal "time out of range" error will occur if the given time value
1499 is out of range "[0..(~0>>1)]".
1500 The last item of the returned list is a flag which indicates whether
1502 daylight savings time is currently in effect. This flag is negative
1503 (-1) if this information is not available on your system. It is zero
1504 (0) when daylight savings time is off, and positive (+1) when
1505 daylight savings time is on.
1506 Thus you can check very quickly whether daylight savings time is
1508 currently in effect by evaluating this function in scalar context (in
1509 scalar context, Perl returns the last item of a list):
1510 if (scalar Timezone > 0) { # yes, daylight savings time
1512 However, a slightly more efficient way would be this:
1514 if (scalar System_Clock > 0) { # yes, daylight savings time
1516 · "$time = Date_to_Time($year,$month,$day, $hour,$min,$sec);"
1518 This function is a replacement for the BSD function "timegm()" (which
1520 is not available on all Unix systems), which converts a given date
1521 and time into a time value, i.e., into the number of seconds since
1522 whatever moment in time your system considers to be the "epoch". On
1523 Unix and most other systems this is the number of seconds since
1524 January 1st 1970 at midnight (GMT). On MacOS Classic this is the
1525 number of seconds since January 1st 1904 at midnight (local time).
1526 Under Unix, the date and time are considered to be in UTC ("Universal
1528 Time Coordinated", and so is the resulting time value.
1529 UTC is almost the same as GMT (or "Greenwich Mean Time"), except that
1531 UTC has leap seconds (in order to account for small variations in the
1532 rotation of the earth, for instance), whereas GMT does not.
1533 Under MacOS Classic, however, both input and output are considered to
1535 be in local time.
1536 The ranges of year and month follow the same rules as throughout the
1538 rest of this module (and not the contorted rules of its Unix
1539 equivalent), i.e., the year "2001" stays "2001" and the month ranges
1540 from 1 to 12.
1541 A fatal "date out of range" error will occur if the given date cannot
1543 be expressed in terms of seconds since the epoch (this happens for
1544 instance when the date lies before the epoch, or if it is later than
1545 19-Jan-2038Â 03:14:07Â GMT on 32Â bit Unix systems, or later than
1546 06-Feb-2040Â 06:28:15 (local time) on a Macintosh with MacOS
1547 Classic).
1548 This function should be very fast, because it is implemented in a
1550 very straightforward manner and doesn't use any internal system
1551 calls.
1552 Moreover, the functions "Date_to_Time()" and "Time_to_Date()" are
1554 guaranteed to be complementary, i.e., that
1555 ""Date_to_Time(Time_to_Date($time))"" and
1556 ""Time_to_Date(Date_to_Time($year,$month,$day, $hour,$min,$sec))""
1557 will always return the initial values.
1558 · "($year,$month,$day, $hour,$min,$sec) = Time_to_Date([time]);"
1560 This function is an alternative to the POSIX "gmtime()" function (and
1562 its built-in Perl equivalent), which converts a given time value into
1563 the corresponding date and time. The given time value must be the
1564 number of seconds since whatever moment in time your system considers
1565 to be the "epoch". On Unix and most other systems this is the number
1566 of seconds since January 1st 1970 at midnight (GMT). On MacOS Classic
1567 this is the number of seconds since January 1st 1904 at midnight
1568 (local time).
1569 Under Unix, the given time value is considered to be in UTC
1571 ("Universal Time Coordinated", and so is the resulting date and time.
1572 UTC is almost the same as GMT (or "Greenwich Mean Time"), except that
1574 UTC has leap seconds (in order to account for small variations in the
1575 rotation of the earth, for instance), whereas GMT does not.
1576 Under MacOS Classic, however, both input and output are considered to
1578 be in local time.
1579 If the input value ""time"" is omitted, the ""time()"" function will
1581 be called automatically, internally (similar to the built-in
1582 functions ""localtime()"" and ""gmtime()"" in Perl).
1583 A fatal "time out of range" error will occur if the given time value
1585 is negative.
1586 This function should be very fast, because it is implemented in a
1588 very straightforward manner and doesn't use any internal system calls
1589 (except for "time()", if the input value is omitted).
1590 Moreover, the functions "Date_to_Time()" and "Time_to_Date()" are
1592 guaranteed to be complementary, i.e., that
1593 ""Date_to_Time(Time_to_Date($time))"" and
1594 ""Time_to_Date(Date_to_Time($year,$month,$day, $hour,$min,$sec))""
1595 will always return the initial values.
1596 · "($year,$month,$day) = Easter_Sunday($year);"
1598 This function calculates the date of Easter Sunday for all years in
1600 the range from 1583 to 2299 (all other year numbers will result in a
1601 fatal "year out of range" error message) using the method known as
1602 the "Gaussian Rule".
1603 Some related christian feast days which depend on the date of Easter
1605 Sunday:
1606 Carnival Monday / Rosenmontag / Veille du Mardi Gras = -48 days
1608 Mardi Gras / Karnevalsdienstag / Mardi Gras = -47 days
1609 Ash Wednesday / Aschermittwoch / Mercredi des Cendres = -46 days
1610 Palm Sunday / Palmsonntag / Dimanche des Rameaux = -7 days
1611 Easter Friday / Karfreitag / Vendredi Saint = -2 days
1612 Easter Saturday / Ostersamstag / Samedi de Paques = -1 day
1613 Easter Monday / Ostermontag / Lundi de Paques = +1 day
1614 Ascension of Christ / Christi Himmelfahrt / Ascension = +39 days
1615 Whitsunday / Pfingstsonntag / Dimanche de Pentecote = +49 days
1616 Whitmonday / Pfingstmontag / Lundi de Pentecote = +50 days
1617 Feast of Corpus Christi / Fronleichnam / Fete-Dieu = +60 days
1618 Use the offsets shown above to calculate the date of the
1620 corresponding feast day as follows:
1621 ($year,$month,$day) = Add_Delta_Days(Easter_Sunday($year), $offset));
1623 · "if ($month = Decode_Month($string[,$lang]))"
1625 This function takes a string as its argument, which should contain
1627 the name of a month in the given or currently selected language (see
1628 further below for details about the multi-language support of this
1629 package), or any uniquely identifying abbreviation of a month's name
1630 (i.e., the first few letters), and returns the corresponding number
1631 (1..12) upon a successful match, or "0" otherwise (therefore, the
1632 return value can also be used as the conditional expression in an
1633 "if" statement).
1634 Note that the input string may not contain any other characters which
1636 do not pertain to the month's name, especially no leading or trailing
1637 whitespace.
1638 Note also that matching is performed in a case-insensitive manner
1640 (this may depend on the "locale" setting on your current system,
1641 though!)
1642 With "1" ("English") as the given language, the following examples
1644 will all return the value "9":
1645 $month = Decode_Month("s",1);
1647 $month = Decode_Month("Sep",1);
1648 $month = Decode_Month("septemb",1);
1649 $month = Decode_Month("September",1);
1650 · "if ($dow = Decode_Day_of_Week($string[,$lang]))"
1652 This function takes a string as its argument, which should contain
1654 the name of a day of week in the given or currently selected language
1655 (see further below for details about the multi-language support of
1656 this package), or any uniquely identifying abbreviation of the name
1657 of a day of week (i.e., the first few letters), and returns the
1658 corresponding number (1..7) upon a successful match, or "0" otherwise
1659 (therefore, the return value can also be used as the conditional
1660 expression in an "if" statement).
1661 Note that the input string may not contain any other characters which
1663 do not pertain to the name of the day of week, especially no leading
1664 or trailing whitespace.
1665 Note also that matching is performed in a case-insensitive manner
1667 (this may depend on the "locale" setting on your current system,
1668 though!)
1669 With "1" ("English") as the given language, the following examples
1671 will all return the value "3":
1672 $dow = Decode_Day_of_Week("w",1);
1674 $dow = Decode_Day_of_Week("Wed",1);
1675 $dow = Decode_Day_of_Week("wednes",1);
1676 $dow = Decode_Day_of_Week("Wednesday",1);
1677 · "if ($lang = Decode_Language($string))"
1679 This function takes a string as its argument, which should contain
1681 the name of one of the languages supported by this package (IN THIS
1682 VERY LANGUAGE ITSELF), or any uniquely identifying abbreviation of
1683 the name of a language (i.e., the first few letters), and returns its
1684 corresponding internal number (1..14 in the original distribution)
1685 upon a successful match, or "0" otherwise (therefore, the return
1686 value can also be used as the conditional expression in an "if"
1687 statement).
1688 Note that the input string may not contain any other characters which
1690 do not pertain to the name of a language, especially no leading or
1691 trailing whitespace.
1692 Note also that matching is performed in a case-insensitive manner
1694 (this may depend on the "locale" setting on your current system,
1695 though!)
1696 The original distribution supports the following fourteen languages:
1698 English ==> 1 (default)
1700 Français (French) ==> 2
1701 Deutsch (German) ==> 3
1702 Español (Spanish) ==> 4
1703 Português (Portuguese) ==> 5
1704 Nederlands (Dutch) ==> 6
1705 Italiano (Italian) ==> 7
1706 Norsk (Norwegian) ==> 8
1707 Svenska (Swedish) ==> 9
1708 Dansk (Danish) ==> 10
1709 suomi (Finnish) ==> 11
1710 Magyar (Hungarian) ==> 12
1711 polski (Polish) ==> 13
1712 Romaneste (Romanian) ==> 14
1713 See the section "How to install additional languages" in the file
1715 "INSTALL.txt" in this distribution for how to add more languages to
1716 this package.
1717 In the original distribution (no other languages installed), the
1719 following examples will all return the value "3":
1720 $lang = Decode_Language("d");
1722 $lang = Decode_Language("de");
1723 $lang = Decode_Language("Deutsch");
1724 Note that you may not be able to enter the special international
1726 characters in some of the languages' names over the keyboard directly
1727 on some systems.
1728 This should never be a problem, though; just enter an abbreviation of
1730 the name of the language consisting of the first few letters up to
1731 the character before the first special international character.
1732 · "if (($year,$month,$day) = Decode_Date_EU($string[,$lang]))"
1734 This function scans a given string and tries to parse any date which
1736 might be embedded in it.
1737 The function returns an empty list if it can't successfully extract a
1739 valid date from its input string, or else it returns the date found.
1740 The function accepts almost any format, as long as the date is given
1742 in the european order (hence its name) day-month-year.
1743 Thereby, zero or more NON-NUMERIC characters may PRECEDE the day and
1745 FOLLOW the year.
1746 Moreover, zero or more NON-ALPHANUMERIC characters are permitted
1748 BETWEEN these three items (i.e., between day and month and between
1749 month and year).
1750 The month may be given either numerically (i.e., a number from "1" to
1752 "12"), or alphanumerically, i.e., as the name of the month in the
1753 given or currently selected language, or any uniquely identifying
1754 abbreviation thereof.
1755 (See further below for details about the multi-language support of
1757 this package!)
1758 If the year is given as one or two digits only (i.e., if the year is
1760 less than 100), it is mapped to a "window" of +/- 50 years around the
1761 current year, as described by the "Moving_Window()" function (see
1762 further below).
1763 If the day, month and year are all given numerically but WITHOUT any
1765 delimiting characters between them, this string of digits will be
1766 mapped to the day, month and year as follows:
1767 Length: Mapping:
1769 3 dmy
1770 4 dmyy
1771 5 dmmyy
1772 6 ddmmyy
1773 7 dmmyyyy
1774 8 ddmmyyyy
1775 (Where "d" stands for "day", "m" stands for "month" and "y" stands
1777 for "year".)
1778 All other strings consisting purely of digits (without any
1780 intervening delimiters) are rejected, i.e., not recognized.
1781 Examples:
1783 "3.1.64"
1785 "3 1 64"
1786 "03.01.64"
1787 "03/01/64"
1788 "3. Jan 1964"
1789 "Birthday: 3. Jan '64 in Backnang/Germany"
1790 "03-Jan-64"
1791 "3.Jan1964"
1792 "3Jan64"
1793 "030164"
1794 "3ja64"
1795 "3164"
1796 Experiment! (See the corresponding example applications in the
1798 "examples" subdirectory of this distribution in order to do so.)
1799 · "if (($year,$month,$day) = Decode_Date_US($string[,$lang]))"
1801 This function scans a given string and tries to parse any date which
1803 might be embedded in it.
1804 The function returns an empty list if it can't successfully extract a
1806 valid date from its input string, or else it returns the date found.
1807 The function accepts almost any format, as long as the date is given
1809 in the U.S. american order (hence its name) month-day-year.
1810 Thereby, zero or more NON-ALPHANUMERIC characters may PRECEDE and
1812 FOLLOW the month (i.e., precede the month and separate it from the
1813 day which follows behind).
1814 Moreover, zero or more NON-NUMERIC characters are permitted BETWEEN
1816 the day and the year, as well as AFTER the year.
1817 The month may be given either numerically (i.e., a number from "1" to
1819 "12"), or alphanumerically, i.e., as the name of the month in the
1820 given or currently selected language, or any uniquely identifying
1821 abbreviation thereof.
1822 (See further below for details about the multi-language support of
1824 this package!)
1825 If the year is given as one or two digits only (i.e., if the year is
1827 less than 100), it is mapped to a "window" of +/- 50 years around the
1828 current year, as described by the "Moving_Window()" function (see
1829 further below).
1830 If the month, day and year are all given numerically but WITHOUT any
1832 delimiting characters between them, this string of digits will be
1833 mapped to the month, day and year as follows:
1834 Length: Mapping:
1836 3 mdy
1837 4 mdyy
1838 5 mddyy
1839 6 mmddyy
1840 7 mddyyyy
1841 8 mmddyyyy
1842 (Where "m" stands for "month", "d" stands for "day" and "y" stands
1844 for "year".)
1845 All other strings consisting purely of digits (without any
1847 intervening delimiters) are rejected, i.e., not recognized.
1848 If only the day and the year form a contiguous string of digits, they
1850 will be mapped as follows:
1851 Length: Mapping:
1853 2 dy
1854 3 dyy
1855 4 ddyy
1856 5 dyyyy
1857 6 ddyyyy
1858 (Where "d" stands for "day" and "y" stands for "year".)
1860 Examples:
1862 "1 3 64"
1864 "01/03/64"
1865 "Jan 3 '64"
1866 "Jan 3 1964"
1867 "===> January 3rd 1964 (birthday)"
1868 "Jan31964"
1869 "Jan364"
1870 "ja364"
1871 "1364"
1872 Experiment! (See the corresponding example applications in the
1874 "examples" subdirectory of this distribution in order to do so.)
1875 · "$year = Fixed_Window($yy);"
1877 This function applies a "fixed window" strategy to two-digit year
1879 numbers in order to convert them into four-digit year numbers.
1880 All other year numbers are passed through unchanged, except for
1882 negative year numbers, which cause the function to return zero ("0")
1883 instead.
1884 Two-digit year numbers ""yy"" below 70 are converted to ""20yy"",
1886 whereas year numbers equal to or greater than 70 (but less than 100)
1887 are converted to ""19yy"".
1888 In the original distribution of this package, the base century is set
1890 to "1900" and the base year to "70" (which is a standard on UNIX
1891 systems), but these constants (also called the "epoch") can actually
1892 be chosen at will (in the files "DateCalc.c" and "DateCalc.h") at
1893 compile time of this module.
1894 · "$year = Moving_Window($yy);"
1896 This function applies a "moving window" strategy to two-digit year
1898 numbers in order to convert them into four-digit year numbers,
1899 provided the necessary system calls (system clock) are available.
1900 Otherwise the function falls back to the "fixed window" strategy
1901 described in the function above.
1902 All other year numbers are passed through unchanged, except for
1904 negative year numbers, which cause the function to return zero ("0")
1905 instead.
1906 Two-digit year numbers are mapped according to a "window" of 50 years
1908 in both directions (past and future) around the current year.
1909 That is, two-digit year numbers are first mapped to the same century
1911 as the current year. If the resulting year is smaller than the
1912 current year minus 50, then one more century is added to the result.
1913 If the resulting year is equal to or greater than the current year
1914 plus 50, then a century is subtracted from the result.
1915 · "$date = Compress($year,$month,$day);"
1917 WARNING: This function is legacy code, its use is deprecated!
1919 This function encodes a date in 16 bits, which is the value being
1921 returned.
1922 The encoding scheme is as follows:
1924 Bit number: FEDCBA9 8765 43210
1926 Contents: yyyyyyy mmmm ddddd
1927 (Where the "yyyyyyy" contain the number of the year, "mmmm" the
1929 number of the month and "ddddd" the number of the day.)
1930 The function returns "0" if the given input values do not represent a
1932 valid date. Therefore, the return value of this function can also be
1933 used as the conditional expression in an "if" statement, in order to
1934 check whether the given input values constitute a valid date).
1935 Through this special encoding scheme, it is possible to COMPARE
1937 compressed dates for equality and order (less than/greater than)
1938 WITHOUT any previous DECODING!
1939 Note however that contiguous dates do NOT necessarily have contiguous
1941 compressed representations!
1942 I.e., incrementing the compressed representation of a date MAY OR MAY
1944 NOT yield a valid new date!
1945 Note also that this function can only handle dates within one
1947 century.
1948 This century can be chosen at will (at compile time of this module)
1950 by defining a base century and year (also called the "epoch"). In the
1951 original distribution of this package, the base century is set to
1952 "1900" and the base year to "70" (which is standard on UNIX systems).
1953 This allows this function to handle dates from "1970" up to "2069".
1955 If the given year is equal to, say, "95", this package will
1957 automatically assume that you really meant "1995" instead. However,
1958 if you specify a year number which is SMALLER than 70, like "64", for
1959 instance, this package will assume that you really meant "2064".
1960 You are not confined to two-digit (abbreviated) year numbers, though.
1962 The function also accepts "full-length" year numbers, provided that
1964 they lie in the supported range (i.e., from "1970" to "2069", in the
1965 original configuration of this package).
1966 Note that this function is maintained mainly for backward
1968 compatibility, and that its use is not recommended.
1969 · "if (($century,$year,$month,$day) = Uncompress($date))"
1971 WARNING: This function is legacy code, its use is deprecated!
1973 This function decodes dates that were encoded previously using the
1975 function ""Compress()"".
1976 It returns the century, year, month and day of the date encoded in
1978 "$date" if "$date" represents a valid date, or an empty list
1979 otherwise.
1980 The year returned in "$year" is actually a two-digit year number
1982 (i.e., the year number taken modulo 100), and only the expression
1983 ""$century + $year"" yields the "full-length" year number (for
1984 example, "1900 + 95 = 1995").
1985 Note that this function is maintained mainly for backward
1987 compatibility, and that its use is not recommended.
1988 · "if (check_compressed($date))"
1990 WARNING: This function is legacy code, its use is deprecated!
1992 This function returns "true" ("1") if the given input value
1994 constitutes a valid compressed date, and "false" ("0") otherwise.
1995 Note that this function is maintained mainly for backward
1997 compatibility, and that its use is not recommended.
1998 · "$string = Compressed_to_Text($date[,$lang]);"
2000 WARNING: This function is legacy code, its use is deprecated!
2002 This function returns a string of fixed length (always 9 characters
2004 long) containing a textual representation of the compressed date
2005 encoded in "$date".
2006 This string has the form "dd-Mmm-yy", where "dd" is the two-digit
2008 number of the day, "Mmm" are the first three letters of the name of
2009 the month in the given or currently selected language (see further
2010 below for details about the multi-language support of this package),
2011 and "yy" is the two-digit year number (i.e., the year number taken
2012 modulo 100).
2013 If "$date" does not represent a valid date, the string "??-???-??" is
2015 returned instead.
2016 Note that this function is maintained mainly for backward
2018 compatibility, and that its use is not recommended.
2019 · "$string = Date_to_Text($year,$month,$day[,$lang]);"
2021 This function returns a string containing a textual representation of
2023 the given date of the form "www dd-Mmm-yyyy", where "www" are the
2024 first three letters of the name of the day of week in the given or
2025 currently selected language, or a special abbreviation, if special
2026 abbreviations have been defined for the given or currently selected
2027 language (see further below for details about the multi-language
2028 support of this package), "dd" is the day (one or two digits), "Mmm"
2029 are the first three letters of the name of the month in the given or
2030 currently selected language, and "yyyy" is the number of the year in
2031 full length.
2032 If the given input values do not constitute a valid date, a fatal
2034 "not a valid date" error occurs.
2035 (See the section "RECIPES" near the end of this document for a code
2037 snippet for how to print dates in any format you like.)
2038 · "$string = Date_to_Text_Long($year,$month,$day[,$lang]);"
2040 This function returns a string containing a textual representation of
2042 the given date roughly of the form "Wwwwww, dd Mmmmmm yyyy", where
2043 "Wwwwww" is the name of the day of week in the given or currently
2044 selected language (see further below for details about the multi-
2045 language support of this package), "dd" is the day (one or two
2046 digits), "Mmmmmm" is the name of the month in the given or currently
2047 selected language, and "yyyy" is the number of the year in full
2048 length.
2049 The exact format of the output string depends on the given or
2051 currently selected language. In the original distribution of this
2052 package, these formats are defined as follows:
2053 1 English : "Wwwwww, Mmmmmm ddth yyyy"
2055 2 French : "Wwwwww dd mmmmmm yyyy"
2056 3 German : "Wwwwww, den dd. Mmmmmm yyyy"
2057 4 Spanish : "Wwwwww, dd de mmmmmm de yyyy"
2058 5 Portuguese : "Wwwwww, dia dd de mmmmmm de yyyy"
2059 6 Dutch : "Wwwwww, dd mmmmmm yyyy"
2060 7 Italian : "Wwwwww, dd Mmmmmm yyyy"
2061 8 Norwegian : "wwwwww, dd. mmmmmm yyyy"
2062 9 Swedish : "wwwwww, dd mmmmmm yyyy"
2063 10 Danish : "wwwwww, dd. mmmmmm yyyy"
2064 11 Finnish : "wwwwww, dd. mmmmmmta yyyy"
2065 12 Hungarian : "dd. Mmmmmm yyyy., wwwwww"
2066 13 Polish : "Wwwwww, dd Mmmmmm yyyy"
2067 14 Romanian : "Wwwwww dd Mmmmmm yyyy"
2068 (You can change these formats in the file "DateCalc.c" before
2070 building this module in order to suit your personal preferences.)
2071 If the given input values do not constitute a valid date, a fatal
2073 "not a valid date" error occurs.
2074 In order to capitalize the day of week at the beginning of the string
2076 in Norwegian, use
2077 ""ucfirst(Date_to_Text_Long($year,$month,$day,8));"".
2078 (See the section "RECIPES" near the end of this document for an
2080 example on how to print dates in any format you like.)
2081 · "$string = English_Ordinal($number);"
2083 This function returns a string containing the (english) abbreviation
2085 of the ordinal number for the given (cardinal) number "$number".
2086 I.e.,
2088 0 => '0th' 10 => '10th' 20 => '20th'
2090 1 => '1st' 11 => '11th' 21 => '21st'
2091 2 => '2nd' 12 => '12th' 22 => '22nd'
2092 3 => '3rd' 13 => '13th' 23 => '23rd'
2093 4 => '4th' 14 => '14th' 24 => '24th'
2094 5 => '5th' 15 => '15th' 25 => '25th'
2095 6 => '6th' 16 => '16th' 26 => '26th'
2096 7 => '7th' 17 => '17th' 27 => '27th'
2097 8 => '8th' 18 => '18th' 28 => '28th'
2098 9 => '9th' 19 => '19th' 29 => '29th'
2099 etc.
2101 · "$string = Calendar($year,$month[,$orthodox[,$lang]]);"
2103 This function returns a calendar of the given month in the given year
2105 (somewhat similar to the UNIX ""cal"" command), in the given or
2106 currently selected language (see further below for details about the
2107 multi-language support of this package).
2108 Example:
2110 print Calendar(1998,5);
2112 This will print:
2114 May 1998
2116 Mon Tue Wed Thu Fri Sat Sun
2117 1 2 3
2118 4 5 6 7 8 9 10
2119 11 12 13 14 15 16 17
2120 18 19 20 21 22 23 24
2121 25 26 27 28 29 30 31
2122 If the optional boolean parameter "$orthodox" is given and true, the
2124 calendar starts on Sunday instead of Monday.
2125 · "$string = Month_to_Text($month[,$lang]);"
2127 This function returns the name of the given month in the given or
2129 currently selected language (see further below for details about the
2130 multi-language support of this package).
2131 If the given month lies outside of the valid range from "1" to "12",
2133 a fatal "month out of range" error will occur.
2134 · "$string = Day_of_Week_to_Text($dow[,$lang]);"
2136 This function returns the name of the given day of week in the given
2138 or currently selected language (see further below for details about
2139 the multi-language support of this package).
2140 If the given day of week lies outside of the valid range from "1" to
2142 "7", a fatal "day of week out of range" error will occur.
2143 · "$string = Day_of_Week_Abbreviation($dow[,$lang]);"
2145 This function returns the special abbreviation of the name of the
2147 given day of week, IF such special abbreviations have been defined
2148 for the given or currently selected language (see further below for
2149 details about the multi-language support of this package).
2150 (In the original distribution of this package, this was only true for
2152 Portuguese. Starting with version 5.1, abbreviations for Polish have
2153 also been introduced. Starting with version 5.7, the abbreviations
2154 for Portuguese have been disabled. So Polish is currently the only
2155 language to define such special abbreviations.)
2156 If not, the first three letters of the name of the day of week in the
2158 given or currently selected language are returned instead.
2159 If the given day of week lies outside of the valid range from "1" to
2161 "7", a fatal "day of week out of range" error will occur.
2162 Currently, this table of special abbreviations is only used by the
2164 functions ""Date_to_Text()"" and ""Calendar()"", internally.
2165 · "$string = Language_to_Text($lang);"
2167 This function returns the name of any language supported by this
2169 package when the internal number representing that language is given
2170 as input.
2171 The original distribution supports the following fourteen languages:
2173 1 ==> English (default)
2175 2 ==> Français (French)
2176 3 ==> Deutsch (German)
2177 4 ==> Español (Spanish)
2178 5 ==> Português (Portuguese)
2179 6 ==> Nederlands (Dutch)
2180 7 ==> Italiano (Italian)
2181 8 ==> Norsk (Norwegian)
2182 9 ==> Svenska (Swedish)
2183 10 ==> Dansk (Danish)
2184 11 ==> suomi (Finnish)
2185 12 ==> Magyar (Hungarian)
2186 13 ==> polski (Polish)
2187 14 ==> Romaneste (Romanian)
2188 See the section "How to install additional languages" in the file
2190 "INSTALL.txt" in this distribution for how to add more languages to
2191 this package.
2192 See the description of the function ""Languages()"" further below to
2194 determine how many languages are actually available in a given
2195 installation of this package.
2196 · "$lang = Language();"
2198 · "Language($lang); # DEPRECATED"
2200 · "$oldlang = Language($newlang); # DEPRECATED"
2202 This function can be used to determine which language is currently
2204 selected, and to change the selected language (this latter use is
2205 deprecated, because this global setting may cause conflicts between
2206 threads or modules running concurrently).
2207 Thereby, each language has a unique internal number.
2209 The original distribution contains the following fourteen languages:
2211 1 ==> English (default)
2213 2 ==> Français (French)
2214 3 ==> Deutsch (German)
2215 4 ==> Español (Spanish)
2216 5 ==> Português (Portuguese)
2217 6 ==> Nederlands (Dutch)
2218 7 ==> Italiano (Italian)
2219 8 ==> Norsk (Norwegian)
2220 9 ==> Svenska (Swedish)
2221 10 ==> Dansk (Danish)
2222 11 ==> suomi (Finnish)
2223 12 ==> Magyar (Hungarian)
2224 13 ==> polski (Polish)
2225 14 ==> Romaneste (Romanian)
2226 See the section "How to install additional languages" in the file
2228 "INSTALL.txt" in this distribution for how to add more languages to
2229 this package.
2230 See the description of the function ""Languages()"" further below to
2232 determine how many languages are actually available in a given
2233 installation of this package.
2234 BEWARE that in order for your programs to be portable, you should
2236 NEVER actually use the internal number of a language in this package
2237 EXPLICITLY, because the same number could mean different languages on
2238 different systems, depending on what languages have been added to any
2239 given installation of this package.
2240 Therefore, you should always use a statement such as
2242 Language(Decode_Language("Name_of_Language")); # DEPRECATED
2244 or
2246 DateCalc_Function(@parameters,Decode_Language("Name_of_Language")); # RECOMMENDED
2248 to select the desired language, and
2250 $language = Language_to_Text(Language());
2252 or
2254 $old_language = Language_to_Text(Language("Name_of_new_Language")); # DEPRECATED
2256 to determine the (previously) selected language.
2258 If the so chosen language is not available in the current
2260 installation, this will result in an appropriate error message,
2261 instead of silently using the wrong (a random) language (which just
2262 happens to have the same internal number in the other installation).
2263 BEWARE that when using the function ""Language()"", the selected
2265 language is a global setting, shared by all threads or modules you
2266 might be running concurrently, thus possibly causing conflicts
2267 between them.
2268 In order to avoid these conflicts, you should NEVER use the function
2270 ""Language()"", but should ALWAYS pass a language number (as returned
2271 by the function ""Decode_Language()"") to the functions which are
2272 language-dependent, which are:
2273 "Decode_Month()", "Decode_Day_of_Week()", "Compressed_to_Text()",
2275 "Date_to_Text()", "Date_to_Text_Long()", "Calendar()",
2276 "Month_to_Text()", "Day_of_Week_to_Text()",
2277 "Day_of_Week_Abbreviation()", "Decode_Date_EU()", "Decode_Date_US()",
2278 "Decode_Date_EU2()", "Decode_Date_US2()", "Parse_Date()".
2279 Note that when you pass an invalid number, such as e.g. zero, or no
2281 language parameter at all, these functions will revert to their
2282 behaviour in the versions of this module prior to 6.0, which means
2283 that the global setting (as set by ""Language()"") becomes active
2284 again (only in case of an invalid or missing language parameter!).
2285 In the C library "DateCalc.c", where omitting a parameter is not an
2287 option, passing a zero for the language is therefore the recommended
2288 way to guarantee backward compatibility.
2289 · "$max_lang = Languages();"
2291 This function returns the (maximum) number of languages which are
2293 currently available in your installation of this package.
2294 (This may vary from installation to installation.)
2296 See the section "How to install additional languages" in the file
2298 "INSTALL.txt" in this distribution for how to add more languages to
2299 this package.
2300 In the original distribution of this package there are fourteen
2302 built-in languages, therefore the value returned by this function
2303 will be "14" if no other languages have been added to your particular
2304 installation.
2305 · "if (($year,$month,$day) = Decode_Date_EU2($string[,$lang))"
2307 This function is the Perl equivalent of the function
2309 ""Decode_Date_EU()"" (implemented in C), included here merely as an
2310 example to demonstrate how easy it is to write your own routine in
2311 Perl (using regular expressions) adapted to your own special needs,
2312 should the necessity arise, and intended primarily as a basis for
2313 your own development.
2314 In one particular case this Perl version is actually slightly more
2316 permissive than its C equivalent, as far as the class of permitted
2317 intervening (i.e., delimiting) characters is concerned.
2318 (Can you tell the subtle, almost insignificant difference by looking
2320 at the code? Or by experimenting? Hint: Try the string "a3b1c64d"
2321 with both functions.)
2322 · "if (($year,$month,$day) = Decode_Date_US2($string[,$lang))"
2324 This function is the Perl equivalent of the function
2326 ""Decode_Date_US()"" (implemented in C), included here merely as an
2327 example to demonstrate how easy it is to write your own routine in
2328 Perl (using regular expressions) adapted to your own special needs,
2329 should the necessity arise, and intended primarily as a basis for
2330 your own development.
2331 In one particular case this Perl version is actually slightly more
2333 permissive than its C equivalent.
2334 (Hint: This is the same difference as with the ""Decode_Date_EU()""
2336 and ""Decode_Date_EU2()"" pair of functions.)
2337 In a different case, the C version is a little bit more permissive
2339 than its Perl equivalent.
2340 (Can you tell the difference by looking at the code? Or by
2342 experimenting? Hint: Try the string "(1/364)" with both functions.)
2343 · "if (($year,$month,$day) = Parse_Date($string[,$lang))"
2345 This function is useful for parsing dates as returned by the UNIX
2347 ""date"" command or as found in the headers of e-mail (in order to
2348 determine the date at which some e-mail has been sent or received,
2349 for instance).
2350 Example #1:
2352 ($year,$month,$day) = Parse_Date(`/bin/date`);
2354 Example #2:
2356 while (<MAIL>)
2358 {
2359 if (/^From \S/)
2360 {
2361 ($year,$month,$day) = Parse_Date($_);
2362 ...
2363 }
2364 ...
2365 }
2366 The function returns an empty list if it can't extract a valid date
2368 from the input string.
2369 · "$lower = ISO_LC($string);"
2371 Returns a copy of the given string where all letters of the
2373 ISO-Latin-1 character set have been replaced by their lower case
2374 equivalents.
2375 Similar to Perl's built-in function ""lc()"" (see "lc" in
2377 perlfunc(1)) but for the whole ISO-Latin-1 character set, not just
2378 plain ASCII.
2379 · "$upper = ISO_UC($string);"
2381 Returns a copy of the given string where all letters of the
2383 ISO-Latin-1 character set have been replaced by their upper case
2384 equivalents.
2385 Similar to Perl's built-in function ""uc()"" (see "uc" in
2387 perlfunc(1)) but for the whole ISO-Latin-1 character set, not just
2388 plain ASCII.
2389 · "$string = Date::Calc::Version();"
2391 This function returns a string with the (numeric) version number of
2393 the CÂ library ("DateCalc.c") at the core of this package (which is
2394 also (automatically) the version number of the "Calc.xs" file).
2395 Note that under all normal circumstances, this version number should
2397 be identical with the one found in the Perl variable
2398 "$Date::Calc::VERSION" (the version number of the "Calc.pm" file).
2399 Since this function is not exported, you always have to qualify it
2401 explicitly, i.e., ""Date::Calc::Version()"".
2402 This is to avoid possible name space conflicts with version functions
2404 from other modules.
2405
2407 1) How do I compare two dates?
2408 Solution #1:
2410 use Date::Calc qw( Date_to_Days );
2412 if (Date_to_Days($year1,$month1,$day1) <
2414 Date_to_Days($year2,$month2,$day2))
2415 if (Date_to_Days($year1,$month1,$day1) <=
2417 Date_to_Days($year2,$month2,$day2))
2418 if (Date_to_Days($year1,$month1,$day1) >
2420 Date_to_Days($year2,$month2,$day2))
2421 if (Date_to_Days($year1,$month1,$day1) >=
2423 Date_to_Days($year2,$month2,$day2))
2424 if (Date_to_Days($year1,$month1,$day1) ==
2426 Date_to_Days($year2,$month2,$day2))
2427 if (Date_to_Days($year1,$month1,$day1) !=
2429 Date_to_Days($year2,$month2,$day2))
2430 $cmp = (Date_to_Days($year1,$month1,$day1) <=>
2432 Date_to_Days($year2,$month2,$day2));
2433 Solution #2:
2435 use Date::Calc qw( Delta_Days );
2437 if (Delta_Days($year1,$month1,$day1,
2439 $year2,$month2,$day2) > 0)
2440 if (Delta_Days($year1,$month1,$day1,
2442 $year2,$month2,$day2) >= 0)
2443 if (Delta_Days($year1,$month1,$day1,
2445 $year2,$month2,$day2) < 0)
2446 if (Delta_Days($year1,$month1,$day1,
2448 $year2,$month2,$day2) <= 0)
2449 if (Delta_Days($year1,$month1,$day1,
2451 $year2,$month2,$day2) == 0)
2452 if (Delta_Days($year1,$month1,$day1,
2454 $year2,$month2,$day2) != 0)
2455 2) How do I check whether a given date lies within a certain range of
2457 dates?
2458 use Date::Calc qw( Date_to_Days );
2460 $lower = Date_to_Days($year1,$month1,$day1);
2462 $upper = Date_to_Days($year2,$month2,$day2);
2463 $date = Date_to_Days($year,$month,$day);
2465 if (($date >= $lower) && ($date <= $upper))
2467 {
2468 # ok
2469 }
2470 else
2471 {
2472 # not ok
2473 }
2474 3) How do I compare two dates with times? How do I check whether two
2476 dates and times lie more or less than a given time interval apart?
2477 Solution #1:
2479 use Date::Calc qw( Add_Delta_DHMS Date_to_Days );
2481 @date1 = (2002,8,31,23,59,1);
2483 @date2 = (2002,9,1,11,30,59); # ==> less than 12 hours
2484 #@date1 = (2002,8,31,22,59,1);
2486 #@date2 = (2002,9,1,11,30,59); # ==> more than 12 hours
2487 # Omit the next line if you just want to compare the two dates
2489 # (and change @date3 and @d3 to @date1 and @d1, respectively):
2490 @date3 = Add_Delta_DHMS(@date1, 0,12,0,0); # ==> is the difference within 12 hours?
2492 @d2 = ( Date_to_Days(@date2[0..2]), ($date2[3]*60+$date2[4])*60+$date2[5] );
2494 @d3 = ( Date_to_Days(@date3[0..2]), ($date3[3]*60+$date3[4])*60+$date3[5] );
2495 @diff = ( $d2[0]-$d3[0], $d2[1]-$d3[1] );
2497 if ($diff[0] > 0 and $diff[1] < 0) { $diff[0]--; $diff[1] += 86400; }
2499 if ($diff[0] < 0 and $diff[1] > 0) { $diff[0]++; $diff[1] -= 86400; }
2500 if (($diff[0] || $diff[1]) >= 0) { print "More than 12 hours.\n"; }
2502 else { print "Less than 12 hours.\n"; }
2503 Solution #2:
2505 This solution is only feasible if your dates are guaranteed to lie
2507 within the range given by your system's epoch and overflow date and
2508 time!
2509 Unix: 1-Jan-1970 00:00:00 to 19-Jan-2038 03:14:07
2511 MacOS: 1-Jan-1904 00:00:00 to 6-Feb-2040 06:28:15
2512 use Date::Calc qw( Date_to_Time );
2514 @date1 = (2002,8,31,23,59,1);
2516 @date2 = (2002,9,1,11,30,59); # ==> less than 12 hours
2517 #@date1 = (2002,8,31,22,59,1);
2519 #@date2 = (2002,9,1,11,30,59); # ==> more than 12 hours
2520 $d1 = Date_to_Time(@date1);
2522 $d2 = Date_to_Time(@date2);
2523 if ($d1 <= $d2) { print "The two dates are in chronological order.\n"; }
2525 else { print "The two dates are in reversed order.\n"; }
2526 if ($d1 + 12*60*60 <= $d2) { print "More than 12 hours.\n"; }
2528 else { print "Less than 12 hours.\n"; }
2529 4) How do I verify whether someone has a certain age?
2531 use Date::Calc qw( Decode_Date_EU Today leap_year Delta_Days );
2533 $date = <STDIN>; # get birthday
2535 ($year1,$month1,$day1) = Decode_Date_EU($date);
2537 ($year2,$month2,$day2) = Today();
2539 if (($day1 == 29) && ($month1 == 2) && !leap_year($year2))
2541 { $day1--; }
2542 if ( (($year2 - $year1) > 18) ||
2544 ( (($year2 - $year1) == 18) &&
2545 (Delta_Days($year2,$month1,$day1, $year2,$month2,$day2) >= 0) ) )
2546 {
2547 print "Ok - you are over 18.\n";
2548 }
2549 else
2550 {
2551 print "Sorry - you aren't 18 yet!\n";
2552 }
2553 Or, alternatively (substituting the last "if" statement above):
2555 if (($year1+18 <=> $year2 || $month1 <=> $month2 || $day1 <=> $day2) <= 0)
2557 { print "Ok - you are over 18.\n"; }
2558 else
2559 { print "Sorry - you aren't 18 yet!\n"; }
2560 5) How do I calculate the number of the week of month the current date
2562 lies in?
2563 For example:
2565 April 1998
2567 Mon Tue Wed Thu Fri Sat Sun
2568 1 2 3 4 5 = week #1
2569 6 7 8 9 10 11 12 = week #2
2570 13 14 15 16 17 18 19 = week #3
2571 20 21 22 23 24 25 26 = week #4
2572 27 28 29 30 = week #5
2573 Solution:
2575 use Date::Calc qw( Today Day_of_Week );
2577 ($year,$month,$day) = Today();
2579 $week = int(($day + Day_of_Week($year,$month,1) - 2) / 7) + 1;
2581 6) How do I calculate whether a given date is the 1st, 2nd, 3rd, 4th
2583 or 5th of that day of week in the given month?
2584 For example:
2586 October 2000
2588 Mon Tue Wed Thu Fri Sat Sun
2589 1
2590 2 3 4 5 6 7 8
2591 9 10 11 12 13 14 15
2592 16 17 18 19 20 21 22
2593 23 24 25 26 27 28 29
2594 30 31
2595 Is Sunday, the 15th of October 2000, the 1st, 2nd, 3rd, 4th or 5th
2597 Sunday of that month?
2598 Solution:
2600 use Date::Calc qw( Day_of_Week Delta_Days
2602 Nth_Weekday_of_Month_Year
2603 Date_to_Text_Long English_Ordinal
2604 Day_of_Week_to_Text Month_to_Text );
2605 ($year,$month,$day) = (2000,10,15);
2607 $dow = Day_of_Week($year,$month,$day);
2609 $n = int( Delta_Days(
2611 Nth_Weekday_of_Month_Year($year,$month,$dow,1),
2612 $year,$month,$day)
2613 / 7) + 1;
2614 printf("%s is the %s %s in %s %d.\n",
2616 Date_to_Text_Long($year,$month,$day),
2617 English_Ordinal($n),
2618 Day_of_Week_to_Text($dow),
2619 Month_to_Text($month),
2620 $year);
2621 This prints:
2623 Sunday, October 15th 2000 is the 3rd Sunday in October 2000.
2625 7) How do I calculate the date of the Wednesday of the same week as
2627 the current date?
2628 Solution #1:
2630 use Date::Calc qw( Today Day_of_Week Add_Delta_Days );
2632 $searching_dow = 3; # 3 = Wednesday
2634 @today = Today();
2636 $current_dow = Day_of_Week(@today);
2638 @date = Add_Delta_Days(@today, $searching_dow - $current_dow);
2640 Solution #2:
2642 use Date::Calc qw( Today Add_Delta_Days
2644 Monday_of_Week Week_of_Year );
2645 $searching_dow = 3; # 3 = Wednesday
2647 @today = Today();
2649 @date = Add_Delta_Days( Monday_of_Week( Week_of_Year(@today) ),
2651 $searching_dow - 1 );
2652 Solution #3:
2654 use Date::Calc qw( Standard_to_Business Today
2656 Business_to_Standard );
2657 @business = Standard_to_Business(Today());
2659 $business[2] = 3; # 3 = Wednesday
2661 @date = Business_to_Standard(@business);
2663 8) How can I add a week offset to a business date (including across
2665 year boundaries)?
2666 use Date::Calc qw( Business_to_Standard Add_Delta_Days
2668 Standard_to_Business );
2669 @temp = Business_to_Standard($year,$week,$dow);
2671 @temp = Add_Delta_Days(@temp, $week_offset * 7);
2673 ($year,$week,$dow) = Standard_to_Business(@temp);
2675 9) How do I calculate the last and the next Saturday for any given
2677 date?
2678 use Date::Calc qw( Today Day_of_Week Add_Delta_Days
2680 Day_of_Week_to_Text Date_to_Text );
2681 $searching_dow = 6; # 6 = Saturday
2683 @today = Today();
2685 $current_dow = Day_of_Week(@today);
2687 if ($searching_dow == $current_dow)
2689 {
2690 @prev = Add_Delta_Days(@today,-7);
2691 @next = Add_Delta_Days(@today,+7);
2692 }
2693 else
2694 {
2695 if ($searching_dow > $current_dow)
2696 {
2697 @next = Add_Delta_Days(@today,
2698 $searching_dow - $current_dow);
2699 @prev = Add_Delta_Days(@next,-7);
2700 }
2701 else
2702 {
2703 @prev = Add_Delta_Days(@today,
2704 $searching_dow - $current_dow);
2705 @next = Add_Delta_Days(@prev,+7);
2706 }
2707 }
2708 $dow = Day_of_Week_to_Text($searching_dow);
2710 print "Today is: ", ' ' x length($dow),
2712 Date_to_Text(@today), "\n";
2713 print "Last $dow was: ", Date_to_Text(@prev), "\n";
2714 print "Next $dow will be: ", Date_to_Text(@next), "\n";
2715 This will print something like:
2717 Today is: Sun 12-Apr-1998
2719 Last Saturday was: Sat 11-Apr-1998
2720 Next Saturday will be: Sat 18-Apr-1998
2721 10) How can I calculate the last business day (payday!) of a month?
2723 Solution #1 (holidays NOT taken into account):
2725 use Date::Calc qw( Days_in_Month Day_of_Week Add_Delta_Days );
2727 $day = Days_in_Month($year,$month);
2729 $dow = Day_of_Week($year,$month,$day);
2730 if ($dow > 5)
2731 {
2732 ($year,$month,$day) =
2733 Add_Delta_Days($year,$month,$day, 5-$dow);
2734 }
2735 Solution #2 (holidays taken into account):
2737 This solution expects a multi-dimensional array "@holiday", which
2739 contains all holidays, as follows: ""$holiday[$year][$month][$day]
2740 = 1;"".
2741 (See the description of the function ""Easter_Sunday()"" further
2743 above for how to calculate the moving (variable) christian feast
2744 days!)
2745 Days which are not holidays remain undefined or should have a value
2747 of zero in this array.
2748 use Date::Calc qw( Days_in_Month Add_Delta_Days Day_of_Week );
2750 $day = Days_in_Month($year,$month);
2752 while (1)
2753 {
2754 while ($holiday[$year][$month][$day])
2755 {
2756 ($year,$month,$day) =
2757 Add_Delta_Days($year,$month,$day, -1);
2758 }
2759 $dow = Day_of_Week($year,$month,$day);
2760 if ($dow > 5)
2761 {
2762 ($year,$month,$day) =
2763 Add_Delta_Days($year,$month,$day, 5-$dow);
2764 }
2765 else { last; }
2766 }
2767 Solution #3 (holidays taken into account, more comfortable, but
2769 requires Date::Calendar(3) and Date::Calc::Object(3)):
2770 use Date::Calc::Object qw( Today Add_Delta_YM Date_to_Text_Long );
2772 use Date::Calendar::Profiles qw($Profiles);
2773 use Date::Calendar;
2774 $calendar = Date::Calendar->new( $Profiles->{'DE-BW'} );
2776 @today = Today();
2778 @nextmonth = Add_Delta_YM(@today[0,1],1, 0,1);
2779 $workaround = $calendar->add_delta_workdays(@nextmonth,+1);
2781 $payday = $calendar->add_delta_workdays($workaround,-2);
2782 print "Pay day = ", Date_to_Text_Long($payday->date()), "\n";
2784 The "workaround" is necessary due to a bug in the method
2786 "add_delta_workdays()" when adding a negative number of workdays.
2787 11) How do I convert a MS Visual Basic "DATETIME" value into its date
2789 and time constituents?
2790 use Date::Calc qw( Add_Delta_DHMS Date_to_Text );
2792 $datetime = "35883.121653";
2794 ($Dd,$Dh,$Dm,$Ds) = ($datetime =~ /^(\d+)\.(\d\d)(\d\d)(\d\d)$/);
2796 ($year,$month,$day, $hour,$min,$sec) =
2798 Add_Delta_DHMS(1900,1,1, 0,0,0, $Dd,$Dh,$Dm,$Ds);
2799 printf("The given date is %s %02d:%02d:%02d\n",
2801 Date_to_Text($year,$month,$day), $hour, $min, $sec);
2802 This prints:
2804 The given date is Tue 31-Mar-1998 12:16:53
2806 Since I do not have or use Visual Basic, I can't guarantee that the
2808 number format assumed here is really the one used by Visual Basic -
2809 but you get the general idea. ":-)"
2810 Moreover, consider the following:
2812 Morten Sickel <Morten.Sickel@nrpa.no> wrote:
2814 I discovered a bug in Excel (2000): Excel thinks that 1900 was a
2816 leap year. Users should use 31-Dec-1899 as the date to add an Excel
2817 date value to in order to get the correct date.
2818 I found out on the web that this bug originated in Lotus 123, which
2820 made 29-Feb-1900 an "industrial standard". MS chose to keep the bug
2821 in order to be compatible with Lotus 123. But they have not
2822 mentioned anything about it in the help files.
2823 12) How can I send a reminder to members of a group on the day before a
2825 meeting which occurs every first Friday of a month?
2826 use Date::Calc qw( Today Date_to_Days Add_Delta_YMD
2828 Nth_Weekday_of_Month_Year );
2829 ($year,$month,$day) = Today();
2831 $tomorrow = Date_to_Days($year,$month,$day) + 1;
2833 $dow = 5; # 5 = Friday
2835 $n = 1; # 1 = First of that day of week
2836 $meeting_this_month = Date_to_Days(
2838 Nth_Weekday_of_Month_Year($year,$month,$dow,$n) );
2839 ($year,$month,$day) = Add_Delta_YMD($year,$month,$day, 0,1,0);
2841 $meeting_next_month = Date_to_Days(
2843 Nth_Weekday_of_Month_Year($year,$month,$dow,$n) );
2844 if (($tomorrow == $meeting_this_month) ||
2846 ($tomorrow == $meeting_next_month))
2847 {
2848 # Send reminder e-mail!
2849 }
2850 13) How can I print a date in a different format than provided by the
2852 functions ""Date_to_Text()"", ""Date_to_Text_Long()"" or
2853 ""Compressed_to_Text()""?
2854 use Date::Calc qw( Today Day_of_Week_to_Text
2856 Day_of_Week Month_to_Text
2857 English_Ordinal );
2858 ($year,$month,$day) = Today();
2860 For example with leading zeros for the day: "Fri 03-Jan-1964"
2862 printf("%.3s %02d-%.3s-%d\n",
2864 Day_of_Week_to_Text(Day_of_Week($year,$month,$day)),
2865 $day,
2866 Month_to_Text($month),
2867 $year);
2868 For example in U.S. american format: "April 12th, 1998"
2870 $string = sprintf("%s %s, %d",
2872 Month_to_Text($month),
2873 English_Ordinal($day),
2874 $year);
2875 For example in one of the possible formats as specified by
2877 ISOÂ 8601:
2878 @date = ($year,$month,$day,$hour,$min,$sec);
2880 $date = sprintf("%d-%02d-%02d %02d:%02d:%02d", @date);
2881 (See also "printf" in perlfunc(1) and/or "sprintf" in perlfunc(1)!)
2883 14) How can I iterate through a range of dates?
2885 use Date::Calc qw( Delta_Days Add_Delta_Days );
2887 @start = (1999,5,27);
2889 @stop = (1999,6,1);
2890 $j = Delta_Days(@start,@stop);
2892 for ( $i = 0; $i <= $j; $i++ )
2894 {
2895 @date = Add_Delta_Days(@start,$i);
2896 printf("%4d/%02d/%02d\n", @date);
2897 }
2898 Note that the loop can be improved; see also the recipe below.
2900 15) How can I create a (Perl) list of dates in a certain range?
2902 use Date::Calc qw( Delta_Days Add_Delta_Days Date_to_Text );
2904 sub date_range
2906 {
2907 my(@date) = (@_)[0,1,2];
2908 my(@list);
2909 my($i);
2910 $i = Delta_Days(@_);
2912 while ($i-- >= 0)
2913 {
2914 push( @list, [ @date ] );
2915 @date = Add_Delta_Days(@date, 1) if ($i >= 0);
2916 }
2917 return(@list);
2918 }
2919 @range = &date_range(1999,11,3, 1999,12,24); # in chronological order
2921 foreach $date (@range)
2923 {
2924 print Date_to_Text(@{$date}), "\n";
2925 }
2926 Note that you probably shouldn't use this one, because it is much
2928 more efficient to iterate through all the dates (as shown in the
2929 recipe immediately above) than to construct such an array and then
2930 to loop through it. Also, it is much more space-efficient not to
2931 create this array.
2932 16) How can I calculate the difference in days between dates, but
2934 without counting Saturdays and Sundays?
2935 sub Delta_Business_Days
2937 {
2938 my(@date1) = (@_)[0,1,2];
2939 my(@date2) = (@_)[3,4,5];
2940 my($minus,$result,$dow1,$dow2,$diff,$temp);
2941 $minus = 0;
2943 $result = Delta_Days(@date1,@date2);
2944 if ($result != 0)
2945 {
2946 if ($result < 0)
2947 {
2948 $minus = 1;
2949 $result = -$result;
2950 $dow1 = Day_of_Week(@date2);
2951 $dow2 = Day_of_Week(@date1);
2952 }
2953 else
2954 {
2955 $dow1 = Day_of_Week(@date1);
2956 $dow2 = Day_of_Week(@date2);
2957 }
2958 $diff = $dow2 - $dow1;
2959 $temp = $result;
2960 if ($diff != 0)
2961 {
2962 if ($diff < 0)
2963 {
2964 $diff += 7;
2965 }
2966 $temp -= $diff;
2967 $dow1 += $diff;
2968 if ($dow1 > 6)
2969 {
2970 $result--;
2971 if ($dow1 > 7)
2972 {
2973 $result--;
2974 }
2975 }
2976 }
2977 if ($temp != 0)
2978 {
2979 $temp /= 7;
2980 $result -= ($temp << 1);
2981 }
2982 }
2983 if ($minus) { return -$result; }
2984 else { return $result; }
2985 }
2986 This solution is probably of little practical value, however,
2988 because it doesn't take legal holidays into account.
2989 See Date::Calendar(3) for how to do that.
2991 17) How can I "normalize" the output of the "Delta_YMDHMS()" (or
2993 "Delta_YMD()") function so that it contains only positive values?
2994 I.e., how can I show a difference in date (and time) in a more
2996 human-readable form, for example in order to show how much time
2997 until (or since) the expiration of something (e.g. an account, a
2998 domain, a credit card, etc.) is left (has passed)?
2999 Correct solution: Use the functions "N_Delta_YMDHMS()" and
3001 "N_Delta_YMD()" instead!
3002 The following gives a rudimentary sketch of a (much inferior)
3004 solution, which is maintained here only for historical reasons of
3005 this module:
3006 a) Delta_YMDHMS():
3008 #!perl
3010 use strict;
3011 use Date::Calc qw(Today_and_Now Delta_YMDHMS Add_Delta_YMDHMS Delta_DHMS Date_to_Text);
3012 my $today = [Today_and_Now()];
3014 my $target = [2005,1,1,0,0,0];
3015 my $sign = "until";
3017 my $delta = Normalize_Delta_YMDHMS($today,$target);
3018 if ($delta->[0] < 0)
3019 {
3020 $sign = "since";
3021 $delta = Normalize_Delta_YMDHMS($target,$today);
3022 }
3023 printf("Today is %s %02d:%02d:%02d\n", Date_to_Text(@{$today}[0..2]), @{$today}[3..5]);
3024 printf
3025 (
3026 "%d year%s, %d month%s, %d day%s, %d hour%s, %d minute%s, %d second%s %s %s %02d:%02d:%02d\n",
3027 $delta->[0], (($delta->[0]==1)?'':'s'),
3028 $delta->[1], (($delta->[1]==1)?'':'s'),
3029 $delta->[2], (($delta->[2]==1)?'':'s'),
3030 $delta->[3], (($delta->[3]==1)?'':'s'),
3031 $delta->[4], (($delta->[4]==1)?'':'s'),
3032 $delta->[5], (($delta->[5]==1)?'':'s'),
3033 $sign,
3034 Date_to_Text(@{$target}[0..2]),
3035 @{$target}[3..5]
3036 );
3037 sub Normalize_Delta_YMDHMS
3039 {
3040 my($date1,$date2) = @_;
3041 my(@delta);
3042 @delta = Delta_YMDHMS(@$date1,@$date2);
3044 while ($delta[1] < 0 or
3045 $delta[2] < 0 or
3046 $delta[3] < 0 or
3047 $delta[4] < 0 or
3048 $delta[5] < 0)
3049 {
3050 if ($delta[1] < 0) { $delta[0]--; $delta[1] += 12; }
3051 if ($delta[2] < 0)
3052 {
3053 $delta[1]--;
3054 @delta[2..5] = (0,0,0,0);
3055 @delta[2..5] = Delta_DHMS(Add_Delta_YMDHMS(@$date1,@delta),@$date2);
3056 }
3057 if ($delta[3] < 0) { $delta[2]--; $delta[3] += 24; }
3058 if ($delta[4] < 0) { $delta[3]--; $delta[4] += 60; }
3059 if ($delta[5] < 0) { $delta[4]--; $delta[5] += 60; }
3060 }
3061 return \@delta;
3062 }
3063 b) Delta_YMD():
3065 #!perl
3067 use strict;
3068 use Date::Calc qw(Today Delta_YMD Add_Delta_YM Delta_Days Date_to_Text);
3069 my($sign,$delta);
3071 my $today = [Today()];
3072 my $target = [2005,1,1];
3073 if (Delta_Days(@$today,@$target) < 0)
3075 {
3076 $sign = "since";
3077 $delta = Normalize_Delta_YMD($target,$today);
3078 }
3079 else
3080 {
3081 $sign = "until";
3082 $delta = Normalize_Delta_YMD($today,$target);
3083 }
3084 print "Today is ", Date_to_Text(@$today), "\n";
3085 printf
3086 (
3087 "%d year%s, %d month%s, %d day%s %s %s\n",
3088 $delta->[0], (($delta->[0]==1)?'':'s'),
3089 $delta->[1], (($delta->[1]==1)?'':'s'),
3090 $delta->[2], (($delta->[2]==1)?'':'s'),
3091 $sign,
3092 Date_to_Text(@$target)
3093 );
3094 sub Normalize_Delta_YMD
3096 {
3097 my($date1,$date2) = @_;
3098 my(@delta);
3099 @delta = Delta_YMD(@$date1,@$date2);
3101 while ($delta[1] < 0 or $delta[2] < 0)
3102 {
3103 if ($delta[1] < 0) { $delta[0]--; $delta[1] += 12; }
3104 if ($delta[2] < 0)
3105 {
3106 $delta[1]--;
3107 $delta[2] = Delta_Days(Add_Delta_YM(@$date1,@delta[0,1]),@$date2);
3108 }
3109 }
3110 return \@delta;
3111 }
3112 Note that for normalizing just a time vector, you can use the
3114 built-in function "Normalize_DHMS()". However, this will yield
3115 either all positive OR all negative values, NOT all positive values
3116 as above.
3117
3119 Date::Calc::Util(3), Date::Calc::Object(3), Date::Calendar(3),
3120 Date::Calendar::Year(3), Date::Calendar::Profiles(3).
3121 "The Calendar FAQ":
3123 http://www.tondering.dk/claus/calendar.html
3124 by Claus Tondering <claus@tondering.dk>
3125
3127 When you are using the (deprecated) function "Language()", the language
3128 setting is stored in a global variable.
3129 This may cause conflicts between threads or modules running
3131 concurrently.
3132 Therefore, in order to avoid such conflicts, NEVER use the function
3134 "Language()", but ALWAYS pass a language parameter to the functions
3135 which are language-dependent.
3136
3138 This man page documents "Date::Calc" version 6.4.
3139
3141 Steffen Beyer
3142 mailto:STBEY@cpan.org
3143 http://www.engelschall.com/u/sb/download/
3144
3146 Copyright (c) 1995 - 2015 by Steffen Beyer. All rights reserved.
3147
3149 This package is free software; you can use, modify and redistribute it
3150 under the same terms as Perl itself, i.e., at your option, under the
3151 terms either of the "Artistic License" or the "GNU General Public
3152 License".
3153 The C library at the core of the module "Date::Calc::XS" can, at your
3155 discretion, also be used, modified and redistributed under the terms of
3156 the "GNU Library General Public License".
3157 Please refer to the files "Artistic.txt", "GNU_GPL.txt" and
3159 "GNU_LGPL.txt" in the "license" subdirectory of this distribution for
3160 any details!
3161
3163 This package is distributed in the hope that it will be useful, but
3164 WITHOUT ANY WARRANTY; without even the implied warranty of
3165 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
3166 See the "GNU General Public License" for more details.
3168
3170 Hey! The above document had some coding errors, which are explained
3171 below:
3172 Around line 1761:
3174 Non-ASCII character seen before =encoding in 'Français'. Assuming
3175 CP1252
3176perl v5.32.0 2020-07-28 Date::Calc(3)