{
    "mode": "perldoc",
    "parameter": "Date::Calendar::Year",
    "section": "",
    "url": "https://www.chedong.com/phpMan.php/perldoc/Date%3A%3ACalendar%3A%3AYear/json",
    "generated": "2026-06-10T19:37:45Z",
    "synopsis": "use Date::Calendar::Year qw( checkyear emptyperiod );\nuse Date::Calendar::Year qw( :all ); # same as above\ncheckyear(YEAR|DATE); # dies if year < 1583 or year > 2299\nemptyperiod();        # warns about empty interval if $^W is set\n$index = $year->date2index(YEAR,MONTH,DAY|DATE);\n$date  = $year->index2date(INDEX);\nuse Date::Calendar::Profiles qw( $Profiles );\n$year2000USFL = Date::Calendar::Year->new( 2000, $Profiles->{'US-FL'} [,LANG[,WEEKEND]] );\n$year2001DENW = Date::Calendar::Year->new( 2001, $Profiles->{'DE-NW'} [,LANG[,WEEKEND]] );\n$year = Date::Calendar::Year->new( 2001, {} );\n$year->init( 2002, $Profiles->{'DE-SN'} [,LANG[,WEEKEND]] );\n$vector = $year->vecfull(); # vector of full holidays\n$vector = $year->vechalf(); # vector of half holidays\n$vector = $year->vecwork(); # NOT a vector of workdays but a workspace!\n$size   = $year->valdays(); # number of days in that year, size of vectors\n$base   = $year->valbase(); # number of days for [year,1,1] since [1,1,1]\n$number = $year->valyear(); # the year's number itself\n$number = $year->year();     # alias for valyear()\n@names    = $year->labels(YEAR,MONTH,DAY|DATE);\n@holidays = $year->labels();\n$holidays = $year->labels();\n@dates    = $year->search(PATTERN);\n$dates    = $year->search(PATTERN);\n$hashref  = $year->tags(YEAR,MONTH,DAY|DATE);\n$hashref  = $year->tags(INDEX);\n$days     = $year->deltaworkdays(YEAR,MONTH1,DAY1|DATE1\n,YEAR,MONTH2,DAY2|DATE2\n,FLAG1,FLAG2);\n($date,$rest,$sign) = $year->adddeltaworkdays(YEAR,MONTH,DAY|DATE\n,DELTA,SIGN);\n$flag     = $year->isfull(YEAR,MONTH,DAY|DATE);\n$flag     = $year->ishalf(YEAR,MONTH,DAY|DATE);\n$flag     = $year->iswork(YEAR,MONTH,DAY|DATE);",
    "sections": {
        "NAME": {
            "content": "Date::Calendar::Year - Implements embedded \"year\" objects for Date::Calendar\n",
            "subsections": []
        },
        "MOTTO": {
            "content": "There is more than one way to do it - this is just one of them!\n",
            "subsections": []
        },
        "PREFACE": {
            "content": "Note that Date::Calendar::Year (and Date::Calendar) can only deal with years lying within the\nrange [1583..2299].\n",
            "subsections": []
        },
        "SYNOPSIS": {
            "content": "use Date::Calendar::Year qw( checkyear emptyperiod );\nuse Date::Calendar::Year qw( :all ); # same as above\n\ncheckyear(YEAR|DATE); # dies if year < 1583 or year > 2299\nemptyperiod();        # warns about empty interval if $^W is set\n\n$index = $year->date2index(YEAR,MONTH,DAY|DATE);\n$date  = $year->index2date(INDEX);\n\nuse Date::Calendar::Profiles qw( $Profiles );\n$year2000USFL = Date::Calendar::Year->new( 2000, $Profiles->{'US-FL'} [,LANG[,WEEKEND]] );\n$year2001DENW = Date::Calendar::Year->new( 2001, $Profiles->{'DE-NW'} [,LANG[,WEEKEND]] );\n\n$year = Date::Calendar::Year->new( 2001, {} );\n$year->init( 2002, $Profiles->{'DE-SN'} [,LANG[,WEEKEND]] );\n\n$vector = $year->vecfull(); # vector of full holidays\n$vector = $year->vechalf(); # vector of half holidays\n$vector = $year->vecwork(); # NOT a vector of workdays but a workspace!\n$size   = $year->valdays(); # number of days in that year, size of vectors\n$base   = $year->valbase(); # number of days for [year,1,1] since [1,1,1]\n$number = $year->valyear(); # the year's number itself\n$number = $year->year();     # alias for valyear()\n\n@names    = $year->labels(YEAR,MONTH,DAY|DATE);\n@holidays = $year->labels();\n$holidays = $year->labels();\n\n@dates    = $year->search(PATTERN);\n$dates    = $year->search(PATTERN);\n\n$hashref  = $year->tags(YEAR,MONTH,DAY|DATE);\n$hashref  = $year->tags(INDEX);\n\n$days     = $year->deltaworkdays(YEAR,MONTH1,DAY1|DATE1\n,YEAR,MONTH2,DAY2|DATE2\n,FLAG1,FLAG2);\n\n($date,$rest,$sign) = $year->adddeltaworkdays(YEAR,MONTH,DAY|DATE\n,DELTA,SIGN);\n\n$flag     = $year->isfull(YEAR,MONTH,DAY|DATE);\n$flag     = $year->ishalf(YEAR,MONTH,DAY|DATE);\n$flag     = $year->iswork(YEAR,MONTH,DAY|DATE);\n",
            "subsections": []
        },
        "INTERFACE": {
            "content": "Note that whenever a year number, a date, a time or a combined date and time are expected as\ninput parameters by one of the methods of this class, you can always pass a Date::Calc[::Object]\ndate object or an array reference (of an array of appropriate length) instead!\n\nSee Date::Calc::Object(3) for more details.\n\nSo instead of calling a given method like this:\n\n$object->method1( $year,$month,$day );\n$object->method2( $year1,$month1,$day1, $year2,$month2,$day2 );\n$object->method3( $year1, $year2, $year3 );\n\nYou can also call it like so:\n\n$object->method1( $date );\n$object->method1( [1964,1,3] );\n\n$object->method2( $year1,$month1,$day1, $date2 );\n$object->method2( $date1, $year2,$month2,$day2 );\n$object->method2( $date1, $date2 );\n$object->method2( $year1,$month1,$day1, [2001,3,17] );\n$object->method2( [1964,1,3], $year2,$month2,$day2 );\n$object->method2( [1964,1,3], [2001,3,17] );\n$object->method2( $date1, [2001,3,17] );\n$object->method2( [1964,1,3], $date2 );\n\n$object->method3( $year1, $date2, [2001,3,17] );\n\nAnd similarly if a time or a combined date and time are expected.\n\nIf you substitute an expected year number by an anonymous array (this is the recommended way of\nwriting date constants, for increased readability of your programs), it must contain three\nvalues, nevertheless (otherwise the use of an anonymous array would be pointless).\n\nDon't confuse year numbers and their substitutes (a date object or an array reference) with\nDate::Calendar::Year objects, which are a totally different thing!\n\nBut incidentally \":-)\", you may also pass a Date::Calendar::Year object whenever a year number\nis expected. However, and perhaps against your expectations at times, only the year number from\nthat object will be used, not the year object itself (the year object in question might be using\nthe wrong profile!).\n\nMoreover, whenever a method of this class returns a date, it does so by returning a\nDate::Calc[::Object] date object.\n",
            "subsections": []
        },
        "IMPLEMENTATION": {
            "content": "Each Date::Calendar::Year object consists mainly of three bit vectors, plus some administrative\nattributes, all stored in a (blessed) hash.\n\nAll three bit vectors contain as many bits as there are days in the corresponding year, i.e.,\neither 365 or 366.\n\nThe first bit vector, called \"FULL\", contains set bits for Saturdays, Sundays and all \"full\"\nlegal holidays (i.e., days off, on which you usually do not work).\n\nThe second bit vector, called \"HALF\", contains set bits for all \"half\" holidays, i.e., holidays\nwhere you get only half a day off from work.\n\nThe third and last bit vector, called \"WORK\", is used as a workspace, in which various\ncalculations are performed throughout this module.\n\nIts name does NOT come from \"working days\" (as you might think), but from \"workspace\".\n\nIt only so happens that it is used to calculate the working days sometimes, at some places in\nthis module.\n\nBut you are free to use it yourself, for whatever calculation you would like to carry out\nyourself.\n\nThe two other bit vectors, \"FULL\" and \"HALF\", should never be changed, unless you know EXACTLY\nwhat you're doing!\n",
            "subsections": []
        },
        "DESCRIPTION": {
            "content": "Functions\n\n* \"checkyear(YEAR);\"\n\nThis function checks that the given year lies in the permitted range [1583..2299]. It returns\nnothing in case of success, and throws an exception (\"given year out of range [1583..2299]\")\notherwise.\n\n* \"emptyperiod();\"\n\nThis function issues a warning (from the perspective of the caller of a Date::* module) that\nthe given range of dates is empty (\"dates interval is empty\"), provided that warnings are\nenabled (i.e., \"$^W\" is true).\n\nThis function is currently used by the method \"deltaworkdays()\" in this class, and by its\nequivalent from the Date::Calendar module.\n\nIt is called whenever the range of dates of which the difference in working days is to be\ncalculated is empty. This can happen for instance if you specify two adjacent dates both of\nwhich are not to be included in the difference.\n\nMethods\n\n* \"$index = $year->date2index(YEAR,MONTH,DAY|DATE);\"\n\nThis method converts a given date into the number of the day in that year (this is sometimes\nalso referred to as the \"julian\" date), i.e., a number between 0 (for January 1st) and the\nnumber of days in the given year minus one, i.e., 364 or 365 (for December 31st).\n\nYou may need this in order to access the bit vectors returned by the methods \"vecfull()\",\n\"vechalf()\" and \"vecwork()\".\n\nNote that there are shorthand methods in this module called \"isfull()\", \"ishalf()\" and\n\"iswork()\", which serve to test individual bits of the three bit vectors which are a part of\neach Date::Calendar::Year object.\n\nAn exception (\"given year != object's year\") is thrown if the year associated with the year\nobject itself and the year from the given date do not match.\n\nAn exception (\"invalid date\") is also thrown if the given arguments do not constitute a valid\ndate, or (\"given year out of range [1583..2299]\") if the given year lies outside of the\npermitted range.\n\n* \"$date = $year->index2date(INDEX);\"\n\nThis method converts an index (or \"julian date\") for the given year back into a date.\n\nAn exception (\"invalid index\") is thrown if the given index is outside of the permitted range\nfor the given year, i.e., \"[0..364]\" or \"[0..365]\".\n\nNote that this method returns a Date::Calc OBJECT!\n\n* \"$year2000USFL = Date::Calendar::Year->new( 2000, $Profiles->{'US-FL'} [,LANG[,WEEKEND]]\n);\"\n\n\"$year2001DENW = Date::Calendar::Year->new( 2001, $Profiles->{'DE-NW'} [,LANG[,WEEKEND]]\n);\"\n\n\"$year = Date::Calendar::Year->new( 2001, {} );\"\n\nThis is the constructor method. Call it to create a new Date::Calendar::Year object.\n\nThe first argument must be a year number in the range [1583..2299].\n\nThe second argument must be the reference of a hash, which usually contains names of holidays\nand commemorative days as keys and strings containing the date or formula for each holiday as\nvalues.\n\nReading this hash and initializing the object's internal data is performed by an extra method,\ncalled \"init()\", which is called internally by the constructor method, and which is described\nimmediately below, after this method.\n\nIn case you want to call the \"init()\" method yourself, explicitly, after creating the object,\nyou can pass an empty profile (e.g., just an empty anonymous hash) to the \"new()\" method, in\norder to create an empty object, and also to improve performance.\n\nThe third argument is optional, and must consist of the valid name or number of a language as\nprovided by the Date::Calc(3) module, if given.\n\nThis argument determines which language shall be used when reading the profile, since the\nprofile may contain names of months and weekdays in its formulas in that language.\n\nThe default is English if no value or no valid value is specified (and if the global default\nhas not been changed with \"Language()\").\n\nAfter the third argument, a list of day numbers which will constitute the \"weekend\" can\noptionally be specified, where 1=Monday, 2=Tuesday, 3=Wednesday, 4=Thursday, 5=Friday,\n6=Saturday and 7=Sunday.\n\nIf no values are given, 6 and 7 (Saturday and Sunday) are automatically taken as default.\n\nIf values outside of the range 1..7 are given, they will be ignored.\n\nThis can be used to switch off this feature and to have no regularly recurring holidays at all\nwhen for instance a zero is given.\n\n* \"$year->init( 2002, $Profiles->{'DE-SN'} [,LANG[,WEEKEND]] );\"\n\nThis method is called by the \"new()\" constructor method, internally, and has the same\narguments as the latter.\n\nSee immediately above for a description of these arguments.\n\nNote that you can also call this method explicitly yourself, if needed, and you can of course\nsubclass the Date::Calendar::Year class and override the \"init()\" method with a method of your\nown.\n\nThe holiday scheme or \"profile\" (i.e., the reference of a hash passed as the second argument\nto this method) must obey the following semantics and syntax:\n\nThe keys are the names of the holiday or commemorative day in question. Keys must be unique\n(but see further below).\n\nThe difference between a holiday and a commemorative day is that you (usually) get a day off\non a holiday, whereas on a purely commemorative day, you don't.\n\nA commemorative day is just a date with a name, nothing more.\n\nThe values belonging to these keys can either be the code reference of a callback function\n(see Date::Calendar::Profiles(3) for more details and examples), or a string.\n\nAll other values cause a fatal error with program abortion.\n\nThe strings can specify three types of dates:\n\n-  fixed dates\n(like New Year, or first of January),\n\n-  dates relative to Easter Sunday\n(like Ascension = Easter Sunday + 39 days), and\n\n-  the 1st, 2nd, 3rd, 4th or last\nof a given day of week in a given month\n(like \"the 4th Thursday of November\", or Thanksgiving).\n\nAll other types of dates must be specified via callback functions.\n\nNote that the \"last\" of a given day of week is written as the \"5th\", because the last is\nalways either the 5th or the 4th of the given day of week. So the \"init()\" module first\ncalculates the 5th of the requested day of week, and if that doesn't exist, takes the 4th\ninstead.\n\nThere are also two modifier characters which may prefix the string with the date formula, \"#\"\nand \":\".\n\nThe character \"#\" (mnemonic: it's only a comment) signals that the date in question is a\npurely commemorative day, i.e., it will not enter into any date calculations, but can be\nqueried with the \"labels()\" and \"search()\" methods, and appears when printing a calendar, for\ninstance.\n\nThe character \":\" (mnemonic: divided into two halves) specifies that the date in question is\nonly a \"half\" holiday, i.e., you only get half a day off instead of a full day. Some companies\nhave this sort of thing. \":-)\"\n\nThe exact syntax for the date formula strings is the following (by example):\n\n-  Fixed dates:\n\n\"Christmas\"  =>  \"24.12\",   # European format (day, month)\n\"Christmas\"  =>  \"24.12.\",\n\n\"Christmas\"  =>  \"24Dec\",\n\"Christmas\"  =>  \"24.Dec\",\n\"Christmas\"  =>  \"24Dec.\",\n\"Christmas\"  =>  \"24.Dec.\",\n\n\"Christmas\"  =>  \"24-12\",\n\"Christmas\"  =>  \"24-12-\",\n\n\"Christmas\"  =>  \"24-Dec\",\n\"Christmas\"  =>  \"24-Dec-\",\n\n\"Christmas\"  =>  \"12/25\",   # American format (month, day)\n\"Christmas\"  =>  \"Dec25\",\n\"Christmas\"  =>  \"Dec/25\",\n\n-  Dates relative to Easter Sunday:\n\n\"Ladies' Carnival\"  =>  \"-52\",\n\"Carnival Monday\"   =>  \"-48\",\n\"Mardi Gras\"        =>  \"-47\",\n\"Ash Wednesday\"     =>  \"-46\",\n\"Palm Sunday\"       =>   \"-7\",\n\"Maundy Thursday\"   =>   \"-3\",\n\"Good Friday\"       =>   \"-2\",\n\"Easter Sunday\"     =>   \"+0\",\n\"Easter Monday\"     =>   \"+1\",\n\"Ascension\"         =>  \"+39\",\n\"Whitsunday\"        =>  \"+49\",\n\"Whitmonday\"        =>  \"+50\",\n\"Corpus Christi\"    =>  \"+60\",\n\n-  The 1st, 2nd, 3rd, 4th or last day of week:\n\n\"Thanksgiving\"      =>  \"4Thu11\",\n\"Thanksgiving\"      =>  \"4/Thu/Nov\",\n\"Columbus Day\"      =>  \"2/Mon/Oct\",\n\"Columbus Day\"      =>  \"2/Mon/10\",\n\"Columbus Day\"      =>  \"2/1/Oct\",\n\"Columbus Day\"      =>  \"2/1/10\",\n\"Memorial Day\"      =>  \"5/Mon/May\", # LAST Monday of May\n\nRemember that each of these date formula strings may also be prefixed with either \"#\" or \":\":\n\n\"Christmas\"         =>  \":24.12.\", # only half a day off\n\"Valentine's Day\"   =>  \"#Feb/14\", # not an official holiday\n\nNote that the name of the month or day of week may have any length you like, it just must\nspecify the intended month or day of week unambiguously. So \"D\", \"De\", \"Dec\", \"Dece\", \"Decem\",\n\"Decemb\", \"Decembe\" and \"December\" would all be valid, for example. Note also that case is\nignored.\n\nWhen specifying day and month numbers, or offsets relative to Easter Sunday, leading zeros are\npermitted (for nicely indented formatting, for instance) but ignored.\n\nLeading zeros are not permitted in front of the ordinal number [1..5] or the number of the day\nof week [1..7] when specifying the nth day of week in a month.\n\nBEWARE that if keys are not unique in the source code, later entries will overwrite previous\nones! I.e.,\n\n...\n\"My special holiday\" => \"01-11\",\n\"My special holiday\" => \"02-11\",\n...\n\nwill NOT set two holidays of the same name, one on November first, the other on November\nsecond, but only one, on November second!\n\nTherefore, in order to use sets of defaults and to be able to override some of them, you must\nFIRST include any hash containing the default definitions, and THEN write down your own\ndefinitions (see also the Date::Calendar::Profiles module for examples of this!), like this:\n\n$defaults =\n{\n\"Holiday #1\" => \"01-01\",\n\"Holiday #2\" => \"02-02\",\n\"Holiday #3\" => \"03-03\"\n};\n\n$variant1 =\n{\n%$defaults,\n\"Holiday #2\" => \"09-02\",\n\"Holiday #4\" => \"04-04\"\n};\n\nThis is because of the way hashes work in Perl.\n\nThe \"init()\" method proceeds as follows:\n\nFirst it checks whether the given year number lies in the range [1583..2299]. A fatal error\noccurs if not.\n\nThen it determines the number of days in the requested year, and stores it in the given\nDate::Calendar::Year object.\n\nIt then calls the Bit::Vector(3) module to allocate three bit vectors with a number of bits\nequal to the number of days in the requested year, and stores the three object references (of\nthe bit vectors) in the Date::Calendar::Year object.\n\n(See also the description of the three methods \"vecfull()\", \"vechalf()\" and \"vecfull()\"\nimmediately below.)\n\nIt then sets the bits which correspond to Saturdays and Sundays (or optionally to the days\nwhose numbers have been specified as the \"weekend\") in the \"full holidays\" bit vector.\n\nAt last, it iterates over the keys of the given holiday scheme (of the hash referred to by the\nhash reference passed to the \"init()\" method as the second argument), evaluates the formula\n(or calls the given callback function), and sets the corresponding bit in the \"full\" or \"half\"\nholidays bit vector if the calculated date is valid.\n\nA fatal error occurs if the date formula cannot be parsed or if the date returned by a formula\nor callback function is invalid (e.g. 30-Feb-2001 or the like) or lies outside the given year\n(e.g. Easter+365).\n\nFinally, the \"init()\" method makes sure that days marked as \"full\" holidays do not appear as\n\"half\" holidays as well.\n\nThen the \"init()\" method returns.\n\nNote that when deciphering the date formulas, the \"init()\" method uses the functions\n\"DecodeDayofWeek()\" and \"DecodeMonth()\" from the Date::Calc(3) module, which are\nlanguage-dependent.\n\nTherefore the \"init()\" method allows you to pass it an optional third argument, which must\nconsist of the valid name or number of a language as provided by the Date::Calc(3) module.\n\nFor the time of scanning the given holiday scheme, the \"init()\" method will use the language\nthat has been specified, or the global setting from \"Language()\" if no or an invalid language\nparameter is given.\n\nThe default is English if none is specified and if the global setting has not been modified.\n\nThis means that you can provide the names of months and days of week in your holiday profile\nin any of the languages supported by the Date::Calc(3) module, provided you give the \"init()\"\nmethod a clue (the third parameter) which language to expect.\n\n* \"$vector = $year->vecfull();\"\n\nThis method returns a reference to the bit vector in the given year object which contains all\n\"full\" holidays.\n\nBEWARE that you should NEVER change the contents of this bit vector unless you know EXACTLY\nwhat you're doing!\n\nYou should usually only read from this bit vector, or use it as an operand in bit vector\noperations - but never as an lvalue.\n\n* \"$vector = $year->vechalf();\"\n\nThis method returns a reference to the bit vector in the given year object which contains all\n\"half\" holidays.\n\nBEWARE that you should NEVER change the contents of this bit vector unless you know EXACTLY\nwhat you're doing!\n\nYou should usually only read from this bit vector, or use it as an operand in bit vector\noperations - but never as an lvalue.\n\n* \"$vector = $year->vecwork();\"\n\nThis method returns a reference to the \"workspace\" bit vector in the given year object.\n\nNote that you cannot rely on the contents of this bit vector.\n\nYou have to set it up yourself before performing any calculations with it.\n\nCurrently the contents of this bit vector are modified by the two methods \"deltaworkdays()\"\nand \"adddeltaworkdays()\", in ways which are hard to predict (depending on the calculations\nbeing performed).\n\nThe size of this bit vector can be determined through either \"\"$days = $vector->Size();\"\" or\n\"\"$days = $year->valdays();\"\".\n\n* \"$size = $year->valdays();\"\n\nThis method returns the number of days in the given year object, i.e., either 365 or 366. This\nis also the size (number of bits) of the three bit vectors contained in the given year object.\n\n* \"$base = $year->valbase();\"\n\nThis method returns the value of the expression \"\"DatetoDays($year->valyear(),1,1)\"\", or in\nother words, the number of days between January 1st of the year 1 and January 1st of the given\nyear, plus one.\n\nThis value is used internally by the method \"date2index()\" in order to calculate the \"julian\"\ndate or day of the year for a given date.\n\nThe expression above is computed only once in method \"init()\" and then stored in one of the\nyear object's attributes, of which this method just returns the value.\n\n* \"$number = $year->valyear();\"\n\n\"$number = $year->year();\"\n\nThese two methods are identical, the latter being a shortcut of the former.\n\nThey return the number of the year for which a calendar has been stored in the given year\nobject.\n\nThe method name \"valyear()\" is used here in order to be consistent with the other attribute\naccessor methods of this class, and the method \"year()\" is necessary in order to be able to\npass Date::Calendar::Year objects as parameters instead of a year number in the methods of the\nDate::Calendar and Date::Calendar::Year modules.\n\n* \"@names = $year->labels(YEAR,MONTH,DAY|DATE);\"\n\n\"@holidays = $year->labels();\"\n\n\"$holidays = $year->labels();\"\n\nIf any arguments are given, they are supposed to represent a date. In that case, a list of all\nlabels (= names of holidays) associated with that date are returned. The first item returned\nis always the name of the day of week for that date.\n\nIf no arguments are given, the list of all available labels in the given year is returned.\nThis list does NOT include any names of the days of week (which would be pointless in this\ncase).\n\nIn list context, the resulting list itself is returned. In scalar context, the number of items\nin the resulting list is returned.\n\n* \"@dates = $year->search(PATTERN);\"\n\n\"$dates = $year->search(PATTERN);\"\n\nThis method searches through all the labels of the given year and returns a list of date\nobjects with all dates whose labels match the given pattern.\n\nNote that this is a simple, case-insensitive substring search, NOT a full-fledged regular\nexpression search!\n\nThe result is guaranteed to be sorted chronologically.\n\nIn scalar context, only the number of items in the resulting list is returned, instead of the\nresulting list itself (as in list context).\n\n* \"$hashref = $year->tags(YEAR,MONTH,DAY|DATE);\"\n\n\"$hashref = $year->tags(INDEX);\"\n\nThis method returns a hash reference for the given calendar and date (or index). The hash it\nrefers to is a copy of the calendar profile's internal hash which contains the names for the\ngiven date as keys and 0, 1, 2, or 3 as their corresponding values meaning the following:\n\n0    =>    commemorative day\n1    =>    \"half\" holiday\n2    =>    \"full\" holiday\n3    =>    both a \"half\" and a \"full\" holiday\n\nThe value \"3\" should only occur if a date has been redefined by the underlying profile using\nthe same key (i.e., the same name) but with a different type of holiday.\n\nThe index must be a number such as returned by the method \"date2index()\"; it can be used here\ninstead of a date or a date object in order to speed up processing (= no need to calculate it\ninternally).\n\n* \"$days = $year->deltaworkdays(YEAR,MONTH1,DAY1, YEAR,MONTH2,DAY2, FLAG1,FLAG2);\"\n\n\"$days = $year->deltaworkdays(DATE1,DATE2,FLAG1,FLAG2);\"\n\nThis method calculates the number of work days (i.e., the number of days, but excluding all\nholidays) between two dates.\n\nIn other words, this method is equivalent to the \"DeltaDays()\" function of the Date::Calc\nmodule, except that it disregards holidays in its counting.\n\nThe two flags indicate whether the start and end dates should be included in the counting\n(that is, of course, only in case they aren't holidays), or not.\n\nIt is common, for example, that you want to know how many work days are left between the\ncurrent date and a given deadline.\n\nTypically, you will want to count the current date but not the deadline's date. So you would\nspecify \"true\" (\"1\") for FLAG1 and \"false\" (\"0\") for FLAG2 in order to achieve that.\n\nIn other words, a value of \"true\" means \"including this date\", a value of \"false\" means\n\"excluding this date\".\n\nAs with the \"DeltaDays()\" function from the Date::Calc module, the dates have to be given in\nchronological order to yield a positive result. If the dates are reversed, the result will be\nnegative.\n\nThe parameter FLAG1 is associated with the first given date, the parameter FLAG2 with the\nsecond given date (regardless of whether the dates are in chronological order or not).\n\nAn exception (\"given year != object's year\") is thrown if the year number of either of the two\ngiven dates does not match the year number associated with the given year object.\n\nAn exception (\"invalid date\") is also raised if either of the two date arguments does not\nconstitute a valid date.\n\n* \"($date,$rest,$sign) = $year->adddeltaworkdays(YEAR,MONTH,DAY, DELTA, SIGN);\"\n\n\"($date,$rest,$sign) = $year->adddeltaworkdays(DATE,DELTA,SIGN);\"\n\nThis method is the equivalent of the \"AddDeltaDays()\" function from the Date::Calc module,\nexcept that it adds work days and skips holidays.\n\nIn other words, you can add or subtract a number of work days \"DELTA\" to/from a given date and\nget a new date as the result (as a Date::Calc object).\n\nYou add days (i.e., you go forward in time) with a positive offset \"DELTA\", and you subtract\ndays (i.e., you go backwards in time) with a negative offset.\n\nNote that an exception (\"invalid date\") is raised if the given date argument (the \"start\"\ndate) does not constitute a valid date.\n\nBeware that this method is limited to date calculations within a single year (in contrast to\nthe method with the same name from the Date::Calendar module).\n\nTherefore, the method does not only return a date (object), but also a \"rest\" and a \"sign\".\n\nThe \"rest\" indicates how many days are still left from your original DELTA after going in the\ndesired direction and reaching a year boundary.\n\nThe \"sign\" indicates in which direction (future or past) one needs to go in order to \"eat up\"\nthe \"rest\" (by subtracting a day from the \"rest\" for each work day passed), or to adjust the\nresulting date (in order to skip any holidays directly after a year boundary), if at all.\n\nThe \"sign\" is -1 for going backwards in time, +1 for going forward, and 0 if the result\ndoesn't need any more fixing (for instance because the result lies in the same year as the\nstarting date).\n\nThe method \"adddeltaworkdays()\" from the Date::Calendar module uses the \"rest\" and \"sign\"\nreturn values from this method in order to perform calculations which may cross year\nboundaries.\n\nTherefore, it is not recommended to use this method here directly, as it is rather clumsy to\nuse, but to use the method with the same name from the Date::Calendar module instead, which\ndoes the same but is much easier to use and moreover allows calculations which cross an\narbitrary number of year boundaries.\n\nBEWARE that this method may currently return unexpected (i.e., contradicting the above\ndocumentation) or plain wrong results when going back in time (this is a bug!).\n\nHowever, it works correctly and as documented above when going forward in time.\n\n* \"$flag = $year->isfull(YEAR,MONTH,DAY|DATE);\"\n\nThis method returns \"true\" (\"1\") if the bit corresponding to the given date is set in the bit\nvector representing \"full\" holidays, and \"false\" (\"0\") otherwise.\n\nI.e., the method returns \"true\" if the given date is a (full) holiday (according to the\ncalendar profile associated with the given year object).\n\n* \"$flag = $year->ishalf(YEAR,MONTH,DAY|DATE);\"\n\nThis method returns \"true\" (\"1\") if the bit corresponding to the given date is set in the bit\nvector representing \"half\" holidays, and \"false\" (\"0\") otherwise.\n\nI.e., the method returns \"true\" if the given date is a half holiday (according to the calendar\nprofile associated with the given year object).\n\nNote that if a date is a \"full\" holiday, the \"half\" bit is never set, even if you try to do so\nin your calendar profile, on purpose or by accident.\n\n* \"$flag = $year->iswork(YEAR,MONTH,DAY|DATE);\"\n\nThis method returns \"true\" (\"1\") if the bit corresponding to the given date is set in the bit\nvector used to perform all sorts of calculations, and \"false\" (\"0\") otherwise.\n\nBEWARE that the \"work\" in this method's name does NOT come from \"work days\"!\n\nIt comes from the fact that the corresponding bit vector can be used for any \"work\" that you\nneed to do. In other words, it's a \"work space\".\n\nTherefore, this bit vector might contain about everything you could imagine - including a bit\npattern which marks all \"work days\" with set bits, if it so happens!\n\nBut you better don't rely on it, unless you put the bit pattern there yourself in the first\nplace.\n\nNote that you can get a reference to this bit vector (in order to fill it with any bit pattern\nyou like) using the method \"vecwork()\", described further above in this document.\n\nThe number of bits in this bit vector is the same as the number of days in the given year\n\"$year\", which you can retrieve through either \"\"$days = $year->vecwork->Size();\"\" or \"\"$days\n= $year->valdays();\"\".\n\nSee also Bit::Vector(3) for more details.\n",
            "subsections": []
        },
        "SEE ALSO": {
            "content": "Bit::Vector(3), Date::Calendar(3), Date::Calendar::Profiles(3), Date::Calc::Object(3),\nDate::Calc(3), Date::Calc::Util(3).\n",
            "subsections": []
        },
        "KNOWN BUGS": {
            "content": "The method \"adddeltaworkdays()\" is known to produce results which are sometimes off by one\nworking day when a negative offset is used. As a workaround, try to add one working day first\nand then subtract one working day more than initially intended. See also the file\n\"examples/bug.pl\" for how to do this.\n",
            "subsections": []
        },
        "VERSION": {
            "content": "This man page documents \"Date::Calendar::Year\" version 6.4.\n",
            "subsections": []
        },
        "AUTHOR": {
            "content": "Steffen Beyer\nmailto:STBEY@cpan.org\nhttp://www.engelschall.com/u/sb/download/\n",
            "subsections": []
        },
        "COPYRIGHT": {
            "content": "Copyright (c) 2000 - 2015 by Steffen Beyer. All rights reserved.\n",
            "subsections": []
        },
        "LICENSE": {
            "content": "This package is free software; you can use, modify and redistribute it under the same terms as\nPerl itself, i.e., at your option, under the terms either of the \"Artistic License\" or the \"GNU\nGeneral Public License\".\n\nThe C library at the core of the module \"Date::Calc::XS\" can, at your discretion, also be used,\nmodified and redistributed under the terms of the \"GNU Library General Public License\".\n\nPlease refer to the files \"Artistic.txt\", \"GNUGPL.txt\" and \"GNULGPL.txt\" in the \"license\"\nsubdirectory of this distribution for any details!\n",
            "subsections": []
        },
        "DISCLAIMER": {
            "content": "This package is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY;\nwithout even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.\n\nSee the \"GNU General Public License\" for more details.\n",
            "subsections": []
        }
    },
    "summary": "Date::Calendar::Year - Implements embedded \"year\" objects for Date::Calendar",
    "flags": [],
    "examples": [],
    "see_also": [
        {
            "name": "Vector",
            "section": "3",
            "url": "https://www.chedong.com/phpMan.php/man/Vector/3/json"
        },
        {
            "name": "Calendar",
            "section": "3",
            "url": "https://www.chedong.com/phpMan.php/man/Calendar/3/json"
        },
        {
            "name": "Profiles",
            "section": "3",
            "url": "https://www.chedong.com/phpMan.php/man/Profiles/3/json"
        },
        {
            "name": "Object",
            "section": "3",
            "url": "https://www.chedong.com/phpMan.php/man/Object/3/json"
        },
        {
            "name": "Calc",
            "section": "3",
            "url": "https://www.chedong.com/phpMan.php/man/Calc/3/json"
        },
        {
            "name": "Util",
            "section": "3",
            "url": "https://www.chedong.com/phpMan.php/man/Util/3/json"
        }
    ]
}