Date-Calc
view release on metacpan or search on metacpan
CHANGES.txt view on Meta::CPAN
in "Date::Calc", "Date::Calc::Object" and "Date::Calendar::Year"
and more test cases have been added
+ Updated the documentation to reflect all changes
+ Updated version numbers of dependencies in "t/f000.t"
Version 5.8 12.09.2009
+ Added a new function "N_Delta_YMD()"
+ Added a new test script "t/f037.t"
+ Updated the "Calc.pod" manual page accordingly
+ Renamed "calendar.cgi" in the "examples"
subdirectory to "calendar.pl"
+ Added a new CGI script named "datecalc.pl"
to the "examples" subdirectory
Version 5.7 23.08.2009
+ Fixed "october" => "oktober" in Dutch
+ Disabled the special abbreviated names
of the days of the week in Portuguese
+ Made the days which form the weekend con-
figurable in "Calendar.pm" and "Year.pm"
+ Added some test cases for this new feature
in "t/m008.t"
+ The file "examples/calendar.cgi" now
also supports this new feature
+ Updated "README.txt" and "INSTALL.txt"
and the dependency on "Bit::Vector" 7.0
+ Added an additional "README.htm" file to this
distribution highlighting its key points
+ Updated the documentation of "Date::Calc",
"Date::Calendar", "Date::Calendar::Profiles",
"Date::Calendar::Year" and "Date::Object"
+ See the new module "Date::Calc::Util" (which
is available separately; to be released soon)
CHANGES.txt view on Meta::CPAN
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.
Version 5.3 29.09.2002
+ Simplified the error message handlers in "Calc.xs".
Version 5.2 18.09.2002
+ Changed the Polish profiles from ISO-Latin-2 to ISO-Latin-1.
+ Fixed the broken tests in "t/f034.t" and "t/m006.t".
+ Synchronized "Carp::Clan" and "ToolBox.h" with "Bit::Vector" 6.2.
Version 5.1 08.09.2002
+ Integrated modifications needed for MacOS / MacPerl.
+ Added new method "normalize()" (Date::Calc::Object).
+ Added a new test script "t/m011.t" for "normalize()".
+ Added a calendar profile for Mexico (Date::Calendar::Profiles).
+ Little additions to and corrections of the documentation (Date::Calc).
+ Added Polish (Date::Calc) and a calendar profile for Poland.
+ Added Hungarian (Date::Calc).
+ Added some more commemorative days to the profile of Brazil.
Version 5.0 10.10.2001
Module "Date::Calc":
+ Added the following new functions:
* check_time()
* Delta_YMD()
CHANGES.txt view on Meta::CPAN
+ Added a missing "#include <stdio.h>" statement in DateCalc.c
(apparently only relevant to very few platforms).
+ Now automatically detects Perl's "PL_na" macro or switches to its
older incarnation (in Calc.xs). Same goes for the "GIMME_V" macro.
+ Changed the function "Add_Delta_YMD()" to have a more intuitive,
consistent and reversible behaviour. This might break existing
code, though. (To get the old behaviour, use the new function
"Add_Delta_YM()" plus "Add_Delta_Days()" thereafter instead.)
+ Changed the corresponding test script (t/f029.t) accordingly.
+ Added an optional boolean parameter "orthodox" to "Calendar()"
for calendars starting with Sunday instead of Monday.
+ Changed the behaviour of the "Decode_Date_*()" set of functions:
if the current year is available on the system, then a "moving
window" strategy is applied to year numbers < 100; otherwise
it defaults to the previous behaviour (see version 4.3 below).
+ Also changed the test scripts t/f016.t, t/f027.t and t/f028.t
accordingly.
+ Changed the "Week_of_Year()" function: In scalar context, it
now returns just the week number. BEWARE, this is a DANGEROUS
feature - see the manual page for why this is so!
+ Fixed the misspelled word "whether" in the documentation.
Module "Date::Calc::Object":
+ Added the module Date::Calc::Object, an object-oriented add-on
to Date::Calc with overloaded operators.
Modules "Date::Calendar[::(Year|Profiles)]":
+ Added the modules Date::Calendar, Date::Calendar::Year and
Date::Calendar::Profiles, for calculations which need to
take holidays into account (and for generating calendars).
Module "Carp::Clan":
+ Added the module Carp::Clan (used by all new Date::* modules).
All modules:
+ Now test scripts for Date::Calc and Carp::Clan ("functions") are
in files ./t/f*.t, whereas test scripts of other, object-oriented
modules ("methods") are in files ./t/m*.t.
CHANGES.txt view on Meta::CPAN
Version 3.2 15.06.1997
+ Added the function "week_of_year()" in the C core because the C function
"week_number()" returns the last week of the previous year or the first
week of the next year in a rather hidden way.
+ The Perl function "week_number()" was not affected by this change.
Version 3.1 12.06.1997
+ Added a new function "calendar()" to the "Date::CalcLib" module.
+ Added a demo program in C named "cal.c_" (imitates the UNIX "cal"
command) to demonstrate the use of the C core as a stand-alone library.
Version 3.0 16.02.1997
+ Added the "Date::DateCalcLib" module as a library of useful functions
that were contained in the various demo files in previous versions.
+ Modified the demo programs to use this library instead.
+ Changed the conventions for unsuccessful returns: Now an empty list
is returned instead of zeros in all list elements. This makes it
CREDITS.txt view on Meta::CPAN
Many thanks to Tim Zingelman <zingelman@fnal.gov> for reporting the problem
fixed in version 2.3 and for testing an intermediate new version of this
module on his machine!
Many thanks to Jonas Liljegren <jonas@cultcom.se> for posting a subroutine
for calculating easter monday in news:comp.lang.perl.modules and thereby
triggering my writing of the new "Date::CalcLib" module which has been
added in version 3.0 of the "Date::Calc" distribution.
Also many thanks to Claus Tondering <claus@tondering.dk> for his excellent
web pages and FAQ in news:news.answers about calendars and how to calcu-
late easter sunday.
Thanks to Reinhold Stansich <dynaconsult@netway.at> for posting a list
of christian feast days and their offsets from easter sunday in news:
comp.databases.ms-access and to Tammo Schnieder <schniede@hh.sdm.de>
for sending me his posting.
Many thanks to Max Ruffert <mor@mpa-garching.mpg.de> at the Max Planck
Institute for Astrophysics in Garching for looking up Gauss' Rule for
calculating easter sunday (the algorithm which is implemented in the
"Date::CalcLib" module) for me and dictating it to me over the
phone!
Many thanks to Chris Halverson <cdh@CompleteIS.com> for asking me
"is there a "standard" way to create a calendar similar to the output
of cal(1)?", which gave me the idea to write the function "calendar"
which has been added to the module "DateCalcLib" in version 3.1, and
also for the C code demonstrating how to use the C library "lib_date.c"
stand-alone, because that was what he needed to do as well.
Many thanks to Gunardi Wu <gunardi@starindo.net> for notifying me about
the bug in the "Add_Delta_YMD()" function which was fixed in version 4.1.
Thanks to the several people who notified me about two compiler warnings
concerning incompatible character types in Calc.xs line 857 (added two
casts in version 4.2 to fix this flaw).
CREDITS.txt view on Meta::CPAN
Many thanks to ??? ??? <digitaproc@netscape.net> for sending me excellent
feedback and suggestions. He for instance suggested the possibility to
have individual formatting for different date objects, and the ability
to import/export Unix "time" values.
Many special thanks (k) to my girlfriend Ana Maria Lopes Monteiro
<anamaria_l@hotmail.com> for investigating the brazilian holidays
and commemorative days for me!
Very special thanks to the following people for helping in compiling
and verifying the calendar profiles in Date::Calendar::Profiles:
Abe Timmerman <abe@ztreet.demon.nl>
Abigail <abigail@foad.org>
Aldo Calpini <dada@perl.it>
Andie Posey <andie@posey.org>
Arnaud Calvo <arnaud@calvo-france.com>
Arturo Valdes <arturovaldes@usa.net>
Bart Lateur <bart.lateur@skynet.be>
Brian Graham <brian.graham@nec.com.au>
Bruno Tavares <bat@ip.pt> <bat@dustpuppy.ip.pt>
CREDITS.txt view on Meta::CPAN
with a list of argentinian holidays!
Many thanks to Morten Sickel <Morten.Sickel@nrpa.no> for reporting why
Excel (erroneously) regards 1900 as a leap year, and why therefore one
should use 31-Dec-1899 as the epoch for converting Excel date values.
Many thanks to Georg Mavridis <GM@mavridis.net> for providing me with
the list of greek holidays.
Many thanks also to Guenther Degenfelder <guenther.degenfelder@datev.de>
for showing me his "Karl" calendar display program, which inspired me
to write the example script "anniversaries.pl" (in the "examples"
subdirectory of this distribution).
Many special thanks to Thomas Wegner <toms_email@gmx.de> for
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()".
CREDITS.txt view on Meta::CPAN
Thanks to Joachim Ansorg <joachim@ansorgs.de> for sending me the
necessary information to add Romanian to the list of languages
supported by Date::Calc.
Many thanks to Peter Prymmer <PPrymmer@factset.com> for suggesting
a work-around for the problems that can arise when a locale other
than "C" is used!
Thanks to Olle E. Johansson <oej@edvina.net> for sending corrections
for the Swedish calendar profile.
Thanks to Harold van Oostrom <perl@lanceerplaats.nl> for sending in a
fix for the Polish language in Date::Calc. Also many thanks for his patch
to make Date::Calc ready for UTF-8, which unfortunately I haven't had
the time yet to evaluate.
Many thanks also to Sven Geisler <sgeisler@aeccom.com> for sending me
corrections for the profile and official references for ALL federal
states of Australia.
CREDITS.txt view on Meta::CPAN
Norwegian profile.
Thanks a lot to Jesse Vincent <jesse@bestpractical.com> and to
Alistair Francis <alistair.francis@lokku.com> for reporting the
ongoing problem with the boolean type in MacOS X and to Tatsuhiko
Miyagawa (?) and Alistair Francis for providing patches.
Thanks to Thanos Chatziathanassiou <tchatzi@arx.gr> along with
Barret Clark and Qiang (?) for suggesting some changes to the
documentation. Sorry for not including the changes concerning
the Orthodox and Julian calendars since these are outside of
the scope of this module.
Thanks to Anthony DeRobertis <anthony@derobert.net> and Jonathan
Yu <frequency@cpan.org> for alerting me about the problem that in
Date::Calendar and Date::Calendar::Year, it is hardcoded that
Saturday and Sunday are holidays, and for asking to make this
configurable.
Many thanks to H. Merijn Brand <h.m.brand@xs4all.nl> for triggering
the development of a new normalized date difference function.
{
"abstract" : "Gregorian calendar date calculations",
"author" : [
"Steffen Beyer <STBEY@cpan.org>"
],
"dynamic_config" : 1,
"generated_by" : "ExtUtils::MakeMaker version 7.04, CPAN::Meta::Converter version 2.140640",
"license" : [
"perl_5"
],
"meta-spec" : {
"url" : "http://search.cpan.org/perldoc?CPAN::Meta::Spec",
---
abstract: 'Gregorian calendar date calculations'
author:
- 'Steffen Beyer <STBEY@cpan.org>'
build_requires:
ExtUtils::MakeMaker: '0'
configure_requires:
ExtUtils::MakeMaker: '0'
dynamic_config: 1
generated_by: 'ExtUtils::MakeMaker version 7.04, CPAN::Meta::Converter version 2.140640'
license: perl
meta-spec:
====================================
Package "Date::Calc" Version 6.4
====================================
Abstract:
---------
This package provides all sorts of date calculations based on the Gregorian
calendar (the one used in all western countries today).
The package is designed as an efficient (and fast) toolbox, not a bulky
ready-made application. It provides extensive documentation and examples
of use, multi-language support and special functions for business needs.
Moreover, it optionally provides an object-oriented interface with overloaded
operators for greater convenience, and calendar objects which support
profiles of legal holidays and observances for calculations which need to
take those into account.
What's new in version 6.4:
--------------------------
+ Fixed t/f016.t, t/f027.t and t/f028.t which started failing on 01/01/2015
+ Fixed t/f035.t which gave a warning "Unescaped left brace in regex is deprecated"
with Perl 5.21.x
lib/Date/Calc.pod view on Meta::CPAN
=head1 NAME
Date::Calc - Gregorian calendar date calculations
=head1 MOTTO
Keep it small, fast and simple
=head1 PREFACE
This package consists of a C library and a Perl module (which uses
the C library, internally) for all kinds of date calculations based
on the Gregorian calendar (the one used in all western countries today),
thereby complying with all relevant norms and standards: S<ISO/R 2015-1971>,
S<DIN 1355> and, to some extent, S<ISO 8601> (where applicable).
(See also http://www.engelschall.com/u/sb/download/Date-Calc/DIN1355/
for a scan of part of the "S<DIN 1355>" document (in German)).
The module of course handles year numbers of 2000 and above correctly
("Year 2000" or "Y2K" compliance) -- actually all year numbers from 1
to the largest positive integer representable on your system (which
is at least 32767) can be dealt with.
This is not true, however, for the import/export functions in this
package which are an interface to the internal POSIX date and time
functions of your system, which can only cover dates in the following
ranges:
01-Jan-1970 00:00:00 GMT .. 19-Jan-2038 03:14:07 GMT [Unix etc.]
01-Jan-1904 00:00:00 LT .. 06-Feb-2040 06:28:15 LT [MacOS Classic]
(LT = local time)
Note that this package projects the Gregorian calendar back until the
year S<1 A.D.> -- even though the Gregorian calendar was only adopted
in 1582, mostly by the Catholic European countries, in obedience to the
corresponding decree of Pope S<Gregory XIII> in that year.
Some (mainly protestant) countries continued to use the Julian calendar
(used until then) until as late as the beginning of the 20th century.
Finally, note that this package is not intended to do everything you could
ever imagine automagically for you; it is rather intended to serve as a
toolbox (in the best of UNIX spirit and traditions) which should, however,
always get you where you want to go.
See the section "RECIPES" at the bottom of this document for solutions
to common problems!
lib/Date/Calc.pod view on Meta::CPAN
=item *
"Year 2000" ("Y2K") compliance
The upper limit for any year number in this module is only given
by the size of the largest positive integer that can be represented
in a variable of the C type "int" on your system, which is at least
32767, according to the ANSI C standard (exceptions see below).
In order to simplify calculations, this module projects the gregorian
calendar back until the year S<1 A.D.> -- i.e., back B<BEYOND> the
year 1582 when this calendar was first decreed by the Catholic Pope
S<Gregory XIII>!
Therefore, B<BE SURE TO ALWAYS SPECIFY "1998" WHEN YOU MEAN "1998">,
for instance, and B<DO NOT WRITE "98" INSTEAD>, because this will
in fact perform a calculation based on the year "98" A.D. and
B<NOT> "1998"!
An exception from this rule are the functions which contain the
word "compress" in their names (which can only handle years between
1970 and 2069 and also accept the abbreviations "00" to "99"), and
lib/Date/Calc.pod view on Meta::CPAN
C<$doy = Day_of_Year($year,$month,$day);>
This function returns the (relative) number of the day of the given date
in the given year.
E.g., "C<Day_of_Year($year,1,1)>" returns "C<1>",
"C<Day_of_Year($year,2,1)>" returns "C<32>", and
"C<Day_of_Year($year,12,31)>" returns either "C<365>" or "C<366>".
The day of year is sometimes also referred to as the Julian day (or date),
although it has nothing to do with the Julian calendar, the calendar which
was used before the Gregorian calendar.
In order to convert the number returned by this function back into a
date, use the function "C<Add_Delta_Days()>" (described further below),
as follows:
$doy = Day_of_Year($year,$month,$day);
($year,$month,$day) = Add_Delta_Days($year,1,1, $doy - 1);
=item *
lib/Date/Calc.pod view on Meta::CPAN
where counting starts at the 1st of January of the year S<1 A.D.>
I.e., "C<Date_to_Days(1,1,1)>" returns "C<1>", "C<Date_to_Days(1,12,31)>"
returns "C<365>", "C<Date_to_Days(2,1,1)>" returns "C<366>",
"C<Date_to_Days(1998,5,1)>" returns "C<729510>", and so on.
This is sometimes also referred to (not quite correctly) as the Julian
date (or day). This may cause confusion, because also the number of the
day in a year (from 1 to 365 or 366) is frequently called the "Julian day".
More confusing still, this has nothing to do with the Julian calendar,
which was used B<BEFORE> the Gregorian calendar.
The Julian calendar was named after famous Julius Caesar, who had
instituted it in Roman times. The Julian calendar is less precise than
the Gregorian calendar because it has too many leap years compared to
the true mean length of a year (but the Gregorian calendar also still
has one day too much every 5000 years). Anyway, the Julian calendar was
better than what existed before, because rulers had often changed the
calendar used until then in arbitrary ways, in order to lengthen their
own reign, for instance.
In order to convert the number returned by this function back into
a date, use the function "C<Add_Delta_Days()>" (described further
below), as follows:
$days = Date_to_Days($year,$month,$day);
($year,$month,$day) = Add_Delta_Days(1,1,1, $days - 1);
=item *
C<$dow = Day_of_Week($year,$month,$day);>
This function returns the number of the day of week of the given date.
The function returns "C<1>" for Monday, "C<2>" for Tuesday and so on
until "C<7>" for Sunday.
Note that in the Hebrew calendar (on which the Christian calendar is based),
the week starts with Sunday and ends with the Sabbath or Saturday (where
according to the Genesis (as described in the Bible) the Lord rested from
creating the world).
In medieval times, Catholic Popes have decreed the Sunday to be the official
day of rest, in order to dissociate the Christian from the Hebrew belief.
It appears that this actually happened with the Emperor Constantin, who
converted to Christianity but still worshipped the Sun god and therefore
moved the Christian sabbath to the day of the Sun.
lib/Date/Calc.pod view on Meta::CPAN
7 => '7th' 17 => '17th' 27 => '27th'
8 => '8th' 18 => '18th' 28 => '28th'
9 => '9th' 19 => '19th' 29 => '29th'
etc.
=item *
C<$string = Calendar($year,$month[,$orthodox[,$lang]]);>
This function returns a calendar of the given month in the given year
(somewhat similar to the UNIX "C<cal>" command), in the given or currently
selected language (see further below for details about the multi-language
support of this package).
Example:
print Calendar(1998,5);
This will print:
May 1998
Mon Tue Wed Thu Fri Sat Sun
1 2 3
4 5 6 7 8 9 10
11 12 13 14 15 16 17
18 19 20 21 22 23 24
25 26 27 28 29 30 31
If the optional boolean parameter "C<$orthodox>" is given and true,
the calendar starts on Sunday instead of Monday.
=item *
C<$string = Month_to_Text($month[,$lang]);>
This function returns the name of the given month in the given or currently
selected language (see further below for details about the multi-language
support of this package).
If the given month lies outside of the valid range from "C<1>" to "C<12>",
lib/Date/Calc.pod view on Meta::CPAN
else { last; }
}
Solution #3 (holidays taken into account, more comfortable,
but requires Date::Calendar(3) and Date::Calc::Object(3)):
use Date::Calc::Object qw( Today Add_Delta_YM Date_to_Text_Long );
use Date::Calendar::Profiles qw($Profiles);
use Date::Calendar;
$calendar = Date::Calendar->new( $Profiles->{'DE-BW'} );
@today = Today();
@nextmonth = Add_Delta_YM(@today[0,1],1, 0,1);
$workaround = $calendar->add_delta_workdays(@nextmonth,+1);
$payday = $calendar->add_delta_workdays($workaround,-2);
print "Pay day = ", Date_to_Text_Long($payday->date()), "\n";
The "workaround" is necessary due to a bug in the method
"add_delta_workdays()" when adding a negative number of
workdays.
=item 11)
How do I convert a MS Visual Basic "DATETIME" value into its date
lib/Date/Calc.pod view on Meta::CPAN
=back
=head1 SEE ALSO
Date::Calc::Util(3), Date::Calc::Object(3),
Date::Calendar(3), Date::Calendar::Year(3),
Date::Calendar::Profiles(3).
"The Calendar FAQ":
http://www.tondering.dk/claus/calendar.html
by Claus Tondering <claus@tondering.dk>
=head1 BEWARE
When you are using the (deprecated) function "Language()", the language
setting is stored in a global variable.
This may cause conflicts between threads or modules running concurrently.
Therefore, in order to avoid such conflicts, NEVER use the function
lib/Date/Calc/Object.pod view on Meta::CPAN
Note that "C<abs($date)>" and "C<abs($delta)>" are just shorthands
for "C<$date-E<gt>number()>" and "C<$delta-E<gt>number()>".
The operator "C<abs()>", when applied to a date or delta vector,
returns the corresponding number of days (see below for an exception
to this), with the time part (if available) represented by a fraction
after the decimal point.
In the case of dates, the absolute value (to the left of the
decimal point) is the number of days since the 1st of January
S<1 A.D.> (by extrapolating the Gregorian calendar back beyond
its "natural" limit of 1582 A.D.) B<PLUS ONE>.
(I.e., the absolute value of the 1st of January 1 A.D. is 1.)
Exception:
If the "NUMBER" or "number_format()" is set to 0 (the default
setting), the absolute value of a date to the left of the decimal
point is "yyyymmdd", i.e., the number in which the uppermost four
digits correspond to the year, the next lower two digits to the
lib/Date/Calendar.pod view on Meta::CPAN
boundaries.
Note however that Date::Calendar and Date::Calendar::Year can only deal
with years lying within the range [1583..2299].
=head1 SYNOPSIS
use Date::Calendar::Profiles qw( $Profiles );
use Date::Calendar;
$calendar_US_AZ = Date::Calendar->new( $Profiles->{'US-AZ'} [,LANG[,WEEKEND]] );
$calendar_DE_SN = Date::Calendar->new( $Profiles->{'DE-SN'} [,LANG[,WEEKEND]] );
$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);
$hashref = $calendar->tags(YEAR,MONTH,DAY|DATE);
$days = $calendar->delta_workdays(YEAR1,MONTH1,DAY1|DATE1
,YEAR2,MONTH2,DAY2|DATE2
,FLAG1,FLAG2);
($date,$rest) = $calendar->add_delta_workdays(YEAR,MONTH,DAY|DATE
,DELTA);
$date = $calendar->add_delta_workdays(YEAR,MONTH,DAY|DATE
,DELTA);
$flag = $calendar->is_full(YEAR,MONTH,DAY|DATE);
$flag = $calendar->is_half(YEAR,MONTH,DAY|DATE);
$flag = $calendar->is_work(YEAR,MONTH,DAY|DATE);
=head1 INTERFACE
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
length) instead!
See L<Date::Calc::Object(3)> for more details.
lib/Date/Calendar.pod view on Meta::CPAN
Moreover, whenever a method of this class returns a date, it
does so by returning a Date::Calc[::Object] date object.
=head1 DESCRIPTION
=over 2
=item *
C<$calendar = Date::Calendar-E<gt>new(PROFILE[,LANG[,WEEKEND]]);>
The first argument must be the reference of a hash,
which contains a holiday scheme or "profile" 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 Date::Calc(3) module if given.
After the second 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.pod view on Meta::CPAN
If values outside of the range C<1..7> are given,
they will be ignored.
This can be used to switch off this feature and to
have no regularly recurring holidays at all when
for instance a zero is given.
See L<Date::Calendar::Profiles(3)> and L<Date::Calendar::Year(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
of your own).
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.
=item *
C<$year = $calendar-E<gt>year(YEAR|DATE);>
This method returns a Date::Calendar::Year object for the given
year and the profile that was associated with the given calendar
object.
If the cache in the given calendar object already contains an
object for the requested year, the corresponding object reference
is simply returned.
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 "given year out of range" error will occur if the given
year number lies outside the valid range of [1583..2299].
=item *
C<@years = $calendar-E<gt>cache_keys();>
This method returns the list of B<YEAR NUMBERS> of the
Date::Calendar::Year objects contained in the given
calendar object's cache.
=item *
C<@years = $calendar-E<gt>cache_vals();>
This method returns the list of B<OBJECT REFERENCES> of
the Date::Calendar::Year objects contained in the given
calendar object's cache.
=item *
C<$calendar-E<gt>cache_clr();>
This method clears the entire cache of the given calendar
object (by destroying the cache hash and creating a new one).
=item *
C<$calendar-E<gt>cache_add(YEAR|DATE,...);>
Roughly, this method is a shortcut for
for $year (@list)
{
$calendar->year($year);
}
=item *
C<$calendar-E<gt>cache_del(YEAR|DATE,...);>
This method removes the Date::Calendar::Year objects whose
year numbers are given from the cache of the given calendar
object.
Year numbers for which the calendar object's cache doesn't
contain an entry are simply ignored.
=item *
C<$index = $calendar-E<gt>date2index(YEAR,MONTH,DAY|DATE);>
This method converts a given date into the number of the day in
that year (this is sometimes also referred to as the "julian"
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
December 31st).
You may need this in order to access the bit vectors returned
by the Date::Calendar::Year methods "vec_full()", "vec_half()"
and "vec_work()".
If the Date::Calendar::Year object for the given YEAR is not in
the C<$calendar>'s cache yet, it will be created and added.
An exception ("invalid date") is thrown if the given arguments
do not constitute a valid date, or ("given year out of range
[1583..2299]") if the given year lies outside of the permitted
range.
=item *
C<@names = $calendar-E<gt>labels(YEAR,MONTH,DAY|DATE);>
C<@holidays = $calendar-E<gt>labels();>
C<$holidays = $calendar-E<gt>labels();>
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 B<NOT> 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 L<Date::Calendar::Profiles(3)>
and L<Date::Calendar::Year(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.
=item *
C<@dates = $calendar-E<gt>search(PATTERN);>
C<$dates = $calendar-E<gt>search(PATTERN);>
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
match the given pattern.
(Use the methods "cache_clr()", "cache_add()" and "cache_del()"
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,
B<NOT> 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).
=item *
C<$hashref = $calendar-E<gt>tags(YEAR,MONTH,DAY|DATE);>
This method returns a hash reference for the given calendar and
date. The hash it refers to is a copy of the calendar profile's
internal hash which contains the names for the given date as keys
and 0, 1, 2, or 3 as their corresponding values meaning the following:
0 => commemorative day
1 => "half" holiday
2 => "full" holiday
3 => both a "half" and a "full" holiday
The value "3" should only occur if a date has been redefined by the
underlying profile using the same key (i.e., the same name) but with
a different type of holiday.
=item *
C<$days = $calendar-E<gt>delta_workdays(YEAR1,MONTH1,DAY1, YEAR2,MONTH2,DAY2, FLAG1,FLAG2);>
C<$days = $calendar-E<gt>delta_workdays(DATE1,DATE2,FLAG1,FLAG2);>
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 "Delta_Days()"
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
lib/Date/Calendar.pod view on Meta::CPAN
The parameter FLAG1 is associated with the first given date,
the parameter FLAG2 with the second given date (regardless
of whether the dates are in chronological order or not).
An exception ("invalid date") is raised if either of the two
date arguments does not constitute a valid date.
=item *
C<($date,$rest) = $calendar-E<gt>add_delta_workdays(YEAR,MONTH,DAY, DELTA);>
C<($date,$rest) = $calendar-E<gt>add_delta_workdays(DATE,DELTA);>
C<$date = $calendar-E<gt>add_delta_workdays(YEAR,MONTH,DAY, DELTA);>
C<$date = $calendar-E<gt>add_delta_workdays(DATE,DELTA);>
This method is the equivalent of the "Add_Delta_Days()" function
from the Date::Calc module, except that it adds work days and
skips holidays.
In other words, you can add or subtract a number of work days
"DELTA" 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
lib/Date/Calendar.pod view on Meta::CPAN
This program calculates "January 3rd of the given year minus
3 work days":
> perl test.pl 2001
$date = 28-Dec-2000, $rest = 0.
> perl test.pl 2002
$date = 28-Dec-2001, $rest = -0.5.
Note that December 31st is a "half" holiday in 2001 for the
calendar profile used in this example.
You can easily verify the results above with the help of the
"calendar.cgi" CGI script or the "linearcal.pl" script from
the "examples" subdirectory in the Date::Calc distribution.
B<BEWARE> that this method may currently return unexpected
(i.e., contradicting the above documentation) or plain wrong
results when going back in time (this is a bug!).
However, it works correctly and as documented above when
going forward in time.
=item *
C<$flag = $calendar-E<gt>is_full(YEAR,MONTH,DAY|DATE);>
This method returns "true" ("1") if the bit corresponding to
the given date is set in the bit vector representing "full"
holidays, and "false" ("0") otherwise.
I.e., the method returns "true" if the given date is a (full)
holiday (according to the calendar profile associated with the
given calendar object).
The corresponding Date::Calendar::Year object is created first
and stored in the calendar object's cache if necessary (if it's
not already there).
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 "C<$year>", which you can retrieve
through either "C<$days = $vec_full-E<gt>Size();>" or
"C<$days = $year-E<gt>val_days();>".
See L<Date::Calendar::Year(3)> and L<Bit::Vector(3)> for more
details.
=item *
C<$flag = $calendar-E<gt>is_half(YEAR,MONTH,DAY|DATE);>
This method returns "true" ("1") if the bit corresponding to
the given date is set in the bit vector representing "half"
holidays, and "false" ("0") otherwise.
I.e., the method returns "true" if the given date is a half
holiday (according to the calendar profile associated with the
given calendar object).
Note that if a date is a "full" holiday, the "half" 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
not already there).
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 "C<$year>", which you can retrieve
through either "C<$days = $vec_half-E<gt>Size();>" or
"C<$days = $year-E<gt>val_days();>".
See L<Date::Calendar::Year(3)> and L<Bit::Vector(3)> for more
details.
=item *
C<$flag = $calendar-E<gt>is_work(YEAR,MONTH,DAY|DATE);>
This method returns "true" ("1") if the bit corresponding to
the given date is set in the bit vector used to perform all
sorts of calculations, and "false" ("0") otherwise.
The corresponding Date::Calendar::Year object is created first
and stored in the calendar object's cache if necessary (if it's
not already there).
B<BEWARE> that the "work" in this method's name does B<NOT>
come from "work days"!
It comes from the fact that the corresponding bit vector can
be used for any "work" that you need to do. In other words,
it's a "work space".
Therefore, this bit vector might contain about everything you
could imagine - including a bit pattern which marks all "work
days" 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 "C<$year>", which you can retrieve
through either "C<$days = $vec_work-E<gt>Size();>" or
"C<$days = $year-E<gt>val_days();>".
See L<Date::Calendar::Year(3)> and L<Bit::Vector(3)> for more
details.
=back
=head1 SEE ALSO
Date::Calendar::Year(3), Date::Calendar::Profiles(3),
Date::Calc::Object(3), Date::Calc(3), Date::Calc::Util(3),
Bit::Vector(3).
=head1 LIMITATIONS
The calendar profiles included in L<Date::Calendar::Profiles(3)>
usually do not take 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 method "add_delta_workdays()" is known to produce results
which are sometimes off by one working day when a negative
lib/Date/Calendar/Profiles.pm view on Meta::CPAN
{
"New Year's Day" => \&GB_New_Year,
"Good Friday" => "-2",
"Easter Sunday" => "+0",
"Easter Monday" => "+1",
"Early May Bank Holiday" => \&GB_Early_May,
"Late May Bank Holiday" => "5/Mon/May", # Last Monday
#
# Jonathan Stowe <gellyfish@gellyfish.com> told me that spring
# bank holiday is the first Monday after Whitsun, but my pocket
# calendar suggests otherwise. I decided to follow my pocket
# guide and an educated guess ;-), but please correct me if
# I'm wrong!
#
"Summer Bank Holiday" => "5/Mon/Aug", # Last Monday
"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
# Thanks to:
# Bianca Taylor <bianca@unisolve.com.au>
# Andie Posey <andie@posey.org>
# Don Simonetta <don.simonetta@tequinox.com>
# Paul Fenwick <pjf@cpan.org>
# Brian Graham <brian.graham@nec.com.au>
# Pat Waters <pat.waters@dir.qld.gov.au>
# Stephen Riehm <Stephen.Riehm@gmx.net>
# http://www.holidayfestival.com/Australia.html
# http://www.earthcalendar.net/countries/2001/australia.html
# Sven Geisler <sgeisler@aeccom.com>
# Canberra (ACT):
# http://www.workcover.act.gov.au/labourreg/publicholidays.html
# New South Wales (NSW):
# http://www.dir.nsw.gov.au/holidays/index.html
# Northern Territory (NT):
# http://www.nt.gov.au/ocpe/documents/public-holidays/
# Queensland (QLD):
# http://www.wageline.qld.gov.au/publicholidays/list_pubhols.html
# South Australia (SA):
lib/Date/Calendar/Profiles.pod view on Meta::CPAN
This module provides some sample profiles (i.e., holiday schemes)
for use with the Date::Calendar(3) and Date::Calendar::Year(3)
module.
You are not required to use these, you can always roll your own
(this is very easy). See the section "HOW TO ROLL YOUR OWN" below
for more instructions on how to do this, and take the profiles
from this module as examples.
I intend not to make any fixes to any of the calendar profiles
in this module anymore unless there are VERY compelling reasons
to do so. These profiles are merely meant as examples.
The suggested way of using these profiles is to copy them to
your own code and then to modify them as needed. Otherwise
many people could be negatively affected if I made any changes
to a profile someone has been using for years.
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
lib/Date/Calendar/Profiles.pod view on Meta::CPAN
may also return an empty list. This will cause the "init()"
method to simply drop this holiday for that year.
The module Date::Calendar::Profiles exports the sample
callback functions "Advent1()", "Advent2()", "Advent3()",
"Advent4()" and "Advent()", which might assist you in
rolling your own profiles.
=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
lib/Date/Calendar/Profiles.pod view on Meta::CPAN
no strict "vars";
use Date::Calc qw(:all);
use Date::Calendar;
$Birthdays =
{
... # (see above)
};
@today = Today();
$calendar = Date::Calendar->new( $Birthdays );
$calendar->year( $today[0] );
foreach $key (@ARGV)
{
if (@list = $calendar->search( $key ))
{
foreach $date (@list)
{
@labels = $calendar->labels( $date );
$dow = shift(@labels);
# More than one person might have birthday on the same date:
$name = $key;
foreach $person (@labels)
{
if (index(lc($person),lc($key)) >= 0)
{
$name = $person;
last;
}
lib/Date/Calendar/Profiles.pod view on Meta::CPAN
for a short description of that little script.
=head1 SEE ALSO
Date::Calendar(3), Date::Calendar::Year(3),
Date::Calc::Object(3), Date::Calc(3),
Date::Calc::Util(3).
=head1 LIMITATIONS
The calendar profiles included in this module usually do not take
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.
lib/Date/Calendar/Year.pod view on Meta::CPAN
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:
lib/Date/Calendar/Year.pod view on Meta::CPAN
=item *
C<$number = $year-E<gt>val_year();>
C<$number = $year-E<gt>year();>
These two methods are identical, the latter being a shortcut of
the former.
They return the number of the year for which a calendar has been
stored in the given year object.
The method name "val_year()" is used here in order to be consistent
with the other attribute accessor methods of this class, and the
method "year()" is necessary in order to be able to pass
Date::Calendar::Year objects as parameters instead of a year number
in the methods of the Date::Calendar and Date::Calendar::Year
modules.
=item *
lib/Date/Calendar/Year.pod view on Meta::CPAN
In scalar context, only the number of items in the resulting list
is returned, instead of the resulting list itself (as in list context).
=item *
C<$hashref = $year-E<gt>tags(YEAR,MONTH,DAY|DATE);>
C<$hashref = $year-E<gt>tags(INDEX);>
This method returns a hash reference for the given calendar and date
(or index). The hash it refers to is a copy of the calendar profile's
internal hash which contains the names for the given date as keys and
0, 1, 2, or 3 as their corresponding values meaning the following:
0 => commemorative day
1 => "half" holiday
2 => "full" holiday
3 => both a "half" and a "full" holiday
The value "3" should only occur if a date has been redefined by the
underlying profile using the same key (i.e., the same name) but with
lib/Date/Calendar/Year.pod view on Meta::CPAN
=item *
C<$flag = $year-E<gt>is_full(YEAR,MONTH,DAY|DATE);>
This method returns "true" ("1") if the bit corresponding to
the given date is set in the bit vector representing "full"
holidays, and "false" ("0") otherwise.
I.e., the method returns "true" if the given date is a (full)
holiday (according to the calendar profile associated with the
given year object).
=item *
C<$flag = $year-E<gt>is_half(YEAR,MONTH,DAY|DATE);>
This method returns "true" ("1") if the bit corresponding to
the given date is set in the bit vector representing "half"
holidays, and "false" ("0") otherwise.
I.e., the method returns "true" if the given date is a half
holiday (according to the calendar profile associated with the
given year object).
Note that if a date is a "full" holiday, the "half" bit is
never set, even if you try to do so in your calendar profile,
on purpose or by accident.
=item *
C<$flag = $year-E<gt>is_work(YEAR,MONTH,DAY|DATE);>
This method returns "true" ("1") if the bit corresponding to
the given date is set in the bit vector used to perform all
sorts of calculations, and "false" ("0") otherwise.
( run in 1.561 second using v1.01-cache-2.11-cpan-c333fce770f )