view release on metacpan or  search on metacpan

lib/Date/Gregorian/Business.pm  view on Meta::CPAN

is negative and vice versa.  The parameter may be an arbitrary
Date::Gregorian object.  If it is not a Date::Gregorian::Business
object its alignment is taken to be the default (morning).

=item set_next_businessday

I<set_next_businessday> moves an arbitrary date up or down to the
next business day.  Its parameter must be one of the four relation
operators ">=", ">", "<=" or "<" as a string.  ">=" means, the date
should not be changed if it is a business day, or changed to the
closest business day in the future otherwise.  ">" means the date
should be changed to the closest business day truly later than the
current date.  "<=" and "<" likewise work in the other direction.
Alignment does not matter and is not changed.

=item add_businessdays

I<add_businessdays> moves an arbitrary date forward or backwards
in time up to a given number of business days.  A positive number
of days means moving towards the future.  The result is always a
business day.  The alignment will not be changed if the second
parameter is omitted, or else set to the second parameter.  The
result will be rounded to the beginning or end of a business day
if necessary, as determined by its alignment.

Rounding: If you work with simple calendars and integer numbers,
all results will be precise.  However, with calendars containing
fractions of business days or with non-integer values of day
differences, a calculated date may end up somewhere in the middle
of a business day rather than at its beginning or end.  The final
result will stay at that date but move up or down to the desired
alignment.  In other words, fractional days will be rounded down
to morning alignment or up to evening alignment, whichever applies.

No ambiguities: Even if a calculated date lies next to a number of
non-business days in a way that more than one date would satisfy a
desired span of business days, results are always well-defined by
the fact that they must be business days.  Thus, morning alignment
will pull a result to the first business day after weekends and
holidays, while evening alignment will pull a result to the last
business day before any non-business days.  If you add zero business
days to some arbitrary date you get the unique date of the properly
aligned business day next to it.

=item iterate_businessdays_upto iterate_businessdays_downto

I<iterate_businessdays_upto> and I<iterate_businessdays_downto>
provide iterators over a range of business days.  They return a
reference to a subroutine that can be called without argument in a
while condition to set the given date iteratively to each one of a
sequence of dates, while skipping non-business days.  The business
day closest to the current date is always the first one to be
visited (unless the sequence is all empty).  The limit parameter
determines the end of the sequence, together with the relation
parameter:  '<' excludes the upper limit from the sequence, '<='
includes the upper limit, '>=' includes the lower limit and '>'
excludes the lower limit.

Each iterator maintains its own state; therefore it is legal to run
more than one iterator in parallel or even create new iterators
within iterations.  Undefining an iterator after use might help to
save memory.

=item get_alignment

I<get_alignment> retrieves the alignment (either 0 for morning or
1 for evening).

=back

=head2 Configuration

Version compatibility note: The configuration specifications described
here are expected to evolve with further development of this module.
In fact, they should ultimately be replaced by easier-to-use
configuration objects.  We will try to stay downward compatible for
some time, however.

The business calendar to use can be customized both on an
object-by-object basis and by way of general defaults.  Business
calendars can be stored under a name and later referenced by that
name.

A business calendar can be defined through a list of holiday
definitions or more generally through a code reference, as explained
below.  A number of such definitions of common interest will be
accessible in later editions of this module or some related component.

=over 4

=item define_configuration

I<define_configuration> names and defines a configuration.  It can
later be referenced by its name.  By convention, user-defined names
should start with an uppercase letter, while configuration names
provided as a part of the distribution will always start with a
lowercase letter.

=item configure_business

I<configure_business>, used as an object method, re-configures that
object.  It returns the object on success, B<undef> in case of a
bad configuration.

I<configure_business>, used as a class method, defines the default
configuration for new objects created with neither a configuration
parameter nor a reference object.  It returns the class name on
success, B<undef> in case of a bad configuration.

The configuration parameter for I<define_configuration>, I<new> and
I<configure_business> can be the name of a known configuration, an
array reference or a code reference.  A configuration name must be
known at the time it is used, for it is always immediately replaced
by the named configuration.

An array reference used as a configuration has to refer to a
two-element array like this:

  $configuration = [\@weekend_days, \@holidays];

Here, C<@weekend_days> is a list of the non-business days of every