Date-Calc
view release on metacpan or search on metacpan
lib/Date/Calendar/Year.pod view on Meta::CPAN
=item *
C<$year-E<gt>init( 2002, $Profiles-E<gt>{'DE-SN'} [,LANG[,WEEKEND]] );>
This method is called by the "new()" constructor method,
internally, and has the same arguments as the latter.
See immediately above for a description of these arguments.
Note that you can also call this method explicitly yourself,
if needed, and you can of course subclass the Date::Calendar::Year
class and override the "init()" method with a method of your own.
The holiday scheme or "profile" (i.e., the reference of
a hash passed as the second argument to this method) must
obey the following semantics and syntax:
The keys are the names of the holiday or commemorative day
in question. Keys must be unique (but see further below).
The difference between a holiday and a commemorative day is
that you (usually) get a day off on a holiday, whereas on a
purely commemorative day, you don't.
A commemorative day is just a date with a name, nothing more.
The values belonging to these keys can either be the code
reference of a callback function (see L<Date::Calendar::Profiles(3)>
for more details and examples), or a string.
All other values cause a fatal error with program abortion.
The strings can specify three types of dates:
- fixed dates
(like New Year, or first of January),
- dates relative to Easter Sunday
(like Ascension = Easter Sunday + 39 days), and
- the 1st, 2nd, 3rd, 4th or last
of a given day of week in a given month
(like "the 4th Thursday of November", or Thanksgiving).
All other types of dates must be specified via callback
functions.
Note that the "last" of a given day of week is written as
the "5th", because the last is always either the 5th or the
4th of the given day of week. So the "init()" module first
calculates the 5th of the requested day of week, and if that
doesn't exist, takes the 4th instead.
There are also two modifier characters which may prefix the
string with the date formula, "#" and ":".
The character "#" (mnemonic: it's only a comment) signals
that the date in question is a purely commemorative day,
i.e., it will not enter into any date calculations, but
can be queried with the "labels()" and "search()" methods,
and appears when printing a calendar, for instance.
The character ":" (mnemonic: divided into two halves) specifies
that the date in question is only a "half" holiday, i.e., you
only get half a day off instead of a full day. Some companies
have this sort of thing. C<:-)>
The exact syntax for the date formula strings is the following
(by example):
- Fixed dates:
"Christmas" => "24.12", # European format (day, month)
"Christmas" => "24.12.",
"Christmas" => "24Dec",
"Christmas" => "24.Dec",
"Christmas" => "24Dec.",
"Christmas" => "24.Dec.",
"Christmas" => "24-12",
"Christmas" => "24-12-",
"Christmas" => "24-Dec",
"Christmas" => "24-Dec-",
"Christmas" => "12/25", # American format (month, day)
"Christmas" => "Dec25",
"Christmas" => "Dec/25",
- Dates relative to Easter Sunday:
"Ladies' Carnival" => "-52",
"Carnival Monday" => "-48",
"Mardi Gras" => "-47",
"Ash Wednesday" => "-46",
"Palm Sunday" => "-7",
"Maundy Thursday" => "-3",
"Good Friday" => "-2",
"Easter Sunday" => "+0",
"Easter Monday" => "+1",
"Ascension" => "+39",
"Whitsunday" => "+49",
"Whitmonday" => "+50",
"Corpus Christi" => "+60",
- The 1st, 2nd, 3rd, 4th or last day of week:
"Thanksgiving" => "4Thu11",
"Thanksgiving" => "4/Thu/Nov",
"Columbus Day" => "2/Mon/Oct",
"Columbus Day" => "2/Mon/10",
"Columbus Day" => "2/1/Oct",
"Columbus Day" => "2/1/10",
"Memorial Day" => "5/Mon/May", # LAST Monday of May
Remember that each of these date formula strings may
also be prefixed with either "#" or ":":
"Christmas" => ":24.12.", # only half a day off
"Valentine's Day" => "#Feb/14", # not an official holiday
lib/Date/Calendar/Year.pod view on Meta::CPAN
bit vector unless you know B<EXACTLY> what you're doing!
You should usually only read from this bit vector, or use it
as an operand in bit vector operations - but never as an
lvalue.
=item *
C<$vector = $year-E<gt>vec_work();>
This method returns a reference to the "workspace" bit vector
in the given year object.
Note that you cannot rely on the contents of this bit vector.
You have to set it up yourself before performing any calculations
with it.
Currently the contents of this bit vector are modified by the
two methods "delta_workdays()" and "add_delta_workdays()", in
ways which are hard to predict (depending on the calculations
being performed).
The size of this bit vector can be determined through either
"C<$days = $vector-E<gt>Size();>" or
"C<$days = $year-E<gt>val_days();>".
=item *
C<$size = $year-E<gt>val_days();>
This method returns the number of days in the given year object,
i.e., either 365 or 366. This is also the size (number of bits)
of the three bit vectors contained in the given year object.
=item *
C<$base = $year-E<gt>val_base();>
This method returns the value of the expression
"C<Date_to_Days($year-E<gt>val_year(),1,1)>", or in other words,
the number of days between January 1st of the year 1 and January
1st of the given year, plus one.
This value is used internally by the method "date2index()" in order
to calculate the "julian" date or day of the year for a given date.
The expression above is computed only once in method "init()" and
then stored in one of the year object's attributes, of which this
method just returns the value.
=item *
C<$number = $year-E<gt>val_year();>
C<$number = $year-E<gt>year();>
These two methods are identical, the latter being a shortcut of
the former.
They return the number of the year for which a calendar has been
stored in the given year object.
The method name "val_year()" is used here in order to be consistent
with the other attribute accessor methods of this class, and the
method "year()" is necessary in order to be able to pass
Date::Calendar::Year objects as parameters instead of a year number
in the methods of the Date::Calendar and Date::Calendar::Year
modules.
=item *
C<@names = $year-E<gt>labels(YEAR,MONTH,DAY|DATE);>
C<@holidays = $year-E<gt>labels();>
C<$holidays = $year-E<gt>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.
If no arguments are given, the list of all available labels in
the given year is returned. This list does B<NOT> include any
names of the days of week (which would be pointless in this case).
In list context, the resulting list itself is returned. In scalar
context, the number of items in the resulting list is returned.
=item *
C<@dates = $year-E<gt>search(PATTERN);>
C<$dates = $year-E<gt>search(PATTERN);>
This method searches through all the labels of the given year
and returns a list of date objects with all dates whose labels
match the given pattern.
Note that this is a simple, case-insensitive substring search,
B<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).
=item *
C<$hashref = $year-E<gt>tags(YEAR,MONTH,DAY|DATE);>
C<$hashref = $year-E<gt>tags(INDEX);>
This method returns a hash reference for the given calendar and date
(or index). 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.
The index must be a number such as returned by the method "date2index()";
it can be used here instead of a date or a date object in order to speed
up processing (= no need to calculate it internally).
=item *
C<$days = $year-E<gt>delta_workdays(YEAR,MONTH1,DAY1, YEAR,MONTH2,DAY2, FLAG1,FLAG2);>
C<$days = $year-E<gt>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 ("given year != object's year") is thrown if the
year number of either of the two given dates does not match the
year number associated with the given year object.
An exception ("invalid date") is also raised if either of the
two date arguments does not constitute a valid date.
=item *
lib/Date/Calendar/Year.pod view on Meta::CPAN
(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 (the "start" date) does not constitute
a valid date.
Beware that this method is limited to date calculations within
a single year (in contrast to the method with the same name
from the Date::Calendar module).
Therefore, the method does not only return a date (object),
but also a "rest" and a "sign".
The "rest" indicates how many days are still left from your
original DELTA after going in the desired direction and
reaching a year boundary.
The "sign" indicates in which direction (future or past) one
needs to go in order to "eat up" the "rest" (by subtracting
a day from the "rest" for each work day passed), or to adjust
the resulting date (in order to skip any holidays directly
after a year boundary), if at all.
The "sign" is -1 for going backwards in time, +1 for going
forward, and 0 if the result doesn't need any more fixing
(for instance because the result lies in the same year as
the starting date).
The method "add_delta_workdays()" from the Date::Calendar
module uses the "rest" and "sign" return values from this
method in order to perform calculations which may cross
year boundaries.
Therefore, it is not recommended to use this method here
directly, as it is rather clumsy to use, but to use the
method with the same name from the Date::Calendar module
instead, which does the same but is much easier to use
and moreover allows calculations which cross an arbitrary
number of year boundaries.
B<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.
=item *
C<$flag = $year-E<gt>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 year object).
=item *
C<$flag = $year-E<gt>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 year 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.
=item *
C<$flag = $year-E<gt>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.
B<BEWARE> that the "work" in this method's name does B<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) using the method
"vec_work()", described further above in this document.
The number of bits in this bit vector is the same as the number
of days in the given year "C<$year>", which you can retrieve
through either "C<$days = $year-E<gt>vec_work-E<gt>Size();>"
or "C<$days = $year-E<gt>val_days();>".
See also L<Bit::Vector(3)> for more details.
=back
=head1 SEE ALSO
Bit::Vector(3), Date::Calendar(3), Date::Calendar::Profiles(3),
Date::Calc::Object(3), Date::Calc(3), Date::Calc::Util(3).
=head1 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.
=head1 VERSION
This man page documents "Date::Calendar::Year" version 6.4.
=head1 AUTHOR
Steffen Beyer
mailto:STBEY@cpan.org
http://www.engelschall.com/u/sb/download/
( run in 0.517 second using v1.01-cache-2.11-cpan-ceb78f64989 )