1Date::Pcalendar::Year(3U)ser Contributed Perl DocumentatiDoante::Pcalendar::Year(3)
2
3
4

NAME

6       Date::Pcalendar::Year - Implements embedded "year" objects for
7       Date::Pcalendar
8

MOTTO

10       There is more than one way to do it - this is just one of them!
11

PREFACE

13       Note that Date::Pcalendar::Year (and Date::Pcalendar) can only deal
14       with years lying within the range [1583..2299].
15

SYNOPSIS

17         use Date::Pcalendar::Year qw( check_year empty_period );
18         use Date::Pcalendar::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::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
30         $year = Date::Pcalendar::Year->new( 2001, {} );
31         $year->init( 2002, $Profiles->{'DE-SN'} [,LANG[,WEEKEND]] );
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         $hashref  = $year->tags(YEAR,MONTH,DAY|DATE);
49         $hashref  = $year->tags(INDEX);
50
51         $days     = $year->delta_workdays(YEAR,MONTH1,DAY1|DATE1
52                                          ,YEAR,MONTH2,DAY2|DATE2
53                                          ,FLAG1,FLAG2);
54
55         ($date,$rest,$sign) = $year->add_delta_workdays(YEAR,MONTH,DAY|DATE
56                                                        ,DELTA,SIGN);
57
58         $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

INTERFACE

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
68       See Date::Pcalc::Object(3) for more details.
69
70       So instead of calling a given method like this:
71
72         $object->method1( $year,$month,$day );
73         $object->method2( $year1,$month1,$day1, $year2,$month2,$day2 );
74         $object->method3( $year1, $year2, $year3 );
75
76       You can also call it like so:
77
78         $object->method1( $date );
79         $object->method1( [1964,1,3] );
80
81         $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
90         $object->method3( $year1, $date2, [2001,3,17] );
91
92       And similarly if a time or a combined date and time are expected.
93
94       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
100       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
104       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
110       Moreover, whenever a method of this class returns a date, it does so by
111       returning a Date::Pcalc[::Object] date object.
112

IMPLEMENTATION

114       Each Date::Pcalendar::Year object consists mainly of three bit vectors,
115       plus some administrative attributes, all stored in a (blessed) hash.
116
117       All three bit vectors contain as many bits as there are days in the
118       corresponding year, i.e., either 365 or 366.
119
120       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
124       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
127       The third and last bit vector, called "WORK", is used as a workspace,
128       in which various calculations are performed throughout this module.
129
130       Its name does NOT come from "working days" (as you might think), but
131       from "workspace".
132
133       It only so happens that it is used to calculate the working days
134       sometimes, at some places in this module.
135
136       But you are free to use it yourself, for whatever calculation you would
137       like to carry out yourself.
138
139       The two other bit vectors, "FULL" and "HALF", should never be changed,
140       unless you know EXACTLY what you're doing!
141

DESCRIPTION

143       Functions
144
145       • "check_year(YEAR);"
146
147         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
151       • "empty_period();"
152
153         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
158         This function is currently used by the method "delta_workdays()" in
159         this class, and by its equivalent from the Date::Pcalendar module.
160
161         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
166       Methods
167
168       • "$index = $year->date2index(YEAR,MONTH,DAY|DATE);"
169
170         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
175         You may need this in order to access the bit vectors returned by the
176         methods "vec_full()", "vec_half()" and "vec_work()".
177
178         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
183         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
187         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
191       • "$date = $year->index2date(INDEX);"
192
193         This method converts an index (or "julian date") for the given year
194         back into a date.
195
196         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
200         Note that this method returns a Date::Pcalc OBJECT!
201
202       • "$year_2000_US_FL = Date::Pcalendar::Year->new( 2000,
203         $Profiles->{'US-FL'} [,LANG[,WEEKEND]] );"
204
205         "$year_2001_DE_NW = Date::Pcalendar::Year->new( 2001,
206         $Profiles->{'DE-NW'} [,LANG[,WEEKEND]] );"
207
208         "$year = Date::Pcalendar::Year->new( 2001, {} );"
209
210         This is the constructor method. Call it to create a new
211         Date::Pcalendar::Year object.
212
213         The first argument must be a year number in the range [1583..2299].
214
215         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
219         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
224         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
229         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
233         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
237         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
240         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
244         If no values are given, 6 and 7 (Saturday and Sunday) are
245         automatically taken as default.
246
247         If values outside of the range 1..7 are given, they will be ignored.
248
249         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
252       • "$year->init( 2002, $Profiles->{'DE-SN'} [,LANG[,WEEKEND]] );"
253
254         This method is called by the "new()" constructor method, internally,
255         and has the same arguments as the latter.
256
257         See immediately above for a description of these arguments.
258
259         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
263         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
267         The keys are the names of the holiday or commemorative day in
268         question. Keys must be unique (but see further below).
269
270         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
274         A commemorative day is just a date with a name, nothing more.
275
276         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
280         All other values cause a fatal error with program abortion.
281
282         The strings can specify three types of dates:
283
284           -  fixed dates
285              (like New Year, or first of January),
286
287           -  dates relative to Easter Sunday
288              (like Ascension = Easter Sunday + 39 days), and
289
290           -  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
294         All other types of dates must be specified via callback functions.
295
296         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
302         There are also two modifier characters which may prefix the string
303         with the date formula, "#" and ":".
304
305         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
311         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
316         The exact syntax for the date formula strings is the following (by
317         example):
318
319          -  Fixed dates:
320
321             "Christmas"  =>  "24.12",   # European format (day, month)
322             "Christmas"  =>  "24.12.",
323
324             "Christmas"  =>  "24Dec",
325             "Christmas"  =>  "24.Dec",
326             "Christmas"  =>  "24Dec.",
327             "Christmas"  =>  "24.Dec.",
328
329             "Christmas"  =>  "24-12",
330             "Christmas"  =>  "24-12-",
331
332             "Christmas"  =>  "24-Dec",
333             "Christmas"  =>  "24-Dec-",
334
335             "Christmas"  =>  "12/25",   # American format (month, day)
336             "Christmas"  =>  "Dec25",
337             "Christmas"  =>  "Dec/25",
338
339          -  Dates relative to Easter Sunday:
340
341             "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
355          -  The 1st, 2nd, 3rd, 4th or last day of week:
356
357             "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
365         Remember that each of these date formula strings may also be prefixed
366         with either "#" or ":":
367
368             "Christmas"         =>  ":24.12.", # only half a day off
369             "Valentine's Day"   =>  "#Feb/14", # not an official holiday
370
371         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
377         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
381         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
385         BEWARE that if keys are not unique in the source code, later entries
386         will overwrite previous ones! I.e.,
387
388             ...
389             "My special holiday" => "01-11",
390             "My special holiday" => "02-11",
391             ...
392
393         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
396         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
402             $defaults =
403             {
404                 "Holiday #1" => "01-01",
405                 "Holiday #2" => "02-02",
406                 "Holiday #3" => "03-03"
407             };
408
409             $variant1 =
410             {
411                 %$defaults,
412                 "Holiday #2" => "09-02",
413                 "Holiday #4" => "04-04"
414             };
415
416         This is because of the way hashes work in Perl.
417
418         The "init()" method proceeds as follows:
419
420         First it checks whether the given year number lies in the range
421         [1583..2299]. A fatal error occurs if not.
422
423         Then it determines the number of days in the requested year, and
424         stores it in the given Date::Pcalendar::Year object.
425
426         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
431         (See also the description of the three methods "vec_full()",
432         "vec_half()" and "vec_full()" immediately below.)
433
434         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
438         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
444         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
449         Finally, the "init()" method makes sure that days marked as "full"
450         holidays do not appear as "half" holidays as well.
451
452         Then the "init()" method returns.
453
454         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
458         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
462         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
467         The default is English if none is specified and if the global setting
468         has not been modified.
469
470         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
475       • "$vector = $year->vec_full();"
476
477         This method returns a reference to the bit vector in the given year
478         object which contains all "full" holidays.
479
480         BEWARE that you should NEVER change the contents of this bit vector
481         unless you know EXACTLY what you're doing!
482
483         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
486       • "$vector = $year->vec_half();"
487
488         This method returns a reference to the bit vector in the given year
489         object which contains all "half" holidays.
490
491         BEWARE that you should NEVER change the contents of this bit vector
492         unless you know EXACTLY what you're doing!
493
494         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
497       • "$vector = $year->vec_work();"
498
499         This method returns a reference to the "workspace" bit vector in the
500         given year object.
501
502         Note that you cannot rely on the contents of this bit vector.
503
504         You have to set it up yourself before performing any calculations
505         with it.
506
507         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
511         The size of this bit vector can be determined through either ""$days
512         = $vector->Size();"" or ""$days = $year->val_days();"".
513
514       • "$size = $year->val_days();"
515
516         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
520       • "$base = $year->val_base();"
521
522         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
527         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
530         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
534       • "$number = $year->val_year();"
535
536         "$number = $year->year();"
537
538         These two methods are identical, the latter being a shortcut of the
539         former.
540
541         They return the number of the year for which a calendar has been
542         stored in the given year object.
543
544         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
551       • "@names = $year->labels(YEAR,MONTH,DAY|DATE);"
552
553         "@holidays = $year->labels();"
554
555         "$holidays = $year->labels();"
556
557         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
562         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
566         In list context, the resulting list itself is returned. In scalar
567         context, the number of items in the resulting list is returned.
568
569       • "@dates = $year->search(PATTERN);"
570
571         "$dates = $year->search(PATTERN);"
572
573         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
577         Note that this is a simple, case-insensitive substring search, NOT a
578         full-fledged regular expression search!
579
580         The result is guaranteed to be sorted chronologically.
581
582         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
585       • "$hashref  = $year->tags(YEAR,MONTH,DAY|DATE);"
586
587         "$hashref  = $year->tags(INDEX);"
588
589         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
594             0    =>    commemorative day
595             1    =>    "half" holiday
596             2    =>    "full" holiday
597             3    =>    both a "half" and a "full" holiday
598
599         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
603         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
608       • "$days = $year->delta_workdays(YEAR,MONTH1,DAY1, YEAR,MONTH2,DAY2,
609         FLAG1,FLAG2);"
610
611         "$days = $year->delta_workdays(DATE1,DATE2,FLAG1,FLAG2);"
612
613         This method calculates the number of work days (i.e., the number of
614         days, but excluding all holidays) between two dates.
615
616         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
620         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
624         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
627         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
631         In other words, a value of "true" means "including this date", a
632         value of "false" means "excluding this date".
633
634         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
638         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
642         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
646         An exception ("invalid date") is also raised if either of the two
647         date arguments does not constitute a valid date.
648
649       • "($date,$rest,$sign) = $year->add_delta_workdays(YEAR,MONTH,DAY,
650         DELTA, SIGN);"
651
652         "($date,$rest,$sign) = $year->add_delta_workdays(DATE,DELTA,SIGN);"
653
654         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
658         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
662         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
666         Note that an exception ("invalid date") is raised if the given date
667         argument (the "start" date) does not constitute a valid date.
668
669         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
673         Therefore, the method does not only return a date (object), but also
674         a "rest" and a "sign".
675
676         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
680         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
686         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
690         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
694         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
700         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
704         However, it works correctly and as documented above when going
705         forward in time.
706
707       • "$flag = $year->is_full(YEAR,MONTH,DAY|DATE);"
708
709         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
713         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
717       • "$flag = $year->is_half(YEAR,MONTH,DAY|DATE);"
718
719         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
723         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
727         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
731       • "$flag = $year->is_work(YEAR,MONTH,DAY|DATE);"
732
733         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
737         BEWARE that the "work" in this method's name does NOT come from "work
738         days"!
739
740         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
744         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
748         But you better don't rely on it, unless you put the bit pattern there
749         yourself in the first place.
750
751         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
755         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
760         See also Bit::Vector(3) for more details.
761

SEE ALSO

763       Bit::Vector(3), Date::Pcalendar(3), Date::Pcalendar::Profiles(3),
764       Date::Pcalc::Object(3), Date::Pcalc(3), Date::Calc::Util(3).
765

KNOWN BUGS

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

VERSION

774       This man page documents "Date::Pcalendar::Year" version 6.1.
775

AUTHOR

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

LICENSE

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
789       Please refer to the files "Artistic.txt" and "GNU_GPL.txt" in this
790       distribution for details!
791

DISCLAIMER

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
797       See the "GNU General Public License" for more details.
798
799
800
801perl v5.36.0                      2023-01-20          Date::Pcalendar::Year(3)
Impressum