👤
Home Man
Search
Today's Posts
Register

Linux & Unix Commands - Search Man Pages
Man Page or Keyword Search:
Select Section of Man Page:
Select Man Page Repository:

CentOS 7.0 - man page for date::calendar (centos section 3)

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

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

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

DESCRIPTION
       o "$calendar = Date::Calendar->new(PROFILE[,LANG[,WEEKEND]]);"

	 The first argument must be the reference of a hash, which contains a holiday scheme or
	 "profile" to be used in all calculations involving the new calendar object.

	 The second argument is optional, and must consist of the valid name or number of a
	 language as provided by the Date::Calc(3) module if given.

	 After the second argument, a list of day numbers which will constitute the "weekend" can
	 optionally be specified, where 1=Monday, 2=Tuesday, 3=Wednesday, 4=Thursday, 5=Friday,
	 6=Saturday and 7=Sunday.

	 If no values are given, 6 and 7 (Saturday and Sunday) are automatically taken as
	 default.

	 If values outside of the range 1..7 are given, they will be ignored.

	 This can be used to switch off this feature and to have no regularly recurring holidays
	 at all when for instance a zero is given.

	 See Date::Calendar::Profiles(3) and Date::Calendar::Year(3) for more details about these
	 arguments and about how to roll your own calendar profiles.

	 The method creates a new calendar object for a given profile, i.e., a given location and
	 its scheme of holidays (or a scheme of your own).

	 This calendar object is a caching proxy object; it stores the reference of the given
	 profile and contains a hash (the cache) of Date::Calendar::Year objects.

       o "$year = $calendar->year(YEAR|DATE);"

	 This method returns a Date::Calendar::Year object for the given year and the profile
	 that was associated with the given calendar object.

	 If the cache in the given calendar object already contains an object for the requested
	 year, the corresponding object reference is simply returned.

	 If not, a new Date::Calendar::Year object is created using the profile that has been
	 associated with the given calendar object.  The new Date::Calendar::Year object is then
	 stored in the calendar object's cache and its object reference is returned.

	 A fatal "given year out of range" error will occur if the given year number lies outside
	 the valid range of [1583..2299].

       o "@years = $calendar->cache_keys();"

	 This method returns the list of YEAR NUMBERS of the Date::Calendar::Year objects
	 contained in the given calendar object's cache.

       o "@years = $calendar->cache_vals();"

	 This method returns the list of OBJECT REFERENCES of the Date::Calendar::Year objects
	 contained in the given calendar object's cache.

       o "$calendar->cache_clr();"

	 This method clears the entire cache of the given calendar object (by destroying the
	 cache hash and creating a new one).

       o "$calendar->cache_add(YEAR|DATE,...);"

	 Roughly, this method is a shortcut for

	   for $year (@list)
	   {
	       $calendar->year($year);
	   }

       o "$calendar->cache_del(YEAR|DATE,...);"

	 This method removes the Date::Calendar::Year objects whose year numbers are given from
	 the cache of the given calendar object.

	 Year numbers for which the calendar object's cache doesn't contain an entry are simply
	 ignored.

       o "$index = $calendar->date2index(YEAR,MONTH,DAY|DATE);"

	 This method converts a given date into the number of the day in that year (this is
	 sometimes also referred to as the "julian" date), i.e., a number between 0 (for January
	 1st) and the number of days in the given year minus one, i.e., 364 or 365 (for December
	 31st).

	 You may need this in order to access the bit vectors returned by the
	 Date::Calendar::Year methods "vec_full()", "vec_half()" and "vec_work()".

	 If the Date::Calendar::Year object for the given YEAR is not in the $calendar's cache
	 yet, it will be created and added.

	 An exception ("invalid date") is thrown if the given arguments do not constitute a valid
	 date, or ("given year out of range [1583..2299]") if the given year lies outside of the
	 permitted range.

       o "@names = $calendar->labels(YEAR,MONTH,DAY|DATE);"

	 "@holidays = $calendar->labels();"

	 "$holidays = $calendar->labels();"

	 If any arguments are given, they are supposed to represent a date. In that case, a list
	 of all labels (= names of holidays) associated with that date are returned. The first
	 item returned is always the name of the day of week for that date. The corresponding
	 year object for the given date's year is added to the calendar's cache first if
	 necessary.

	 If no arguments are given, the list of all available labels in all years that have
	 previously been accessed in the given calendar (i.e., the years which are already in the
	 given calendar's cache) is constructed. Note that this means that the returned list will
	 be empty if there are no year objects in the given calendar's cache yet (!). The
	 returned list does NOT include any names of the days of week (which would be pointless
	 in this case).

	 Multiple labels are reported only once.

	 Usually all years have the same set of labels, so it may seem superfluous to scan all
	 the years in the cache instead of just one. But there may be exceptions, because it is
	 possible to define calendar profiles which do not contain all possible holidays in every
	 year. See Date::Calendar::Profiles(3) and Date::Calendar::Year(3) for more details.

	 In list context, the resulting list itself is returned. In scalar context, the number of
	 items in the resulting list is returned.

       o "@dates = $calendar->search(PATTERN);"

	 "$dates = $calendar->search(PATTERN);"

	 This method searches through all the labels in all years that have previously been
	 accessed in the given calendar (i.e., the years which are already in the given
	 calendar's cache) and returns a list of date objects with all dates whose labels match
	 the given pattern.

	 (Use the methods "cache_clr()", "cache_add()" and "cache_del()" in order to put the year
	 numbers you want into the calendar object's cache, or to make sure it only contains the
	 year numbers you want to search.)

	 Note that this is a simple, case-insensitive substring search, NOT a full-fledged
	 regular expression search!

	 The result is guaranteed to be sorted chronologically.

	 In scalar context, only the number of items in the resulting list is returned, instead
	 of the resulting list itself (as in list context).

       o "$hashref = $calendar->tags(YEAR,MONTH,DAY|DATE);"

	 This method returns a hash reference for the given calendar and date. The hash it refers
	 to is a copy of the calendar profile's internal hash which contains the names for the
	 given date as keys and 0, 1, 2, or 3 as their corresponding values meaning the
	 following:

	     0	  =>	commemorative day
	     1	  =>	"half" holiday
	     2	  =>	"full" holiday
	     3	  =>	both a "half" and a "full" holiday

	 The value "3" should only occur if a date has been redefined by the underlying profile
	 using the same key (i.e., the same name) but with a different type of holiday.

       o "$days = $calendar->delta_workdays(YEAR1,MONTH1,DAY1, YEAR2,MONTH2,DAY2, FLAG1,FLAG2);"

	 "$days = $calendar->delta_workdays(DATE1,DATE2,FLAG1,FLAG2);"

	 This method calculates the number of work days (i.e., the number of days, but excluding
	 all holidays) between two dates.

	 In other words, this method is equivalent to the "Delta_Days()" function of the
	 Date::Calc module, except that it disregards holidays in its counting.

	 The two flags indicate whether the start and end dates should be included in the
	 counting (that is, of course, only in case they aren't holidays), or not.

	 It is common, for example, that you want to know how many work days are left between the
	 current date and a given deadline.

	 Typically, you will want to count the current date but not the deadline's date. So you
	 would specify "true" ("1") for FLAG1 and "false" ("0") for FLAG2 in order to achieve
	 that.

	 In other words, a value of "true" means "including this date", a value of "false" means
	 "excluding this date".

	 As with the "Delta_Days()" function from the Date::Calc module, the dates have to be
	 given in chronological order to yield a positive result. If the dates are reversed, the
	 result will be negative.

	 The parameter FLAG1 is associated with the first given date, the parameter FLAG2 with
	 the second given date (regardless of whether the dates are in chronological order or
	 not).

	 An exception ("invalid date") is raised if either of the two date arguments does not
	 constitute a valid date.

       o "($date,$rest) = $calendar->add_delta_workdays(YEAR,MONTH,DAY, DELTA);"

	 "($date,$rest) = $calendar->add_delta_workdays(DATE,DELTA);"

	 "$date = $calendar->add_delta_workdays(YEAR,MONTH,DAY, DELTA);"

	 "$date = $calendar->add_delta_workdays(DATE,DELTA);"

	 This method is the equivalent of the "Add_Delta_Days()" function from the Date::Calc
	 module, except that it adds work days and skips holidays.

	 In other words, you can add or subtract a number of work days "DELTA" to/from a given
	 date and get a new date as the result (as a Date::Calc object).

	 You add days (i.e., you go forward in time) with a positive offset "DELTA", and you
	 subtract days (i.e., you go backwards in time) with a negative offset.

	 Note that an exception ("invalid date") is raised if the given date argument does not
	 constitute a valid date.

	 In scalar context, the method just returns the resulting date object, whereas in list
	 context the method not only returns the new date, but also a "rest". This rest is useful
	 for cases in which your profile contains "half" holidays, or when you add or subtract
	 fractions of a day.

	 Sometimes it is not possible to accomodate the requested number of work days, and a rest
	 remains.

	 This rest can currently only assume the value "0.0" (zero), "-0.5" (minus one half) or
	 "0.5" (one half), provided you use only integral or multiples of 0.5 as offsets. A rest
	 of zero indicates that the calculation yielded an exact result. If the rest is 0.5 or
	 -0.5, this is to be interpreted as "the resulting date at 12:00 o'clock", instead of as
	 "the resulting date at 0:00 o'clock".

	 The rest is always positive (or zero) if the offset "DELTA" is positive (or zero), and
	 always negative (or zero) if the offset is negative (or zero).

	 Example:

	   #!perl
	   use Date::Calendar;
	   use Date::Calendar::Profiles qw( $Profiles );
	   $year = shift;
	   $cal = Date::Calendar->new( $Profiles->{'sdm-MUC'} );
	   ($date,$rest) = $cal->add_delta_workdays($year,1,3, -3);
	   $date->date_format(1);
	   print "\$date = $date, \$rest = $rest.\n";
	   __END__

	 This program calculates "January 3rd of the given year minus 3 work days":

	   > perl test.pl 2001
	   $date = 28-Dec-2000, $rest = 0.
	   > perl test.pl 2002
	   $date = 28-Dec-2001, $rest = -0.5.

	 Note that December 31st is a "half" holiday in 2001 for the calendar profile used in
	 this example.

	 You can easily verify the results above with the help of the "calendar.cgi" CGI script
	 or the "linearcal.pl" script from the "examples" subdirectory in the Date::Calc
	 distribution.

	 BEWARE that this method may currently return unexpected (i.e., contradicting the above
	 documentation) or plain wrong results when going back in time (this is a bug!).

	 However, it works correctly and as documented above when going forward in time.

       o "$flag = $calendar->is_full(YEAR,MONTH,DAY|DATE);"

	 This method returns "true" ("1") if the bit corresponding to the given date is set in
	 the bit vector representing "full" holidays, and "false" ("0") otherwise.

	 I.e., the method returns "true" if the given date is a (full) holiday (according to the
	 calendar profile associated with the given calendar object).

	 The corresponding Date::Calendar::Year object is created first and stored in the
	 calendar object's cache if necessary (if it's not already there).

	 Note that you can get a reference to this bit vector (in order to use this bit vector in
	 bit vector operations) as follows:

	   $vec_full = $calendar->year($year)->vec_full();

	 The number of bits in this bit vector is the same as the number of days in the given
	 year "$year", which you can retrieve through either ""$days = $vec_full->Size();"" or
	 ""$days = $year->val_days();"".

	 See Date::Calendar::Year(3) and Bit::Vector(3) for more details.

       o "$flag = $calendar->is_half(YEAR,MONTH,DAY|DATE);"

	 This method returns "true" ("1") if the bit corresponding to the given date is set in
	 the bit vector representing "half" holidays, and "false" ("0") otherwise.

	 I.e., the method returns "true" if the given date is a half holiday (according to the
	 calendar profile associated with the given calendar object).

	 Note that if a date is a "full" holiday, the "half" bit is never set, even if you try to
	 do so in your calendar profile, on purpose or by accident.

	 The corresponding Date::Calendar::Year object is created first and stored in the
	 calendar object's cache if necessary (if it's not already there).

	 Note that you can get a reference to this bit vector (in order to use this bit vector in
	 bit vector operations) as follows:

	   $vec_half = $calendar->year($year)->vec_half();

	 The number of bits in this bit vector is the same as the number of days in the given
	 year "$year", which you can retrieve through either ""$days = $vec_half->Size();"" or
	 ""$days = $year->val_days();"".

	 See Date::Calendar::Year(3) and Bit::Vector(3) for more details.

       o "$flag = $calendar->is_work(YEAR,MONTH,DAY|DATE);"

	 This method returns "true" ("1") if the bit corresponding to the given date is set in
	 the bit vector used to perform all sorts of calculations, and "false" ("0") otherwise.

	 The corresponding Date::Calendar::Year object is created first and stored in the
	 calendar object's cache if necessary (if it's not already there).

	 BEWARE that the "work" in this method's name does NOT come from "work days"!

	 It comes from the fact that the corresponding bit vector can be used for any "work" that
	 you need to do. In other words, it's a "work space".

	 Therefore, this bit vector might contain about everything you could imagine - including
	 a bit pattern which marks all "work days" with set bits, if it so happens!

	 But you better don't rely on it, unless you put the bit pattern there yourself in the
	 first place.

	 Note that you can get a reference to this bit vector (in order to fill it with any bit
	 pattern you like) as follows:

	   $vec_work = $calendar->year($year)->vec_work();

	 The number of bits in this bit vector is the same as the number of days in the given
	 year "$year", which you can retrieve through either ""$days = $vec_work->Size();"" or
	 ""$days = $year->val_days();"".

	 See Date::Calendar::Year(3) and Bit::Vector(3) for more details.

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

LIMITATIONS
       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).

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

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 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!

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.

perl v5.16.3				    2009-10-31				Date::Calendar(3)


All times are GMT -4. The time now is 06:47 PM.

Unix & Linux Forums Content Copyrightę1993-2018. All Rights Reserved.
×
UNIX.COM Login
Username:
Password:  
Show Password