{
    "mode": "info",
    "parameter": "Date::Calendar::Year",
    "section": "",
    "url": "https://www.chedong.com/phpMan.php/info/Date%3A%3ACalendar%3A%3AYear/json",
    "generated": "2026-07-05T09:29:10Z",
    "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": {
        "Date::Calendar::Year(3User Contributed Perl DocumentaDate::Calendar::Year(3pm)": {
            "content": "",
            "subsections": []
        },
        "NAME": {
            "content": "Date::Calendar::Year - Implements embedded \"year\" objects for\nDate::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\nyears lying within the range [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\ntime are expected as input parameters by one of the methods of this\nclass, you can always pass a Date::Calc[::Object] date object or an\narray 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\nis the recommended way of writing date constants, for increased\nreadability of your programs), it must contain three values,\nnevertheless (otherwise the use of an anonymous array would be\npointless).\n\nDon't confuse year numbers and their substitutes (a date object or an\narray reference) with Date::Calendar::Year objects, which are a totally\ndifferent thing!\n\nBut incidentally \":-)\", you may also pass a Date::Calendar::Year object\nwhenever a year number is expected. However, and perhaps against your\nexpectations at times, only the year number from that object will be\nused, not the year object itself (the year object in question might be\nusing the wrong profile!).\n\nMoreover, whenever a method of this class returns a date, it does so by\nreturning a Date::Calc[::Object] date object.\n",
            "subsections": []
        },
        "IMPLEMENTATION": {
            "content": "Each Date::Calendar::Year object consists mainly of three bit vectors,\nplus some administrative attributes, all stored in a (blessed) hash.\n\nAll three bit vectors contain as many bits as there are days in the\ncorresponding year, i.e., either 365 or 366.\n\nThe first bit vector, called \"FULL\", contains set bits for Saturdays,\nSundays and all \"full\" legal holidays (i.e., days off, on which you\nusually do not work).\n\nThe second bit vector, called \"HALF\", contains set bits for all \"half\"\nholidays, i.e., holidays where you get only half a day off from work.\n\nThe third and last bit vector, called \"WORK\", is used as a workspace,\nin which various calculations are performed throughout this module.\n\nIts name does NOT come from \"working days\" (as you might think), but\nfrom \"workspace\".\n\nIt only so happens that it is used to calculate the working days\nsometimes, at some places in this module.\n\nBut you are free to use it yourself, for whatever calculation you would\nlike to carry out yourself.\n\nThe two other bit vectors, \"FULL\" and \"HALF\", should never be changed,\nunless you know EXACTLY what you're doing!\n",
            "subsections": []
        },
        "DESCRIPTION": {
            "content": "Functions\n\no \"checkyear(YEAR);\"\n\nThis function checks that the given year lies in the permitted range\n[1583..2299]. It returns nothing in case of success, and throws an\nexception (\"given year out of range [1583..2299]\") otherwise.\n\no \"emptyperiod();\"\n\nThis function issues a warning (from the perspective of the caller of\na Date::* module) that the given range of dates is empty (\"dates\ninterval is empty\"), provided that warnings are enabled (i.e., \"$^W\"\nis true).\n\nThis function is currently used by the method \"deltaworkdays()\" in\nthis class, and by its equivalent from the Date::Calendar module.\n\nIt is called whenever the range of dates of which the difference in\nworking days is to be calculated is empty. This can happen for\ninstance if you specify two adjacent dates both of which are not to\nbe included in the difference.\n\nMethods\n\no \"$index = $year->date2index(YEAR,MONTH,DAY|DATE);\"\n\nThis method converts a given date into the number of the day in that\nyear (this is sometimes also referred to as the \"julian\" date), i.e.,\na number between 0 (for January 1st) and the number of days in the\ngiven 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\nmethods \"vecfull()\", \"vechalf()\" and \"vecwork()\".\n\nNote that there are shorthand methods in this module called\n\"isfull()\", \"ishalf()\" and \"iswork()\", which serve to test\nindividual bits of the three bit vectors which are a part of each\nDate::Calendar::Year object.\n\nAn exception (\"given year != object's year\") is thrown if the year\nassociated with the year object itself and the year from the given\ndate do not match.\n\nAn exception (\"invalid date\") is also thrown if the given arguments\ndo not constitute a valid date, or (\"given year out of range\n[1583..2299]\") if the given year lies outside of the permitted range.\n\no \"$date = $year->index2date(INDEX);\"\n\nThis method converts an index (or \"julian date\") for the given year\nback into a date.\n\nAn exception (\"invalid index\") is thrown if the given index is\noutside of the permitted range for the given year, i.e., \"[0..364]\"\nor \"[0..365]\".\n\nNote that this method returns a Date::Calc OBJECT!\n\no \"$year2000USFL = Date::Calendar::Year->new( 2000,\n$Profiles->{'US-FL'} [,LANG[,WEEKEND]] );\"\n\n\"$year2001DENW = Date::Calendar::Year->new( 2001,\n$Profiles->{'DE-NW'} [,LANG[,WEEKEND]] );\"\n\n\"$year = Date::Calendar::Year->new( 2001, {} );\"\n\nThis is the constructor method. Call it to create a new\nDate::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\ncontains names of holidays and commemorative days as keys and strings\ncontaining the date or formula for each holiday as values.\n\nReading this hash and initializing the object's internal data is\nperformed by an extra method, called \"init()\", which is called\ninternally 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,\nafter creating the object, you can pass an empty profile (e.g., just\nan empty anonymous hash) to the \"new()\" method, in order to create an\nempty object, and also to improve performance.\n\nThe third argument is optional, and must consist of the valid name or\nnumber of a language as provided by the Date::Calc(3) module, if\ngiven.\n\nThis argument determines which language shall be used when reading\nthe profile, since the profile may contain names of months and\nweekdays in its formulas in that language.\n\nThe default is English if no value or no valid value is specified\n(and if the global default has not been changed with \"Language()\").\n\nAfter the third argument, a list of day numbers which will constitute\nthe \"weekend\" can optionally be specified, where 1=Monday, 2=Tuesday,\n3=Wednesday, 4=Thursday, 5=Friday, 6=Saturday and 7=Sunday.\n\nIf no values are given, 6 and 7 (Saturday and Sunday) are\nautomatically 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\nrecurring holidays at all when for instance a zero is given.\n\no \"$year->init( 2002, $Profiles->{'DE-SN'} [,LANG[,WEEKEND]] );\"\n\nThis method is called by the \"new()\" constructor method, internally,\nand has the same arguments 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\nneeded, and you can of course subclass the Date::Calendar::Year class\nand override the \"init()\" method with a method of your own.\n\nThe holiday scheme or \"profile\" (i.e., the reference of a hash passed\nas the second argument to this method) must obey the following\nsemantics and syntax:\n\nThe keys are the names of the holiday or commemorative day in\nquestion. Keys must be unique (but see further below).\n\nThe difference between a holiday and a commemorative day is that you\n(usually) get a day off on a holiday, whereas on a purely\ncommemorative 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\nof a callback function (see Date::Calendar::Profiles(3) for more\ndetails 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\",\nbecause the last is always either the 5th or the 4th of the given day\nof week. So the \"init()\" module first calculates the 5th of the\nrequested 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\nwith the date formula, \"#\" and \":\".\n\nThe character \"#\" (mnemonic: it's only a comment) signals that the\ndate in question is a purely commemorative day, i.e., it will not\nenter into any date calculations, but can be queried with the\n\"labels()\" and \"search()\" methods, and appears when printing a\ncalendar, for instance.\n\nThe character \":\" (mnemonic: divided into two halves) specifies that\nthe date in question is only a \"half\" holiday, i.e., you only get\nhalf a day off instead of a full day. Some companies have this sort\nof thing. \":-)\"\n\nThe exact syntax for the date formula strings is the following (by\nexample):\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\nwith 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\nyou like, it just must specify the intended month or day of week\nunambiguously. So \"D\", \"De\", \"Dec\", \"Dece\", \"Decem\", \"Decemb\",\n\"Decembe\" and \"December\" would all be valid, for example. Note also\nthat case is ignored.\n\nWhen specifying day and month numbers, or offsets relative to Easter\nSunday, leading zeros are permitted (for nicely indented formatting,\nfor instance) but ignored.\n\nLeading zeros are not permitted in front of the ordinal number [1..5]\nor the number of the day of week [1..7] when specifying the nth day\nof week in a month.\n\nBEWARE that if keys are not unique in the source code, later entries\nwill overwrite previous ones! 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,\nthe other on November second, but only one, on November second!\n\nTherefore, in order to use sets of defaults and to be able to\noverride some of them, you must FIRST include any hash containing the\ndefault definitions, and THEN write down your own definitions (see\nalso the Date::Calendar::Profiles module for examples of this!), like\nthis:\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\n[1583..2299]. A fatal error occurs if not.\n\nThen it determines the number of days in the requested year, and\nstores it in the given Date::Calendar::Year object.\n\nIt then calls the Bit::Vector(3) module to allocate three bit vectors\nwith a number of bits equal to the number of days in the requested\nyear, and stores the three object references (of the bit vectors) in\nthe Date::Calendar::Year object.\n\n(See also the description of the three methods \"vecfull()\",\n\"vechalf()\" and \"vecfull()\" immediately below.)\n\nIt then sets the bits which correspond to Saturdays and Sundays (or\noptionally to the days whose numbers have been specified as the\n\"weekend\") in the \"full holidays\" bit vector.\n\nAt last, it iterates over the keys of the given holiday scheme (of\nthe hash referred to by the hash reference passed to the \"init()\"\nmethod as the second argument), evaluates the formula (or calls the\ngiven callback function), and sets the corresponding bit in the\n\"full\" or \"half\" holidays bit vector if the calculated date is valid.\n\nA fatal error occurs if the date formula cannot be parsed or if the\ndate returned by a formula or callback function is invalid (e.g.\n30-Feb-2001 or the like) or lies outside the given year (e.g.\nEaster+365).\n\nFinally, the \"init()\" method makes sure that days marked as \"full\"\nholidays do not appear as \"half\" holidays as well.\n\nThen the \"init()\" method returns.\n\nNote that when deciphering the date formulas, the \"init()\" method\nuses the functions \"DecodeDayofWeek()\" and \"DecodeMonth()\" from\nthe Date::Calc(3) module, which are language-dependent.\n\nTherefore the \"init()\" method allows you to pass it an optional third\nargument, which must consist of the valid name or number of a\nlanguage as provided by the Date::Calc(3) module.\n\nFor the time of scanning the given holiday scheme, the \"init()\"\nmethod will use the language that has been specified, or the global\nsetting from \"Language()\" if no or an invalid language parameter is\ngiven.\n\nThe default is English if none is specified and if the global setting\nhas not been modified.\n\nThis means that you can provide the names of months and days of week\nin your holiday profile in any of the languages supported by the\nDate::Calc(3) module, provided you give the \"init()\" method a clue\n(the third parameter) which language to expect.\n\no \"$vector = $year->vecfull();\"\n\nThis method returns a reference to the bit vector in the given year\nobject which contains all \"full\" holidays.\n\nBEWARE that you should NEVER change the contents of this bit vector\nunless you know EXACTLY what you're doing!\n\nYou should usually only read from this bit vector, or use it as an\noperand in bit vector operations - but never as an lvalue.\n\no \"$vector = $year->vechalf();\"\n\nThis method returns a reference to the bit vector in the given year\nobject which contains all \"half\" holidays.\n\nBEWARE that you should NEVER change the contents of this bit vector\nunless you know EXACTLY what you're doing!\n\nYou should usually only read from this bit vector, or use it as an\noperand in bit vector operations - but never as an lvalue.\n\no \"$vector = $year->vecwork();\"\n\nThis method returns a reference to the \"workspace\" bit vector in the\ngiven 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\nwith it.\n\nCurrently the contents of this bit vector are modified by the two\nmethods \"deltaworkdays()\" and \"adddeltaworkdays()\", in ways which\nare hard to predict (depending on the calculations being performed).\n\nThe size of this bit vector can be determined through either \"\"$days\n= $vector->Size();\"\" or \"\"$days = $year->valdays();\"\".\n\no \"$size = $year->valdays();\"\n\nThis method returns the number of days in the given year object,\ni.e., either 365 or 366. This is also the size (number of bits) of\nthe three bit vectors contained in the given year object.\n\no \"$base = $year->valbase();\"\n\nThis method returns the value of the expression\n\"\"DatetoDays($year->valyear(),1,1)\"\", or in other words, the\nnumber of days between January 1st of the year 1 and January 1st of\nthe given year, plus one.\n\nThis value is used internally by the method \"date2index()\" in order\nto calculate the \"julian\" date or day of the year for a given date.\n\nThe expression above is computed only once in method \"init()\" and\nthen stored in one of the year object's attributes, of which this\nmethod just returns the value.\n\no \"$number = $year->valyear();\"\n\n\"$number = $year->year();\"\n\nThese two methods are identical, the latter being a shortcut of the\nformer.\n\nThey return the number of the year for which a calendar has been\nstored in the given year object.\n\nThe method name \"valyear()\" is used here in order to be consistent\nwith the other attribute accessor methods of this class, and the\nmethod \"year()\" is necessary in order to be able to pass\nDate::Calendar::Year objects as parameters instead of a year number\nin the methods of the Date::Calendar and Date::Calendar::Year\nmodules.\n\no \"@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\nthat case, a list of all labels (= names of holidays) associated with\nthat date are returned. The first item returned is always the name of\nthe day of week for that date.\n\nIf no arguments are given, the list of all available labels in the\ngiven year is returned. This list does NOT include any names of the\ndays of week (which would be pointless in this case).\n\nIn list context, the resulting list itself is returned. In scalar\ncontext, the number of items in the resulting list is returned.\n\no \"@dates = $year->search(PATTERN);\"\n\n\"$dates = $year->search(PATTERN);\"\n\nThis method searches through all the labels of the given year and\nreturns a list of date objects with all dates whose labels match the\ngiven pattern.\n\nNote that this is a simple, case-insensitive substring search, NOT a\nfull-fledged regular expression search!\n\nThe result is guaranteed to be sorted chronologically.\n\nIn scalar context, only the number of items in the resulting list is\nreturned, instead of the resulting list itself (as in list context).\n\no \"$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\n(or index). The hash it refers to is a copy of the calendar profile's\ninternal hash which contains the names for the given date as keys and\n0, 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\nunderlying profile using the same key (i.e., the same name) but with\na different type of holiday.\n\nThe index must be a number such as returned by the method\n\"date2index()\"; it can be used here instead of a date or a date\nobject in order to speed up processing (= no need to calculate it\ninternally).\n\no \"$days = $year->deltaworkdays(YEAR,MONTH1,DAY1, YEAR,MONTH2,DAY2,\nFLAG1,FLAG2);\"\n\n\"$days = $year->deltaworkdays(DATE1,DATE2,FLAG1,FLAG2);\"\n\nThis method calculates the number of work days (i.e., the number of\ndays, but excluding all holidays) between two dates.\n\nIn other words, this method is equivalent to the \"DeltaDays()\"\nfunction of the Date::Calc module, except that it disregards holidays\nin its counting.\n\nThe two flags indicate whether the start and end dates should be\nincluded in the counting (that is, of course, only in case they\naren't holidays), or not.\n\nIt is common, for example, that you want to know how many work days\nare left between the current date and a given deadline.\n\nTypically, you will want to count the current date but not the\ndeadline's date. So you would specify \"true\" (\"1\") for FLAG1 and\n\"false\" (\"0\") for FLAG2 in order to achieve that.\n\nIn other words, a value of \"true\" means \"including this date\", a\nvalue of \"false\" means \"excluding this date\".\n\nAs with the \"DeltaDays()\" function from the Date::Calc module, the\ndates have to be given in chronological order to yield a positive\nresult. If the dates are reversed, the result will be negative.\n\nThe parameter FLAG1 is associated with the first given date, the\nparameter FLAG2 with the second given date (regardless of whether the\ndates are in chronological order or not).\n\nAn exception (\"given year != object's year\") is thrown if the year\nnumber of either of the two given dates does not match the year\nnumber associated with the given year object.\n\nAn exception (\"invalid date\") is also raised if either of the two\ndate arguments does not constitute a valid date.\n\no \"($date,$rest,$sign) = $year->adddeltaworkdays(YEAR,MONTH,DAY,\nDELTA, SIGN);\"\n\n\"($date,$rest,$sign) = $year->adddeltaworkdays(DATE,DELTA,SIGN);\"\n\nThis method is the equivalent of the \"AddDeltaDays()\" function from\nthe Date::Calc module, except that it adds work days and skips\nholidays.\n\nIn other words, you can add or subtract a number of work days \"DELTA\"\nto/from a given date and get a new date as the result (as a\nDate::Calc object).\n\nYou add days (i.e., you go forward in time) with a positive offset\n\"DELTA\", and you subtract days (i.e., you go backwards in time) with\na negative offset.\n\nNote that an exception (\"invalid date\") is raised if the given date\nargument (the \"start\" date) does not constitute a valid date.\n\nBeware that this method is limited to date calculations within a\nsingle year (in contrast to the method with the same name from the\nDate::Calendar module).\n\nTherefore, the method does not only return a date (object), but also\na \"rest\" and a \"sign\".\n\nThe \"rest\" indicates how many days are still left from your original\nDELTA after going in the desired direction and reaching a year\nboundary.\n\nThe \"sign\" indicates in which direction (future or past) one needs to\ngo in order to \"eat up\" the \"rest\" (by subtracting a day from the\n\"rest\" for each work day passed), or to adjust the resulting date (in\norder to skip any holidays directly after a year boundary), if at\nall.\n\nThe \"sign\" is -1 for going backwards in time, +1 for going forward,\nand 0 if the result doesn't need any more fixing (for instance\nbecause the result lies in the same year as the starting date).\n\nThe method \"adddeltaworkdays()\" from the Date::Calendar module uses\nthe \"rest\" and \"sign\" return values from this method in order to\nperform calculations which may cross year boundaries.\n\nTherefore, it is not recommended to use this method here directly, as\nit is rather clumsy to use, but to use the method with the same name\nfrom the Date::Calendar module instead, which does the same but is\nmuch 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.,\ncontradicting the above documentation) or plain wrong results when\ngoing back in time (this is a bug!).\n\nHowever, it works correctly and as documented above when going\nforward in time.\n\no \"$flag = $year->isfull(YEAR,MONTH,DAY|DATE);\"\n\nThis method returns \"true\" (\"1\") if the bit corresponding to the\ngiven date is set in the bit vector representing \"full\" holidays, and\n\"false\" (\"0\") otherwise.\n\nI.e., the method returns \"true\" if the given date is a (full) holiday\n(according to the calendar profile associated with the given year\nobject).\n\no \"$flag = $year->ishalf(YEAR,MONTH,DAY|DATE);\"\n\nThis method returns \"true\" (\"1\") if the bit corresponding to the\ngiven date is set in the bit vector representing \"half\" holidays, and\n\"false\" (\"0\") otherwise.\n\nI.e., the method returns \"true\" if the given date is a half holiday\n(according to the calendar profile associated with the given year\nobject).\n\nNote that if a date is a \"full\" holiday, the \"half\" bit is never set,\neven if you try to do so in your calendar profile, on purpose or by\naccident.\n\no \"$flag = $year->iswork(YEAR,MONTH,DAY|DATE);\"\n\nThis method returns \"true\" (\"1\") if the bit corresponding to the\ngiven date is set in the bit vector used to perform all sorts of\ncalculations, and \"false\" (\"0\") otherwise.\n\nBEWARE that the \"work\" in this method's name does NOT come from \"work\ndays\"!\n\nIt comes from the fact that the corresponding bit vector can be used\nfor any \"work\" that you need to do. In other words, it's a \"work\nspace\".\n\nTherefore, this bit vector might contain about everything you could\nimagine - including a bit pattern which marks all \"work days\" with\nset bits, if it so happens!\n\nBut you better don't rely on it, unless you put the bit pattern there\nyourself in the first place.\n\nNote that you can get a reference to this bit vector (in order to\nfill it with any bit pattern you like) using the method \"vecwork()\",\ndescribed further above in this document.\n\nThe number of bits in this bit vector is the same as the number of\ndays in the given year \"$year\", which you can retrieve through either\n\"\"$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),\nDate::Calc::Object(3), Date::Calc(3), Date::Calc::Util(3).\n",
            "subsections": []
        },
        "KNOWN BUGS": {
            "content": "The method \"adddeltaworkdays()\" is known to produce results which are\nsometimes off by one working day when a negative offset is used. As a\nworkaround, try to add one working day first and then subtract one\nworking 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\nunder the same terms as Perl itself, i.e., at your option, under the\nterms either of the \"Artistic License\" or the \"GNU General Public\nLicense\".\n\nThe C library at the core of the module \"Date::Calc::XS\" can, at your\ndiscretion, also be used, modified and redistributed under the terms of\nthe \"GNU Library General Public License\".\n\nPlease refer to the files \"Artistic.txt\", \"GNUGPL.txt\" and\n\"GNULGPL.txt\" in the \"license\" subdirectory of this distribution for\nany details!\n",
            "subsections": []
        },
        "DISCLAIMER": {
            "content": "This package is distributed in the hope that it will be useful, but\nWITHOUT ANY WARRANTY; without even the implied warranty of\nMERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.\n\nSee the \"GNU General Public License\" for more details.\n\nperl v5.32.0                      2020-12-27         Date::Calendar::Year(3pm)",
            "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"
        }
    ]
}