1Date::Calendar(3) User Contributed Perl Documentation Date::Calendar(3)
2
6 Date::Calendar - Calendar objects for different holiday schemes
7
9 There is more than one way to do it - this is just one of them!
10
12 Basically, Date::Calendar is just a caching proxy class for
13 Date::Calendar::Year objects, which are embedded in each Date::Calendar
14 object.
15 However, and in contrast to Date::Calendar::Year methods,
17 Date::Calendar methods permit calculations spanning an arbitrary number
18 of years, without loss of efficiency.
19 So you should usually use Date::Calendar and not Date::Calendar::Year,
21 since that way you don't have to worry about calculations crossing year
22 boundaries.
23 Note however that Date::Calendar and Date::Calendar::Year can only deal
25 with years lying within the range [1583..2299].
26
28 use Date::Calendar::Profiles qw( $Profiles );
29 use Date::Calendar;
30 $calendar_US_AZ = Date::Calendar->new( $Profiles->{'US-AZ'} [,LANG[,WEEKEND]] );
32 $calendar_DE_SN = Date::Calendar->new( $Profiles->{'DE-SN'} [,LANG[,WEEKEND]] );
33 $year_2000_US_AZ = $calendar_US_AZ->year( 2000 );
35 $year_2001_DE_SN = $calendar_DE_SN->year( 2001 );
36 @years = $calendar->cache_keys(); # returns list of year numbers
38 @years = $calendar->cache_vals(); # returns list of year objects
39 $calendar->cache_clr();
41 $calendar->cache_add(YEAR|DATE,...);
42 $calendar->cache_del(YEAR|DATE,...);
43 $index = $calendar->date2index(YEAR,MONTH,DAY|DATE);
45 @names = $calendar->labels(YEAR,MONTH,DAY|DATE);
47 @holidays = $calendar->labels();
48 $holidays = $calendar->labels();
49 @dates = $calendar->search(PATTERN);
51 $dates = $calendar->search(PATTERN);
52 $hashref = $calendar->tags(YEAR,MONTH,DAY|DATE);
54 $days = $calendar->delta_workdays(YEAR1,MONTH1,DAY1|DATE1
56 ,YEAR2,MONTH2,DAY2|DATE2
57 ,FLAG1,FLAG2);
58 ($date,$rest) = $calendar->add_delta_workdays(YEAR,MONTH,DAY|DATE
60 ,DELTA);
61 $date = $calendar->add_delta_workdays(YEAR,MONTH,DAY|DATE
62 ,DELTA);
63 $flag = $calendar->is_full(YEAR,MONTH,DAY|DATE);
65 $flag = $calendar->is_half(YEAR,MONTH,DAY|DATE);
66 $flag = $calendar->is_work(YEAR,MONTH,DAY|DATE);
67
69 Note that whenever a year number, a date, a time or a combined date and
70 time are expected as input parameters by one of the methods of this
71 class, you can always pass a Date::Calc[::Object] date object or an
72 array reference (of an array of appropriate length) instead!
73 See Date::Calc::Object(3) for more details.
75 So instead of calling a given method like this:
77 $object->method1( $year,$month,$day );
79 $object->method2( $year1,$month1,$day1, $year2,$month2,$day2 );
80 $object->method3( $year1, $year2, $year3 );
81 You can also call it like so:
83 $object->method1( $date );
85 $object->method1( [1964,1,3] );
86 $object->method2( $year1,$month1,$day1, $date2 );
88 $object->method2( $date1, $year2,$month2,$day2 );
89 $object->method2( $date1, $date2 );
90 $object->method2( $year1,$month1,$day1, [2001,3,17] );
91 $object->method2( [1964,1,3], $year2,$month2,$day2 );
92 $object->method2( [1964,1,3], [2001,3,17] );
93 $object->method2( $date1, [2001,3,17] );
94 $object->method2( [1964,1,3], $date2 );
95 $object->method3( $year1, $date2, [2001,3,17] );
97 And similarly if a time or a combined date and time are expected.
99 If you substitute an expected year number by an anonymous array (this
101 is the recommended way of writing date constants, for increased
102 readability of your programs), it must contain three values,
103 nevertheless (otherwise the use of an anonymous array would be
104 pointless).
105 Don't confuse year numbers and their substitutes (a date object or an
107 array reference) with Date::Calendar::Year objects, which are a totally
108 different thing!
109 But incidentally ":-)", you may also pass a Date::Calendar::Year object
111 whenever a year number is expected. However, and perhaps against your
112 expectations at times, especially in conjunction with the method
113 "cache_add()", only the year number from that object will be used, not
114 the year object itself (the year object in question might be using the
115 wrong profile!).
116 Moreover, whenever a method of this class returns a date, it does so by
118 returning a Date::Calc[::Object] date object.
119
121 • "$calendar = Date::Calendar->new(PROFILE[,LANG[,WEEKEND]]);"
122 The first argument must be the reference of a hash, which contains a
124 holiday scheme or "profile" to be used in all calculations involving
125 the new calendar object.
126 The second argument is optional, and must consist of the valid name
128 or number of a language as provided by the Date::Calc(3) module if
129 given.
130 After the second argument, a list of day numbers which will
132 constitute the "weekend" can optionally be specified, where 1=Monday,
133 2=Tuesday, 3=Wednesday, 4=Thursday, 5=Friday, 6=Saturday and
134 7=Sunday.
135 If no values are given, 6 and 7 (Saturday and Sunday) are
137 automatically taken as default.
138 If values outside of the range 1..7 are given, they will be ignored.
140 This can be used to switch off this feature and to have no regularly
142 recurring holidays at all when for instance a zero is given.
143 See Date::Calendar::Profiles(3) and Date::Calendar::Year(3) for more
145 details about these arguments and about how to roll your own calendar
146 profiles.
147 The method creates a new calendar object for a given profile, i.e., a
149 given location and its scheme of holidays (or a scheme of your own).
150 This calendar object is a caching proxy object; it stores the
152 reference of the given profile and contains a hash (the cache) of
153 Date::Calendar::Year objects.
154 • "$year = $calendar->year(YEAR|DATE);"
156 This method returns a Date::Calendar::Year object for the given year
158 and the profile that was associated with the given calendar object.
159 If the cache in the given calendar object already contains an object
161 for the requested year, the corresponding object reference is simply
162 returned.
163 If not, a new Date::Calendar::Year object is created using the
165 profile that has been associated with the given calendar object. The
166 new Date::Calendar::Year object is then stored in the calendar
167 object's cache and its object reference is returned.
168 A fatal "given year out of range" error will occur if the given year
170 number lies outside the valid range of [1583..2299].
171 • "@years = $calendar->cache_keys();"
173 This method returns the list of YEAR NUMBERS of the
175 Date::Calendar::Year objects contained in the given calendar object's
176 cache.
177 • "@years = $calendar->cache_vals();"
179 This method returns the list of OBJECT REFERENCES of the
181 Date::Calendar::Year objects contained in the given calendar object's
182 cache.
183 • "$calendar->cache_clr();"
185 This method clears the entire cache of the given calendar object (by
187 destroying the cache hash and creating a new one).
188 • "$calendar->cache_add(YEAR|DATE,...);"
190 Roughly, this method is a shortcut for
192 for $year (@list)
194 {
195 $calendar->year($year);
196 }
197 • "$calendar->cache_del(YEAR|DATE,...);"
199 This method removes the Date::Calendar::Year objects whose year
201 numbers are given from the cache of the given calendar object.
202 Year numbers for which the calendar object's cache doesn't contain an
204 entry are simply ignored.
205 • "$index = $calendar->date2index(YEAR,MONTH,DAY|DATE);"
207 This method converts a given date into the number of the day in that
209 year (this is sometimes also referred to as the "julian" date), i.e.,
210 a number between 0 (for January 1st) and the number of days in the
211 given year minus one, i.e., 364 or 365 (for December 31st).
212 You may need this in order to access the bit vectors returned by the
214 Date::Calendar::Year methods "vec_full()", "vec_half()" and
215 "vec_work()".
216 If the Date::Calendar::Year object for the given YEAR is not in the
218 $calendar's cache yet, it will be created and added.
219 An exception ("invalid date") is thrown if the given arguments do not
221 constitute a valid date, or ("given year out of range [1583..2299]")
222 if the given year lies outside of the permitted range.
223 • "@names = $calendar->labels(YEAR,MONTH,DAY|DATE);"
225 "@holidays = $calendar->labels();"
227 "$holidays = $calendar->labels();"
229 If any arguments are given, they are supposed to represent a date. In
231 that case, a list of all labels (= names of holidays) associated with
232 that date are returned. The first item returned is always the name of
233 the day of week for that date. The corresponding year object for the
234 given date's year is added to the calendar's cache first if
235 necessary.
236 If no arguments are given, the list of all available labels in all
238 years that have previously been accessed in the given calendar (i.e.,
239 the years which are already in the given calendar's cache) is
240 constructed. Note that this means that the returned list will be
241 empty if there are no year objects in the given calendar's cache yet
242 (!). The returned list does NOT include any names of the days of week
243 (which would be pointless in this case).
244 Multiple labels are reported only once.
246 Usually all years have the same set of labels, so it may seem
248 superfluous to scan all the years in the cache instead of just one.
249 But there may be exceptions, because it is possible to define
250 calendar profiles which do not contain all possible holidays in every
251 year. See Date::Calendar::Profiles(3) and Date::Calendar::Year(3) for
252 more details.
253 In list context, the resulting list itself is returned. In scalar
255 context, the number of items in the resulting list is returned.
256 • "@dates = $calendar->search(PATTERN);"
258 "$dates = $calendar->search(PATTERN);"
260 This method searches through all the labels in all years that have
262 previously been accessed in the given calendar (i.e., the years which
263 are already in the given calendar's cache) and returns a list of date
264 objects with all dates whose labels match the given pattern.
265 (Use the methods "cache_clr()", "cache_add()" and "cache_del()" in
267 order to put the year numbers you want into the calendar object's
268 cache, or to make sure it only contains the year numbers you want to
269 search.)
270 Note that this is a simple, case-insensitive substring search, NOT a
272 full-fledged regular expression search!
273 The result is guaranteed to be sorted chronologically.
275 In scalar context, only the number of items in the resulting list is
277 returned, instead of the resulting list itself (as in list context).
278 • "$hashref = $calendar->tags(YEAR,MONTH,DAY|DATE);"
280 This method returns a hash reference for the given calendar and date.
282 The hash it refers to is a copy of the calendar profile's internal
283 hash which contains the names for the given date as keys and 0, 1, 2,
284 or 3 as their corresponding values meaning the following:
285 0 => commemorative day
287 1 => "half" holiday
288 2 => "full" holiday
289 3 => both a "half" and a "full" holiday
290 The value "3" should only occur if a date has been redefined by the
292 underlying profile using the same key (i.e., the same name) but with
293 a different type of holiday.
294 • "$days = $calendar->delta_workdays(YEAR1,MONTH1,DAY1,
296 YEAR2,MONTH2,DAY2, FLAG1,FLAG2);"
297 "$days = $calendar->delta_workdays(DATE1,DATE2,FLAG1,FLAG2);"
299 This method calculates the number of work days (i.e., the number of
301 days, but excluding all holidays) between two dates.
302 In other words, this method is equivalent to the "Delta_Days()"
304 function of the Date::Calc module, except that it disregards holidays
305 in its counting.
306 The two flags indicate whether the start and end dates should be
308 included in the counting (that is, of course, only in case they
309 aren't holidays), or not.
310 It is common, for example, that you want to know how many work days
312 are left between the current date and a given deadline.
313 Typically, you will want to count the current date but not the
315 deadline's date. So you would specify "true" ("1") for FLAG1 and
316 "false" ("0") for FLAG2 in order to achieve that.
317 In other words, a value of "true" means "including this date", a
319 value of "false" means "excluding this date".
320 As with the "Delta_Days()" function from the Date::Calc module, the
322 dates have to be given in chronological order to yield a positive
323 result. If the dates are reversed, the result will be negative.
324 The parameter FLAG1 is associated with the first given date, the
326 parameter FLAG2 with the second given date (regardless of whether the
327 dates are in chronological order or not).
328 An exception ("invalid date") is raised if either of the two date
330 arguments does not constitute a valid date.
331 • "($date,$rest) = $calendar->add_delta_workdays(YEAR,MONTH,DAY,
333 DELTA);"
334 "($date,$rest) = $calendar->add_delta_workdays(DATE,DELTA);"
336 "$date = $calendar->add_delta_workdays(YEAR,MONTH,DAY, DELTA);"
338 "$date = $calendar->add_delta_workdays(DATE,DELTA);"
340 This method is the equivalent of the "Add_Delta_Days()" function from
342 the Date::Calc module, except that it adds work days and skips
343 holidays.
344 In other words, you can add or subtract a number of work days "DELTA"
346 to/from a given date and get a new date as the result (as a
347 Date::Calc object).
348 You add days (i.e., you go forward in time) with a positive offset
350 "DELTA", and you subtract days (i.e., you go backwards in time) with
351 a negative offset.
352 Note that an exception ("invalid date") is raised if the given date
354 argument does not constitute a valid date.
355 In scalar context, the method just returns the resulting date object,
357 whereas in list context the method not only returns the new date, but
358 also a "rest". This rest is useful for cases in which your profile
359 contains "half" holidays, or when you add or subtract fractions of a
360 day.
361 Sometimes it is not possible to accommodate the requested number of
363 work days, and a rest remains.
364 This rest can currently only assume the value "0.0" (zero), "-0.5"
366 (minus one half) or "0.5" (one half), provided you use only integral
367 or multiples of 0.5 as offsets. A rest of zero indicates that the
368 calculation yielded an exact result. If the rest is 0.5 or -0.5, this
369 is to be interpreted as "the resulting date at 12:00 o'clock",
370 instead of as "the resulting date at 0:00 o'clock".
371 The rest is always positive (or zero) if the offset "DELTA" is
373 positive (or zero), and always negative (or zero) if the offset is
374 negative (or zero).
375 Example:
377 #!perl
379 use Date::Calendar;
380 use Date::Calendar::Profiles qw( $Profiles );
381 $year = shift;
382 $cal = Date::Calendar->new( $Profiles->{'sdm-MUC'} );
383 ($date,$rest) = $cal->add_delta_workdays($year,1,3, -3);
384 $date->date_format(1);
385 print "\$date = $date, \$rest = $rest.\n";
386 __END__
387 This program calculates "January 3rd of the given year minus 3 work
389 days":
390 > perl test.pl 2001
392 $date = 28-Dec-2000, $rest = 0.
393 > perl test.pl 2002
394 $date = 28-Dec-2001, $rest = -0.5.
395 Note that December 31st is a "half" holiday in 2001 for the calendar
397 profile used in this example.
398 You can easily verify the results above with the help of the
400 "calendar.cgi" CGI script or the "linearcal.pl" script from the
401 "examples" subdirectory in the Date::Calc distribution.
402 BEWARE that this method may currently return unexpected (i.e.,
404 contradicting the above documentation) or plain wrong results when
405 going back in time (this is a bug!).
406 However, it works correctly and as documented above when going
408 forward in time.
409 • "$flag = $calendar->is_full(YEAR,MONTH,DAY|DATE);"
411 This method returns "true" ("1") if the bit corresponding to the
413 given date is set in the bit vector representing "full" holidays, and
414 "false" ("0") otherwise.
415 I.e., the method returns "true" if the given date is a (full) holiday
417 (according to the calendar profile associated with the given calendar
418 object).
419 The corresponding Date::Calendar::Year object is created first and
421 stored in the calendar object's cache if necessary (if it's not
422 already there).
423 Note that you can get a reference to this bit vector (in order to use
425 this bit vector in bit vector operations) as follows:
426 $vec_full = $calendar->year($year)->vec_full();
428 The number of bits in this bit vector is the same as the number of
430 days in the given year "$year", which you can retrieve through either
431 ""$days = $vec_full->Size();"" or ""$days = $year->val_days();"".
432 See Date::Calendar::Year(3) and Bit::Vector(3) for more details.
434 • "$flag = $calendar->is_half(YEAR,MONTH,DAY|DATE);"
436 This method returns "true" ("1") if the bit corresponding to the
438 given date is set in the bit vector representing "half" holidays, and
439 "false" ("0") otherwise.
440 I.e., the method returns "true" if the given date is a half holiday
442 (according to the calendar profile associated with the given calendar
443 object).
444 Note that if a date is a "full" holiday, the "half" bit is never set,
446 even if you try to do so in your calendar profile, on purpose or by
447 accident.
448 The corresponding Date::Calendar::Year object is created first and
450 stored in the calendar object's cache if necessary (if it's not
451 already there).
452 Note that you can get a reference to this bit vector (in order to use
454 this bit vector in bit vector operations) as follows:
455 $vec_half = $calendar->year($year)->vec_half();
457 The number of bits in this bit vector is the same as the number of
459 days in the given year "$year", which you can retrieve through either
460 ""$days = $vec_half->Size();"" or ""$days = $year->val_days();"".
461 See Date::Calendar::Year(3) and Bit::Vector(3) for more details.
463 • "$flag = $calendar->is_work(YEAR,MONTH,DAY|DATE);"
465 This method returns "true" ("1") if the bit corresponding to the
467 given date is set in the bit vector used to perform all sorts of
468 calculations, and "false" ("0") otherwise.
469 The corresponding Date::Calendar::Year object is created first and
471 stored in the calendar object's cache if necessary (if it's not
472 already there).
473 BEWARE that the "work" in this method's name does NOT come from "work
475 days"!
476 It comes from the fact that the corresponding bit vector can be used
478 for any "work" that you need to do. In other words, it's a "work
479 space".
480 Therefore, this bit vector might contain about everything you could
482 imagine - including a bit pattern which marks all "work days" with
483 set bits, if it so happens!
484 But you better don't rely on it, unless you put the bit pattern there
486 yourself in the first place.
487 Note that you can get a reference to this bit vector (in order to
489 fill it with any bit pattern you like) as follows:
490 $vec_work = $calendar->year($year)->vec_work();
492 The number of bits in this bit vector is the same as the number of
494 days in the given year "$year", which you can retrieve through either
495 ""$days = $vec_work->Size();"" or ""$days = $year->val_days();"".
496 See Date::Calendar::Year(3) and Bit::Vector(3) for more details.
498
500 Date::Calendar::Year(3), Date::Calendar::Profiles(3),
501 Date::Calc::Object(3), Date::Calc(3), Date::Calc::Util(3),
502 Bit::Vector(3).
503
505 The calendar profiles included in Date::Calendar::Profiles(3) usually
506 do not take historical irregularities into account (even though some do
507 in order to show how this can be done), they only provide means for
508 calculating regularly recurring events (the profiles should therefore
509 not be relied upon for historical faithfulness).
510
512 The method "add_delta_workdays()" is known to produce results which are
513 sometimes off by one working day when a negative offset is used. As a
514 workaround, try to add one working day first and then subtract one
515 working day more than initially intended. See also the file
516 "examples/bug.pl" for how to do this.
517
519 This man page documents "Date::Calendar" version 6.4.
520
522 Steffen Beyer
523 mailto:STBEY@cpan.org
524 http://www.engelschall.com/u/sb/download/
525
527 Copyright (c) 2000 - 2015 by Steffen Beyer. All rights reserved.
528
530 This package is free software; you can use, modify and redistribute it
531 under the same terms as Perl itself, i.e., at your option, under the
532 terms either of the "Artistic License" or the "GNU General Public
533 License".
534 The C library at the core of the module "Date::Calc::XS" can, at your
536 discretion, also be used, modified and redistributed under the terms of
537 the "GNU Library General Public License".
538 Please refer to the files "Artistic.txt", "GNU_GPL.txt" and
540 "GNU_LGPL.txt" in the "license" subdirectory of this distribution for
541 any details!
542
544 This package is distributed in the hope that it will be useful, but
545 WITHOUT ANY WARRANTY; without even the implied warranty of
546 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
547 See the "GNU General Public License" for more details.
549perl v5.34.0 2021-07-22 Date::Calendar(3)