1Date::Pcalendar::Year(3U)ser Contributed Perl DocumentatiDoante::Pcalendar::Year(3)
2
6 Date::Pcalendar::Year - Implements embedded "year" objects for
7 Date::Pcalendar
8
10 There is more than one way to do it - this is just one of them!
11
13 Note that Date::Pcalendar::Year (and Date::Pcalendar) can only deal
14 with years lying within the range [1583..2299].
15
17 use Date::Pcalendar::Year qw( check_year empty_period );
18 use Date::Pcalendar::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::Pcalendar::Profiles qw( $Profiles );
27 $year_2000_US_FL = Date::Pcalendar::Year->new( 2000, $Profiles->{'US-FL'} [,LANG[,WEEKEND]] );
28 $year_2001_DE_NW = Date::Pcalendar::Year->new( 2001, $Profiles->{'DE-NW'} [,LANG[,WEEKEND]] );
29 $year = Date::Pcalendar::Year->new( 2001, {} );
31 $year->init( 2002, $Profiles->{'DE-SN'} [,LANG[,WEEKEND]] );
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::Pcalc[::Object] date object or an
66 array reference (of an array of appropriate length) instead!
67 See Date::Pcalc::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
96 readability of your programs), it must contain three values,
97 nevertheless (otherwise the use of an anonymous array would be
98 pointless).
99 Don't confuse year numbers and their substitutes (a date object or an
101 array reference) with Date::Pcalendar::Year objects, which are a
102 totally different thing!
103 But incidentally ":-)", you may also pass a Date::Pcalendar::Year
105 object whenever a year number is expected. However, and perhaps against
106 your expectations at times, only the year number from that object will
107 be used, not the year object itself (the year object in question might
108 be using the wrong profile!).
109 Moreover, whenever a method of this class returns a date, it does so by
111 returning a Date::Pcalc[::Object] date object.
112
114 Each Date::Pcalendar::Year object consists mainly of three bit vectors,
115 plus some administrative attributes, all stored in a (blessed) hash.
116 All three bit vectors contain as many bits as there are days in the
118 corresponding year, i.e., either 365 or 366.
119 The first bit vector, called "FULL", contains set bits for Saturdays,
121 Sundays and all "full" legal holidays (i.e., days off, on which you
122 usually do not work).
123 The second bit vector, called "HALF", contains set bits for all "half"
125 holidays, i.e., holidays where you get only half a day off from work.
126 The third and last bit vector, called "WORK", is used as a workspace,
128 in which various calculations are performed throughout this module.
129 Its name does NOT come from "working days" (as you might think), but
131 from "workspace".
132 It only so happens that it is used to calculate the working days
134 sometimes, at some places in this module.
135 But you are free to use it yourself, for whatever calculation you would
137 like to carry out yourself.
138 The two other bit vectors, "FULL" and "HALF", should never be changed,
140 unless you know EXACTLY what you're doing!
141
143 Functions
144 • "check_year(YEAR);"
146 This function checks that the given year lies in the permitted range
148 [1583..2299]. It returns nothing in case of success, and throws an
149 exception ("given year out of range [1583..2299]") otherwise.
150 • "empty_period();"
152 This function issues a warning (from the perspective of the caller of
154 a Date::* module) that the given range of dates is empty ("dates
155 interval is empty"), provided that warnings are enabled (i.e., "$^W"
156 is true).
157 This function is currently used by the method "delta_workdays()" in
159 this class, and by its equivalent from the Date::Pcalendar module.
160 It is called whenever the range of dates of which the difference in
162 working days is to be calculated is empty. This can happen for
163 instance if you specify two adjacent dates both of which are not to
164 be included in the difference.
165 Methods
167 • "$index = $year->date2index(YEAR,MONTH,DAY|DATE);"
169 This method converts a given date into the number of the day in that
171 year (this is sometimes also referred to as the "julian" date), i.e.,
172 a number between 0 (for January 1st) and the number of days in the
173 given year minus one, i.e., 364 or 365 (for December 31st).
174 You may need this in order to access the bit vectors returned by the
176 methods "vec_full()", "vec_half()" and "vec_work()".
177 Note that there are shorthand methods in this module called
179 "is_full()", "is_half()" and "is_work()", which serve to test
180 individual bits of the three bit vectors which are a part of each
181 Date::Pcalendar::Year object.
182 An exception ("given year != object's year") is thrown if the year
184 associated with the year object itself and the year from the given
185 date do not match.
186 An exception ("invalid date") is also thrown if the given arguments
188 do not constitute a valid date, or ("given year out of range
189 [1583..2299]") if the given year lies outside of the permitted range.
190 • "$date = $year->index2date(INDEX);"
192 This method converts an index (or "julian date") for the given year
194 back into a date.
195 An exception ("invalid index") is thrown if the given index is
197 outside of the permitted range for the given year, i.e., "[0..364]"
198 or "[0..365]".
199 Note that this method returns a Date::Pcalc OBJECT!
201 • "$year_2000_US_FL = Date::Pcalendar::Year->new( 2000,
203 $Profiles->{'US-FL'} [,LANG[,WEEKEND]] );"
204 "$year_2001_DE_NW = Date::Pcalendar::Year->new( 2001,
206 $Profiles->{'DE-NW'} [,LANG[,WEEKEND]] );"
207 "$year = Date::Pcalendar::Year->new( 2001, {} );"
209 This is the constructor method. Call it to create a new
211 Date::Pcalendar::Year object.
212 The first argument must be a year number in the range [1583..2299].
214 The second argument must be the reference of a hash, which usually
216 contains names of holidays and commemorative days as keys and strings
217 containing the date or formula for each holiday as values.
218 Reading this hash and initializing the object's internal data is
220 performed by an extra method, called "init()", which is called
221 internally by the constructor method, and which is described
222 immediately below, after this method.
223 In case you want to call the "init()" method yourself, explicitly,
225 after creating the object, you can pass an empty profile (e.g., just
226 an empty anonymous hash) to the "new()" method, in order to create an
227 empty object, and also to improve performance.
228 The third argument is optional, and must consist of the valid name or
230 number of a language as provided by the Date::Pcalc(3) module, if
231 given.
232 This argument determines which language shall be used when reading
234 the profile, since the profile may contain names of months and
235 weekdays in its formulas in that language.
236 The default is English if no value or no valid value is specified
238 (and if the global default has not been changed with "Language()").
239 After the third argument, a list of day numbers which will constitute
241 the "weekend" can optionally be specified, where 1=Monday, 2=Tuesday,
242 3=Wednesday, 4=Thursday, 5=Friday, 6=Saturday and 7=Sunday.
243 If no values are given, 6 and 7 (Saturday and Sunday) are
245 automatically taken as default.
246 If values outside of the range 1..7 are given, they will be ignored.
248 This can be used to switch off this feature and to have no regularly
250 recurring holidays at all when for instance a zero is given.
251 • "$year->init( 2002, $Profiles->{'DE-SN'} [,LANG[,WEEKEND]] );"
253 This method is called by the "new()" constructor method, internally,
255 and has the same arguments as the latter.
256 See immediately above for a description of these arguments.
258 Note that you can also call this method explicitly yourself, if
260 needed, and you can of course subclass the Date::Pcalendar::Year
261 class and override the "init()" method with a method of your own.
262 The holiday scheme or "profile" (i.e., the reference of a hash passed
264 as the second argument to this method) must obey the following
265 semantics and syntax:
266 The keys are the names of the holiday or commemorative day in
268 question. Keys must be unique (but see further below).
269 The difference between a holiday and a commemorative day is that you
271 (usually) get a day off on a holiday, whereas on a purely
272 commemorative day, you don't.
273 A commemorative day is just a date with a name, nothing more.
275 The values belonging to these keys can either be the code reference
277 of a callback function (see Date::Pcalendar::Profiles(3) for more
278 details and examples), or a string.
279 All other values cause a fatal error with program abortion.
281 The strings can specify three types of dates:
283 - fixed dates
285 (like New Year, or first of January),
286 - dates relative to Easter Sunday
288 (like Ascension = Easter Sunday + 39 days), and
289 - the 1st, 2nd, 3rd, 4th or last
291 of a given day of week in a given month
292 (like "the 4th Thursday of November", or Thanksgiving).
293 All other types of dates must be specified via callback functions.
295 Note that the "last" of a given day of week is written as the "5th",
297 because the last is always either the 5th or the 4th of the given day
298 of week. So the "init()" module first calculates the 5th of the
299 requested day of week, and if that doesn't exist, takes the 4th
300 instead.
301 There are also two modifier characters which may prefix the string
303 with the date formula, "#" and ":".
304 The character "#" (mnemonic: it's only a comment) signals that the
306 date in question is a purely commemorative day, i.e., it will not
307 enter into any date calculations, but can be queried with the
308 "labels()" and "search()" methods, and appears when printing a
309 calendar, for instance.
310 The character ":" (mnemonic: divided into two halfs) specifies that
312 the date in question is only a "half" holiday, i.e., you only get
313 half a day off instead of a full day. Some companies have this sort
314 of thing. ":-)"
315 The exact syntax for the date formula strings is the following (by
317 example):
318 - Fixed dates:
320 "Christmas" => "24.12", # European format (day, month)
322 "Christmas" => "24.12.",
323 "Christmas" => "24Dec",
325 "Christmas" => "24.Dec",
326 "Christmas" => "24Dec.",
327 "Christmas" => "24.Dec.",
328 "Christmas" => "24-12",
330 "Christmas" => "24-12-",
331 "Christmas" => "24-Dec",
333 "Christmas" => "24-Dec-",
334 "Christmas" => "12/25", # American format (month, day)
336 "Christmas" => "Dec25",
337 "Christmas" => "Dec/25",
338 - Dates relative to Easter Sunday:
340 "Ladies' Carnival" => "-52",
342 "Carnival Monday" => "-48",
343 "Mardi Gras" => "-47",
344 "Ash Wednesday" => "-46",
345 "Palm Sunday" => "-7",
346 "Maundy Thursday" => "-3",
347 "Good Friday" => "-2",
348 "Easter Sunday" => "+0",
349 "Easter Monday" => "+1",
350 "Ascension" => "+39",
351 "Whitsunday" => "+49",
352 "Whitmonday" => "+50",
353 "Corpus Christi" => "+60",
354 - The 1st, 2nd, 3rd, 4th or last day of week:
356 "Thanksgiving" => "4Thu11",
358 "Thanksgiving" => "4/Thu/Nov",
359 "Columbus Day" => "2/Mon/Oct",
360 "Columbus Day" => "2/Mon/10",
361 "Columbus Day" => "2/1/Oct",
362 "Columbus Day" => "2/1/10",
363 "Memorial Day" => "5/Mon/May", # LAST Monday of May
364 Remember that each of these date formula strings may also be prefixed
366 with either "#" or ":":
367 "Christmas" => ":24.12.", # only half a day off
369 "Valentine's Day" => "#Feb/14", # not an official holiday
370 Note that the name of the month or day of week may have any length
372 you like, it just must specify the intended month or day of week
373 unambiguously. So "D", "De", "Dec", "Dece", "Decem", "Decemb",
374 "Decembe" and "December" would all be valid, for example. Note also
375 that case is ignored.
376 When specifying day and month numbers, or offsets relative to Easter
378 Sunday, leading zeros are permitted (for nicely indented formatting,
379 for instance) but ignored.
380 Leading zeros are not permitted in front of the ordinal number [1..5]
382 or the number of the day of week [1..7] when specifying the nth day
383 of week in a month.
384 BEWARE that if keys are not unique in the source code, later entries
386 will overwrite previous ones! I.e.,
387 ...
389 "My special holiday" => "01-11",
390 "My special holiday" => "02-11",
391 ...
392 will NOT set two holidays of the same name, one on November first,
394 the other on November second, but only one, on November second!
395 Therefore, in order to use sets of defaults and to be able to
397 override some of them, you must FIRST include any hash containing the
398 default definitions, and THEN write down your own definitions (see
399 also the Date::Pcalendar::Profiles module for examples of this!),
400 like this:
401 $defaults =
403 {
404 "Holiday #1" => "01-01",
405 "Holiday #2" => "02-02",
406 "Holiday #3" => "03-03"
407 };
408 $variant1 =
410 {
411 %$defaults,
412 "Holiday #2" => "09-02",
413 "Holiday #4" => "04-04"
414 };
415 This is because of the way hashes work in Perl.
417 The "init()" method proceeds as follows:
419 First it checks whether the given year number lies in the range
421 [1583..2299]. A fatal error occurs if not.
422 Then it determines the number of days in the requested year, and
424 stores it in the given Date::Pcalendar::Year object.
425 It then calls the Bit::Vector(3) module to allocate three bit vectors
427 with a number of bits equal to the number of days in the requested
428 year, and stores the three object references (of the bit vectors) in
429 the Date::Pcalendar::Year object.
430 (See also the description of the three methods "vec_full()",
432 "vec_half()" and "vec_full()" immediately below.)
433 It then sets the bits which correspond to Saturdays and Sundays (or
435 optionally to the days whose numbers have been specified as the
436 "weekend") in the "full holidays" bit vector.
437 At last, it iterates over the keys of the given holiday scheme (of
439 the hash referred to by the hash reference passed to the "init()"
440 method as the second argument), evaluates the formula (or calls the
441 given callback function), and sets the corresponding bit in the
442 "full" or "half" holidays bit vector if the calculated date is valid.
443 A fatal error occurs if the date formula cannot be parsed or if the
445 date returned by a formula or callback function is invalid (e.g.
446 30-Feb-2001 or the like) or lies outside the given year (e.g.
447 Easter+365).
448 Finally, the "init()" method makes sure that days marked as "full"
450 holidays do not appear as "half" holidays as well.
451 Then the "init()" method returns.
453 Note that when deciphering the date formulas, the "init()" method
455 uses the functions "Decode_Day_of_Week()" and "Decode_Month()" from
456 the Date::Pcalc(3) module, which are language-dependent.
457 Therefore the "init()" method allows you to pass it an optional third
459 argument, which must consist of the valid name or number of a
460 language as provided by the Date::Pcalc(3) module.
461 For the time of scanning the given holiday scheme, the "init()"
463 method will use the language that has been specified, or the global
464 setting from "Language()" if no or an invalid language parameter is
465 given.
466 The default is English if none is specified and if the global setting
468 has not been modified.
469 This means that you can provide the names of months and days of week
471 in your holiday profile in any of the languages supported by the
472 Date::Pcalc(3) module, provided you give the "init()" method a clue
473 (the third parameter) which language to expect.
474 • "$vector = $year->vec_full();"
476 This method returns a reference to the bit vector in the given year
478 object which contains all "full" holidays.
479 BEWARE that you should NEVER change the contents of this bit vector
481 unless you know EXACTLY what you're doing!
482 You should usually only read from this bit vector, or use it as an
484 operand in bit vector operations - but never as an lvalue.
485 • "$vector = $year->vec_half();"
487 This method returns a reference to the bit vector in the given year
489 object which contains all "half" holidays.
490 BEWARE that you should NEVER change the contents of this bit vector
492 unless you know EXACTLY what you're doing!
493 You should usually only read from this bit vector, or use it as an
495 operand in bit vector operations - but never as an lvalue.
496 • "$vector = $year->vec_work();"
498 This method returns a reference to the "workspace" bit vector in the
500 given year object.
501 Note that you cannot rely on the contents of this bit vector.
503 You have to set it up yourself before performing any calculations
505 with it.
506 Currently the contents of this bit vector are modified by the two
508 methods "delta_workdays()" and "add_delta_workdays()", in ways which
509 are hard to predict (depending on the calculations being performed).
510 The size of this bit vector can be determined through either ""$days
512 = $vector->Size();"" or ""$days = $year->val_days();"".
513 • "$size = $year->val_days();"
515 This method returns the number of days in the given year object,
517 i.e., either 365 or 366. This is also the size (number of bits) of
518 the three bit vectors contained in the given year object.
519 • "$base = $year->val_base();"
521 This method returns the value of the expression
523 ""Date_to_Days($year->val_year(),1,1)"", or in other words, the
524 number of days between January 1st of the year 1 and January 1st of
525 the given year, plus one.
526 This value is used internally by the method "date2index()" in order
528 to calculate the "julian" date or day of the year for a given date.
529 The expression above is computed only once in method "init()" and
531 then stored in one of the year object's attributes, of which this
532 method just returns the value.
533 • "$number = $year->val_year();"
535 "$number = $year->year();"
537 These two methods are identical, the latter being a shortcut of the
539 former.
540 They return the number of the year for which a calendar has been
542 stored in the given year object.
543 The method name "val_year()" is used here in order to be consistent
545 with the other attribute accessor methods of this class, and the
546 method "year()" is necessary in order to be able to pass
547 Date::Pcalendar::Year objects as parameters instead of a year number
548 in the methods of the Date::Pcalendar and Date::Pcalendar::Year
549 modules.
550 • "@names = $year->labels(YEAR,MONTH,DAY|DATE);"
552 "@holidays = $year->labels();"
554 "$holidays = $year->labels();"
556 If any arguments are given, they are supposed to represent a date. In
558 that case, a list of all labels (= names of holidays) associated with
559 that date are returned. The first item returned is always the name of
560 the day of week for that date.
561 If no arguments are given, the list of all available labels in the
563 given year is returned. This list does NOT include any names of the
564 days of week (which would be pointless in this case).
565 In list context, the resulting list itself is returned. In scalar
567 context, the number of items in the resulting list is returned.
568 • "@dates = $year->search(PATTERN);"
570 "$dates = $year->search(PATTERN);"
572 This method searches through all the labels of the given year and
574 returns a list of date objects with all dates whose labels match the
575 given pattern.
576 Note that this is a simple, case-insensitive substring search, NOT a
578 full-fledged regular expression search!
579 The result is guaranteed to be sorted chronologically.
581 In scalar context, only the number of items in the resulting list is
583 returned, instead of the resulting list itself (as in list context).
584 • "$hashref = $year->tags(YEAR,MONTH,DAY|DATE);"
586 "$hashref = $year->tags(INDEX);"
588 This method returns a hash reference for the given calendar and date
590 (or index). The hash it refers to is a copy of the calendar profile's
591 internal hash which contains the names for the given date as keys and
592 0, 1, 2, or 3 as their corresponding values meaning the following:
593 0 => commemorative day
595 1 => "half" holiday
596 2 => "full" holiday
597 3 => both a "half" and a "full" holiday
598 The value "3" should only occur if a date has been redefined by the
600 underlying profile using the same key (i.e., the same name) but with
601 a different type of holiday.
602 The index must be a number such as returned by the method
604 "date2index()"; it can be used here instead of a date or a date
605 object in order to speed up processing (= no need to calculate it
606 internally).
607 • "$days = $year->delta_workdays(YEAR,MONTH1,DAY1, YEAR,MONTH2,DAY2,
609 FLAG1,FLAG2);"
610 "$days = $year->delta_workdays(DATE1,DATE2,FLAG1,FLAG2);"
612 This method calculates the number of work days (i.e., the number of
614 days, but excluding all holidays) between two dates.
615 In other words, this method is equivalent to the "Delta_Days()"
617 function of the Date::Pcalc module, except that it disregards
618 holidays in its counting.
619 The two flags indicate whether the start and end dates should be
621 included in the counting (that is, of course, only in case they
622 aren't holidays), or not.
623 It is common, for example, that you want to know how many work days
625 are left between the current date and a given deadline.
626 Typically, you will want to count the current date but not the
628 deadline's date. So you would specify "true" ("1") for FLAG1 and
629 "false" ("0") for FLAG2 in order to achieve that.
630 In other words, a value of "true" means "including this date", a
632 value of "false" means "excluding this date".
633 As with the "Delta_Days()" function from the Date::Pcalc module, the
635 dates have to be given in chronological order to yield a positive
636 result. If the dates are reversed, the result will be negative.
637 The parameter FLAG1 is associated with the first given date, the
639 parameter FLAG2 with the second given date (regardless of whether the
640 dates are in chronological order or not).
641 An exception ("given year != object's year") is thrown if the year
643 number of either of the two given dates does not match the year
644 number associated with the given year object.
645 An exception ("invalid date") is also raised if either of the two
647 date arguments does not constitute a valid date.
648 • "($date,$rest,$sign) = $year->add_delta_workdays(YEAR,MONTH,DAY,
650 DELTA, SIGN);"
651 "($date,$rest,$sign) = $year->add_delta_workdays(DATE,DELTA,SIGN);"
653 This method is the equivalent of the "Add_Delta_Days()" function from
655 the Date::Pcalc module, except that it adds work days and skips
656 holidays.
657 In other words, you can add or subtract a number of work days "DELTA"
659 to/from a given date and get a new date as the result (as a
660 Date::Pcalc object).
661 You add days (i.e., you go forward in time) with a positive offset
663 "DELTA", and you subtract days (i.e., you go backwards in time) with
664 a negative offset.
665 Note that an exception ("invalid date") is raised if the given date
667 argument (the "start" date) does not constitute a valid date.
668 Beware that this method is limited to date calculations within a
670 single year (in contrast to the method with the same name from the
671 Date::Pcalendar module).
672 Therefore, the method does not only return a date (object), but also
674 a "rest" and a "sign".
675 The "rest" indicates how many days are still left from your original
677 DELTA after going in the desired direction and reaching a year
678 boundary.
679 The "sign" indicates in which direction (future or past) one needs to
681 go in order to "eat up" the "rest" (by subtracting a day from the
682 "rest" for each work day passed), or to adjust the resulting date (in
683 order to skip any holidays directly after a year boundary), if at
684 all.
685 The "sign" is -1 for going backwards in time, +1 for going forward,
687 and 0 if the result doesn't need any more fixing (for instance
688 because the result lies in the same year as the starting date).
689 The method "add_delta_workdays()" from the Date::Pcalendar module
691 uses the "rest" and "sign" return values from this method in order to
692 perform calculations which may cross year boundaries.
693 Therefore, it is not recommended to use this method here directly, as
695 it is rather clumsy to use, but to use the method with the same name
696 from the Date::Pcalendar module instead, which does the same but is
697 much easier to use and moreover allows calculations which cross an
698 arbitrary number of year boundaries.
699 BEWARE that this method may currently return unexpected (i.e.,
701 contradicting the above documentation) or plain wrong results when
702 going back in time (this is a bug!).
703 However, it works correctly and as documented above when going
705 forward in time.
706 • "$flag = $year->is_full(YEAR,MONTH,DAY|DATE);"
708 This method returns "true" ("1") if the bit corresponding to the
710 given date is set in the bit vector representing "full" holidays, and
711 "false" ("0") otherwise.
712 I.e., the method returns "true" if the given date is a (full) holiday
714 (according to the calendar profile associated with the given year
715 object).
716 • "$flag = $year->is_half(YEAR,MONTH,DAY|DATE);"
718 This method returns "true" ("1") if the bit corresponding to the
720 given date is set in the bit vector representing "half" holidays, and
721 "false" ("0") otherwise.
722 I.e., the method returns "true" if the given date is a half holiday
724 (according to the calendar profile associated with the given year
725 object).
726 Note that if a date is a "full" holiday, the "half" bit is never set,
728 even if you try to do so in your calendar profile, on purpose or by
729 accident.
730 • "$flag = $year->is_work(YEAR,MONTH,DAY|DATE);"
732 This method returns "true" ("1") if the bit corresponding to the
734 given date is set in the bit vector used to perform all sorts of
735 calculations, and "false" ("0") otherwise.
736 BEWARE that the "work" in this method's name does NOT come from "work
738 days"!
739 It comes from the fact that the corresponding bit vector can be used
741 for any "work" that you need to do. In other words, it's a "work
742 space".
743 Therefore, this bit vector might contain about everything you could
745 imagine - including a bit pattern which marks all "work days" with
746 set bits, if it so happens!
747 But you better don't rely on it, unless you put the bit pattern there
749 yourself in the first place.
750 Note that you can get a reference to this bit vector (in order to
752 fill it with any bit pattern you like) using the method "vec_work()",
753 described further above in this document.
754 The number of bits in this bit vector is the same as the number of
756 days in the given year "$year", which you can retrieve through either
757 ""$days = $year->vec_work->Size();"" or ""$days =
758 $year->val_days();"".
759 See also Bit::Vector(3) for more details.
761
763 Bit::Vector(3), Date::Pcalendar(3), Date::Pcalendar::Profiles(3),
764 Date::Pcalc::Object(3), Date::Pcalc(3), Date::Calc::Util(3).
765
767 The method "add_delta_workdays()" is known to produce results which are
768 sometimes off by one working day when a negative offset is used. As a
769 workaround, try to add one working day first and then subtract one
770 working day more than initially intended. See also the file
771 "examples/bug.pl" for how to do this.
772
774 This man page documents "Date::Pcalendar::Year" version 6.1.
775
777 Steffen Beyer
778 mailto:STBEY@cpan.org
779 http://www.engelschall.com/u/sb/download/
780
782 Copyright (c) 2000 - 2009 by Steffen Beyer. All rights reserved.
783
785 This package is free software; you can redistribute it and/or modify it
786 under the same terms as Perl itself, i.e., under the terms of the
787 "Artistic License" or the "GNU General Public License".
788 Please refer to the files "Artistic.txt" and "GNU_GPL.txt" in this
790 distribution for details!
791
793 This package is distributed in the hope that it will be useful, but
794 WITHOUT ANY WARRANTY; without even the implied warranty of
795 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
796 See the "GNU General Public License" for more details.
798perl v5.34.0 2021-07-22 Date::Pcalendar::Year(3)