view release on metacpan or  search on metacpan

lib/Date/Calendar/Year.pod  view on Meta::CPAN

Methods

=over 2

=item *

C<$index = $year-E<gt>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 methods "vec_full()", "vec_half()" and "vec_work()".

Note that there are shorthand methods in this module called
"is_full()", "is_half()" and "is_work()", which serve to test
individual bits of the three bit vectors which are a part of
each Date::Calendar::Year object.

An exception ("given year != object's year") is thrown if the
year associated with the year object itself and the year from
the given date do not match.

An exception ("invalid date") is also 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.

=item *

C<$date = $year-E<gt>index2date(INDEX);>

This method converts an index (or "julian date") for the
given year back into a date.

An exception ("invalid index") is thrown if the given index
is outside of the permitted range for the given year, i.e.,
C<[0..364]> or C<[0..365]>.

Note that this method returns a Date::Calc B<OBJECT>!

=item *

C<$year_2000_US_FL = Date::Calendar::Year-E<gt>new( 2000, $Profiles-E<gt>{'US-FL'} [,LANG[,WEEKEND]] );>

C<$year_2001_DE_NW = Date::Calendar::Year-E<gt>new( 2001, $Profiles-E<gt>{'DE-NW'} [,LANG[,WEEKEND]] );>

C<$year = Date::Calendar::Year-E<gt>new( 2001, {} );>

This is the constructor method. Call it to create a new
Date::Calendar::Year object.

The first argument must be a year number in the range
[1583..2299].

The second argument must be the reference of a hash,
which usually contains names of holidays and commemorative
days as keys and strings containing the date or formula
for each holiday as values.

Reading this hash and initializing the object's internal
data is performed by an extra method, called "init()",
which is called internally by the constructor method,
and which is described immediately below, after this
method.

In case you want to call the "init()" method yourself,
explicitly, after creating the object, you can pass an
empty profile (e.g., just an empty anonymous hash) to
the "new()" method, in order to create an empty object,
and also to improve performance.

The third 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.

This argument determines which language shall be used
when reading the profile, since the profile may contain
names of months and weekdays in its formulas in that
language.

The default is English if no value or no valid value
is specified (and if the global default has not been
changed with "Language()").

After the third 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 C<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.

=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

Note that the name of the month or day of week may have any
length you like, it just must specify the intended month or
day of week unambiguously. So "D", "De", "Dec", "Dece",
"Decem", "Decemb", "Decembe" and "December" would all
be valid, for example. Note also that case is ignored.

When specifying day and month numbers, or offsets relative
to Easter Sunday, leading zeros are permitted (for nicely
indented formatting, for instance) but ignored.

Leading zeros are not permitted in front of the ordinal
number [1..5] or the number of the day of week [1..7]
when specifying the nth day of week in a month.

B<BEWARE> that if keys are not unique in the source code,
later entries will overwrite previous ones! I.e.,

    ...
    "My special holiday" => "01-11",
    "My special holiday" => "02-11",
    ...

will B<NOT> set two holidays of the same name, one on November
first, the other on November second, but only one, on November
second!

Therefore, in order to use sets of defaults and to be able
to override some of them, you must B<FIRST> include any hash
containing the default definitions, and B<THEN> write down
your own definitions (see also the Date::Calendar::Profiles
module for examples of this!), like this:

    $defaults =
    {
        "Holiday #1" => "01-01",
        "Holiday #2" => "02-02",
        "Holiday #3" => "03-03"
    };

    $variant1 =
    {
        %$defaults,
        "Holiday #2" => "09-02",
        "Holiday #4" => "04-04"
    };

This is because of the way hashes work in Perl.

The "init()" method proceeds as follows:

First it checks whether the given year number lies in
the range [1583..2299]. A fatal error occurs if not.

Then it determines the number of days in the requested
year, and stores it in the given Date::Calendar::Year
object.

It then calls the Bit::Vector(3) module to allocate three
bit vectors with a number of bits equal to the number of
days in the requested year, and stores the three object
references (of the bit vectors) in the Date::Calendar::Year
object.

(See also the description of the three methods "vec_full()",
"vec_half()" and "vec_full()" immediately below.)

It then sets the bits which correspond to Saturdays and
Sundays (or optionally to the days whose numbers have been
specified as the "weekend") in the "full holidays" bit vector.

At last, it iterates over the keys of the given holiday
scheme (of the hash referred to by the hash reference
passed to the "init()" method as the second argument),
evaluates the formula (or calls the given callback
function), and sets the corresponding bit in the "full"
or "half" holidays bit vector if the calculated date
is valid.

A fatal error occurs if the date formula cannot be parsed
or if the date returned by a formula or callback function
is invalid (e.g. 30-Feb-2001 or the like) or lies outside
the given year (e.g. Easter+365).

Finally, the "init()" method makes sure that days marked
as "full" holidays do not appear as "half" holidays as
well.

Then the "init()" method returns.

Note that when deciphering the date formulas, the "init()"
method uses the functions "Decode_Day_of_Week()" and
"Decode_Month()" from the Date::Calc(3) module, which
are language-dependent.

Therefore the "init()" method allows you to pass it an optional
third argument, which must consist of the valid name or number
of a language as provided by the Date::Calc(3) module.

For the time of scanning the given holiday scheme, the "init()"
method will use the language that has been specified, or the
global setting from "Language()" if no or an invalid language
parameter is given.

The default is English if none is specified and if the
global setting has not been modified.

This means that you can provide the names of months and days of
week in your holiday profile in any of the languages supported
by the Date::Calc(3) module, provided you give the "init()"
method a clue (the third parameter) which language to expect.

=item *

C<$vector = $year-E<gt>vec_full();>

This method returns a reference to the bit vector in the
given year object which contains all "full" holidays.

B<BEWARE> that you should B<NEVER> change the contents of this
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_half();>

This method returns a reference to the bit vector in the
given year object which contains all "half" holidays.

B<BEWARE> that you should B<NEVER> change the contents of this
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.