Steffen Beyer > Date-Calc > Date::Calendar



Annotate this POD


New  5
Open  10
Stalled  2
View/Report Bugs
Module Version: 6.4   Source  


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 Date::Calendar object.

However, and in contrast to Date::Calendar::Year methods, Date::Calendar methods permit calculations spanning an arbitrary number of years, without loss of efficiency.

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 boundaries.

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 );
  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


  $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

  ($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 length) instead!

See Date::Calc::Object(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 would be pointless).

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 :-), 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 "cache_add()", 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.



Date::Calendar::Year(3), Date::Calendar::Profiles(3), Date::Calc::Object(3), Date::Calc(3), Date::Calc::Util(3), Bit::Vector(3).


The calendar profiles included in 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 regularly recurring events (the profiles should therefore not be relied upon for historical faithfulness).


The method "add_delta_workdays()" is known to produce results which are sometimes off by one working day when a negative offset is used. As a workaround, try to add one working day first and then subtract one working day more than initially intended. See also the file "examples/" for how to do this.


This man page documents "Date::Calendar" version 6.4.


  Steffen Beyer


Copyright (c) 2000 - 2015 by Steffen Beyer. All rights reserved.


This package is free software; you can use, modify and redistribute it under the same terms as Perl itself, i.e., at your option, under the terms either of the "Artistic License" or the "GNU General Public License".

The C library at the core of the module "Date::Calc::XS" can, at your discretion, also be used, modified and redistributed under the terms of the "GNU Library General Public License".

Please refer to the files "Artistic.txt", "GNU_GPL.txt" and "GNU_LGPL.txt" in the "license" subdirectory of this distribution for any details!


This package is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

See the "GNU General Public License" for more details.

syntax highlighting: