Date::Calendar::Year(3) User Contributed Perl Documentation Date::Calendar::Year(3)

Date::Calendar::Year - Implements embedded "year" objects for Date::Calendar

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

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

  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[,WEEKEND]] );
  $year_2001_DE_NW = Date::Calendar::Year->new( 2001, $Profiles->{'DE-NW'} [,LANG[,WEEKEND]] );
  $year = Date::Calendar::Year->new( 2001, {} );
  $year->init( 2002, $Profiles->{'DE-SN'} [,LANG[,WEEKEND]] );
  $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);

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

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!

Functions

Methods

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

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.

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

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

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.

2015-03-07 perl v5.34.0