Date-Calc
view release on metacpan or search on metacpan
CHANGES.txt view on Meta::CPAN
+ Made some tiny changes to the documentation
Version 5.5 was skipped due to an unauthorized upload by someone else
Version 5.4 03.10.2004
+ Added compiler directives for C++.
+ Removed "Carp::Clan" from the distribution (available separately).
+ Fixed bug in initialization of "Date::Calendar::Year" objects.
+ Added method "tags()" to "Date::Calendar" and "Date::Calendar::Year".
+ Fixed the formula for "Labor Day" in the U.S. to "1/Mon/Sep".
+ Added a new recipe to the "Date::Calc" documentation.
+ Added Romanian to the list of languages supported by "Date::Calc".
+ Changed the example script "calendar.cgi" to highlight the name
which led to a given date being a holiday.
+ Fixed the Polish entries in "Date::Calc".
+ Added a few commemorative days to the Norwegian calendar profile.
+ Added "use bytes" to all Perl files to avoid problems on systems
not using the standard locale "C".
+ Fixed test 5 of t/m005.t to (hopefully) work under other locales.
CREDITS.txt view on Meta::CPAN
porting version 5.0 of this module to MacOS and MacPerl. His
port (plus some additions - see below) is now version 5.1.
Thanks to Ken Clarke <perlprogrammer@shaw.ca> for his addition to
the documentation concerning the function "Monday_of_Week()".
Many thanks to Nora Elia Castillo <nec@leia.sunmexico.Sun.COM> for
sending me the list of holidays for Mexico!
Thanks to dLux (Balázs Tibor Szabó) <dlux@dlux.hu> for his much
simpler formula in recipe #4 in the "Date::Calc" documentation.
Thanks to Daniel Berger <djberge@qwest.com> for suggesting a
normalization method for delta vectors in Date::Calc::Object,
which has been added in version 5.1.
Thanks to Danny Rathjens <dkr@rathjens.org> for suggesting the
improvement in the documentation of Date::Calc concerning the
paragraph which says that ALL ranges start with 1 - except,
of course, hours, minutes and seconds.
CREDITS.txt view on Meta::CPAN
The bug hasn't been fixed yet, but there is a workaround which seems
to remedy the problem: First add one workday to the date in question,
and then subtract one workday more than initially.
Many thanks to Mike Swieton <swietonm@student.gvsu.edu> (and many other
people in the past) for sending in a patch so that ToolBox.h will compile
with C++ compilers.
Thanks to Joe Rice <riceja@water-melon.net> and Sridhar Gopal
<sridhar.gopal@bankofamerica.com> for pointing out that the formula
for Labor Day in the U.S. apparently was wrong; it returned
September 8th in 2003 but Labor Day in that year actually was on
September 1st. It should obviously be "1/Mon/Sep" instead.
Many thanks to M.S. Tawfik <mstawfik@optonline.net> for finding a
bug in the "init()" method of Date::Calendar::Year when the year
starts with a Sunday (such as in 1995) and for sending a patch!
Thanks to George Cooke <quatto@hotmail.com> for raising the question
of how to "normalize" the results of the "Delta_YMD()" function to
lib/Date/Calendar/Profiles.pm view on Meta::CPAN
"Christmas Day" => \&GB_Christmas,
"Boxing Day" => \&GB_Boxing
};
sub GB_New_Year
{
my($year,$label) = @_;
return( &Next_Monday($year,1,1) );
}
#
# The following formula (also from Jonathan Stowe <gellyfish@gellyfish.com>)
# also contradicts my pocket calendar, but for lack of a better guess I
# left it as it is. Please tell me the correct formula in case this one
# is wrong! Thank you!
#
sub GB_Early_May # May bank holiday is the first Monday after May 1st
{
my($year,$label) = @_;
if (Day_of_Week($year,5,1) == 1)
{ return( Nth_Weekday_of_Month_Year($year,5,1,2) ); }
else
{ return( Nth_Weekday_of_Month_Year($year,5,1,1) ); }
}
lib/Date/Calendar/Profiles.pm view on Meta::CPAN
"Queen's Birthday" => "2/Mon/Jun",
"Royal Show (Brisbane)" => \&AU_QLD_Brisbane
};
$Profiles->{'AU-TAS'} = # Tasmania
{
%{$Profiles->{'AU'}},
"New Year's Day" => "01.01.",
"Regatta Day" => "2/Tue/Feb",
"Lauceston Cup Day" => \&AU_Lauceston,
"King Island Show Day" => "1/Tue/Mar", # uncertain! (maybe Tuesday after 1/Sun/Mar?)
"Eight Hour Day" => "2/Mon/Mar", # dubious, formula probably wrong!
"Easter Saturday" => "-1",
"Queen's Birthday" => "2/Mon/Jun",
"Recreation Day" => "1/Mon/Nov" # only North Tasmania - date not confirmed!
};
$Profiles->{'AU-SA'} = # South Australia
{
%{$Profiles->{'AU'}},
"New Year's Day" => "01.01.",
"Easter Saturday" => "-1",
"Adelaide Cup Day" => "3/Mon/May", # uncertain! (maybe Monday after 3/Sun/May?)
lib/Date/Calendar/Profiles.pm view on Meta::CPAN
%{$Profiles->{'AU'}},
"New Year's Day" => "01.01.",
"Labour Day" => "1/Mon/Mar",
"Foundation Day" => "1/Mon/Jun",
"Queen's Birthday" => "1/Mon/Oct"
};
$Profiles->{'AU-ACT'} = # Australian Capital Territory
{
%{$Profiles->{'AU'}},
"New Year's Day" => "01.01.",
"Canberra Day" => "2/Mon/Mar", # dubious, formula probably wrong!
"Easter Saturday" => "-1",
"Queen's Birthday" => "2/Mon/Jun",
"Labour Day" => "1/Mon/Oct"
};
$Profiles->{'AU-NSW'} = # New South Wales
{
%{$Profiles->{'AU'}},
"New Year's Day" => \&AU_New_Year,
"Easter Saturday" => "-1",
"Queen's Birthday" => "2/Mon/Jun",
lib/Date/Calendar/Profiles.pod view on Meta::CPAN
Any improvements are therefore left as an exercise
to the inclined reader.
=head1 DESCRIPTION
The method "init()" in module Date::Calendar::Year(3) is
responsible for parsing the calendar schemes contained
here in the Date::Calendar::Profiles module.
This method offers a "mini-language" which allows to
specify common date formulas, like for instance a simple
fixed date (in various different formats, e.g. american
or european), or things like "the second Sunday of May"
(Mother's Day), or "Easter Sunday minus 46 days" (Ash
Wednesday), to cite just a few.
See the section "DATE FORMULA SYNTAX" below for more
details.
There are some more complicated formulas, however, which
cannot be expressed in such simple terms.
The rule that if a holiday falls on a weekend, it will
be substituted by either the adjacent Friday or Monday
(whichever lies closer), is an example of this.
In order to be able to deal with such formulas, and in
order to be as flexible as possible, the "init()" method
offers the possibility of using callback functions to
deal with such dates and formulas.
See the section "CALLBACK INTERFACE" below for more
details on this topic.
In order to assist you with more common cases of odd
formulas, the module Date::Calendar::Profiles exports
the following utility subroutines (which are meant to
be used as "filters" in callback functions of your own):
=over 2
=item *
C<($year,$month,$day[,ANYTHING]) = Previous_Friday($year,$month,$day[,ANYTHING]);>
If the given date falls on a Saturday or Sunday, this
lib/Date/Calendar/Profiles.pod view on Meta::CPAN
=head1 HOW TO ROLL YOUR OWN
Every calendar profile (holiday scheme) is a hash.
The name of the holiday (like "Christmas", for instance)
serves as the key in this hash and must therefore be
unique (unless you want to override a default which was
set previously, but see below for more on this).
The value for each key is either a string, which specifies
a simple date formula, or the reference of a callback function.
See the section "CALLBACK INTERFACE" above for a description
of the interface (in and out) of these callback functions.
See the section "DATE FORMULA SYNTAX" above and the description
of the "init()" method in L<Date::Calendar::Year(3)> for the
exact syntax of date formula strings.
B<BEWARE> that if keys are not unique in the source code,
later entries will overwrite previous ones! I.e.,
...
"My special holiday" => "01-11",
"My special holiday" => "02-11",
...
will B<NOT> set two holidays of the same name, one on November
lib/Date/Calendar/Profiles.pod view on Meta::CPAN
historical irregularities into account (even though some do in order
to show how this can be done), they only provide means for calculating
B<regularly> recurring events (B<the profiles should therefore not be
relied upon for historical faithfulness>).
=head1 KNOWN BUGS
The australian calendar profiles are known to contain wrong dates.
This is due to the fact that Australia decrees its holidays individually
for each year, difficulting the calculation of the holidays by way of
a formula. An effort to compare (and to correct) the current implementation
with official documents (web pages) by the Australian authorities is under
way. This hasn't been finished yet because it is very time-consuming.
=head1 VERSION
This man page documents "Date::Calendar::Profiles" version 6.4.
=head1 AUTHOR
Steffen Beyer
lib/Date/Calendar/Year.pod view on Meta::CPAN
C<$year = Date::Calendar::Year-E<gt>new( 2001, {} );>
This is the constructor method. Call it to create a new
Date::Calendar::Year object.
The first argument must be a year number in the range
[1583..2299].
The second argument must be the reference of a hash,
which usually contains names of holidays and commemorative
days as keys and strings containing the date or formula
for each holiday as values.
Reading this hash and initializing the object's internal
data is performed by an extra method, called "init()",
which is called internally by the constructor method,
and which is described immediately below, after this
method.
In case you want to call the "init()" method yourself,
explicitly, after creating the object, you can pass an
empty profile (e.g., just an empty anonymous hash) to
the "new()" method, in order to create an empty object,
and also to improve performance.
The third argument is optional, and must consist of
the valid name or number of a language as provided by
the Date::Calc(3) module, if given.
This argument determines which language shall be used
when reading the profile, since the profile may contain
names of months and weekdays in its formulas in that
language.
The default is English if no value or no valid value
is specified (and if the global default has not been
changed with "Language()").
After the third argument, a list of day numbers which
will constitute the "weekend" can optionally be specified,
where 1=Monday, 2=Tuesday, 3=Wednesday, 4=Thursday,
5=Friday, 6=Saturday and 7=Sunday.
lib/Date/Calendar/Year.pod view on Meta::CPAN
All other types of dates must be specified via callback
functions.
Note that the "last" of a given day of week is written as
the "5th", because the last is always either the 5th or the
4th of the given day of week. So the "init()" module first
calculates the 5th of the requested day of week, and if that
doesn't exist, takes the 4th instead.
There are also two modifier characters which may prefix the
string with the date formula, "#" and ":".
The character "#" (mnemonic: it's only a comment) signals
that the date in question is a purely commemorative day,
i.e., it will not enter into any date calculations, but
can be queried with the "labels()" and "search()" methods,
and appears when printing a calendar, for instance.
The character ":" (mnemonic: divided into two halves) specifies
that the date in question is only a "half" holiday, i.e., you
only get half a day off instead of a full day. Some companies
have this sort of thing. C<:-)>
The exact syntax for the date formula strings is the following
(by example):
- Fixed dates:
"Christmas" => "24.12", # European format (day, month)
"Christmas" => "24.12.",
"Christmas" => "24Dec",
"Christmas" => "24.Dec",
"Christmas" => "24Dec.",
lib/Date/Calendar/Year.pod view on Meta::CPAN
- The 1st, 2nd, 3rd, 4th or last day of week:
"Thanksgiving" => "4Thu11",
"Thanksgiving" => "4/Thu/Nov",
"Columbus Day" => "2/Mon/Oct",
"Columbus Day" => "2/Mon/10",
"Columbus Day" => "2/1/Oct",
"Columbus Day" => "2/1/10",
"Memorial Day" => "5/Mon/May", # LAST Monday of May
Remember that each of these date formula strings may
also be prefixed with either "#" or ":":
"Christmas" => ":24.12.", # only half a day off
"Valentine's Day" => "#Feb/14", # not an official holiday
Note that the name of the month or day of week may have any
length you like, it just must specify the intended month or
day of week unambiguously. So "D", "De", "Dec", "Dece",
"Decem", "Decemb", "Decembe" and "December" would all
be valid, for example. Note also that case is ignored.
lib/Date/Calendar/Year.pod view on Meta::CPAN
(See also the description of the three methods "vec_full()",
"vec_half()" and "vec_full()" immediately below.)
It then sets the bits which correspond to Saturdays and
Sundays (or optionally to the days whose numbers have been
specified as the "weekend") in the "full holidays" bit vector.
At last, it iterates over the keys of the given holiday
scheme (of the hash referred to by the hash reference
passed to the "init()" method as the second argument),
evaluates the formula (or calls the given callback
function), and sets the corresponding bit in the "full"
or "half" holidays bit vector if the calculated date
is valid.
A fatal error occurs if the date formula cannot be parsed
or if the date returned by a formula or callback function
is invalid (e.g. 30-Feb-2001 or the like) or lies outside
the given year (e.g. Easter+365).
Finally, the "init()" method makes sure that days marked
as "full" holidays do not appear as "half" holidays as
well.
Then the "init()" method returns.
Note that when deciphering the date formulas, the "init()"
method uses the functions "Decode_Day_of_Week()" and
"Decode_Month()" from the Date::Calc(3) module, which
are language-dependent.
Therefore the "init()" method allows you to pass it an optional
third argument, which must consist of the valid name or number
of a language as provided by the Date::Calc(3) module.
For the time of scanning the given holiday scheme, the "init()"
method will use the language that has been specified, or the
( run in 1.537 second using v1.01-cache-2.11-cpan-3cd7ad12f66 )