.\" Automatically generated by Pod::Man v1.34, Pod::Parser v1.13
.\" ========================================================================
.de Sh \" Subsection heading
.de Sp \" Vertical space (when we can't use .PP)
.de Vb \" Begin verbatim text
.de Ve \" End verbatim text
.\" Set up some character translations and predefined strings. \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote. | will give a
.\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to
.\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C'
.\" expand to `' in nroff, nothing in troff, for use with C<>.
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
.\" entries marked with X<> in POD. Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
. tm Index:\\$1\t\\n%\t"\\$2"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear. Run. Save yourself. No user-serviceable parts.
. \" fudge factors for nroff and troff
. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
. \" simple accents for nroff and troff
. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
. \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
. \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
. \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
.\" ========================================================================
.TH CALENDAR 1 "2002-09-28" "perl v5.8.0" "User Contributed Perl Documentation"
Date::Calendar \- Calendar objects for different holiday schemes
There is more than one way to do it \- this is just one of them!
Basically, Date::Calendar is just a caching proxy class for
Date::Calendar::Year objects, which are embedded in each
However, and in contrast to Date::Calendar::Year methods, Date::Calendar
methods permit calculations spanning an arbitrary number of years, without
So you should usually use Date::Calendar and not Date::Calendar::Year,
since that way you don't have to worry about calculations crossing year
Note however that Date::Calendar and Date::Calendar::Year can only deal
with years lying within the range [1583..2299].
\& use Date::Calendar::Profiles qw( $Profiles );
\& $calendar_US_AZ = Date::Calendar->new( $Profiles->{'US-AZ'} [,LANG] );
\& $calendar_DE_SN = Date::Calendar->new( $Profiles->{'DE-SN'} [,LANG] );
\& $year_2000_US_AZ = $calendar_US_AZ->year( 2000 );
\& $year_2001_DE_SN = $calendar_DE_SN->year( 2001 );
\& @years = $calendar->cache_keys(); # returns list of year numbers
\& @years = $calendar->cache_vals(); # returns list of year objects
\& $calendar->cache_clr();
\& $calendar->cache_add(YEAR|DATE,...);
\& $calendar->cache_del(YEAR|DATE,...);
\& $index = $calendar->date2index(YEAR,MONTH,DAY|DATE);
\& @names = $calendar->labels(YEAR,MONTH,DAY|DATE);
\& @holidays = $calendar->labels();
\& $holidays = $calendar->labels();
\& @dates = $calendar->search(PATTERN);
\& $dates = $calendar->search(PATTERN);
\& $days = $calendar->delta_workdays(YEAR1,MONTH1,DAY1|DATE1
\& ,YEAR2,MONTH2,DAY2|DATE2
\& ($date,$rest) = $calendar->add_delta_workdays(YEAR,MONTH,DAY|DATE
\& $date = $calendar->add_delta_workdays(YEAR,MONTH,DAY|DATE
\& $flag = $calendar->is_full(YEAR,MONTH,DAY|DATE);
\& $flag = $calendar->is_half(YEAR,MONTH,DAY|DATE);
\& $flag = $calendar->is_work(YEAR,MONTH,DAY|DATE);
Note that whenever a year number, a date, a time or a combined
date and time are expected as input parameters by one of the
methods of this class, you can always pass a Date::Calc[::Object]
date object or an array reference (of an array of appropriate
See \fIDate::Calc::Object\fR\|(3) for more details.
So instead of calling a given method like this:
\& $object->method1( $year,$month,$day );
\& $object->method2( $year1,$month1,$day1, $year2,$month2,$day2 );
\& $object->method3( $year1, $year2, $year3 );
You can also call it like so:
\& $object->method1( $date );
\& $object->method1( [1964,1,3] );
\& $object->method2( $year1,$month1,$day1, $date2 );
\& $object->method2( $date1, $year2,$month2,$day2 );
\& $object->method2( $date1, $date2 );
\& $object->method2( $year1,$month1,$day1, [2001,3,17] );
\& $object->method2( [1964,1,3], $year2,$month2,$day2 );
\& $object->method2( [1964,1,3], [2001,3,17] );
\& $object->method2( $date1, [2001,3,17] );
\& $object->method2( [1964,1,3], $date2 );
\& $object->method3( $year1, $date2, [2001,3,17] );
And similarly if a time or a combined date and time are expected.
If you substitute an expected year number by an anonymous array
(this is the recommended way of writing date constants, for
increased readability of your programs), it must contain three
values, nevertheless (otherwise the use of an anonymous array
Don't confuse year numbers and their substitutes (a date object
or an array reference) with Date::Calendar::Year objects, which
are a totally different thing!
But incidentally \f(CW\*(C`:\-)\*(C'\fR, you may also pass a Date::Calendar::Year
object whenever a year number is expected. However, and perhaps
against your expectations at times, especially in conjunction
with the method \*(L"\fIcache_add()\fR\*(R", only the year number from that
object will be used, not the year object itself (the year
object in question might be using the wrong profile!).
Moreover, whenever a method of this class returns a date, it
does so by returning a Date::Calc[::Object] date object.
\&\f(CW\*(C`$calendar = Date::Calendar\->new(PROFILE[,LANG]);\*(C'\fR
The first argument must be the reference of a hash,
which contains a holiday scheme or \*(L"profile\*(R" to be used
in all calculations involving the new calendar object.
The second argument is optional, and must consist of
the valid name or number of a language as provided by
the \fIDate::Calc\fR\|(3) module if given.
See \fIDate::Calendar::Profiles\fR\|(3) and \fIDate::Calendar::Year\fR\|(3)
for more details about these arguments and about how
to roll your own calendar profiles.
The method creates a new calendar object for a given profile,
i.e., a given location and its scheme of holidays (or a scheme
This calendar object is a caching proxy object; it stores the
reference of the given profile and contains a hash (the cache)
of Date::Calendar::Year objects.
\&\f(CW\*(C`$year = $calendar\->year(YEAR|DATE);\*(C'\fR
This method returns a Date::Calendar::Year object for the given
year and the profile that was associated with the given calendar
If the cache in the given calendar object already contains an
object for the requested year, the corresponding object reference
If not, a new Date::Calendar::Year object is created using the
profile that has been associated with the given calendar object.
The new Date::Calendar::Year object is then stored in the calendar
object's cache and its object reference is returned.
A fatal \*(L"given year out of range\*(R" error will occur if the given
year number lies outside the valid range of [1583..2299].
\&\f(CW\*(C`@years = $calendar\->cache_keys();\*(C'\fR
This method returns the list of \fB\s-1YEAR\s0 \s-1NUMBERS\s0\fR of the
Date::Calendar::Year objects contained in the given
\&\f(CW\*(C`@years = $calendar\->cache_vals();\*(C'\fR
This method returns the list of \fB\s-1OBJECT\s0 \s-1REFERENCES\s0\fR of
the Date::Calendar::Year objects contained in the given
\&\f(CW\*(C`$calendar\->cache_clr();\*(C'\fR
This method clears the entire cache of the given calendar
object (by destroying the cache hash and creating a new one).
\&\f(CW\*(C`$calendar\->cache_add(YEAR|DATE,...);\*(C'\fR
Roughly, this method is a shortcut for
\& $calendar->year($year);
\&\f(CW\*(C`$calendar\->cache_del(YEAR|DATE,...);\*(C'\fR
This method removes the Date::Calendar::Year objects whose
year numbers are given from the cache of the given calendar
Year numbers for which the calendar object's cache doesn't
contain an entry are simply ignored.
\&\f(CW\*(C`$index = $calendar\->date2index(YEAR,MONTH,DAY|DATE);\*(C'\fR
This method converts a given date into the number of the day in
that year (this is sometimes also referred to as the \*(L"julian\*(R"
date), i.e., a number between 0 (for January 1st) and the number
of days in the given year minus one, i.e., 364 or 365 (for
You may need this in order to access the bit vectors returned
by the Date::Calendar::Year methods \*(L"\fIvec_full()\fR\*(R", \*(L"\fIvec_half()\fR\*(R"
and \*(L"\fIvec_work()\fR\*(R".
If the Date::Calendar::Year object for the given \s-1YEAR\s0 is not in
the \f(CW$calendar\fR's cache yet, it will be created and added.
An exception (\*(L"invalid date\*(R") is thrown if the given arguments
do not constitute a valid date, or (\*(L"given year out of range
[1583..2299]\*(R") if the given year lies outside of the permitted
\&\f(CW\*(C`@names = $calendar\->labels(YEAR,MONTH,DAY|DATE);\*(C'\fR
\&\f(CW\*(C`@holidays = $calendar\->labels();\*(C'\fR
\&\f(CW\*(C`$holidays = $calendar\->labels();\*(C'\fR
If any arguments are given, they are supposed to represent a
date. In that case, a list of all labels (= names of holidays)
associated with that date are returned. The first item returned
is always the name of the day of week for that date. The
corresponding year object for the given date's year is
added to the calendar's cache first if necessary.
If no arguments are given, the list of all available labels in
all years that have previously been accessed in the given calendar
(i.e., the years which are already in the given calendar's cache)
is constructed. Note that this means that the returned list will
be empty if there are no year objects in the given calendar's
cache yet (!). The returned list does \fB\s-1NOT\s0\fR include any names
of the days of week (which would be pointless in this case).
Multiple labels are reported only once.
Usually all years have the same set of labels, so it may seem
superfluous to scan all the years in the cache instead of just
one. But there may be exceptions, because it is possible to
define calendar profiles which do not contain all possible
holidays in every year. See \fIDate::Calendar::Profiles\fR\|(3)
and \fIDate::Calendar::Year\fR\|(3) for more details.
In list context, the resulting list itself is returned. In scalar
context, the number of items in the resulting list is returned.
\&\f(CW\*(C`@dates = $calendar\->search(PATTERN);\*(C'\fR
\&\f(CW\*(C`$dates = $calendar\->search(PATTERN);\*(C'\fR
This method searches through all the labels in all years that
have previously been accessed in the given calendar (i.e., the
years which are already in the given calendar's cache) and
returns a list of date objects with all dates whose labels
(Use the methods \*(L"\fIcache_clr()\fR\*(R", \*(L"\fIcache_add()\fR\*(R" and \*(L"\fIcache_del()\fR\*(R"
in order to put the year numbers you want into the calendar
object's cache, or to make sure it only contains the year
numbers you want to search.)
Note that this is a simple, case-insensitive substring search,
\&\fB\s-1NOT\s0\fR a full-fledged regular expression search!
The result is guaranteed to be sorted chronologically.
In scalar context, only the number of items in the resulting list
is returned, instead of the resulting list itself (as in list context).
\&\f(CW\*(C`$days = $calendar\->delta_workdays(YEAR1,MONTH1,DAY1, YEAR2,MONTH2,DAY2, FLAG1,FLAG2);\*(C'\fR
\&\f(CW\*(C`$days = $calendar\->delta_workdays(DATE1,DATE2,FLAG1,FLAG2);\*(C'\fR
This method calculates the number of work days (i.e., the number
of days, but excluding all holidays) between two dates.
In other words, this method is equivalent to the \*(L"\fIDelta_Days()\fR\*(R"
function of the Date::Calc module, except that it disregards
holidays in its counting.
The two flags indicate whether the start and end dates should be
included in the counting (that is, of course, only in case they
aren't holidays), or not.
It is common, for example, that you want to know how many work
days are left between the current date and a given deadline.
Typically, you will want to count the current date but not the
deadline's date. So you would specify \*(L"true\*(R" (\*(L"1\*(R") for \s-1FLAG1\s0
and \*(L"false\*(R" (\*(L"0\*(R") for \s-1FLAG2\s0 in order to achieve that.
In other words, a value of \*(L"true\*(R" means \*(L"including this date\*(R",
a value of \*(L"false\*(R" means \*(L"excluding this date\*(R".
As with the \*(L"\fIDelta_Days()\fR\*(R" function from the Date::Calc module,
the dates have to be given in chronological order to yield a
positive result. If the dates are reversed, the result will
The parameter \s-1FLAG1\s0 is associated with the first given date,
the parameter \s-1FLAG2\s0 with the second given date (regardless
of whether the dates are in chronological order or not).
An exception (\*(L"invalid date\*(R") is raised if either of the two
date arguments does not constitute a valid date.
\&\f(CW\*(C`($date,$rest) = $calendar\->add_delta_workdays(YEAR,MONTH,DAY, DELTA);\*(C'\fR
\&\f(CW\*(C`($date,$rest) = $calendar\->add_delta_workdays(DATE,DELTA);\*(C'\fR
\&\f(CW\*(C`$date = $calendar\->add_delta_workdays(YEAR,MONTH,DAY, DELTA);\*(C'\fR
\&\f(CW\*(C`$date = $calendar\->add_delta_workdays(DATE,DELTA);\*(C'\fR
This method is the equivalent of the \*(L"\fIAdd_Delta_Days()\fR\*(R" function
from the Date::Calc module, except that it adds work days and
In other words, you can add or subtract a number of work days
\&\*(L"\s-1DELTA\s0\*(R" to/from a given date and get a new date as the result
(as a Date::Calc object).
You add days (i.e., you go forward in time) with a positive
offset \*(L"\s-1DELTA\s0\*(R", and you subtract days (i.e., you go backwards
in time) with a negative offset.
Note that an exception (\*(L"invalid date\*(R") is raised if the
given date argument does not constitute a valid date.
In scalar context, the method just returns the resulting date
object, whereas in list context the method not only returns the
new date, but also a \*(L"rest\*(R". This rest is useful for cases in
which your profile contains \*(L"half\*(R" holidays, or when you add
or subtract fractions of a day.
Sometimes it is not possible to accomodate the requested number
of work days, and a rest remains.
This rest can currently only assume the value \*(L"0.0\*(R" (zero),
\&\*(L"\-0.5\*(R" (minus one half) or \*(L"0.5\*(R" (one half), provided you
use only integral or multiples of 0.5 as offsets. A rest
of zero indicates that the calculation yielded an exact
result. If the rest is 0.5 or \-0.5, this is to be interpreted
as \*(L"the resulting date at 12:00 o'clock\*(R", instead of as \*(L"the
resulting date at 0:00 o'clock\*(R".
The rest is always positive (or zero) if the offset \*(L"\s-1DELTA\s0\*(R"
is positive (or zero), and always negative (or zero) if the
offset is negative (or zero).
\& use Date::Calendar::Profiles qw( $Profiles );
\& $cal = Date::Calendar->new( $Profiles->{'sdm-MUC'} );
\& ($date,$rest) = $cal->add_delta_workdays($year,1,3, -3);
\& $date->date_format(1);
\& print "\e$date = $date, \e$rest = $rest.\en";
This program calculates \*(L"January 3rd of the given year minus
\& $date = 28-Dec-2000, $rest = 0.
\& $date = 28-Dec-2001, $rest = -0.5.
Note that December 31st is a \*(L"half\*(R" holiday in 2001 for the
calendar profile used in this example.
You can easily verify the results above with the help of the
\&\*(L"calendar.cgi\*(R" \s-1CGI\s0 script or the \*(L"linearcal.pl\*(R" script from
the \*(L"examples\*(R" subdirectory in the Date::Calc distribution.
\&\f(CW\*(C`$flag = $calendar\->is_full(YEAR,MONTH,DAY|DATE);\*(C'\fR
This method returns \*(L"true\*(R" (\*(L"1\*(R") if the bit corresponding to
the given date is set in the bit vector representing \*(L"full\*(R"
holidays, and \*(L"false\*(R" (\*(L"0\*(R") otherwise.
I.e., the method returns \*(L"true\*(R" if the given date is a (full)
holiday (according to the calendar profile associated with the
The corresponding Date::Calendar::Year object is created first
and stored in the calendar object's cache if necessary (if it's
Note that you can get a reference to this bit vector (in order
to use this bit vector in bit vector operations) as follows:
\& $vec_full = $calendar->year($year)->vec_full();
The number of bits in this bit vector is the same as the number
of days in the given year "\f(CW$year\fR\*(L", which you can retrieve
through either \*(R"\f(CW\*(C`$days = $vec_full\->Size();\*(C'\fR\*(L" or
\&\*(R"\f(CW\*(C`$days = $year\->val_days();\*(C'\fR".
See \fIDate::Calendar::Year\fR\|(3) and \fIBit::Vector\fR\|(3) for more
\&\f(CW\*(C`$flag = $calendar\->is_half(YEAR,MONTH,DAY|DATE);\*(C'\fR
This method returns \*(L"true\*(R" (\*(L"1\*(R") if the bit corresponding to
the given date is set in the bit vector representing \*(L"half\*(R"
holidays, and \*(L"false\*(R" (\*(L"0\*(R") otherwise.
I.e., the method returns \*(L"true\*(R" if the given date is a half
holiday (according to the calendar profile associated with the
Note that if a date is a \*(L"full\*(R" holiday, the \*(L"half\*(R" bit is
never set, even if you try to do so in your calendar profile,
on purpose or by accident.
The corresponding Date::Calendar::Year object is created first
and stored in the calendar object's cache if necessary (if it's
Note that you can get a reference to this bit vector (in order
to use this bit vector in bit vector operations) as follows:
\& $vec_half = $calendar->year($year)->vec_half();
The number of bits in this bit vector is the same as the number
of days in the given year "\f(CW$year\fR\*(L", which you can retrieve
through either \*(R"\f(CW\*(C`$days = $vec_half\->Size();\*(C'\fR\*(L" or
\&\*(R"\f(CW\*(C`$days = $year\->val_days();\*(C'\fR".
See \fIDate::Calendar::Year\fR\|(3) and \fIBit::Vector\fR\|(3) for more
\&\f(CW\*(C`$flag = $calendar\->is_work(YEAR,MONTH,DAY|DATE);\*(C'\fR
This method returns \*(L"true\*(R" (\*(L"1\*(R") if the bit corresponding to
the given date is set in the bit vector used to perform all
sorts of calculations, and \*(L"false\*(R" (\*(L"0\*(R") otherwise.
The corresponding Date::Calendar::Year object is created first
and stored in the calendar object's cache if necessary (if it's
\&\fB\s-1BEWARE\s0\fR that the \*(L"work\*(R" in this method's name does \fB\s-1NOT\s0\fR
come from \*(L"work days\*(R"!
It comes from the fact that the corresponding bit vector can
be used for any \*(L"work\*(R" that you need to do. In other words,
it's a \*(L"work space\*(R".
Therefore, this bit vector might contain about everything you
could imagine \- including a bit pattern which marks all \*(L"work
days\*(R" with set bits, if it so happens!
But you better don't rely on it, unless you put the bit pattern
there yourself in the first place.
Note that you can get a reference to this bit vector (in order
to fill it with any bit pattern you like) as follows:
\& $vec_work = $calendar->year($year)->vec_work();
The number of bits in this bit vector is the same as the number
of days in the given year "\f(CW$year\fR\*(L", which you can retrieve
through either \*(R"\f(CW\*(C`$days = $vec_work\->Size();\*(C'\fR\*(L" or
\&\*(R"\f(CW\*(C`$days = $year\->val_days();\*(C'\fR".
See \fIDate::Calendar::Year\fR\|(3) and \fIBit::Vector\fR\|(3) for more
\&\fIDate::Calendar::Year\fR\|(3), \fIDate::Calendar::Profiles\fR\|(3),
\&\fIDate::Calc::Object\fR\|(3), \fIDate::Calc\fR\|(3), \fIBit::Vector\fR\|(3).
This man page documents \*(L"Date::Calendar\*(R" version 5.3.
\& mailto:sb@engelschall.com
\& http://www.engelschall.com/u/sb/download/
Copyright (c) 2000 \- 2002 by Steffen Beyer. All rights reserved.
This package is free software; you can redistribute it and/or
modify it under the same terms as Perl itself, i.e., under the
terms of the \*(L"Artistic License\*(R" or the \*(L"\s-1GNU\s0 General Public License\*(R".
Please refer to the files \*(L"Artistic.txt\*(R" and \*(L"\s-1GNU_GPL\s0.txt\*(R"
in this distribution for details!
This package is distributed in the hope that it will be useful,
but \s-1WITHOUT\s0 \s-1ANY\s0 \s-1WARRANTY\s0; without even the implied warranty of
\&\s-1MERCHANTABILITY\s0 or \s-1FITNESS\s0 \s-1FOR\s0 A \s-1PARTICULAR\s0 \s-1PURPOSE\s0.
See the \*(L"\s-1GNU\s0 General Public License\*(R" for more details.
projects / OpenSPARC-T2-DV / blob