1Date::Calendar::Year(3)User Contributed Perl DocumentatioDnate::Calendar::Year(3)
2
6 Date::Calendar::Year - Implements embedded "year" objects for
7 Date::Calendar
8
10 There is more than one way to do it - this is just one of them!
11
13 Note that Date::Calendar::Year (and Date::Calendar) can only deal with
14 years lying within the range [1583..2299].
15
17 use Date::Calendar::Year qw( check_year empty_period );
18 use Date::Calendar::Year qw( :all ); # same as above
19 check_year(YEAR⎪DATE); # dies if year < 1583 or year > 2299
21 empty_period(); # warns about empty interval if $^W is set
22 $index = $year->date2index(YEAR,MONTH,DAY⎪DATE);
24 $date = $year->index2date(INDEX);
25 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 $year = Date::Calendar::Year->new( 2001, {} );
31 $year->init( 2002, $Profiles->{'DE-SN'} [,LANG] );
32 $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 @names = $year->labels(YEAR,MONTH,DAY⎪DATE);
42 @holidays = $year->labels();
43 $holidays = $year->labels();
44 @dates = $year->search(PATTERN);
46 $dates = $year->search(PATTERN);
47 $hashref = $year->tags(YEAR,MONTH,DAY⎪DATE);
49 $hashref = $year->tags(INDEX);
50 $days = $year->delta_workdays(YEAR,MONTH1,DAY1⎪DATE1
52 ,YEAR,MONTH2,DAY2⎪DATE2
53 ,FLAG1,FLAG2);
54 ($date,$rest,$sign) = $year->add_delta_workdays(YEAR,MONTH,DAY⎪DATE
56 ,DELTA,SIGN);
57 $flag = $year->is_full(YEAR,MONTH,DAY⎪DATE);
59 $flag = $year->is_half(YEAR,MONTH,DAY⎪DATE);
60 $flag = $year->is_work(YEAR,MONTH,DAY⎪DATE);
61
63 Note that whenever a year number, a date, a time or a combined date and
64 time are expected as input parameters by one of the methods of this
65 class, you can always pass a Date::Calc[::Object] date object or an
66 array reference (of an array of appropriate length) instead!
67 See Date::Calc::Object(3) for more details.
69 So instead of calling a given method like this:
71 $object->method1( $year,$month,$day );
73 $object->method2( $year1,$month1,$day1, $year2,$month2,$day2 );
74 $object->method3( $year1, $year2, $year3 );
75 You can also call it like so:
77 $object->method1( $date );
79 $object->method1( [1964,1,3] );
80 $object->method2( $year1,$month1,$day1, $date2 );
82 $object->method2( $date1, $year2,$month2,$day2 );
83 $object->method2( $date1, $date2 );
84 $object->method2( $year1,$month1,$day1, [2001,3,17] );
85 $object->method2( [1964,1,3], $year2,$month2,$day2 );
86 $object->method2( [1964,1,3], [2001,3,17] );
87 $object->method2( $date1, [2001,3,17] );
88 $object->method2( [1964,1,3], $date2 );
89 $object->method3( $year1, $date2, [2001,3,17] );
91 And similarly if a time or a combined date and time are expected.
93 If you substitute an expected year number by an anonymous array (this
95 is the recommended way of writing date constants, for increased read‐
96 ability of your programs), it must contain three values, nevertheless
97 (otherwise the use of an anonymous array would be pointless).
98 Don't confuse year numbers and their substitutes (a date object or an
100 array reference) with Date::Calendar::Year objects, which are a totally
101 different thing!
102 But incidentally ":-)", you may also pass a Date::Calendar::Year object
104 whenever a year number is expected. However, and perhaps against your
105 expectations at times, only the year number from that object will be
106 used, not the year object itself (the year object in question might be
107 using the wrong profile!).
108 Moreover, whenever a method of this class returns a date, it does so by
110 returning a Date::Calc[::Object] date object.
111
113 Each Date::Calendar::Year object consists mainly of three bit vectors,
114 plus some administrative attributes, all stored in a (blessed) hash.
115 All three bit vectors contain as many bits as there are days in the
117 corresponding year, i.e., either 365 or 366.
118 The first bit vector, called "FULL", contains set bits for Saturdays,
120 Sundays and all "full" legal holidays (i.e., days off, on which you
121 usually do not work).
122 The second bit vector, called "HALF", contains set bits for all "half"
124 holidays, i.e., holidays where you get only half a day off from work.
125 The third and last bit vector, called "WORK", is used as a workspace,
127 in which various calculations are performed throughout this module.
128 Its name does NOT come from "working days" (as you might think), but
130 from "workspace".
131 It only so happens that it is used to calculate the working days some‐
133 times, at some places in this module.
134 But you are free to use it yourself, for whatever calculation you would
136 like to carry out yourself.
137 The two other bit vectors, "FULL" and "HALF", should never be changed,
139 unless you know EXACTLY what you're doing!
140
142 Functions
143 · "check_year(YEAR);"
145 This function checks that the given year lies in the permitted range
147 [1583..2299]. It returns nothing in case of success, and throws an
148 exception ("given year out of range [1583..2299]") otherwise.
149 · "empty_period();"
151 This function issues a warning (from the perspective of the caller of
153 a Date::* module) that the given range of dates is empty ("dates
154 interval is empty"), provided that warnings are enabled (i.e., "$^W"
155 is true).
156 This function is currently used by the method "delta_workdays()" in
158 this class, and by its equivalent from the Date::Calendar module.
159 It is called whenever the range of dates of which the difference in
161 working days is to be calculated is empty. This can happen for
162 instance if you specify two adjacent dates both of which are not to
163 be included in the difference.
164 Methods
166 · "$index = $year->date2index(YEAR,MONTH,DAY⎪DATE);"
168 This method converts a given date into the number of the day in that
170 year (this is sometimes also referred to as the "julian" date), i.e.,
171 a number between 0 (for January 1st) and the number of days in the
172 given year minus one, i.e., 364 or 365 (for December 31st).
173 You may need this in order to access the bit vectors returned by the
175 methods "vec_full()", "vec_half()" and "vec_work()".
176 Note that there are shorthand methods in this module called
178 "is_full()", "is_half()" and "is_work()", which serve to test indi‐
179 vidual bits of the three bit vectors which are a part of each
180 Date::Calendar::Year object.
181 An exception ("given year != object's year") is thrown if the year
183 associated with the year object itself and the year from the given
184 date do not match.
185 An exception ("invalid date") is also thrown if the given arguments
187 do not constitute a valid date, or ("given year out of range
188 [1583..2299]") if the given year lies outside of the permitted range.
189 · "$date = $year->index2date(INDEX);"
191 This method converts an index (or "julian date") for the given year
193 back into a date.
194 An exception ("invalid index") is thrown if the given index is out‐
196 side of the permitted range for the given year, i.e., "[0..364]" or
197 "[0..365]".
198 Note that this method returns a Date::Calc OBJECT!
200 · "$year_2000_US_FL = Date::Calendar::Year->new( 2000, $Pro‐
202 files->{'US-FL'} [,LANG] );"
203 "$year_2001_DE_NW = Date::Calendar::Year->new( 2001, $Pro‐
205 files->{'DE-NW'} [,LANG] );"
206 "$year = Date::Calendar::Year->new( 2001, {} );"
208 This is the constructor method. Call it to create a new Date::Calen‐
210 dar::Year object.
211 The first argument must be a year number in the range [1583..2299].
213 The second argument must be the reference of a hash, which usually
215 contains names of holidays and commemorative days as keys and strings
216 containing the date or formula for each holiday as values.
217 Reading this hash and initializing the object's internal data is per‐
219 formed by an extra method, called "init()", which is called inter‐
220 nally by the constructor method, and which is described immediately
221 below, after this method.
222 In case you call the "init()" method yourself, explicitly, after cre‐
224 ating the object, you can pass an empty profile (e.g., just an empty
225 anonymous hash) to the "new()" method in order to improve perfor‐
226 mance.
227 The third argument is optional, and must consist of the valid name or
229 number of a language as provided by the Date::Calc(3) module if
230 given.
231 This argument determines which language shall be used when reading
233 the profile, since the profile may contain names of months and week‐
234 days in its formulas in that language.
235 The default is English if none is specified.
237 · "$year->init( 2002, $Profiles->{'DE-SN'} [,LANG] );"
239 This method is called by the "new()" constructor method, internally,
241 and has the same arguments as the latter.
242 See immediately above for a description of these arguments.
244 Note that you can also call this method explicitly yourself, if
246 needed, and you can of course subclass the Date::Calendar::Year class
247 and override the "init()" method with an method of your own.
248 The holiday scheme or "profile" (i.e., the reference of a hash passed
250 as the second argument to this method) must obey the following seman‐
251 tics and syntax:
252 The keys are the names of the holiday or commemorative day in ques‐
254 tion. Keys must be unique (but see further below).
255 The difference between a holiday and a commemorative day is that you
257 (usually) get a day off on a holiday, whereas on a purely commemora‐
258 tive day, you don't.
259 A commemorative day is just a date with a name, nothing more.
261 The values belonging to these keys can either be the code reference
263 of a callback function (see Date::Calendar::Profiles(3) for more
264 details and examples), or a string.
265 All other values cause a fatal error with program abortion.
267 The strings can specify three types of dates:
269 - fixed dates
271 (like New Year, or first of January),
272 - dates relative to Easter Sunday
274 (like Ascension = Easter Sunday + 39 days), and
275 - the 1st, 2nd, 3rd, 4th or last
277 of a given day of week in a given month
278 (like "the 4th Thursday of November", or Thanksgiving).
279 All other types of dates must be specified via callback functions.
281 Note that the "last" of a given day of week is written as the "5th",
283 because the last is always either the 5th or the 4th of the given day
284 of week. So the "init()" module first calculates the 5th of the
285 requested day of week, and if that doesn't exist, takes the 4th
286 instead.
287 There are also two modifier characters which may prefix the string
289 with the date formula, "#" and ":".
290 The character "#" (mnemonic: it's only a comment) signals that the
292 date in question is a purely commemorative day, i.e., it will not
293 enter into any date calculations, but can be queried with the
294 "labels()" and "search()" methods, and appears when printing a calen‐
295 dar, for instance.
296 The character ":" (mnemonic: divided into two halfs) specifies that
298 the date in question is only a "half" holiday, i.e., you only get
299 half a day off instead of a full day. Some companies have this sort
300 of thing. ":-)"
301 The exact syntax for the date formula strings is the following (by
303 example):
304 - Fixed dates:
306 "Christmas" => "24.12", # European format (day, month)
308 "Christmas" => "24.12.",
309 "Christmas" => "24Dec",
311 "Christmas" => "24.Dec",
312 "Christmas" => "24Dec.",
313 "Christmas" => "24.Dec.",
314 "Christmas" => "24-12",
316 "Christmas" => "24-12-",
317 "Christmas" => "24-Dec",
319 "Christmas" => "24-Dec-",
320 "Christmas" => "12/25", # American format (month, day)
322 "Christmas" => "Dec25",
323 "Christmas" => "Dec/25",
324 - Dates relative to Easter Sunday:
326 "Ladies' Carnival" => "-52",
328 "Carnival Monday" => "-48",
329 "Mardi Gras" => "-47",
330 "Ash Wednesday" => "-46",
331 "Palm Sunday" => "-7",
332 "Maundy Thursday" => "-3",
333 "Good Friday" => "-2",
334 "Easter Sunday" => "+0",
335 "Easter Monday" => "+1",
336 "Ascension" => "+39",
337 "Whitsunday" => "+49",
338 "Whitmonday" => "+50",
339 "Corpus Christi" => "+60",
340 - The 1st, 2nd, 3rd, 4th or last day of week:
342 "Thanksgiving" => "4Thu11",
344 "Thanksgiving" => "4/Thu/Nov",
345 "Columbus Day" => "2/Mon/Oct",
346 "Columbus Day" => "2/Mon/10",
347 "Columbus Day" => "2/1/Oct",
348 "Columbus Day" => "2/1/10",
349 "Memorial Day" => "5/Mon/May", # LAST Monday of May
350 Remember that each of these date formula strings may also be prefixed
352 with either "#" or ":":
353 "Christmas" => ":24.12.", # only half a day off
355 "Valentine's Day" => "#Feb/14", # not an official holiday
356 Note that the name of the month or day of week may have any length
358 you like, it just must specify the intended month or day of week
359 unambiguously. So "D", "De", "Dec", "Dece", "Decem", "Decemb",
360 "Decembe" and "December" would all be valid, for example. Note also
361 that case is ignored.
362 When specifying day and month numbers, or offsets relative to Easter
364 Sunday, leading zeros are permitted (for nicely indented formatting,
365 for instance) but ignored.
366 Leading zeros are not permitted in front of the ordinal number [1..5]
368 or the number of the day of week [1..7] when specifying the nth day
369 of week in a month.
370 BEWARE that if keys are not unique in the source code, later entries
372 will overwrite previous ones! I.e.,
373 ...
375 "My special holiday" => "01-11",
376 "My special holiday" => "02-11",
377 ...
378 will NOT set two holidays of the same name, one on November first,
380 the other on November second, but only one, on November second!
381 Therefore, in order to use sets of defaults and to be able to over‐
383 ride some of them, you must FIRST include any hash containing the
384 default definitions, and THEN write down your own definitions (see
385 also the Date::Calendar::Profiles module for examples of this!), like
386 this:
387 $defaults =
389 {
390 "Holiday #1" => "01-01",
391 "Holiday #2" => "02-02",
392 "Holiday #3" => "03-03"
393 };
394 $variant1 =
396 {
397 %$defaults,
398 "Holiday #2" => "09-02",
399 "Holiday #4" => "04-04"
400 };
401 This is because of the way hashes work in Perl.
403 The "init()" method proceeds as follows:
405 First it checks whether the given year number lies in the range
407 [1583..2299]. A fatal error occurs if not.
408 Then it determines the number of days in the requested year, and
410 stores it in the given Date::Calendar::Year object.
411 It then calls the Bit::Vector(3) module to allocate three bit vectors
413 with a number of bits equal to the number of days in the requested
414 year, and stores the three object references (of the bit vectors) in
415 the Date::Calendar::Year object.
416 (See also the description of the three methods "vec_full()",
418 "vec_half()" and "vec_full()" immediately below.)
419 It then sets the bits which correspond to Saturdays and Sundays in
421 the "full holidays" bit vector.
422 At last, it iterates over the keys of the given holiday scheme (of
424 the hash referred to by the hash reference passed to the "init()"
425 method as the second argument), evaluates the formula (or calls the
426 given callback function), and sets the corresponding bit in the
427 "full" or "half" holidays bit vector if the calculated date is valid.
428 A fatal error occurs if the date formula cannot be parsed or if the
430 date returned by a formula or callback function is invalid (e.g.
431 30-Feb-2001 or the like) or lies outside the given year (e.g.
432 Easter+365).
433 Finally, the "init()" method makes sure that days marked as "full"
435 holidays do not appear as "half" holidays as well.
436 Then the "init()" method returns.
438 Note that when deciphering the date formulas, the "init()" method
440 uses the functions "Decode_Day_of_Week()" and "Decode_Month()" from
441 the Date::Calc(3) module, which are language-dependent.
442 Therefore the "init()" method allows you to pass it an optional third
444 argument, which must consist of the valid name or number of a lan‐
445 guage as provided by the Date::Calc(3) module.
446 For the time of scanning the given holiday scheme, the "init()"
448 method will temporarily set the language to the value specified, and
449 it will restore the original value before returning.
450 The default is English if none is specified.
452 This means that you can provide the names of months and days of week
454 in your holiday profile in any of the languages supported by the
455 Date::Calc(3) module, provided you give the "init()" method a clue
456 (the third parameter) which language to expect.
457 · "$vector = $year->vec_full();"
459 This method returns a reference to the bit vector in the given year
461 object which contains all "full" holidays.
462 BEWARE that you should NEVER change the contents of this bit vector
464 unless you know EXACTLY what you're doing!
465 You should usually only read from this bit vector, or use it as an
467 operand in bit vector operations - but never as an lvalue.
468 · "$vector = $year->vec_half();"
470 This method returns a reference to the bit vector in the given year
472 object which contains all "half" holidays.
473 BEWARE that you should NEVER change the contents of this bit vector
475 unless you know EXACTLY what you're doing!
476 You should usually only read from this bit vector, or use it as an
478 operand in bit vector operations - but never as an lvalue.
479 · "$vector = $year->vec_work();"
481 This method returns a reference to the "workspace" bit vector in the
483 given year object.
484 Note that you cannot rely on the contents of this bit vector.
486 You have to set it up yourself before performing any calculations
488 with it.
489 Currently the contents of this bit vector are modified by the two
491 methods "delta_workdays()" and "add_delta_workdays()", in ways which
492 are hard to predict (depending on the calculations being performed).
493 The size of this bit vector can be determined through either ""$days
495 = $vector->Size();"" or ""$days = $year->val_days();"".
496 · "$size = $year->val_days();"
498 This method returns the number of days in the given year object,
500 i.e., either 365 or 366. This is also the size (number of bits) of
501 the three bit vectors contained in the given year object.
502 · "$base = $year->val_base();"
504 This method returns the value of the expression
506 ""Date_to_Days($year->val_year(),1,1)"", or in other words, the num‐
507 ber of days between January 1st of the year 1 and January 1st of the
508 given year, plus one.
509 This value is used internally by the method "date2index()" in order
511 to calculate the "julian" date or day of the year for a given date.
512 The expression above is computed only once in method "init()" and
514 then stored in one of the year object's attributes, of which this
515 method just returns the value.
516 · "$number = $year->val_year();"
518 "$number = $year->year();"
520 These two methods are identical, the latter being a shortcut of the
522 former.
523 They return the number of the year for which a calendar has been
525 stored in the given year object.
526 The method name "val_year()" is used here in order to be consistent
528 with the other attribute accessor methods of this class, and the
529 method "year()" is necessary in order to be able to pass Date::Calen‐
530 dar::Year objects as parameters instead of a year number in the meth‐
531 ods of the Date::Calendar and Date::Calendar::Year modules.
532 · "@names = $year->labels(YEAR,MONTH,DAY⎪DATE);"
534 "@holidays = $year->labels();"
536 "$holidays = $year->labels();"
538 If any arguments are given, they are supposed to represent a date. In
540 that case, a list of all labels (= names of holidays) associated with
541 that date are returned. The first item returned is always the name of
542 the day of week for that date.
543 If no arguments are given, the list of all available labels in the
545 given year is returned. This list does NOT include any names of the
546 days of week (which would be pointless in this case).
547 In list context, the resulting list itself is returned. In scalar
549 context, the number of items in the resulting list is returned.
550 · "@dates = $year->search(PATTERN);"
552 "$dates = $year->search(PATTERN);"
554 This method searches through all the labels of the given year and
556 returns a list of date objects with all dates whose labels match the
557 given pattern.
558 Note that this is a simple, case-insensitive substring search, NOT a
560 full-fledged regular expression search!
561 The result is guaranteed to be sorted chronologically.
563 In scalar context, only the number of items in the resulting list is
565 returned, instead of the resulting list itself (as in list context).
566 · "$hashref = $year->tags(YEAR,MONTH,DAY⎪DATE);"
568 "$hashref = $year->tags(INDEX);"
570 This method returns a hash reference for the given calendar and date
572 (or index). The hash it refers to is a copy of the calendar profile's
573 internal hash which contains the names for the given date as keys and
574 0, 1, 2, or 3 as their corresponding values meaning the following:
575 0 => commemorative day
577 1 => "half" holiday
578 2 => "full" holiday
579 3 => both a "half" and a "full" holiday
580 The value "3" should only occur if a date has been redefined by the
582 underlying profile using the same key (i.e., the same name) but with
583 a different type of holiday.
584 The index must be a number such as returned by the method
586 "date2index()"; it can be used here instead of a date or a date
587 object in order to speed up processing (= no need to calculate it
588 internally).
589 · "$days = $year->delta_workdays(YEAR,MONTH1,DAY1, YEAR,MONTH2,DAY2,
591 FLAG1,FLAG2);"
592 "$days = $year->delta_workdays(DATE1,DATE2,FLAG1,FLAG2);"
594 This method calculates the number of work days (i.e., the number of
596 days, but excluding all holidays) between two dates.
597 In other words, this method is equivalent to the "Delta_Days()" func‐
599 tion of the Date::Calc module, except that it disregards holidays in
600 its counting.
601 The two flags indicate whether the start and end dates should be
603 included in the counting (that is, of course, only in case they
604 aren't holidays), or not.
605 It is common, for example, that you want to know how many work days
607 are left between the current date and a given deadline.
608 Typically, you will want to count the current date but not the dead‐
610 line's date. So you would specify "true" ("1") for FLAG1 and "false"
611 ("0") for FLAG2 in order to achieve that.
612 In other words, a value of "true" means "including this date", a
614 value of "false" means "excluding this date".
615 As with the "Delta_Days()" function from the Date::Calc module, the
617 dates have to be given in chronological order to yield a positive
618 result. If the dates are reversed, the result will be negative.
619 The parameter FLAG1 is associated with the first given date, the
621 parameter FLAG2 with the second given date (regardless of whether the
622 dates are in chronological order or not).
623 An exception ("given year != object's year") is thrown if the year
625 number of either of the two given dates does not match the year num‐
626 ber associated with the given year object.
627 An exception ("invalid date") is also raised if either of the two
629 date arguments does not constitute a valid date.
630 · "($date,$rest,$sign) = $year->add_delta_workdays(YEAR,MONTH,DAY,
632 DELTA, SIGN);"
633 "($date,$rest,$sign) = $year->add_delta_workdays(DATE,DELTA,SIGN);"
635 This method is the equivalent of the "Add_Delta_Days()" function from
637 the Date::Calc module, except that it adds work days and skips holi‐
638 days.
639 In other words, you can add or subtract a number of work days "DELTA"
641 to/from a given date and get a new date as the result (as a
642 Date::Calc object).
643 You add days (i.e., you go forward in time) with a positive offset
645 "DELTA", and you subtract days (i.e., you go backwards in time) with
646 a negative offset.
647 Note that an exception ("invalid date") is raised if the given date
649 argument (the "start" date) does not constitute a valid date.
650 Beware that this method is limited to date calculations within a sin‐
652 gle year (in contrast to the method with the same name from the
653 Date::Calendar module).
654 Therefore, the method does not only return a date (object), but also
656 a "rest" and a "sign".
657 The "rest" indicates how many days are still left from your original
659 DELTA after going in the desired direction and reaching a year bound‐
660 ary.
661 The "sign" indicates in which direction (future or past) one needs to
663 go in order to "eat up" the "rest" (by subtracting a day from the
664 "rest" for each work day passed), or to adjust the resulting date (in
665 order to skip any holidays directly after a year boundary), if at
666 all.
667 The "sign" is -1 for going backwards in time, +1 for going forward,
669 and 0 if the result doesn't need any more fixing (for instance
670 because the result lies in the same year as the starting date).
671 The method "add_delta_workdays()" from the Date::Calendar module uses
673 the "rest" and "sign" return values from this method in order to per‐
674 form calculations which may cross year boundaries.
675 Therefore, it is not recommended to use this method here directly, as
677 it is rather clumsy to use, but to use the method with the same name
678 from the Date::Calendar module instead, which does the same but is
679 much easier to use and moreover allows calculations which cross an
680 arbitrary number of year boundaries.
681 · "$flag = $year->is_full(YEAR,MONTH,DAY⎪DATE);"
683 This method returns "true" ("1") if the bit corresponding to the
685 given date is set in the bit vector representing "full" holidays, and
686 "false" ("0") otherwise.
687 I.e., the method returns "true" if the given date is a (full) holiday
689 (according to the calendar profile associated with the given year
690 object).
691 · "$flag = $year->is_half(YEAR,MONTH,DAY⎪DATE);"
693 This method returns "true" ("1") if the bit corresponding to the
695 given date is set in the bit vector representing "half" holidays, and
696 "false" ("0") otherwise.
697 I.e., the method returns "true" if the given date is a half holiday
699 (according to the calendar profile associated with the given year
700 object).
701 Note that if a date is a "full" holiday, the "half" bit is never set,
703 even if you try to do so in your calendar profile, on purpose or by
704 accident.
705 · "$flag = $year->is_work(YEAR,MONTH,DAY⎪DATE);"
707 This method returns "true" ("1") if the bit corresponding to the
709 given date is set in the bit vector used to perform all sorts of cal‐
710 culations, and "false" ("0") otherwise.
711 BEWARE that the "work" in this method's name does NOT come from "work
713 days"!
714 It comes from the fact that the corresponding bit vector can be used
716 for any "work" that you need to do. In other words, it's a "work
717 space".
718 Therefore, this bit vector might contain about everything you could
720 imagine - including a bit pattern which marks all "work days" with
721 set bits, if it so happens!
722 But you better don't rely on it, unless you put the bit pattern there
724 yourself in the first place.
725 Note that you can get a reference to this bit vector (in order to
727 fill it with any bit pattern you like) using the method "vec_work()",
728 described further above in this document.
729 The number of bits in this bit vector is the same as the number of
731 days in the given year "$year", which you can retrieve through either
732 ""$days = $year->vec_work->Size();"" or ""$days =
733 $year->val_days();"".
734 See also Bit::Vector(3) for more details.
736
738 Bit::Vector(3), Date::Calendar(3), Date::Calendar::Profiles(3),
739 Date::Calc::Object(3), Date::Calc(3).
740
742 The method "add_delta_workdays()" is known to produce results which are
743 sometimes off by one working day when a negative offset is used. As a
744 workaround, try to add one working day first and then subtract one
745 working day more than initially intended. See also the file "exam‐
746 ples/bug.pl" for how to do this.
747
749 This man page documents "Date::Calendar::Year" version 5.4.
750
752 Steffen Beyer
753 mailto:sb@engelschall.com
754 http://www.engelschall.com/u/sb/download/
755
757 Copyright (c) 2000 - 2004 by Steffen Beyer. All rights reserved.
758
760 This package is free software; you can redistribute it and/or modify it
761 under the same terms as Perl itself, i.e., under the terms of the
762 "Artistic License" or the "GNU General Public License".
763 Please refer to the files "Artistic.txt" and "GNU_GPL.txt" in this dis‐
765 tribution for details!
766
768 This package is distributed in the hope that it will be useful, but
769 WITHOUT ANY WARRANTY; without even the implied warranty of MER‐
770 CHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
771 See the "GNU General Public License" for more details.
773perl v5.8.8 2004-10-03 Date::Calendar::Year(3)