1Calendar(3) User Contributed Perl Documentation 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 Date::Cal‐
13 endar::Year objects, which are embedded in each Date::Calendar object.
14 However, and in contrast to Date::Calendar::Year methods, Date::Calen‐
16 dar methods permit calculations spanning an arbitrary number of years,
17 without loss of efficiency.
18 So you should usually use Date::Calendar and not Date::Calendar::Year,
20 since that way you don't have to worry about calculations crossing year
21 boundaries.
22 Note however that Date::Calendar and Date::Calendar::Year can only deal
24 with years lying within the range [1583..2299].
25
27 use Date::Calendar::Profiles qw( $Profiles );
28 use Date::Calendar;
29 $calendar_US_AZ = Date::Calendar->new( $Profiles->{'US-AZ'} [,LANG] );
31 $calendar_DE_SN = Date::Calendar->new( $Profiles->{'DE-SN'} [,LANG] );
32 $year_2000_US_AZ = $calendar_US_AZ->year( 2000 );
34 $year_2001_DE_SN = $calendar_DE_SN->year( 2001 );
35 @years = $calendar->cache_keys(); # returns list of year numbers
37 @years = $calendar->cache_vals(); # returns list of year objects
38 $calendar->cache_clr();
40 $calendar->cache_add(YEAR⎪DATE,...);
41 $calendar->cache_del(YEAR⎪DATE,...);
42 $index = $calendar->date2index(YEAR,MONTH,DAY⎪DATE);
44 @names = $calendar->labels(YEAR,MONTH,DAY⎪DATE);
46 @holidays = $calendar->labels();
47 $holidays = $calendar->labels();
48 @dates = $calendar->search(PATTERN);
50 $dates = $calendar->search(PATTERN);
51 $hashref = $calendar->tags(YEAR,MONTH,DAY⎪DATE);
53 $days = $calendar->delta_workdays(YEAR1,MONTH1,DAY1⎪DATE1
55 ,YEAR2,MONTH2,DAY2⎪DATE2
56 ,FLAG1,FLAG2);
57 ($date,$rest) = $calendar->add_delta_workdays(YEAR,MONTH,DAY⎪DATE
59 ,DELTA);
60 $date = $calendar->add_delta_workdays(YEAR,MONTH,DAY⎪DATE
61 ,DELTA);
62 $flag = $calendar->is_full(YEAR,MONTH,DAY⎪DATE);
64 $flag = $calendar->is_half(YEAR,MONTH,DAY⎪DATE);
65 $flag = $calendar->is_work(YEAR,MONTH,DAY⎪DATE);
66
68 Note that whenever a year number, a date, a time or a combined date and
69 time are expected as input parameters by one of the methods of this
70 class, you can always pass a Date::Calc[::Object] date object or an
71 array reference (of an array of appropriate length) instead!
72 See Date::Calc::Object(3) for more details.
74 So instead of calling a given method like this:
76 $object->method1( $year,$month,$day );
78 $object->method2( $year1,$month1,$day1, $year2,$month2,$day2 );
79 $object->method3( $year1, $year2, $year3 );
80 You can also call it like so:
82 $object->method1( $date );
84 $object->method1( [1964,1,3] );
85 $object->method2( $year1,$month1,$day1, $date2 );
87 $object->method2( $date1, $year2,$month2,$day2 );
88 $object->method2( $date1, $date2 );
89 $object->method2( $year1,$month1,$day1, [2001,3,17] );
90 $object->method2( [1964,1,3], $year2,$month2,$day2 );
91 $object->method2( [1964,1,3], [2001,3,17] );
92 $object->method2( $date1, [2001,3,17] );
93 $object->method2( [1964,1,3], $date2 );
94 $object->method3( $year1, $date2, [2001,3,17] );
96 And similarly if a time or a combined date and time are expected.
98 If you substitute an expected year number by an anonymous array (this
100 is the recommended way of writing date constants, for increased read‐
101 ability of your programs), it must contain three values, nevertheless
102 (otherwise the use of an anonymous array would be pointless).
103 Don't confuse year numbers and their substitutes (a date object or an
105 array reference) with Date::Calendar::Year objects, which are a totally
106 different thing!
107 But incidentally ":-)", you may also pass a Date::Calendar::Year object
109 whenever a year number is expected. However, and perhaps against your
110 expectations at times, especially in conjunction with the method
111 "cache_add()", only the year number from that object will be used, not
112 the year object itself (the year object in question might be using the
113 wrong profile!).
114 Moreover, whenever a method of this class returns a date, it does so by
116 returning a Date::Calc[::Object] date object.
117
119 · "$calendar = Date::Calendar->new(PROFILE[,LANG]);"
120 The first argument must be the reference of a hash, which contains a
122 holiday scheme or "profile" to be used in all calculations involving
123 the new calendar object.
124 The second argument is optional, and must consist of the valid name
126 or number of a language as provided by the Date::Calc(3) module if
127 given.
128 See Date::Calendar::Profiles(3) and Date::Calendar::Year(3) for more
130 details about these arguments and about how to roll your own calendar
131 profiles.
132 The method creates a new calendar object for a given profile, i.e., a
134 given location and its scheme of holidays (or a scheme of your own).
135 This calendar object is a caching proxy object; it stores the refer‐
137 ence of the given profile and contains a hash (the cache) of
138 Date::Calendar::Year objects.
139 · "$year = $calendar->year(YEAR⎪DATE);"
141 This method returns a Date::Calendar::Year object for the given year
143 and the profile that was associated with the given calendar object.
144 If the cache in the given calendar object already contains an object
146 for the requested year, the corresponding object reference is simply
147 returned.
148 If not, a new Date::Calendar::Year object is created using the pro‐
150 file that has been associated with the given calendar object. The
151 new Date::Calendar::Year object is then stored in the calendar
152 object's cache and its object reference is returned.
153 A fatal "given year out of range" error will occur if the given year
155 number lies outside the valid range of [1583..2299].
156 · "@years = $calendar->cache_keys();"
158 This method returns the list of YEAR NUMBERS of the Date::Calen‐
160 dar::Year objects contained in the given calendar object's cache.
161 · "@years = $calendar->cache_vals();"
163 This method returns the list of OBJECT REFERENCES of the Date::Calen‐
165 dar::Year objects contained in the given calendar object's cache.
166 · "$calendar->cache_clr();"
168 This method clears the entire cache of the given calendar object (by
170 destroying the cache hash and creating a new one).
171 · "$calendar->cache_add(YEAR⎪DATE,...);"
173 Roughly, this method is a shortcut for
175 for $year (@list)
177 {
178 $calendar->year($year);
179 }
180 · "$calendar->cache_del(YEAR⎪DATE,...);"
182 This method removes the Date::Calendar::Year objects whose year num‐
184 bers are given from the cache of the given calendar object.
185 Year numbers for which the calendar object's cache doesn't contain an
187 entry are simply ignored.
188 · "$index = $calendar->date2index(YEAR,MONTH,DAY⎪DATE);"
190 This method converts a given date into the number of the day in that
192 year (this is sometimes also referred to as the "julian" date), i.e.,
193 a number between 0 (for January 1st) and the number of days in the
194 given year minus one, i.e., 364 or 365 (for December 31st).
195 You may need this in order to access the bit vectors returned by the
197 Date::Calendar::Year methods "vec_full()", "vec_half()" and
198 "vec_work()".
199 If the Date::Calendar::Year object for the given YEAR is not in the
201 $calendar's cache yet, it will be created and added.
202 An exception ("invalid date") is thrown if the given arguments do not
204 constitute a valid date, or ("given year out of range [1583..2299]")
205 if the given year lies outside of the permitted range.
206 · "@names = $calendar->labels(YEAR,MONTH,DAY⎪DATE);"
208 "@holidays = $calendar->labels();"
210 "$holidays = $calendar->labels();"
212 If any arguments are given, they are supposed to represent a date. In
214 that case, a list of all labels (= names of holidays) associated with
215 that date are returned. The first item returned is always the name of
216 the day of week for that date. The corresponding year object for the
217 given date's year is added to the calendar's cache first if neces‐
218 sary.
219 If no arguments are given, the list of all available labels in all
221 years that have previously been accessed in the given calendar (i.e.,
222 the years which are already in the given calendar's cache) is con‐
223 structed. Note that this means that the returned list will be empty
224 if there are no year objects in the given calendar's cache yet (!).
225 The returned list does NOT include any names of the days of week
226 (which would be pointless in this case).
227 Multiple labels are reported only once.
229 Usually all years have the same set of labels, so it may seem super‐
231 fluous to scan all the years in the cache instead of just one. But
232 there may be exceptions, because it is possible to define calendar
233 profiles which do not contain all possible holidays in every year.
234 See Date::Calendar::Profiles(3) and Date::Calendar::Year(3) for more
235 details.
236 In list context, the resulting list itself is returned. In scalar
238 context, the number of items in the resulting list is returned.
239 · "@dates = $calendar->search(PATTERN);"
241 "$dates = $calendar->search(PATTERN);"
243 This method searches through all the labels in all years that have
245 previously been accessed in the given calendar (i.e., the years which
246 are already in the given calendar's cache) and returns a list of date
247 objects with all dates whose labels match the given pattern.
248 (Use the methods "cache_clr()", "cache_add()" and "cache_del()" in
250 order to put the year numbers you want into the calendar object's
251 cache, or to make sure it only contains the year numbers you want to
252 search.)
253 Note that this is a simple, case-insensitive substring search, NOT a
255 full-fledged regular expression search!
256 The result is guaranteed to be sorted chronologically.
258 In scalar context, only the number of items in the resulting list is
260 returned, instead of the resulting list itself (as in list context).
261 · "$hashref = $calendar->tags(YEAR,MONTH,DAY⎪DATE);"
263 This method returns a hash reference for the given calendar and date.
265 The hash it refers to is a copy of the calendar profile's internal
266 hash which contains the names for the given date as keys and 0, 1, 2,
267 or 3 as their corresponding values meaning the following:
268 0 => commemorative day
270 1 => "half" holiday
271 2 => "full" holiday
272 3 => both a "half" and a "full" holiday
273 The value "3" should only occur if a date has been redefined by the
275 underlying profile using the same key (i.e., the same name) but with
276 a different type of holiday.
277 · "$days = $calendar->delta_workdays(YEAR1,MONTH1,DAY1,
279 YEAR2,MONTH2,DAY2, FLAG1,FLAG2);"
280 "$days = $calendar->delta_workdays(DATE1,DATE2,FLAG1,FLAG2);"
282 This method calculates the number of work days (i.e., the number of
284 days, but excluding all holidays) between two dates.
285 In other words, this method is equivalent to the "Delta_Days()" func‐
287 tion of the Date::Calc module, except that it disregards holidays in
288 its counting.
289 The two flags indicate whether the start and end dates should be
291 included in the counting (that is, of course, only in case they
292 aren't holidays), or not.
293 It is common, for example, that you want to know how many work days
295 are left between the current date and a given deadline.
296 Typically, you will want to count the current date but not the dead‐
298 line's date. So you would specify "true" ("1") for FLAG1 and "false"
299 ("0") for FLAG2 in order to achieve that.
300 In other words, a value of "true" means "including this date", a
302 value of "false" means "excluding this date".
303 As with the "Delta_Days()" function from the Date::Calc module, the
305 dates have to be given in chronological order to yield a positive
306 result. If the dates are reversed, the result will be negative.
307 The parameter FLAG1 is associated with the first given date, the
309 parameter FLAG2 with the second given date (regardless of whether the
310 dates are in chronological order or not).
311 An exception ("invalid date") is raised if either of the two date
313 arguments does not constitute a valid date.
314 · "($date,$rest) = $calendar->add_delta_workdays(YEAR,MONTH,DAY,
316 DELTA);"
317 "($date,$rest) = $calendar->add_delta_workdays(DATE,DELTA);"
319 "$date = $calendar->add_delta_workdays(YEAR,MONTH,DAY, DELTA);"
321 "$date = $calendar->add_delta_workdays(DATE,DELTA);"
323 This method is the equivalent of the "Add_Delta_Days()" function from
325 the Date::Calc module, except that it adds work days and skips holi‐
326 days.
327 In other words, you can add or subtract a number of work days "DELTA"
329 to/from a given date and get a new date as the result (as a
330 Date::Calc object).
331 You add days (i.e., you go forward in time) with a positive offset
333 "DELTA", and you subtract days (i.e., you go backwards in time) with
334 a negative offset.
335 Note that an exception ("invalid date") is raised if the given date
337 argument does not constitute a valid date.
338 In scalar context, the method just returns the resulting date object,
340 whereas in list context the method not only returns the new date, but
341 also a "rest". This rest is useful for cases in which your profile
342 contains "half" holidays, or when you add or subtract fractions of a
343 day.
344 Sometimes it is not possible to accomodate the requested number of
346 work days, and a rest remains.
347 This rest can currently only assume the value "0.0" (zero), "-0.5"
349 (minus one half) or "0.5" (one half), provided you use only integral
350 or multiples of 0.5 as offsets. A rest of zero indicates that the
351 calculation yielded an exact result. If the rest is 0.5 or -0.5, this
352 is to be interpreted as "the resulting date at 12:00 o'clock",
353 instead of as "the resulting date at 0:00 o'clock".
354 The rest is always positive (or zero) if the offset "DELTA" is posi‐
356 tive (or zero), and always negative (or zero) if the offset is nega‐
357 tive (or zero).
358 Example:
360 #!perl
362 use Date::Calendar;
363 use Date::Calendar::Profiles qw( $Profiles );
364 $year = shift;
365 $cal = Date::Calendar->new( $Profiles->{'sdm-MUC'} );
366 ($date,$rest) = $cal->add_delta_workdays($year,1,3, -3);
367 $date->date_format(1);
368 print "\$date = $date, \$rest = $rest.\n";
369 __END__
370 This program calculates "January 3rd of the given year minus 3 work
372 days":
373 > perl test.pl 2001
375 $date = 28-Dec-2000, $rest = 0.
376 > perl test.pl 2002
377 $date = 28-Dec-2001, $rest = -0.5.
378 Note that December 31st is a "half" holiday in 2001 for the calendar
380 profile used in this example.
381 You can easily verify the results above with the help of the "calen‐
383 dar.cgi" CGI script or the "linearcal.pl" script from the "examples"
384 subdirectory in the Date::Calc distribution.
385 · "$flag = $calendar->is_full(YEAR,MONTH,DAY⎪DATE);"
387 This method returns "true" ("1") if the bit corresponding to the
389 given date is set in the bit vector representing "full" holidays, and
390 "false" ("0") otherwise.
391 I.e., the method returns "true" if the given date is a (full) holiday
393 (according to the calendar profile associated with the given calendar
394 object).
395 The corresponding Date::Calendar::Year object is created first and
397 stored in the calendar object's cache if necessary (if it's not
398 already there).
399 Note that you can get a reference to this bit vector (in order to use
401 this bit vector in bit vector operations) as follows:
402 $vec_full = $calendar->year($year)->vec_full();
404 The number of bits in this bit vector is the same as the number of
406 days in the given year "$year", which you can retrieve through either
407 ""$days = $vec_full->Size();"" or ""$days = $year->val_days();"".
408 See Date::Calendar::Year(3) and Bit::Vector(3) for more details.
410 · "$flag = $calendar->is_half(YEAR,MONTH,DAY⎪DATE);"
412 This method returns "true" ("1") if the bit corresponding to the
414 given date is set in the bit vector representing "half" holidays, and
415 "false" ("0") otherwise.
416 I.e., the method returns "true" if the given date is a half holiday
418 (according to the calendar profile associated with the given calendar
419 object).
420 Note that if a date is a "full" holiday, the "half" bit is never set,
422 even if you try to do so in your calendar profile, on purpose or by
423 accident.
424 The corresponding Date::Calendar::Year object is created first and
426 stored in the calendar object's cache if necessary (if it's not
427 already there).
428 Note that you can get a reference to this bit vector (in order to use
430 this bit vector in bit vector operations) as follows:
431 $vec_half = $calendar->year($year)->vec_half();
433 The number of bits in this bit vector is the same as the number of
435 days in the given year "$year", which you can retrieve through either
436 ""$days = $vec_half->Size();"" or ""$days = $year->val_days();"".
437 See Date::Calendar::Year(3) and Bit::Vector(3) for more details.
439 · "$flag = $calendar->is_work(YEAR,MONTH,DAY⎪DATE);"
441 This method returns "true" ("1") if the bit corresponding to the
443 given date is set in the bit vector used to perform all sorts of cal‐
444 culations, and "false" ("0") otherwise.
445 The corresponding Date::Calendar::Year object is created first and
447 stored in the calendar object's cache if necessary (if it's not
448 already there).
449 BEWARE that the "work" in this method's name does NOT come from "work
451 days"!
452 It comes from the fact that the corresponding bit vector can be used
454 for any "work" that you need to do. In other words, it's a "work
455 space".
456 Therefore, this bit vector might contain about everything you could
458 imagine - including a bit pattern which marks all "work days" with
459 set bits, if it so happens!
460 But you better don't rely on it, unless you put the bit pattern there
462 yourself in the first place.
463 Note that you can get a reference to this bit vector (in order to
465 fill it with any bit pattern you like) as follows:
466 $vec_work = $calendar->year($year)->vec_work();
468 The number of bits in this bit vector is the same as the number of
470 days in the given year "$year", which you can retrieve through either
471 ""$days = $vec_work->Size();"" or ""$days = $year->val_days();"".
472 See Date::Calendar::Year(3) and Bit::Vector(3) for more details.
474
476 Date::Calendar::Year(3), Date::Calendar::Profiles(3),
477 Date::Calc::Object(3), Date::Calc(3), Bit::Vector(3).
478
480 The method "add_delta_workdays()" is known to produce results which are
481 sometimes off by one working day when a negative offset is used. As a
482 workaround, try to add one working day first and then subtract one
483 working day more than initially intended. See also the file "exam‐
484 ples/bug.pl" for how to do this.
485
487 This man page documents "Date::Calendar" version 5.4.
488
490 Steffen Beyer
491 mailto:sb@engelschall.com
492 http://www.engelschall.com/u/sb/download/
493
495 Copyright (c) 2000 - 2004 by Steffen Beyer. All rights reserved.
496
498 This package is free software; you can redistribute it and/or modify it
499 under the same terms as Perl itself, i.e., under the terms of the
500 "Artistic License" or the "GNU General Public License".
501 Please refer to the files "Artistic.txt" and "GNU_GPL.txt" in this dis‐
503 tribution for details!
504
506 This package is distributed in the hope that it will be useful, but
507 WITHOUT ANY WARRANTY; without even the implied warranty of MER‐
508 CHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
509 See the "GNU General Public License" for more details.
511perl v5.8.8 2004-10-03 Calendar(3)