libdate-manip-perl 6.25-1 / usr / share / perl5 / Date / Manip / Calc.pod

# Copyright (c) 1995-2011 Sullivan Beck. All rights reserved.
# This program is free software; you can redistribute it and/or modify it
# under the same terms as Perl itself.

=pod

=head1 NAME

Date::Manip::Calc - describes date calculations

=head1 SYNOPSIS

Two objects (both of which are either Date::Manip::Date or
Date::Manip::Delta objects) may be used to creates a third object
based on those two.

   $delta  = $date->calc($date2 [,$subtract] [,$mode]);
   $date2  = $date->calc($delta [,$subtract]);
   $date2  = $delta->calc($date1 [,$subtract]);
   $delta3 = $delta1->calc($delta2 [,$subtract]);

=head1 DESCRIPTION

This document describes date calculations. Date calculations involve
two types of Date::Manip objects: dates and deltas. These are described
in the Date::Manip::Date and Date::Manip::Delta manuals respectively.

Two objects (two dates, two deltas, or one of each) are used.  In all
cases, if a second object is not passed in, undef is returned.

There are 3 types of date calculations:

=over 4

=item B<Date-Date calculations>

   $delta  = $date->calc($date2 [,$subtract] [,$mode]);

Two dates can be worked with and a delta will be produced which is
the amount of time between the two dates.

$date1 and $date2 are Date::Manip::Date objects with valid dates.
The Date::Manip::Delta object returned is the amount of time between
them. If $subtract is not passed in (or is 0), the delta produced
is:

   DELTA = DATE2 - DATE1

If $subtract is non-zero, the delta produced is:

   DELTA = DATE1 - DATE2

The $subtract argument has special importance when doing approximate
calculations, and this is described below.

If either date is invalid, a delta object will be returned which
has an error associated with it.

The $mode argument describes the type of calculation and is described
below.

=item B<Date-Delta calculations>

Date-delta calculations can be performed using either a Date::Manip::Date
or Date::Manip::Delta object as the primary object:

   $date2  = $date1->calc($delta [,$subtract]);
   $date2  = $delta->calc($date1 [,$subtract]);

A date and delta can be worked with to yield a date that is the
given amount of time before or after it.

$date1 and $delta are valid Date::Manip::Date and Date::Manip::Delta
objects respectively. A new Date::Manip::Date object is produced.

Both of the calls above perform the same function and produce exactly the
same results.

If $subtract is not passed in, or is 0, the resulting date is
formed as:

   DATE2 = DATE1 + DELTA

If $subtract is non-zero, the resulting date is:

   DATE2 = DATE1 - DELTA

The $subtract argument has special importance when doing approximate
calculations, and this is described below.

=item B<Delta-Delta calculations>

Delta-delta calculations can be performed to add two amounts of time
together, or subtract them.

   $delta3 = $delta1->calc($delta2 [,$subtract]);

If $subtract is not passed in, or is 0, the resulting delta formed
is:

   DELTA3 = DELTA1 + DELTA2

If $subtract is non-zero, then the resulting delta is:

   DELTA3 = DELTA1 - DELTA2

$delta1 and $delta2 are valid Date::Manip::Delta objects, and a new
Date::Manip::Delta object is produced.

=back

Date calculations handle the time zones properly. When calculating
the difference between two dates in different time zones, they will
first be converted to a common time zone. Also, when adding a delta
to a date, the resulting date will be in the same time zone as the
original date.

If either of the objects are invalid, the error condition is set in
the object for which the method is called, and undef is returned
instead of a new object.

For example, if the following is called:

   $date2  = $date1->calc($delta);

and $delta does not include a valid delta, then $date1 will have an
error condition set and $date2 will be undef.

=head1 MODE

Date::Manip calculations can be divide into two different types:
business and non-business. Within those types are two sub categories:
exact and approximate. These are described here.

=over 4

=item B<Business and non-business calculations>

A business mode calculation is one where the length of the day is
determined by the length of the work day, and only business days
(i.e. days in which business is conducted) count. Holidays and
weekends are omitted. This is described in more detail below.

A non-business mode calculation is the normal type of calculation
where no days are ignored, and all days are full length.

=item B<Exact and approximate calculations>

An exact calculation is one in which all deltas involved (either the
delta produced by adding two dates or deltas together, or a delta that
is added to a date to produce a second date) is an exact delta. An
exact delta is described in the Date::Manip::Delta manual, but the
short explanation is that an exact delta tells exactly how much time
passed between two dates. Since there is no definite relationship
between months and days, an exact delta will only include values for
the day/hour/minute/second fields (the week field is also allowed in
non-business mode calculations). The inexact fields (year, month, and
week in the case of business mode) will be 0.

An approximate delta is one which includes years and months (i.e.
fields for which an exact length are not known in general) but
which are used for human convenience.

=back

In date-delta and delta-delta calculations, the mode of the
calculation will be determined automatically. In the case of date-date
calculations, the mode is supplied as an argument.

=over 4

=item B<Mode in date-date calculations>

When doing a date-date calculation, the following call is used:

   $delta = $date1->calc($date2 [,$subtract] [,$mode]);

$mode defaults to "exact". The delta produced will be be either
a business or non-business delta, exact or approximate, as specified
by $mode.

Currently, the four possible values that $mode can have are:

   exact    : an exact, non-business mode calculation
   approx   : an approximate, non-business mode calculation
   business : an exact, business mode calculation
   bapprox  : an approximate, business mode calculation

NOTE: When doing a "business" or "bapprox" calculation, both dates
must be in the same time zone or an error is produced.

=item B<Mode in date-delta calculations>

When doing calculations of a date and a delta:

   $date2 = $date1->calc($delta [,$subtract]);
   $date2 = $delta->calc($date1 [,$subtract]);

the mode is not passed in. It is determined exclusively by the
delta. If $delta is a business delta, A business mode calculation is
done. If $delta is a non-business delta, a non-business mode
calculation will be done. If $delta has a non-zero value for either
the year or month field, an approximate calculation will be done.
Otherwise, an exact calculation will be done.

=item B<Mode in delta-delta calculations>

When doing calculations with two deltas:

   $delta3 = $delta1->calc($delta2 [,$subtract]);

the mode is not passed in. It is determined by the two deltas.

If both deltas are business mode, or both are non-business mode, a
new delta will be produced of the same type.

It one of the deltas is a business mode and the other is not, the
resulting delta will have an error condition since there is no
direct correlation between the two types of deltas. Even though
it would be easy to add the two together, it would be impossible
to come up with a result that is meaningful.

If both deltas are exact, the resulting delta is also exact. If
either or both of the deltas is approximate, the resulting delta
is also approximate. It is NOT treated as an error if one of the
deltas is exact and one is approximate.

=back

=head1 BUSINESS MODE CONSIDERATIONS

In order to correctly do business mode calculations, a config file
should exist which contains the section defining holidays (otherwise,
weekends will be ignored, but all other days will be counted as
business days). This is documented below, and in the
Date::Manip::Config section of the documentation.  Some config
variables (namely WorkWeekBeg, WorkWeekEnd, WorkDayBeg, WorkDayEnd,
and WorkDay24Hr) defined the length of the work week and work day.

If the workday is defined as 08:00 to 18:00, a work week consisting of
Mon-Sat, and the standard (American) holidays, then from Tuesday at
12:00 to the following Monday at 14:00 is 5 days and 2 hours.  If the
"end" of the day is reached in a calculation, it automatically
switches to the next day.  So, Tuesday at 12:00 plus 6 hours is
Wednesday at 08:00 (provided Wed is not a holiday).  Also, a date that
is not during a workday automatically becomes the start of the next
workday.  So, Sunday 12:00 and Monday at 03:00 both automatically
becomes Monday at 08:00 (provided Monday is not a holiday).

Note that a business week is treated the same as an exact week
(i.e. from Tuesday to Tuesday, regardless of holidays).  Because this
means that the relationship between days and weeks is NOT unambiguous,
when an exact delta is produced from two dates, it will be in terms of
d/h/mn/s (i.e. no week field).

Also note that daylight saving time effects are ignored in business
mode calculations.

Anyone using business mode is going to notice a few quirks about it
which should be explained.  When I designed business mode, I had in
mind what a business which promises 1 business day turnaround really
means.

If you do a business calculation (with the workday set to 9:00-17:00),
you will get the following:

   Saturday at noon + 1 business day = Tuesday at 9:00
   Saturday at noon - 1 business day = Friday at 9:00

What does this mean?

As an example, say I use a business that works 9-5 and they have a
drop box so I can drop things off over the weekend and they promise 1
business day turnaround.  If I drop something off Friday night,
Saturday, or Sunday, it doesn't matter.  They're going to get started
on it Monday morning.  It'll be 1 business day to finish the job, so
the earliest I can expect it to be done is around 17:00 Monday or 9:00
Tuesday morning.  Unfortunately, there is some ambiguity as to what
day 17:00 really falls on, similar to the ambiguity that occurs when
you ask what day midnight falls on.  Although it's not the only
answer, Date::Manip treats midnight as the beginning of a day rather
than the end of one.  In the same way, 17:00 is equivalent to 9:00 the
next day and any time the date calculations encounter 17:00, it
automatically switch to 9:00 the next day.  Although this introduces
some quirks, I think this is justified.  I also think that it is the
way most people think of it. If I drop something off first thing
Monday morning, I would expect to pick it up first thing Tuesday if
there is 1 business day turnaround.

Equivalently, if I want a job to be finished on Saturday (despite the fact
that I cannot pick it up since the business is closed), I have to drop it
off no later than Friday at 9:00.  That gives them a full business day to
finish it off.  Of course, I could just as easily drop it off at 17:00
Thursday, or any time between then and 9:00 Friday.  Again, it's a matter
of treating 17:00 as ambiguous.

So Saturday + 1 business day = Tuesday at 9:00 (which means anything
from Monday 17:00 to Tuesday 9:00), but Monday at 9:01 + 1 business
day = Tuesday at 9:01 which is unambiguous.

=head1 EXACT AND APPROXIMATE CALCULATIONS

In many cases, it is somewhat ambiguous what amount of time a delta
actually refers to.  Although it is ALWAYS known how many months in a
year, hours in a day, etc., it is NOT known (in the general case) how
many days are in a month.  As a result, the part of the delta
containing month/year and the part with sec/min/hr/day must be treated
separately.  For example, "Mar 31, 12:00:00" plus a delta of "1 month
2 days" would yield "May 2 12:00:00".  The year/month is first handled
while keeping the same date.  Mar 31 plus one month is Apr 31 (but
since Apr only has 30 days, it becomes Apr 30).  Apr 30 + 2 days is
May 2.

Likewise, when calculating the delta between two dates, the delta may
take two different forms. The exact form is to use only the days,
hours, minutes, and seconds (weeks are also included, except in
business calculations) and expressing the delta exactly. In approximate
mode, the other fields (years and months; weeks in the case of business
calculations) are used to produce a more human format.

For example, the two dates "Mar 12 1995" and "Apr 13 1995" would have
an exact delta of "31 days" but in the approximate mode, it would be
returned as "1 month 1 day".  Also, "Mar 31" and "Apr 30" would have
deltas of "30 days" or "1 month" (since Apr 31 doesn't exist, it drops
down to Apr 30).  Approximate mode is a more human way of looking at
things (you'd say 1 month and 2 days more often then 33 days), but it
is less meaningful in terms of absolute time.

One other difference is that an exact delta is exactly the amount of
time that has passed, including all effects of daylight saving
time. Approximate deltas ignore the affects of daylight saving time.
So, for example, the approximate time between Jan 1 00:00:00 and Jun 1
00:00:00 in America/New_York is 0:5:0:0:0:0:0, but is exactly
0:0:21:4:23:0:0 .

=head1 SUBTRACTION

In exact calculations, and in delta-delta calculations, the the
$subtract argument is easy to understand.  When working with an
approximate delta however (either when adding an approximate delta to
a date, or when taking two dates to get an approximate delta), there
is a degree of uncertainty in how the calculation is done, and the
$subtract argument is used to specify exactly how the approximate
delta is to be use. An example illustrates this quite well.

If you take the date Jan 4, 2000 and subtract a delta of "1 month 1
week" from it, you end up with Nov 27, 1999 (Jan 4, 2000 minus 1 month
is Dec 4, 1999; minus 1 week is Nov 27, 1999). But Nov 27, 1999 plus a
delta of "1 month 1 week" is Jan 3, 2000 (Nov 27, 1999 plus 1 month is
Dec 27, 1999; plus 1 week is Jan 3, 2000).

In other words the approximate delta (but NOT the exact delta) is different
depending on whether you move from earlier date to the later date, or vice
versa. And depending on what you are calculating, both are useful.

In order to resolve this, the $subtract argument can take on the values
0, 1, or 2, and have the following meaning.

=over 4

=item B<$subtract in approximate date-date calculations>

In the call:

   $delta = $date1->calc($date2,$subtract,"approx");

if $subtract is 0, the resulting delta can be added to $date1 to get
$date2. Obviously $delta may still be negative (if $date2 comes before
$date1).

If $subtract is 1, the resulting delta can be subtracted from $date1
to get $date2 (the deltas from these two are identical except for having
an opposite sign).

If $subtract is 2, the resulting delta can be added to $date2 to get
$date1. In other words, the following are identical:

   $delta = $date1->calc($date2,2,"approx");
   $delta = $date2->calc($date1,"approx");

=item B<$subtract in approximate date-delta calculations>

In the call:

   $date2 = $date1->calc($delta,$subtract);

If $subtract is 0, the resulting date is determined by adding $delta to $date1.

If $subtract is 1, the resulting date is determined by subtracting $delta from
$date1.

If $subtract is 2, the resulting date is the date which $delta can be added to
to get $date1. This is NOT available with business calculations (for them,
this is treated the same as $subtract=1).

With business calculations, the $subtract=2 argument is ambiguous.
For example, the date 1997-11-26 17:00:00 plus a delta of "business 1
month 1 day" gives a date of 1998-01-05 08:00, and the date 1997-11-28
17:00:00 plus the same delta also gives the value of 1998-01-05 08:00.
Since there is no single date which the delta could be added to to
get $date1, this option cannot be implemented.

=back

=head1 APPROXIMATE DATE/DATE CALCULATION

There are two different ways to look at the approximate delta between
two dates.

In Date::Manip 5.xx, the approximate delta between the two dates:

   Jan 10 1996 noon
   Jan  7 1998 noon

was +1:11:4:0:0:0:0 (or 1 year, 11 months, 4 weeks).  In calculating
this, the first date was adjusted as far as it could go towards the
second date without going past it with each unit starting with the
years and ending with the seconds.

This gave a strictly positive or negative delta, but it isn't
actually how most people would think of the delta.

As of Date::Manip 6.0, the delta is +2:0:-0:3:0:0:0 (or 2 years minus
3 days). Although this leads to mixed-sign deltas, it is actually how
more people would think about the delta. It has the additional
advantage of being easier to calculate.

For non-business mode calculations, the year/month part of the
approximate delta will move a date from the year/month of the first
date into the year/month of the second date. The remainder of the
delta will adjust the days/hours/minutes/seconds as appropriate.

For approximate business mode calculations, the year and date will be
done approximately, and the remainder will be done exactly. There will
be no value for the weeks field in the delta produced.

=head1 KNOWN BUGS

None known.

=head1 BUGS AND QUESTIONS

Please refer to the Date::Manip::Problems documentation for
information on submitting bug reports or questions to the author.

=head1 SEE ALSO

Date::Manip        - main module documentation

=head1 LICENSE

This script is free software; you can redistribute it and/or
modify it under the same terms as Perl itself.

=head1 AUTHOR

Sullivan Beck (sbeck@cpan.org)

=cut