DOC HOME SITE MAP MAN PAGES GNU INFO SEARCH
 

Date::Calendar::Year

NAME

Date::Calendar::Year - Implements embedded ``year'' objects for Date::Calendar

MOTTO

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

PREFACE

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

SYNOPSIS

  use Date::Calendar::Year qw( check_year empty_period );
  use Date::Calendar::Year qw( :all ); # same as above
  check_year(YEAR|DATE); # dies if year < 1583 or year > 2299
  empty_period();        # warns about empty interval if $^W is set
  $index = $year->date2index(YEAR,MONTH,DAY|DATE);
  $date  = $year->index2date(INDEX);
  use Date::Calendar::Profiles qw( $Profiles );
  $year_2000_US_FL = Date::Calendar::Year->new( 2000, $Profiles->{'US-FL'} [,LANG] );
  $year_2001_DE_NW = Date::Calendar::Year->new( 2001, $Profiles->{'DE-NW'} [,LANG] );
  $year = Date::Calendar::Year->new( 2001, {} );
  $year->init( 2002, $Profiles->{'DE-SN'} [,LANG] );
  $vector = $year->vec_full(); # vector of full holidays
  $vector = $year->vec_half(); # vector of half holidays
  $vector = $year->vec_work(); # NOT a vector of workdays but a workspace!
  $size   = $year->val_days(); # number of days in that year, size of vectors
  $base   = $year->val_base(); # number of days for [year,1,1] since [1,1,1]
  $number = $year->val_year(); # the year's number itself
  $number = $year->year();     # alias for val_year()
  @names    = $year->labels(YEAR,MONTH,DAY|DATE);
  @holidays = $year->labels();
  $holidays = $year->labels();
  @dates    = $year->search(PATTERN);
  $dates    = $year->search(PATTERN);
  $hashref  = $year->tags(YEAR,MONTH,DAY|DATE);
  $hashref  = $year->tags(INDEX);
  $days     = $year->delta_workdays(YEAR,MONTH1,DAY1|DATE1
                                   ,YEAR,MONTH2,DAY2|DATE2
                                   ,FLAG1,FLAG2);
  ($date,$rest,$sign) = $year->add_delta_workdays(YEAR,MONTH,DAY|DATE
                                                 ,DELTA,SIGN);
  $flag     = $year->is_full(YEAR,MONTH,DAY|DATE);
  $flag     = $year->is_half(YEAR,MONTH,DAY|DATE);
  $flag     = $year->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, 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.

IMPLEMENTATION

Each Date::Calendar::Year object consists mainly of three bit vectors, plus some administrative attributes, all stored in a (blessed) hash.

All three bit vectors contain as many bits as there are days in the corresponding year, i.e., either 365 or 366.

The first bit vector, called ``FULL'', contains set bits for Saturdays, Sundays and all ``full'' legal holidays (i.e., days off, on which you usually do not work).

The second bit vector, called ``HALF'', contains set bits for all ``half'' holidays, i.e., holidays where you get only half a day off from work.

The third and last bit vector, called ``WORK'', is used as a workspace, in which various calculations are performed throughout this module.

Its name does NOT come from ``working days'' (as you might think), but from ``workspace''.

It only so happens that it is used to calculate the working days sometimes, at some places in this module.

But you are free to use it yourself, for whatever calculation you would like to carry out yourself.

The two other bit vectors, ``FULL'' and ``HALF'', should never be changed, unless you know EXACTLY what you're doing!

DESCRIPTION

Functions

Methods

SEE ALSO

Bit::Vector(3), Date::Calendar(3), Date::Calendar::Profiles(3), Date::Calc::Object(3), Date::Calc(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::Year'' 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.