{
    "mode": "perldoc",
    "parameter": "Date::Pcalendar",
    "section": "",
    "url": "https://www.chedong.com/phpMan.php/perldoc/Date%3A%3APcalendar/json",
    "generated": "2026-06-12T13:53:58Z",
    "synopsis": "use Date::Pcalendar::Profiles qw( $Profiles );\nuse Date::Pcalendar;\n$calendarUSAZ  = Date::Pcalendar->new( $Profiles->{'US-AZ'} [,LANG[,WEEKEND]] );\n$calendarDESN  = Date::Pcalendar->new( $Profiles->{'DE-SN'} [,LANG[,WEEKEND]] );\n$year2000USAZ = $calendarUSAZ->year( 2000 );\n$year2001DESN = $calendarDESN->year( 2001 );\n@years = $calendar->cachekeys(); # returns list of year numbers\n@years = $calendar->cachevals(); # returns list of year objects\n$calendar->cacheclr();\n$calendar->cacheadd(YEAR|DATE,...);\n$calendar->cachedel(YEAR|DATE,...);\n$index        = $calendar->date2index(YEAR,MONTH,DAY|DATE);\n@names        = $calendar->labels(YEAR,MONTH,DAY|DATE);\n@holidays     = $calendar->labels();\n$holidays     = $calendar->labels();\n@dates        = $calendar->search(PATTERN);\n$dates        = $calendar->search(PATTERN);\n$hashref      = $calendar->tags(YEAR,MONTH,DAY|DATE);\n$days         = $calendar->deltaworkdays(YEAR1,MONTH1,DAY1|DATE1\n,YEAR2,MONTH2,DAY2|DATE2\n,FLAG1,FLAG2);\n($date,$rest) = $calendar->adddeltaworkdays(YEAR,MONTH,DAY|DATE\n,DELTA);\n$date         = $calendar->adddeltaworkdays(YEAR,MONTH,DAY|DATE\n,DELTA);\n$flag         = $calendar->isfull(YEAR,MONTH,DAY|DATE);\n$flag         = $calendar->ishalf(YEAR,MONTH,DAY|DATE);\n$flag         = $calendar->iswork(YEAR,MONTH,DAY|DATE);",
    "sections": {
        "NAME": {
            "content": "Date::Pcalendar - Calendar objects for different holiday schemes\n",
            "subsections": []
        },
        "MOTTO": {
            "content": "There is more than one way to do it - this is just one of them!\n",
            "subsections": []
        },
        "PREFACE": {
            "content": "Basically, Date::Pcalendar is just a caching proxy class for Date::Pcalendar::Year objects,\nwhich are embedded in each Date::Pcalendar object.\n\nHowever, and in contrast to Date::Pcalendar::Year methods, Date::Pcalendar methods permit\ncalculations spanning an arbitrary number of years, without loss of efficiency.\n\nSo you should usually use Date::Pcalendar and not Date::Pcalendar::Year, since that way you\ndon't have to worry about calculations crossing year boundaries.\n\nNote however that Date::Pcalendar and Date::Pcalendar::Year can only deal with years lying\nwithin the range [1583..2299].\n",
            "subsections": []
        },
        "SYNOPSIS": {
            "content": "use Date::Pcalendar::Profiles qw( $Profiles );\nuse Date::Pcalendar;\n\n$calendarUSAZ  = Date::Pcalendar->new( $Profiles->{'US-AZ'} [,LANG[,WEEKEND]] );\n$calendarDESN  = Date::Pcalendar->new( $Profiles->{'DE-SN'} [,LANG[,WEEKEND]] );\n\n$year2000USAZ = $calendarUSAZ->year( 2000 );\n$year2001DESN = $calendarDESN->year( 2001 );\n\n@years = $calendar->cachekeys(); # returns list of year numbers\n@years = $calendar->cachevals(); # returns list of year objects\n\n$calendar->cacheclr();\n$calendar->cacheadd(YEAR|DATE,...);\n$calendar->cachedel(YEAR|DATE,...);\n\n$index        = $calendar->date2index(YEAR,MONTH,DAY|DATE);\n\n@names        = $calendar->labels(YEAR,MONTH,DAY|DATE);\n@holidays     = $calendar->labels();\n$holidays     = $calendar->labels();\n\n@dates        = $calendar->search(PATTERN);\n$dates        = $calendar->search(PATTERN);\n\n$hashref      = $calendar->tags(YEAR,MONTH,DAY|DATE);\n\n$days         = $calendar->deltaworkdays(YEAR1,MONTH1,DAY1|DATE1\n,YEAR2,MONTH2,DAY2|DATE2\n,FLAG1,FLAG2);\n\n($date,$rest) = $calendar->adddeltaworkdays(YEAR,MONTH,DAY|DATE\n,DELTA);\n$date         = $calendar->adddeltaworkdays(YEAR,MONTH,DAY|DATE\n,DELTA);\n\n$flag         = $calendar->isfull(YEAR,MONTH,DAY|DATE);\n$flag         = $calendar->ishalf(YEAR,MONTH,DAY|DATE);\n$flag         = $calendar->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\nDate::Pcalc[::Object] date object or an array reference (of an array of appropriate length)\ninstead!\n\nSee Date::Pcalc::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::Pcalendar::Year objects, which are a totally different thing!\n\nBut incidentally \":-)\", you may also pass a Date::Pcalendar::Year object whenever a year number\nis expected. However, and perhaps against your expectations at times, especially in conjunction\nwith the method \"cacheadd()\", only the year number from that object will be used, not the year\nobject itself (the year object in question might be using the wrong profile!).\n\nMoreover, whenever a method of this class returns a date, it does so by returning a\nDate::Pcalc[::Object] date object.\n",
            "subsections": []
        },
        "DESCRIPTION": {
            "content": "* \"$calendar = Date::Pcalendar->new(PROFILE[,LANG[,WEEKEND]]);\"\n\nThe first argument must be the reference of a hash, which contains a holiday scheme or\n\"profile\" to be used in all calculations involving the new calendar object.\n\nThe second argument is optional, and must consist of the valid name or number of a language as\nprovided by the Date::Pcalc(3) module if given.\n\nAfter the second 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\nSee Date::Pcalendar::Profiles(3) and Date::Pcalendar::Year(3) for more details about these\narguments and about how to roll your own calendar profiles.\n\nThe method creates a new calendar object for a given profile, i.e., a given location and its\nscheme of holidays (or a scheme of your own).\n\nThis calendar object is a caching proxy object; it stores the reference of the given profile\nand contains a hash (the cache) of Date::Pcalendar::Year objects.\n\n* \"$year = $calendar->year(YEAR|DATE);\"\n\nThis method returns a Date::Pcalendar::Year object for the given year and the profile that was\nassociated with the given calendar object.\n\nIf the cache in the given calendar object already contains an object for the requested year,\nthe corresponding object reference is simply returned.\n\nIf not, a new Date::Pcalendar::Year object is created using the profile that has been\nassociated with the given calendar object. The new Date::Pcalendar::Year object is then stored\nin the calendar object's cache and its object reference is returned.\n\nA fatal \"given year out of range\" error will occur if the given year number lies outside the\nvalid range of [1583..2299].\n\n* \"@years = $calendar->cachekeys();\"\n\nThis method returns the list of YEAR NUMBERS of the Date::Pcalendar::Year objects contained in\nthe given calendar object's cache.\n\n* \"@years = $calendar->cachevals();\"\n\nThis method returns the list of OBJECT REFERENCES of the Date::Pcalendar::Year objects\ncontained in the given calendar object's cache.\n\n* \"$calendar->cacheclr();\"\n\nThis method clears the entire cache of the given calendar object (by destroying the cache hash\nand creating a new one).\n\n* \"$calendar->cacheadd(YEAR|DATE,...);\"\n\nRoughly, this method is a shortcut for\n\nfor $year (@list)\n{\n$calendar->year($year);\n}\n\n* \"$calendar->cachedel(YEAR|DATE,...);\"\n\nThis method removes the Date::Pcalendar::Year objects whose year numbers are given from the\ncache of the given calendar object.\n\nYear numbers for which the calendar object's cache doesn't contain an entry are simply\nignored.\n\n* \"$index = $calendar->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 Date::Pcalendar::Year\nmethods \"vecfull()\", \"vechalf()\" and \"vecwork()\".\n\nIf the Date::Pcalendar::Year object for the given YEAR is not in the $calendar's cache yet, it\nwill be created and added.\n\nAn exception (\"invalid date\") is thrown if the given arguments do not constitute a valid date,\nor (\"given year out of range [1583..2299]\") if the given year lies outside of the permitted\nrange.\n\n* \"@names = $calendar->labels(YEAR,MONTH,DAY|DATE);\"\n\n\"@holidays = $calendar->labels();\"\n\n\"$holidays = $calendar->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. The corresponding year object for the\ngiven date's year is added to the calendar's cache first if necessary.\n\nIf no arguments are given, the list of all available labels in all years that have previously\nbeen accessed in the given calendar (i.e., the years which are already in the given calendar's\ncache) is constructed. Note that this means that the returned list will be empty if there are\nno year objects in the given calendar's cache yet (!). The returned list does NOT include any\nnames of the days of week (which would be pointless in this case).\n\nMultiple labels are reported only once.\n\nUsually all years have the same set of labels, so it may seem superfluous to scan all the\nyears in the cache instead of just one. But there may be exceptions, because it is possible to\ndefine calendar profiles which do not contain all possible holidays in every year. See\nDate::Pcalendar::Profiles(3) and Date::Pcalendar::Year(3) for more details.\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 = $calendar->search(PATTERN);\"\n\n\"$dates = $calendar->search(PATTERN);\"\n\nThis method searches through all the labels in all years that have previously been accessed in\nthe given calendar (i.e., the years which are already in the given calendar's cache) and\nreturns a list of date objects with all dates whose labels match the given pattern.\n\n(Use the methods \"cacheclr()\", \"cacheadd()\" and \"cachedel()\" in order to put the year\nnumbers you want into the calendar object's cache, or to make sure it only contains the year\nnumbers you want to search.)\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 = $calendar->tags(YEAR,MONTH,DAY|DATE);\"\n\nThis method returns a hash reference for the given calendar and date. The hash it refers to is\na copy of the calendar profile's internal hash which contains the names for the given date as\nkeys 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\n* \"$days = $calendar->deltaworkdays(YEAR1,MONTH1,DAY1, YEAR2,MONTH2,DAY2, FLAG1,FLAG2);\"\n\n\"$days = $calendar->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::Pcalc\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::Pcalc 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 (\"invalid date\") is raised if either of the two date arguments does not\nconstitute a valid date.\n\n* \"($date,$rest) = $calendar->adddeltaworkdays(YEAR,MONTH,DAY, DELTA);\"\n\n\"($date,$rest) = $calendar->adddeltaworkdays(DATE,DELTA);\"\n\n\"$date = $calendar->adddeltaworkdays(YEAR,MONTH,DAY, DELTA);\"\n\n\"$date = $calendar->adddeltaworkdays(DATE,DELTA);\"\n\nThis method is the equivalent of the \"AddDeltaDays()\" function from the Date::Pcalc 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::Pcalc 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 does not\nconstitute a valid date.\n\nIn scalar context, the method just returns the resulting date object, whereas in list context\nthe method not only returns the new date, but also a \"rest\". This rest is useful for cases in\nwhich your profile contains \"half\" holidays, or when you add or subtract fractions of a day.\n\nSometimes it is not possible to accommodate the requested number of work days, and a rest\nremains.\n\nThis rest can currently only assume the value \"0.0\" (zero), \"-0.5\" (minus one half) or \"0.5\"\n(one half), provided you use only integral or multiples of 0.5 as offsets. A rest of zero\nindicates that the calculation yielded an exact result. If the rest is 0.5 or -0.5, this is to\nbe interpreted as \"the resulting date at 12:00 o'clock\", instead of as \"the resulting date at\n0:00 o'clock\".\n\nThe rest is always positive (or zero) if the offset \"DELTA\" is positive (or zero), and always\nnegative (or zero) if the offset is negative (or zero).\n\nExample:\n\n#!perl\nuse Date::Pcalendar;\nuse Date::Pcalendar::Profiles qw( $Profiles );\n$year = shift;\n$cal = Date::Pcalendar->new( $Profiles->{'sdm-MUC'} );\n($date,$rest) = $cal->adddeltaworkdays($year,1,3, -3);\n$date->dateformat(1);\nprint \"\\$date = $date, \\$rest = $rest.\\n\";\nEND\n\nThis program calculates \"January 3rd of the given year minus 3 work days\":\n\n> perl test.pl 2001\n$date = 28-Dec-2000, $rest = 0.\n> perl test.pl 2002\n$date = 28-Dec-2001, $rest = -0.5.\n\nNote that December 31st is a \"half\" holiday in 2001 for the calendar profile used in this\nexample.\n\nYou can easily verify the results above with the help of the \"calendar.cgi\" CGI script or the\n\"linearcal.pl\" script from the \"examples\" subdirectory in the Date::Pcalc distribution.\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 = $calendar->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 calendar object).\n\nThe corresponding Date::Pcalendar::Year object is created first and stored in the calendar\nobject's cache if necessary (if it's not already there).\n\nNote that you can get a reference to this bit vector (in order to use this bit vector in bit\nvector operations) as follows:\n\n$vecfull = $calendar->year($year)->vecfull();\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 = $vecfull->Size();\"\" or \"\"$days =\n$year->valdays();\"\".\n\nSee Date::Pcalendar::Year(3) and Bit::Vector(3) for more details.\n\n* \"$flag = $calendar->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 calendar 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\nThe corresponding Date::Pcalendar::Year object is created first and stored in the calendar\nobject's cache if necessary (if it's not already there).\n\nNote that you can get a reference to this bit vector (in order to use this bit vector in bit\nvector operations) as follows:\n\n$vechalf = $calendar->year($year)->vechalf();\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 = $vechalf->Size();\"\" or \"\"$days =\n$year->valdays();\"\".\n\nSee Date::Pcalendar::Year(3) and Bit::Vector(3) for more details.\n\n* \"$flag = $calendar->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\nThe corresponding Date::Pcalendar::Year object is created first and stored in the calendar\nobject's cache if necessary (if it's not already there).\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) as follows:\n\n$vecwork = $calendar->year($year)->vecwork();\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 = $vecwork->Size();\"\" or \"\"$days =\n$year->valdays();\"\".\n\nSee Date::Pcalendar::Year(3) and Bit::Vector(3) for more details.\n",
            "subsections": []
        },
        "SEE ALSO": {
            "content": "Date::Pcalendar::Year(3), Date::Pcalendar::Profiles(3), Date::Pcalc::Object(3), Date::Pcalc(3),\nDate::Calc::Util(3), Bit::Vector(3).\n",
            "subsections": []
        },
        "LIMITATIONS": {
            "content": "The calendar profiles included in Date::Pcalendar::Profiles(3) usually do not take historical\nirregularities into account (even though some do in order to show how this can be done), they\nonly provide means for calculating regularly recurring events (the profiles should therefore not\nbe relied upon for historical faithfulness).\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::Pcalendar\" version 6.1.\n",
            "subsections": []
        },
        "AUTHOR": {
            "content": "Steffen Beyer\nmailto:STBEY@cpan.org\nhttp://www.engelschall.com/u/sb/download/\n",
            "subsections": []
        },
        "COPYRIGHT": {
            "content": "Copyright (c) 2000 - 2009 by Steffen Beyer. All rights reserved.\n",
            "subsections": []
        },
        "LICENSE": {
            "content": "This package is free software; you can redistribute it and/or modify it under the same terms as\nPerl itself, i.e., under the terms of the \"Artistic License\" or the \"GNU General Public\nLicense\".\n\nPlease refer to the files \"Artistic.txt\" and \"GNUGPL.txt\" in this distribution for 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::Pcalendar - Calendar objects for different holiday schemes",
    "flags": [],
    "examples": [],
    "see_also": [
        {
            "name": "Year",
            "section": "3",
            "url": "https://www.chedong.com/phpMan.php/man/Year/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": "Pcalc",
            "section": "3",
            "url": "https://www.chedong.com/phpMan.php/man/Pcalc/3/json"
        },
        {
            "name": "Util",
            "section": "3",
            "url": "https://www.chedong.com/phpMan.php/man/Util/3/json"
        },
        {
            "name": "Vector",
            "section": "3",
            "url": "https://www.chedong.com/phpMan.php/man/Vector/3/json"
        }
    ]
}