Date::Calendar - Calendar objects for different holiday schemes


NAME

Date::Calendar - Calendar objects for different holiday schemes


MOTTO

There is more than one way to do it - this is just one of them!


PREFACE

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


SYNOPSIS

  use Date::Calendar::Profiles qw( $Profiles );
  use Date::Calendar;
  $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);
  $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);


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 the Date::Calc::Object(3) manpage 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.


DESCRIPTION


SEE ALSO

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


KNOWN BUGS

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/bug.pl'' for how to do this.


VERSION

This man page documents ``Date::Calendar'' version 5.4.


AUTHOR

  Steffen Beyer
  mailto:sb@engelschall.com
  http://www.engelschall.com/u/sb/download/


COPYRIGHT

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


LICENSE

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 ``Artistic License'' or the ``GNU General Public License''.

Please refer to the files ``Artistic.txt'' and ``GNU_GPL.txt'' in this distribution for details!


DISCLAIMER

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.

 Date::Calendar - Calendar objects for different holiday schemes