Commit | Line | Data |
---|---|---|
86530b38 AT |
1 | |
2 | =head1 NAME | |
3 | ||
4 | Date::Calendar - Calendar objects for different holiday schemes | |
5 | ||
6 | =head1 MOTTO | |
7 | ||
8 | There is more than one way to do it - this is just one of them! | |
9 | ||
10 | =head1 PREFACE | |
11 | ||
12 | Basically, Date::Calendar is just a caching proxy class for | |
13 | Date::Calendar::Year objects, which are embedded in each | |
14 | Date::Calendar object. | |
15 | ||
16 | However, and in contrast to Date::Calendar::Year methods, Date::Calendar | |
17 | methods permit calculations spanning an arbitrary number of years, without | |
18 | loss of efficiency. | |
19 | ||
20 | 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 | ||
24 | Note however that Date::Calendar and Date::Calendar::Year can only deal | |
25 | with years lying within the range [1583..2299]. | |
26 | ||
27 | =head1 SYNOPSIS | |
28 | ||
29 | use Date::Calendar::Profiles qw( $Profiles ); | |
30 | use Date::Calendar; | |
31 | ||
32 | $calendar_US_AZ = Date::Calendar->new( $Profiles->{'US-AZ'} [,LANG] ); | |
33 | $calendar_DE_SN = Date::Calendar->new( $Profiles->{'DE-SN'} [,LANG] ); | |
34 | ||
35 | $year_2000_US_AZ = $calendar_US_AZ->year( 2000 ); | |
36 | $year_2001_DE_SN = $calendar_DE_SN->year( 2001 ); | |
37 | ||
38 | @years = $calendar->cache_keys(); # returns list of year numbers | |
39 | @years = $calendar->cache_vals(); # returns list of year objects | |
40 | ||
41 | $calendar->cache_clr(); | |
42 | $calendar->cache_add(YEAR|DATE,...); | |
43 | $calendar->cache_del(YEAR|DATE,...); | |
44 | ||
45 | $index = $calendar->date2index(YEAR,MONTH,DAY|DATE); | |
46 | ||
47 | @names = $calendar->labels(YEAR,MONTH,DAY|DATE); | |
48 | @holidays = $calendar->labels(); | |
49 | $holidays = $calendar->labels(); | |
50 | ||
51 | @dates = $calendar->search(PATTERN); | |
52 | $dates = $calendar->search(PATTERN); | |
53 | ||
54 | $days = $calendar->delta_workdays(YEAR1,MONTH1,DAY1|DATE1 | |
55 | ,YEAR2,MONTH2,DAY2|DATE2 | |
56 | ,FLAG1,FLAG2); | |
57 | ||
58 | ($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 | ||
63 | $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 | ||
67 | =head1 INTERFACE | |
68 | ||
69 | Note that whenever a year number, a date, a time or a combined | |
70 | date and time are expected as input parameters by one of the | |
71 | methods of this class, you can always pass a Date::Calc[::Object] | |
72 | date object or an array reference (of an array of appropriate | |
73 | length) instead! | |
74 | ||
75 | See L<Date::Calc::Object(3)> for more details. | |
76 | ||
77 | So instead of calling a given method like this: | |
78 | ||
79 | $object->method1( $year,$month,$day ); | |
80 | $object->method2( $year1,$month1,$day1, $year2,$month2,$day2 ); | |
81 | $object->method3( $year1, $year2, $year3 ); | |
82 | ||
83 | You can also call it like so: | |
84 | ||
85 | $object->method1( $date ); | |
86 | $object->method1( [1964,1,3] ); | |
87 | ||
88 | $object->method2( $year1,$month1,$day1, $date2 ); | |
89 | $object->method2( $date1, $year2,$month2,$day2 ); | |
90 | $object->method2( $date1, $date2 ); | |
91 | $object->method2( $year1,$month1,$day1, [2001,3,17] ); | |
92 | $object->method2( [1964,1,3], $year2,$month2,$day2 ); | |
93 | $object->method2( [1964,1,3], [2001,3,17] ); | |
94 | $object->method2( $date1, [2001,3,17] ); | |
95 | $object->method2( [1964,1,3], $date2 ); | |
96 | ||
97 | $object->method3( $year1, $date2, [2001,3,17] ); | |
98 | ||
99 | And similarly if a time or a combined date and time are expected. | |
100 | ||
101 | If you substitute an expected year number by an anonymous array | |
102 | (this is the recommended way of writing date constants, for | |
103 | increased readability of your programs), it must contain three | |
104 | values, nevertheless (otherwise the use of an anonymous array | |
105 | would be pointless). | |
106 | ||
107 | Don't confuse year numbers and their substitutes (a date object | |
108 | or an array reference) with Date::Calendar::Year objects, which | |
109 | are a totally different thing! | |
110 | ||
111 | But incidentally C<:-)>, you may also pass a Date::Calendar::Year | |
112 | object whenever a year number is expected. However, and perhaps | |
113 | against your expectations at times, especially in conjunction | |
114 | with the method "cache_add()", only the year number from that | |
115 | object will be used, not the year object itself (the year | |
116 | object in question might be using the wrong profile!). | |
117 | ||
118 | Moreover, whenever a method of this class returns a date, it | |
119 | does so by returning a Date::Calc[::Object] date object. | |
120 | ||
121 | =head1 DESCRIPTION | |
122 | ||
123 | =over 2 | |
124 | ||
125 | =item * | |
126 | ||
127 | C<$calendar = Date::Calendar-E<gt>new(PROFILE[,LANG]);> | |
128 | ||
129 | The first argument must be the reference of a hash, | |
130 | which contains a holiday scheme or "profile" to be used | |
131 | in all calculations involving the new calendar object. | |
132 | ||
133 | The second argument is optional, and must consist of | |
134 | the valid name or number of a language as provided by | |
135 | the Date::Calc(3) module if given. | |
136 | ||
137 | See L<Date::Calendar::Profiles(3)> and L<Date::Calendar::Year(3)> | |
138 | for more details about these arguments and about how | |
139 | to roll your own calendar profiles. | |
140 | ||
141 | The method creates a new calendar object for a given profile, | |
142 | i.e., a given location and its scheme of holidays (or a scheme | |
143 | of your own). | |
144 | ||
145 | This calendar object is a caching proxy object; it stores the | |
146 | reference of the given profile and contains a hash (the cache) | |
147 | of Date::Calendar::Year objects. | |
148 | ||
149 | =item * | |
150 | ||
151 | C<$year = $calendar-E<gt>year(YEAR|DATE);> | |
152 | ||
153 | This method returns a Date::Calendar::Year object for the given | |
154 | year and the profile that was associated with the given calendar | |
155 | object. | |
156 | ||
157 | If the cache in the given calendar object already contains an | |
158 | object for the requested year, the corresponding object reference | |
159 | is simply returned. | |
160 | ||
161 | If not, a new Date::Calendar::Year object is created using the | |
162 | profile that has been associated with the given calendar object. | |
163 | The new Date::Calendar::Year object is then stored in the calendar | |
164 | object's cache and its object reference is returned. | |
165 | ||
166 | A fatal "given year out of range" error will occur if the given | |
167 | year number lies outside the valid range of [1583..2299]. | |
168 | ||
169 | =item * | |
170 | ||
171 | C<@years = $calendar-E<gt>cache_keys();> | |
172 | ||
173 | This method returns the list of B<YEAR NUMBERS> of the | |
174 | Date::Calendar::Year objects contained in the given | |
175 | calendar object's cache. | |
176 | ||
177 | =item * | |
178 | ||
179 | C<@years = $calendar-E<gt>cache_vals();> | |
180 | ||
181 | This method returns the list of B<OBJECT REFERENCES> of | |
182 | the Date::Calendar::Year objects contained in the given | |
183 | calendar object's cache. | |
184 | ||
185 | =item * | |
186 | ||
187 | C<$calendar-E<gt>cache_clr();> | |
188 | ||
189 | This method clears the entire cache of the given calendar | |
190 | object (by destroying the cache hash and creating a new one). | |
191 | ||
192 | =item * | |
193 | ||
194 | C<$calendar-E<gt>cache_add(YEAR|DATE,...);> | |
195 | ||
196 | Roughly, this method is a shortcut for | |
197 | ||
198 | for $year (@list) | |
199 | { | |
200 | $calendar->year($year); | |
201 | } | |
202 | ||
203 | =item * | |
204 | ||
205 | C<$calendar-E<gt>cache_del(YEAR|DATE,...);> | |
206 | ||
207 | This method removes the Date::Calendar::Year objects whose | |
208 | year numbers are given from the cache of the given calendar | |
209 | object. | |
210 | ||
211 | Year numbers for which the calendar object's cache doesn't | |
212 | contain an entry are simply ignored. | |
213 | ||
214 | =item * | |
215 | ||
216 | C<$index = $calendar-E<gt>date2index(YEAR,MONTH,DAY|DATE);> | |
217 | ||
218 | This method converts a given date into the number of the day in | |
219 | that year (this is sometimes also referred to as the "julian" | |
220 | date), i.e., a number between 0 (for January 1st) and the number | |
221 | of days in the given year minus one, i.e., 364 or 365 (for | |
222 | December 31st). | |
223 | ||
224 | You may need this in order to access the bit vectors returned | |
225 | by the Date::Calendar::Year methods "vec_full()", "vec_half()" | |
226 | and "vec_work()". | |
227 | ||
228 | If the Date::Calendar::Year object for the given YEAR is not in | |
229 | the C<$calendar>'s cache yet, it will be created and added. | |
230 | ||
231 | An exception ("invalid date") is thrown if the given arguments | |
232 | do not constitute a valid date, or ("given year out of range | |
233 | [1583..2299]") if the given year lies outside of the permitted | |
234 | range. | |
235 | ||
236 | =item * | |
237 | ||
238 | C<@names = $calendar-E<gt>labels(YEAR,MONTH,DAY|DATE);> | |
239 | ||
240 | C<@holidays = $calendar-E<gt>labels();> | |
241 | ||
242 | C<$holidays = $calendar-E<gt>labels();> | |
243 | ||
244 | If any arguments are given, they are supposed to represent a | |
245 | date. In that case, a list of all labels (= names of holidays) | |
246 | associated with that date are returned. The first item returned | |
247 | is always the name of the day of week for that date. The | |
248 | corresponding year object for the given date's year is | |
249 | added to the calendar's cache first if necessary. | |
250 | ||
251 | If no arguments are given, the list of all available labels in | |
252 | all years that have previously been accessed in the given calendar | |
253 | (i.e., the years which are already in the given calendar's cache) | |
254 | is constructed. Note that this means that the returned list will | |
255 | be empty if there are no year objects in the given calendar's | |
256 | cache yet (!). The returned list does B<NOT> include any names | |
257 | of the days of week (which would be pointless in this case). | |
258 | ||
259 | Multiple labels are reported only once. | |
260 | ||
261 | Usually all years have the same set of labels, so it may seem | |
262 | superfluous to scan all the years in the cache instead of just | |
263 | one. But there may be exceptions, because it is possible to | |
264 | define calendar profiles which do not contain all possible | |
265 | holidays in every year. See L<Date::Calendar::Profiles(3)> | |
266 | and L<Date::Calendar::Year(3)> for more details. | |
267 | ||
268 | In list context, the resulting list itself is returned. In scalar | |
269 | context, the number of items in the resulting list is returned. | |
270 | ||
271 | =item * | |
272 | ||
273 | C<@dates = $calendar-E<gt>search(PATTERN);> | |
274 | ||
275 | C<$dates = $calendar-E<gt>search(PATTERN);> | |
276 | ||
277 | This method searches through all the labels in all years that | |
278 | have previously been accessed in the given calendar (i.e., the | |
279 | years which are already in the given calendar's cache) and | |
280 | returns a list of date objects with all dates whose labels | |
281 | match the given pattern. | |
282 | ||
283 | (Use the methods "cache_clr()", "cache_add()" and "cache_del()" | |
284 | in order to put the year numbers you want into the calendar | |
285 | object's cache, or to make sure it only contains the year | |
286 | numbers you want to search.) | |
287 | ||
288 | Note that this is a simple, case-insensitive substring search, | |
289 | B<NOT> a full-fledged regular expression search! | |
290 | ||
291 | The result is guaranteed to be sorted chronologically. | |
292 | ||
293 | In scalar context, only the number of items in the resulting list | |
294 | is returned, instead of the resulting list itself (as in list context). | |
295 | ||
296 | =item * | |
297 | ||
298 | C<$days = $calendar-E<gt>delta_workdays(YEAR1,MONTH1,DAY1, YEAR2,MONTH2,DAY2, FLAG1,FLAG2);> | |
299 | ||
300 | C<$days = $calendar-E<gt>delta_workdays(DATE1,DATE2,FLAG1,FLAG2);> | |
301 | ||
302 | This method calculates the number of work days (i.e., the number | |
303 | of days, but excluding all holidays) between two dates. | |
304 | ||
305 | In other words, this method is equivalent to the "Delta_Days()" | |
306 | function of the Date::Calc module, except that it disregards | |
307 | holidays in its counting. | |
308 | ||
309 | The two flags indicate whether the start and end dates should be | |
310 | included in the counting (that is, of course, only in case they | |
311 | aren't holidays), or not. | |
312 | ||
313 | It is common, for example, that you want to know how many work | |
314 | days are left between the current date and a given deadline. | |
315 | ||
316 | Typically, you will want to count the current date but not the | |
317 | deadline's date. So you would specify "true" ("1") for FLAG1 | |
318 | and "false" ("0") for FLAG2 in order to achieve that. | |
319 | ||
320 | In other words, a value of "true" means "including this date", | |
321 | a value of "false" means "excluding this date". | |
322 | ||
323 | As with the "Delta_Days()" function from the Date::Calc module, | |
324 | the dates have to be given in chronological order to yield a | |
325 | positive result. If the dates are reversed, the result will | |
326 | be negative. | |
327 | ||
328 | The parameter FLAG1 is associated with the first given date, | |
329 | the parameter FLAG2 with the second given date (regardless | |
330 | of whether the dates are in chronological order or not). | |
331 | ||
332 | An exception ("invalid date") is raised if either of the two | |
333 | date arguments does not constitute a valid date. | |
334 | ||
335 | =item * | |
336 | ||
337 | C<($date,$rest) = $calendar-E<gt>add_delta_workdays(YEAR,MONTH,DAY, DELTA);> | |
338 | ||
339 | C<($date,$rest) = $calendar-E<gt>add_delta_workdays(DATE,DELTA);> | |
340 | ||
341 | C<$date = $calendar-E<gt>add_delta_workdays(YEAR,MONTH,DAY, DELTA);> | |
342 | ||
343 | C<$date = $calendar-E<gt>add_delta_workdays(DATE,DELTA);> | |
344 | ||
345 | This method is the equivalent of the "Add_Delta_Days()" function | |
346 | from the Date::Calc module, except that it adds work days and | |
347 | skips holidays. | |
348 | ||
349 | In other words, you can add or subtract a number of work days | |
350 | "DELTA" to/from a given date and get a new date as the result | |
351 | (as a Date::Calc object). | |
352 | ||
353 | You add days (i.e., you go forward in time) with a positive | |
354 | offset "DELTA", and you subtract days (i.e., you go backwards | |
355 | in time) with a negative offset. | |
356 | ||
357 | Note that an exception ("invalid date") is raised if the | |
358 | given date argument does not constitute a valid date. | |
359 | ||
360 | In scalar context, the method just returns the resulting date | |
361 | object, whereas in list context the method not only returns the | |
362 | new date, but also a "rest". This rest is useful for cases in | |
363 | which your profile contains "half" holidays, or when you add | |
364 | or subtract fractions of a day. | |
365 | ||
366 | Sometimes it is not possible to accomodate the requested number | |
367 | of work days, and a rest remains. | |
368 | ||
369 | This rest can currently only assume the value "0.0" (zero), | |
370 | "-0.5" (minus one half) or "0.5" (one half), provided you | |
371 | use only integral or multiples of 0.5 as offsets. A rest | |
372 | of zero indicates that the calculation yielded an exact | |
373 | result. If the rest is 0.5 or -0.5, this is to be interpreted | |
374 | as "the resulting date at 12:00 o'clock", instead of as "the | |
375 | resulting date at 0:00 o'clock". | |
376 | ||
377 | The rest is always positive (or zero) if the offset "DELTA" | |
378 | is positive (or zero), and always negative (or zero) if the | |
379 | offset is negative (or zero). | |
380 | ||
381 | Example: | |
382 | ||
383 | #!perl | |
384 | use Date::Calendar; | |
385 | use Date::Calendar::Profiles qw( $Profiles ); | |
386 | $year = shift; | |
387 | $cal = Date::Calendar->new( $Profiles->{'sdm-MUC'} ); | |
388 | ($date,$rest) = $cal->add_delta_workdays($year,1,3, -3); | |
389 | $date->date_format(1); | |
390 | print "\$date = $date, \$rest = $rest.\n"; | |
391 | __END__ | |
392 | ||
393 | This program calculates "January 3rd of the given year minus | |
394 | 3 work days": | |
395 | ||
396 | > perl test.pl 2001 | |
397 | $date = 28-Dec-2000, $rest = 0. | |
398 | > perl test.pl 2002 | |
399 | $date = 28-Dec-2001, $rest = -0.5. | |
400 | ||
401 | Note that December 31st is a "half" holiday in 2001 for the | |
402 | calendar profile used in this example. | |
403 | ||
404 | You can easily verify the results above with the help of the | |
405 | "calendar.cgi" CGI script or the "linearcal.pl" script from | |
406 | the "examples" subdirectory in the Date::Calc distribution. | |
407 | ||
408 | =item * | |
409 | ||
410 | C<$flag = $calendar-E<gt>is_full(YEAR,MONTH,DAY|DATE);> | |
411 | ||
412 | This method returns "true" ("1") if the bit corresponding to | |
413 | the given date is set in the bit vector representing "full" | |
414 | holidays, and "false" ("0") otherwise. | |
415 | ||
416 | I.e., the method returns "true" if the given date is a (full) | |
417 | holiday (according to the calendar profile associated with the | |
418 | given calendar object). | |
419 | ||
420 | The corresponding Date::Calendar::Year object is created first | |
421 | and stored in the calendar object's cache if necessary (if it's | |
422 | not already there). | |
423 | ||
424 | Note that you can get a reference to this bit vector (in order | |
425 | to use this bit vector in bit vector operations) as follows: | |
426 | ||
427 | $vec_full = $calendar->year($year)->vec_full(); | |
428 | ||
429 | The number of bits in this bit vector is the same as the number | |
430 | of days in the given year "C<$year>", which you can retrieve | |
431 | through either "C<$days = $vec_full-E<gt>Size();>" or | |
432 | "C<$days = $year-E<gt>val_days();>". | |
433 | ||
434 | See L<Date::Calendar::Year(3)> and L<Bit::Vector(3)> for more | |
435 | details. | |
436 | ||
437 | =item * | |
438 | ||
439 | C<$flag = $calendar-E<gt>is_half(YEAR,MONTH,DAY|DATE);> | |
440 | ||
441 | This method returns "true" ("1") if the bit corresponding to | |
442 | the given date is set in the bit vector representing "half" | |
443 | holidays, and "false" ("0") otherwise. | |
444 | ||
445 | I.e., the method returns "true" if the given date is a half | |
446 | holiday (according to the calendar profile associated with the | |
447 | given calendar object). | |
448 | ||
449 | Note that if a date is a "full" holiday, the "half" bit is | |
450 | never set, even if you try to do so in your calendar profile, | |
451 | on purpose or by accident. | |
452 | ||
453 | The corresponding Date::Calendar::Year object is created first | |
454 | and stored in the calendar object's cache if necessary (if it's | |
455 | not already there). | |
456 | ||
457 | Note that you can get a reference to this bit vector (in order | |
458 | to use this bit vector in bit vector operations) as follows: | |
459 | ||
460 | $vec_half = $calendar->year($year)->vec_half(); | |
461 | ||
462 | The number of bits in this bit vector is the same as the number | |
463 | of days in the given year "C<$year>", which you can retrieve | |
464 | through either "C<$days = $vec_half-E<gt>Size();>" or | |
465 | "C<$days = $year-E<gt>val_days();>". | |
466 | ||
467 | See L<Date::Calendar::Year(3)> and L<Bit::Vector(3)> for more | |
468 | details. | |
469 | ||
470 | =item * | |
471 | ||
472 | C<$flag = $calendar-E<gt>is_work(YEAR,MONTH,DAY|DATE);> | |
473 | ||
474 | This method returns "true" ("1") if the bit corresponding to | |
475 | the given date is set in the bit vector used to perform all | |
476 | sorts of calculations, and "false" ("0") otherwise. | |
477 | ||
478 | The corresponding Date::Calendar::Year object is created first | |
479 | and stored in the calendar object's cache if necessary (if it's | |
480 | not already there). | |
481 | ||
482 | B<BEWARE> that the "work" in this method's name does B<NOT> | |
483 | come from "work days"! | |
484 | ||
485 | It comes from the fact that the corresponding bit vector can | |
486 | be used for any "work" that you need to do. In other words, | |
487 | it's a "work space". | |
488 | ||
489 | Therefore, this bit vector might contain about everything you | |
490 | could imagine - including a bit pattern which marks all "work | |
491 | days" with set bits, if it so happens! | |
492 | ||
493 | But you better don't rely on it, unless you put the bit pattern | |
494 | there yourself in the first place. | |
495 | ||
496 | Note that you can get a reference to this bit vector (in order | |
497 | to fill it with any bit pattern you like) as follows: | |
498 | ||
499 | $vec_work = $calendar->year($year)->vec_work(); | |
500 | ||
501 | The number of bits in this bit vector is the same as the number | |
502 | of days in the given year "C<$year>", which you can retrieve | |
503 | through either "C<$days = $vec_work-E<gt>Size();>" or | |
504 | "C<$days = $year-E<gt>val_days();>". | |
505 | ||
506 | See L<Date::Calendar::Year(3)> and L<Bit::Vector(3)> for more | |
507 | details. | |
508 | ||
509 | =back | |
510 | ||
511 | =head1 SEE ALSO | |
512 | ||
513 | Date::Calendar::Year(3), Date::Calendar::Profiles(3), | |
514 | Date::Calc::Object(3), Date::Calc(3), Bit::Vector(3). | |
515 | ||
516 | =head1 VERSION | |
517 | ||
518 | This man page documents "Date::Calendar" version 5.3. | |
519 | ||
520 | =head1 AUTHOR | |
521 | ||
522 | Steffen Beyer | |
523 | mailto:sb@engelschall.com | |
524 | http://www.engelschall.com/u/sb/download/ | |
525 | ||
526 | =head1 COPYRIGHT | |
527 | ||
528 | Copyright (c) 2000 - 2002 by Steffen Beyer. All rights reserved. | |
529 | ||
530 | =head1 LICENSE | |
531 | ||
532 | This package is free software; you can redistribute it and/or | |
533 | modify it under the same terms as Perl itself, i.e., under the | |
534 | terms of the "Artistic License" or the "GNU General Public License". | |
535 | ||
536 | Please refer to the files "Artistic.txt" and "GNU_GPL.txt" | |
537 | in this distribution for details! | |
538 | ||
539 | =head1 DISCLAIMER | |
540 | ||
541 | This package is distributed in the hope that it will be useful, | |
542 | but WITHOUT ANY WARRANTY; without even the implied warranty of | |
543 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. | |
544 | ||
545 | See the "GNU General Public License" for more details. | |
546 |