Commit | Line | Data |
---|---|---|
86530b38 AT |
1 | |
2 | =head1 NAME | |
3 | ||
4 | Date::Calendar::Year - Implements embedded "year" objects for Date::Calendar | |
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 | Note that Date::Calendar::Year (and Date::Calendar) can only deal | |
13 | with years lying within the range [1583..2299]. | |
14 | ||
15 | =head1 SYNOPSIS | |
16 | ||
17 | use Date::Calendar::Year qw( check_year empty_period ); | |
18 | use Date::Calendar::Year qw( :all ); # same as above | |
19 | ||
20 | check_year(YEAR|DATE); # dies if year < 1583 or year > 2299 | |
21 | empty_period(); # warns about empty interval if $^W is set | |
22 | ||
23 | $index = $year->date2index(YEAR,MONTH,DAY|DATE); | |
24 | $date = $year->index2date(INDEX); | |
25 | ||
26 | use Date::Calendar::Profiles qw( $Profiles ); | |
27 | $year_2000_US_FL = Date::Calendar::Year->new( 2000, $Profiles->{'US-FL'} [,LANG] ); | |
28 | $year_2001_DE_NW = Date::Calendar::Year->new( 2001, $Profiles->{'DE-NW'} [,LANG] ); | |
29 | ||
30 | $year = Date::Calendar::Year->new( 2001, {} ); | |
31 | $year->init( 2002, $Profiles->{'DE-SN'} [,LANG] ); | |
32 | ||
33 | $vector = $year->vec_full(); # vector of full holidays | |
34 | $vector = $year->vec_half(); # vector of half holidays | |
35 | $vector = $year->vec_work(); # NOT a vector of workdays but a workspace! | |
36 | $size = $year->val_days(); # number of days in that year, size of vectors | |
37 | $base = $year->val_base(); # number of days for [year,1,1] since [1,1,1] | |
38 | $number = $year->val_year(); # the year's number itself | |
39 | $number = $year->year(); # alias for val_year() | |
40 | ||
41 | @names = $year->labels(YEAR,MONTH,DAY|DATE); | |
42 | @holidays = $year->labels(); | |
43 | $holidays = $year->labels(); | |
44 | ||
45 | @dates = $year->search(PATTERN); | |
46 | $dates = $year->search(PATTERN); | |
47 | ||
48 | $days = $year->delta_workdays(YEAR,MONTH1,DAY1|DATE1 | |
49 | ,YEAR,MONTH2,DAY2|DATE2 | |
50 | ,FLAG1,FLAG2); | |
51 | ||
52 | ($date,$rest,$sign) = $year->add_delta_workdays(YEAR,MONTH,DAY|DATE | |
53 | ,DELTA,SIGN); | |
54 | ||
55 | $flag = $year->is_full(YEAR,MONTH,DAY|DATE); | |
56 | $flag = $year->is_half(YEAR,MONTH,DAY|DATE); | |
57 | $flag = $year->is_work(YEAR,MONTH,DAY|DATE); | |
58 | ||
59 | =head1 INTERFACE | |
60 | ||
61 | Note that whenever a year number, a date, a time or a combined | |
62 | date and time are expected as input parameters by one of the | |
63 | methods of this class, you can always pass a Date::Calc[::Object] | |
64 | date object or an array reference (of an array of appropriate | |
65 | length) instead! | |
66 | ||
67 | See L<Date::Calc::Object(3)> for more details. | |
68 | ||
69 | So instead of calling a given method like this: | |
70 | ||
71 | $object->method1( $year,$month,$day ); | |
72 | $object->method2( $year1,$month1,$day1, $year2,$month2,$day2 ); | |
73 | $object->method3( $year1, $year2, $year3 ); | |
74 | ||
75 | You can also call it like so: | |
76 | ||
77 | $object->method1( $date ); | |
78 | $object->method1( [1964,1,3] ); | |
79 | ||
80 | $object->method2( $year1,$month1,$day1, $date2 ); | |
81 | $object->method2( $date1, $year2,$month2,$day2 ); | |
82 | $object->method2( $date1, $date2 ); | |
83 | $object->method2( $year1,$month1,$day1, [2001,3,17] ); | |
84 | $object->method2( [1964,1,3], $year2,$month2,$day2 ); | |
85 | $object->method2( [1964,1,3], [2001,3,17] ); | |
86 | $object->method2( $date1, [2001,3,17] ); | |
87 | $object->method2( [1964,1,3], $date2 ); | |
88 | ||
89 | $object->method3( $year1, $date2, [2001,3,17] ); | |
90 | ||
91 | And similarly if a time or a combined date and time are expected. | |
92 | ||
93 | If you substitute an expected year number by an anonymous array | |
94 | (this is the recommended way of writing date constants, for | |
95 | increased readability of your programs), it must contain three | |
96 | values, nevertheless (otherwise the use of an anonymous array | |
97 | would be pointless). | |
98 | ||
99 | Don't confuse year numbers and their substitutes (a date object | |
100 | or an array reference) with Date::Calendar::Year objects, which | |
101 | are a totally different thing! | |
102 | ||
103 | But incidentally C<:-)>, you may also pass a Date::Calendar::Year | |
104 | object whenever a year number is expected. However, and perhaps | |
105 | against your expectations at times, only the year number from | |
106 | that object will be used, not the year object itself (the year | |
107 | object in question might be using the wrong profile!). | |
108 | ||
109 | Moreover, whenever a method of this class returns a date, it | |
110 | does so by returning a Date::Calc[::Object] date object. | |
111 | ||
112 | =head1 IMPLEMENTATION | |
113 | ||
114 | Each Date::Calendar::Year object consists mainly of three bit | |
115 | vectors, plus some administrative attributes, all stored in a | |
116 | (blessed) hash. | |
117 | ||
118 | All three bit vectors contain as many bits as there are days | |
119 | in the corresponding year, i.e., either 365 or 366. | |
120 | ||
121 | The first bit vector, called "FULL", contains set bits for | |
122 | Saturdays, Sundays and all "full" legal holidays (i.e., | |
123 | days off, on which you usually do not work). | |
124 | ||
125 | The second bit vector, called "HALF", contains set bits for | |
126 | all "half" holidays, i.e., holidays where you get only half | |
127 | a day off from work. | |
128 | ||
129 | The third and last bit vector, called "WORK", is used as a | |
130 | workspace, in which various calculations are performed | |
131 | throughout this module. | |
132 | ||
133 | Its name does B<NOT> come from "working days" (as you might | |
134 | think), but from "workspace". | |
135 | ||
136 | It only so happens that it is used to calculate the working | |
137 | days sometimes, at some places in this module. | |
138 | ||
139 | But you are free to use it yourself, for whatever calculation | |
140 | you would like to carry out yourself. | |
141 | ||
142 | The two other bit vectors, "FULL" and "HALF", should never be | |
143 | changed, unless you know B<EXACTLY> what you're doing! | |
144 | ||
145 | =head1 DESCRIPTION | |
146 | ||
147 | Functions | |
148 | ||
149 | =over 2 | |
150 | ||
151 | =item * | |
152 | ||
153 | C<check_year(YEAR);> | |
154 | ||
155 | This function checks that the given year lies in the permitted | |
156 | range [1583..2299]. It returns nothing in case of success, and | |
157 | throws an exception ("given year out of range [1583..2299]") | |
158 | otherwise. | |
159 | ||
160 | =item * | |
161 | ||
162 | C<empty_period();> | |
163 | ||
164 | This function issues a warning (from the perspective of the | |
165 | caller of a Date::* module) that the given range of dates is | |
166 | empty ("dates interval is empty"), provided that warnings are | |
167 | enabled (i.e., "C<$^W>" is true). | |
168 | ||
169 | This function is currently used by the method "delta_workdays()" | |
170 | in this class, and by its equivalent from the Date::Calendar | |
171 | module. | |
172 | ||
173 | It is called whenever the range of dates of which the difference | |
174 | in working days is to be calculated is empty. This can happen for | |
175 | instance if you specify two adjacent dates both of which are not | |
176 | to be included in the difference. | |
177 | ||
178 | =back | |
179 | ||
180 | Methods | |
181 | ||
182 | =over 2 | |
183 | ||
184 | =item * | |
185 | ||
186 | C<$index = $year-E<gt>date2index(YEAR,MONTH,DAY|DATE);> | |
187 | ||
188 | This method converts a given date into the number of the day in | |
189 | that year (this is sometimes also referred to as the "julian" | |
190 | date), i.e., a number between 0 (for January 1st) and the number | |
191 | of days in the given year minus one, i.e., 364 or 365 (for | |
192 | December 31st). | |
193 | ||
194 | You may need this in order to access the bit vectors returned | |
195 | by the methods "vec_full()", "vec_half()" and "vec_work()". | |
196 | ||
197 | Note that there are shorthand methods in this module called | |
198 | "is_full()", "is_half()" and "is_work()", which serve to test | |
199 | individual bits of the three bit vectors which are a part of | |
200 | each Date::Calendar::Year object. | |
201 | ||
202 | An exception ("given year != object's year") is thrown if the | |
203 | year associated with the year object itself and the year from | |
204 | the given date do not match. | |
205 | ||
206 | An exception ("invalid date") is also thrown if the given | |
207 | arguments do not constitute a valid date, or ("given year | |
208 | out of range [1583..2299]") if the given year lies outside | |
209 | of the permitted range. | |
210 | ||
211 | =item * | |
212 | ||
213 | C<$date = $year-E<gt>index2date(INDEX);> | |
214 | ||
215 | This method converts an index (or "julian date") for the | |
216 | given year back into a date. | |
217 | ||
218 | An exception ("invalid index") is thrown if the given index | |
219 | is outside of the permitted range for the given year, i.e., | |
220 | C<[0..364]> or C<[0..365]>. | |
221 | ||
222 | Note that this method returns a Date::Calc B<OBJECT>! | |
223 | ||
224 | =item * | |
225 | ||
226 | C<$year_2000_US_FL = Date::Calendar::Year-E<gt>new( 2000, $Profiles-E<gt>{'US-FL'} [,LANG] );> | |
227 | ||
228 | C<$year_2001_DE_NW = Date::Calendar::Year-E<gt>new( 2001, $Profiles-E<gt>{'DE-NW'} [,LANG] );> | |
229 | ||
230 | C<$year = Date::Calendar::Year-E<gt>new( 2001, {} );> | |
231 | ||
232 | This is the constructor method. Call it to create a new | |
233 | Date::Calendar::Year object. | |
234 | ||
235 | The first argument must be a year number in the range | |
236 | [1583..2299]. | |
237 | ||
238 | The second argument must be the reference of a hash, | |
239 | which usually contains names of holidays and commemorative | |
240 | days as keys and strings containing the date or formula | |
241 | for each holiday as values. | |
242 | ||
243 | Reading this hash and initializing the object's internal | |
244 | data is performed by an extra method, called "init()", | |
245 | which is called internally by the constructor method, | |
246 | and which is described immediately below, after this | |
247 | method. | |
248 | ||
249 | In case you call the "init()" method yourself, explicitly, | |
250 | after creating the object, you can pass an empty profile | |
251 | (e.g., just an empty anonymous hash) to the "new()" method | |
252 | in order to improve performance. | |
253 | ||
254 | The third argument is optional, and must consist of | |
255 | the valid name or number of a language as provided by | |
256 | the Date::Calc(3) module if given. | |
257 | ||
258 | This argument determines which language shall be used | |
259 | when reading the profile, since the profile may contain | |
260 | names of months and weekdays in its formulas in that | |
261 | language. | |
262 | ||
263 | The default is English if none is specified. | |
264 | ||
265 | =item * | |
266 | ||
267 | C<$year-E<gt>init( 2002, $Profiles-E<gt>{'DE-SN'} [,LANG] );> | |
268 | ||
269 | This method is called by the "new()" constructor method, | |
270 | internally, and has the same arguments as the latter. | |
271 | ||
272 | See immediately above for a description of these arguments. | |
273 | ||
274 | Note that you can also call this method explicitly yourself, | |
275 | if needed, and you can of course subclass the Date::Calendar::Year | |
276 | class and override the "init()" method with an method of your own. | |
277 | ||
278 | The holiday scheme or "profile" (i.e., the reference of | |
279 | a hash passed as the second argument to this method) must | |
280 | obey the following semantics and syntax: | |
281 | ||
282 | The keys are the names of the holiday or commemorative day | |
283 | in question. Keys must be unique (but see further below). | |
284 | ||
285 | The difference between a holiday and a commemorative day is | |
286 | that you (usually) get a day off on a holiday, whereas on a | |
287 | purely commemorative day, you don't. | |
288 | ||
289 | A commemorative day is just a date with a name, nothing more. | |
290 | ||
291 | The values belonging to these keys can either be the code | |
292 | reference of a callback function (see L<Date::Calendar::Profiles(3)> | |
293 | for more details and examples), or a string. | |
294 | ||
295 | All other values cause a fatal error with program abortion. | |
296 | ||
297 | The strings can specify three types of dates: | |
298 | ||
299 | - fixed dates | |
300 | (like New Year, or first of January), | |
301 | ||
302 | - dates relative to Easter Sunday | |
303 | (like Ascension = Easter Sunday + 39 days), and | |
304 | ||
305 | - the 1st, 2nd, 3rd, 4th or last | |
306 | of a given day of week in a given month | |
307 | (like "the 4th Thursday of November", or Thanksgiving). | |
308 | ||
309 | All other types of dates must be specified via callback | |
310 | functions. | |
311 | ||
312 | Note that the "last" of a given day of week is written as | |
313 | the "5th", because the last is always either the 5th or the | |
314 | 4th of the given day of week. So the "init()" module first | |
315 | calculates the 5th of the requested day of week, and if that | |
316 | doesn't exist, takes the 4th instead. | |
317 | ||
318 | There are also two modifier characters which may prefix the | |
319 | string with the date formula, "#" and ":". | |
320 | ||
321 | The character "#" (mnemonic: it's only a comment) signals | |
322 | that the date in question is a purely commemorative day, | |
323 | i.e., it will not enter into any date calculations, but | |
324 | can be queried with the "labels()" and "search()" methods, | |
325 | and appears when printing a calendar, for instance. | |
326 | ||
327 | The character ":" (mnemonic: divided into two halfs) specifies | |
328 | that the date in question is only a "half" holiday, i.e., you | |
329 | only get half a day off instead of a full day. Some companies | |
330 | have this sort of thing. C<:-)> | |
331 | ||
332 | The exact syntax for the date formula strings is the following | |
333 | (by example): | |
334 | ||
335 | - Fixed dates: | |
336 | ||
337 | "Christmas" => "24.12", # European format (day, month) | |
338 | "Christmas" => "24.12.", | |
339 | ||
340 | "Christmas" => "24Dec", | |
341 | "Christmas" => "24.Dec", | |
342 | "Christmas" => "24Dec.", | |
343 | "Christmas" => "24.Dec.", | |
344 | ||
345 | "Christmas" => "24-12", | |
346 | "Christmas" => "24-12-", | |
347 | ||
348 | "Christmas" => "24-Dec", | |
349 | "Christmas" => "24-Dec-", | |
350 | ||
351 | "Christmas" => "12/25", # American format (month, day) | |
352 | "Christmas" => "Dec25", | |
353 | "Christmas" => "Dec/25", | |
354 | ||
355 | - Dates relative to Easter Sunday: | |
356 | ||
357 | "Ladies' Carnival" => "-52", | |
358 | "Carnival Monday" => "-48", | |
359 | "Mardi Gras" => "-47", | |
360 | "Ash Wednesday" => "-46", | |
361 | "Palm Sunday" => "-7", | |
362 | "Maundy Thursday" => "-3", | |
363 | "Good Friday" => "-2", | |
364 | "Easter Sunday" => "+0", | |
365 | "Easter Monday" => "+1", | |
366 | "Ascension" => "+39", | |
367 | "Whitsunday" => "+49", | |
368 | "Whitmonday" => "+50", | |
369 | "Corpus Christi" => "+60", | |
370 | ||
371 | - The 1st, 2nd, 3rd, 4th or last day of week: | |
372 | ||
373 | "Thanksgiving" => "4Thu11", | |
374 | "Thanksgiving" => "4/Thu/Nov", | |
375 | "Columbus Day" => "2/Mon/Oct", | |
376 | "Columbus Day" => "2/Mon/10", | |
377 | "Columbus Day" => "2/1/Oct", | |
378 | "Columbus Day" => "2/1/10", | |
379 | "Memorial Day" => "5/Mon/May", # LAST Monday of May | |
380 | ||
381 | Remember that each of these date formula strings may | |
382 | also be prefixed with either "#" or ":": | |
383 | ||
384 | "Christmas" => ":24.12.", # only half a day off | |
385 | "Valentine's Day" => "#Feb/14", # not an official holiday | |
386 | ||
387 | Note that the name of the month or day of week may have any | |
388 | length you like, it just must specify the intended month or | |
389 | day of week unambiguously. So "D", "De", "Dec", "Dece", | |
390 | "Decem", "Decemb", "Decembe" and "December" would all | |
391 | be valid, for example. Note also that case is ignored. | |
392 | ||
393 | When specifying day and month numbers, or offsets relative | |
394 | to Easter Sunday, leading zeros are permitted (for nicely | |
395 | indented formatting, for instance) but ignored. | |
396 | ||
397 | Leading zeros are not permitted in front of the ordinal | |
398 | number [1..5] or the number of the day of week [1..7] | |
399 | when specifying the nth day of week in a month. | |
400 | ||
401 | B<BEWARE> that if keys are not unique in the source code, | |
402 | later entries will overwrite previous ones! I.e., | |
403 | ||
404 | ... | |
405 | "My special holiday" => "01-11", | |
406 | "My special holiday" => "02-11", | |
407 | ... | |
408 | ||
409 | will B<NOT> set two holidays of the same name, one on November | |
410 | first, the other on November second, but only one, on November | |
411 | second! | |
412 | ||
413 | Therefore, in order to use sets of defaults and to be able | |
414 | to override some of them, you must B<FIRST> include any hash | |
415 | containing the default definitions, and B<THEN> write down | |
416 | your own definitions (see also the Date::Calendar::Profiles | |
417 | module for examples of this!), like this: | |
418 | ||
419 | $defaults = | |
420 | { | |
421 | "Holiday #1" => "01-01", | |
422 | "Holiday #2" => "02-02", | |
423 | "Holiday #3" => "03-03" | |
424 | }; | |
425 | ||
426 | $variant1 = | |
427 | { | |
428 | %$defaults, | |
429 | "Holiday #2" => "09-02", | |
430 | "Holiday #4" => "04-04" | |
431 | }; | |
432 | ||
433 | This is because of the way hashes work in Perl. | |
434 | ||
435 | The "init()" method proceeds as follows: | |
436 | ||
437 | First it checks whether the given year number lies in | |
438 | the range [1583..2299]. A fatal error occurs if not. | |
439 | ||
440 | Then it determines the number of days in the requested | |
441 | year, and stores it in the given Date::Calendar::Year | |
442 | object. | |
443 | ||
444 | It then calls the Bit::Vector(3) module to allocate three | |
445 | bit vectors with a number of bits equal to the number of | |
446 | days in the requested year, and stores the three object | |
447 | references (of the bit vectors) in the Date::Calendar::Year | |
448 | object. | |
449 | ||
450 | (See also the description of the three methods "vec_full()", | |
451 | "vec_half()" and "vec_full()" immediately below.) | |
452 | ||
453 | It then sets the bits which correspond to Saturdays and | |
454 | Sundays in the "full holidays" bit vector. | |
455 | ||
456 | At last, it iterates over the keys of the given holiday | |
457 | scheme (of the hash referred to by the hash reference | |
458 | passed to the "init()" method as the second argument), | |
459 | evaluates the formula (or calls the given callback | |
460 | function), and sets the corresponding bit in the "full" | |
461 | or "half" holidays bit vector if the calculated date | |
462 | is valid. | |
463 | ||
464 | A fatal error occurs if the date formula cannot be parsed | |
465 | or if the date returned by a formula or callback function | |
466 | is invalid (e.g. 30-Feb-2001 or the like) or lies outside | |
467 | the given year (e.g. Easter+365). | |
468 | ||
469 | Finally, the "init()" method makes sure that days marked | |
470 | as "full" holidays do not appear as "half" holidays as | |
471 | well. | |
472 | ||
473 | Then the "init()" method returns. | |
474 | ||
475 | Note that when deciphering the date formulas, the "init()" | |
476 | method uses the functions "Decode_Day_of_Week()" and | |
477 | "Decode_Month()" from the Date::Calc(3) module, which | |
478 | are language-dependent. | |
479 | ||
480 | Therefore the "init()" method allows you to pass it an optional | |
481 | third argument, which must consist of the valid name or number | |
482 | of a language as provided by the Date::Calc(3) module. | |
483 | ||
484 | For the time of scanning the given holiday scheme, the "init()" | |
485 | method will temporarily set the language to the value specified, | |
486 | and it will restore the original value before returning. | |
487 | ||
488 | The default is English if none is specified. | |
489 | ||
490 | This means that you can provide the names of months and days of | |
491 | week in your holiday profile in any of the languages supported | |
492 | by the Date::Calc(3) module, provided you give the "init()" | |
493 | method a clue (the third parameter) which language to expect. | |
494 | ||
495 | =item * | |
496 | ||
497 | C<$vector = $year-E<gt>vec_full();> | |
498 | ||
499 | This method returns a reference to the bit vector in the | |
500 | given year object which contains all "full" holidays. | |
501 | ||
502 | B<BEWARE> that you should B<NEVER> change the contents of this | |
503 | bit vector unless you know B<EXACTLY> what you're doing! | |
504 | ||
505 | You should usually only read from this bit vector, or use it | |
506 | as an operand in bit vector operations - but never as an | |
507 | lvalue. | |
508 | ||
509 | =item * | |
510 | ||
511 | C<$vector = $year-E<gt>vec_half();> | |
512 | ||
513 | This method returns a reference to the bit vector in the | |
514 | given year object which contains all "half" holidays. | |
515 | ||
516 | B<BEWARE> that you should B<NEVER> change the contents of this | |
517 | bit vector unless you know B<EXACTLY> what you're doing! | |
518 | ||
519 | You should usually only read from this bit vector, or use it | |
520 | as an operand in bit vector operations - but never as an | |
521 | lvalue. | |
522 | ||
523 | =item * | |
524 | ||
525 | C<$vector = $year-E<gt>vec_work();> | |
526 | ||
527 | This method returns a reference to the "workspace" bit vector | |
528 | in the given year object. | |
529 | ||
530 | Note that you cannot rely on the contents of this bit vector. | |
531 | ||
532 | You have to set it up yourself before performing any calculations | |
533 | with it. | |
534 | ||
535 | Currently the contents of this bit vector are modified by the | |
536 | two methods "delta_workdays()" and "add_delta_workdays()", in | |
537 | ways which are hard to predict. | |
538 | ||
539 | The size of this bit vector can be determined through either | |
540 | "C<$days = $vector-E<gt>Size();>" or | |
541 | "C<$days = $year-E<gt>val_days();>". | |
542 | ||
543 | =item * | |
544 | ||
545 | C<$size = $year-E<gt>val_days();> | |
546 | ||
547 | This method returns the number of days in the given year object, | |
548 | i.e., either 365 or 366. This is also the size (number of bits) | |
549 | of the three bit vectors contained in the given year object. | |
550 | ||
551 | =item * | |
552 | ||
553 | C<$base = $year-E<gt>val_base();> | |
554 | ||
555 | This method returns the value of the expression | |
556 | "C<Date_to_Days($year-E<gt>val_year(),1,1)>", or in other words, | |
557 | the number of days between January 1st of the year 1 and January | |
558 | 1st of the given year, plus one. | |
559 | ||
560 | This value is used internally by the method "date2index()" in order | |
561 | to calculate the "julian" date or day of the year for a given date. | |
562 | ||
563 | The expression above is computed only once in method "init()" and | |
564 | then stored in one of the year object's attributes, of which this | |
565 | method just returns the value. | |
566 | ||
567 | =item * | |
568 | ||
569 | C<$number = $year-E<gt>val_year();> | |
570 | ||
571 | C<$number = $year-E<gt>year();> | |
572 | ||
573 | These two methods are identical, the latter being a shortcut of | |
574 | the former. | |
575 | ||
576 | They return the number of the year for which a calendar has been | |
577 | stored in the given year object. | |
578 | ||
579 | The method name "val_year()" is used here in order to be consistent | |
580 | with the other attribute accessor methods of this class, and the | |
581 | method "year()" is necessary in order to be able to pass | |
582 | Date::Calendar::Year objects as parameters instead of a year number | |
583 | in the methods of the Date::Calendar and Date::Calendar::Year | |
584 | modules. | |
585 | ||
586 | =item * | |
587 | ||
588 | C<@names = $year-E<gt>labels(YEAR,MONTH,DAY|DATE);> | |
589 | ||
590 | C<@holidays = $year-E<gt>labels();> | |
591 | ||
592 | C<$holidays = $year-E<gt>labels();> | |
593 | ||
594 | If any arguments are given, they are supposed to represent a | |
595 | date. In that case, a list of all labels (= names of holidays) | |
596 | associated with that date are returned. The first item returned | |
597 | is always the name of the day of week for that date. | |
598 | ||
599 | If no arguments are given, the list of all available labels in | |
600 | the given year is returned. This list does B<NOT> include any | |
601 | names of the days of week (which would be pointless in this case). | |
602 | ||
603 | In list context, the resulting list itself is returned. In scalar | |
604 | context, the number of items in the resulting list is returned. | |
605 | ||
606 | =item * | |
607 | ||
608 | C<@dates = $year-E<gt>search(PATTERN);> | |
609 | ||
610 | C<$dates = $year-E<gt>search(PATTERN);> | |
611 | ||
612 | This method searches through all the labels of the given year | |
613 | and returns a list of date objects with all dates whose labels | |
614 | match the given pattern. | |
615 | ||
616 | Note that this is a simple, case-insensitive substring search, | |
617 | B<NOT> a full-fledged regular expression search! | |
618 | ||
619 | The result is guaranteed to be sorted chronologically. | |
620 | ||
621 | In scalar context, only the number of items in the resulting list | |
622 | is returned, instead of the resulting list itself (as in list context). | |
623 | ||
624 | =item * | |
625 | ||
626 | C<$days = $year-E<gt>delta_workdays(YEAR,MONTH1,DAY1, YEAR,MONTH2,DAY2, FLAG1,FLAG2);> | |
627 | ||
628 | C<$days = $year-E<gt>delta_workdays(DATE1,DATE2,FLAG1,FLAG2);> | |
629 | ||
630 | This method calculates the number of work days (i.e., the number | |
631 | of days, but excluding all holidays) between two dates. | |
632 | ||
633 | In other words, this method is equivalent to the "Delta_Days()" | |
634 | function of the Date::Calc module, except that it disregards | |
635 | holidays in its counting. | |
636 | ||
637 | The two flags indicate whether the start and end dates should be | |
638 | included in the counting (that is, of course, only in case they | |
639 | aren't holidays), or not. | |
640 | ||
641 | It is common, for example, that you want to know how many work | |
642 | days are left between the current date and a given deadline. | |
643 | ||
644 | Typically, you will want to count the current date but not the | |
645 | deadline's date. So you would specify "true" ("1") for FLAG1 | |
646 | and "false" ("0") for FLAG2 in order to achieve that. | |
647 | ||
648 | In other words, a value of "true" means "including this date", | |
649 | a value of "false" means "excluding this date". | |
650 | ||
651 | As with the "Delta_Days()" function from the Date::Calc module, | |
652 | the dates have to be given in chronological order to yield a | |
653 | positive result. If the dates are reversed, the result will | |
654 | be negative. | |
655 | ||
656 | The parameter FLAG1 is associated with the first given date, | |
657 | the parameter FLAG2 with the second given date (regardless | |
658 | of whether the dates are in chronological order or not). | |
659 | ||
660 | An exception ("given year != object's year") is thrown if the | |
661 | year number of either of the two given dates does not match the | |
662 | year number associated with the given year object. | |
663 | ||
664 | An exception ("invalid date") is also raised if either of the | |
665 | two date arguments does not constitute a valid date. | |
666 | ||
667 | =item * | |
668 | ||
669 | C<($date,$rest,$sign) = $year-E<gt>add_delta_workdays(YEAR,MONTH,DAY, DELTA, SIGN);> | |
670 | ||
671 | C<($date,$rest,$sign) = $year-E<gt>add_delta_workdays(DATE,DELTA,SIGN);> | |
672 | ||
673 | This method is the equivalent of the "Add_Delta_Days()" function | |
674 | from the Date::Calc module, except that it adds work days and | |
675 | skips holidays. | |
676 | ||
677 | In other words, you can add or subtract a number of work days | |
678 | "DELTA" to/from a given date and get a new date as the result | |
679 | (as a Date::Calc object). | |
680 | ||
681 | You add days (i.e., you go forward in time) with a positive | |
682 | offset "DELTA", and you subtract days (i.e., you go backwards | |
683 | in time) with a negative offset. | |
684 | ||
685 | Note that an exception ("invalid date") is raised if the | |
686 | given date argument (the "start" date) does not constitute | |
687 | a valid date. | |
688 | ||
689 | Beware that this method is limited to date calculations within | |
690 | a single year (in contrast to the method with the same name | |
691 | from the Date::Calendar module). | |
692 | ||
693 | Therefore, the method does not only return a date (object), | |
694 | but also a "rest" and a "sign". | |
695 | ||
696 | The "rest" indicates how many days are still left from your | |
697 | original DELTA after going in the desired direction and | |
698 | reaching a year boundary. | |
699 | ||
700 | The "sign" indicates in which direction (future or past) one | |
701 | needs to go in order to "eat up" the "rest" (by subtracting | |
702 | a day from the "rest" for each work day passed), or to adjust | |
703 | the resulting date (in order to skip any holidays directly | |
704 | after a year boundary), if at all. | |
705 | ||
706 | The "sign" is -1 for going backwards in time, +1 for going | |
707 | forward, and 0 if the result doesn't need any more fixing | |
708 | (for instance because the result lies in the same year as | |
709 | the starting date). | |
710 | ||
711 | The method "add_delta_workdays()" from the Date::Calendar | |
712 | module uses the "rest" and "sign" return values from this | |
713 | method in order to perform calculations which may cross | |
714 | year boundaries. | |
715 | ||
716 | Therefore, it is not recommended to use this method here | |
717 | directly, as it is rather clumsy to use, but to use the | |
718 | method with the same name from the Date::Calendar module | |
719 | instead, which does the same but is much easier to use | |
720 | and moreover allows calculations which cross an arbitrary | |
721 | number of year boundaries. | |
722 | ||
723 | =item * | |
724 | ||
725 | C<$flag = $year-E<gt>is_full(YEAR,MONTH,DAY|DATE);> | |
726 | ||
727 | This method returns "true" ("1") if the bit corresponding to | |
728 | the given date is set in the bit vector representing "full" | |
729 | holidays, and "false" ("0") otherwise. | |
730 | ||
731 | I.e., the method returns "true" if the given date is a (full) | |
732 | holiday (according to the calendar profile associated with the | |
733 | given year object). | |
734 | ||
735 | =item * | |
736 | ||
737 | C<$flag = $year-E<gt>is_half(YEAR,MONTH,DAY|DATE);> | |
738 | ||
739 | This method returns "true" ("1") if the bit corresponding to | |
740 | the given date is set in the bit vector representing "half" | |
741 | holidays, and "false" ("0") otherwise. | |
742 | ||
743 | I.e., the method returns "true" if the given date is a half | |
744 | holiday (according to the calendar profile associated with the | |
745 | given year object). | |
746 | ||
747 | Note that if a date is a "full" holiday, the "half" bit is | |
748 | never set, even if you try to do so in your calendar profile, | |
749 | on purpose or by accident. | |
750 | ||
751 | =item * | |
752 | ||
753 | C<$flag = $year-E<gt>is_work(YEAR,MONTH,DAY|DATE);> | |
754 | ||
755 | This method returns "true" ("1") if the bit corresponding to | |
756 | the given date is set in the bit vector used to perform all | |
757 | sorts of calculations, and "false" ("0") otherwise. | |
758 | ||
759 | B<BEWARE> that the "work" in this method's name does B<NOT> | |
760 | come from "work days"! | |
761 | ||
762 | It comes from the fact that the corresponding bit vector can | |
763 | be used for any "work" that you need to do. In other words, | |
764 | it's a "work space". | |
765 | ||
766 | Therefore, this bit vector might contain about everything you | |
767 | could imagine - including a bit pattern which marks all "work | |
768 | days" with set bits, if it so happens! | |
769 | ||
770 | But you better don't rely on it, unless you put the bit pattern | |
771 | there yourself in the first place. | |
772 | ||
773 | Note that you can get a reference to this bit vector (in order | |
774 | to fill it with any bit pattern you like) using the method | |
775 | "vec_work()", described further above in this document. | |
776 | ||
777 | The number of bits in this bit vector is the same as the number | |
778 | of days in the given year "C<$year>", which you can retrieve | |
779 | through either "C<$days = $year-E<gt>vec_work-E<gt>Size();>" | |
780 | or "C<$days = $year-E<gt>val_days();>". | |
781 | ||
782 | See also L<Bit::Vector(3)> for more details. | |
783 | ||
784 | =back | |
785 | ||
786 | =head1 SEE ALSO | |
787 | ||
788 | Bit::Vector(3), Date::Calendar(3), Date::Calendar::Profiles(3), | |
789 | Date::Calc::Object(3), Date::Calc(3). | |
790 | ||
791 | =head1 VERSION | |
792 | ||
793 | This man page documents "Date::Calendar::Year" version 5.3. | |
794 | ||
795 | =head1 AUTHOR | |
796 | ||
797 | Steffen Beyer | |
798 | mailto:sb@engelschall.com | |
799 | http://www.engelschall.com/u/sb/download/ | |
800 | ||
801 | =head1 COPYRIGHT | |
802 | ||
803 | Copyright (c) 2000 - 2002 by Steffen Beyer. All rights reserved. | |
804 | ||
805 | =head1 LICENSE | |
806 | ||
807 | This package is free software; you can redistribute it and/or | |
808 | modify it under the same terms as Perl itself, i.e., under the | |
809 | terms of the "Artistic License" or the "GNU General Public License". | |
810 | ||
811 | Please refer to the files "Artistic.txt" and "GNU_GPL.txt" | |
812 | in this distribution for details! | |
813 | ||
814 | =head1 DISCLAIMER | |
815 | ||
816 | This package is distributed in the hope that it will be useful, | |
817 | but WITHOUT ANY WARRANTY; without even the implied warranty of | |
818 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. | |
819 | ||
820 | See the "GNU General Public License" for more details. | |
821 |