Steffen Beyer > Date-Pcalc-6.1 > Date::Pcalendar

Download:
Date-Pcalc-6.1.tar.gz

Dependencies

Annotate this POD

CPAN RT

New  1
Open  1
View/Report Bugs
Module Version: 6.1   Source  

NAME ^

Date::Pcalendar - 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::Pcalendar is just a caching proxy class for Date::Pcalendar::Year objects, which are embedded in each Date::Pcalendar object.

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

So you should usually use Date::Pcalendar and not Date::Pcalendar::Year, since that way you don't have to worry about calculations crossing year boundaries.

Note however that Date::Pcalendar and Date::Pcalendar::Year can only deal with years lying within the range [1583..2299].

SYNOPSIS ^

  use Date::Pcalendar::Profiles qw( $Profiles );
  use Date::Pcalendar;

  $calendar_US_AZ  = Date::Pcalendar->new( $Profiles->{'US-AZ'} [,LANG[,WEEKEND]] );
  $calendar_DE_SN  = Date::Pcalendar->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);

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::Pcalc[::Object] date object or an array reference (of an array of appropriate length) instead!

See Date::Pcalc::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::Pcalendar::Year objects, which are a totally different thing!

But incidentally :-), you may also pass a Date::Pcalendar::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::Pcalc[::Object] date object.

DESCRIPTION ^

SEE ALSO ^

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

LIMITATIONS ^

The calendar profiles included in Date::Pcalendar::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).

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::Pcalendar" version 6.1.

AUTHOR ^

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

COPYRIGHT ^

Copyright (c) 2000 - 2009 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.

syntax highlighting: