Date::Manip::Calc(3pm) | User Contributed Perl Documentation | Date::Manip::Calc(3pm) |

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

Nov 3 2016 11:00:00 Dec 5 2016 12:00:00 Elapsed time: 770 hoursThere are several ways to describe the time that elapsed. The first way is to give the difference exactly. This is the exact delta. An exact delta is always described in terms of hours, minutes, and seconds. The problem with this is that we don't think in terms of exact deltas. We think in terms which cannot be expressed exactly. For example, most people would look at those two dates and think:

Percieved: 1 month, 2 days, 1 hourBut the two dates:

Feb 3 2016 11:00:00 Mar 5 2016 12:00:00 Elapsed time: 745 hours Perceived: 1 month, 2 days, 1 hourSome fields in a delta do not have an exact length. A year is usually 365 days long, but sometimes it is 366. A month might be 28, 29, 30, or 31 days long. Perhaps the most unexpected difficulty is that days are not of constant length. Most people would define a day as 24 hours, but when you take daylight saving time into account that definition produces unexpected results. The following calculation illustrates this:

Nov 5, 2011 02:30 EDT + 24 hour Result: Nov 6, 2011 01:30 ESTThis immediately causes most people to redefine a day as the amount of time between the same wallclock time. For example, the amount of time between noon one day and noon the next (regardless of daylight saving time changes). This definition doesn't work either. For example:

Mar 12, 2011 02:30 EST + 1 day (same time next day) Result: Mar 13 02:30 ESTBut that date does not exist! Neither does:

Result: Mar 13 02:30 EDTAn alternate calculation could be:

Nov 5, 2011 01:30 EDT + 1 day (same time next day) Result: Nov 6, 01:30 EDT Result: Nov 6, 01:30 ESTBoth of those results exist. Which result did you mean? The first one is probably correct (since it is 24 hours later), but an hour later, you will have the same clock time again. So, the same time next day definition doesn't work at all for some dates (during a 'spring forward' type daylight saving time transition) and is ambiguous for others (during a 'fall back' type daylight saving time transition). Calculations involving exact deltas are unambiguous in all cases. A second class of delta is called a semi-exact delta, and these add days (and weeks) to the delta, and treats days as a "same time next day" at all times except the two cases where the resulting date falls in the period where a daylight saving time transition is occuring. Then it falls back to the 24 hour definition. A final class of delta is an approximate delta which includes all of the fields (years and months). This allows Date::Manip to handle deltas in a way that is consistent with how most people perceive the elapsed time. It should be noted that there is some uncertaintly there as not everyone's definition of how a delta is perceived is the same, but in general, they should be closer to what most people think of.

**Date/Date calculations**- A calculation involving 2 dates is used to determine the
amount of time (the delta) between them.
$delta = $date1->calc($date2 [,$subtract] [,$mode]);

DELTA = DATE2 - DATE1

DELTA = DATE1 - DATE2

**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]);

DATE2 = DATE1 + DELTA

DATE2 = DATE1 - DELTA

**Delta/Delta calculations**- Delta/delta calculations can be performed to add two
amounts of time together, or subtract them.
$delta3 = $delta1->calc($delta2 [,$subtract] [,$no_normalize]);

DELTA3 = DELTA1 + DELTA2

DELTA3 = DELTA1 - DELTA2

**Business and non-business calculations**- A business 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 (though there is some flexibility in defining what exactly
constitutes the work week as described in the Date::Manip::Config manual).
This is described in more detail below in "BUSINESS MODE
CONSIDERATIONS".

**Exact, semi-exact, and approximate calculations**- An exact calculation is one in which the delta used (or
produced) is an exact delta. An exact delta is described in more detail in
the Date::Manip::Delta manual, but the short explanation is that it is a
delta which only involves fields of an exactly known length (hours,
minutes, and seconds). Business deltas also include days in the exact
part. The value of all other fields in the delta will be zero.

**Mode in date-date calculations**- When doing a date-date calculation, the following call is
used:
$delta = $date1->calc($date2 [,$subtract] [,$mode]);

exact : an exact, non-business calculation semi : a semi-exact, non-business calculation approx : an approximate, non-business calculation business : an exact, business calculation bsemi : a semi-exact, business calculation bapprox : an approximate, business calculation

**Mode in date-delta calculations**- When doing calculations of a date and a delta:
$date2 = $date1->calc($delta [,$subtract]); $date2 = $delta->calc($date1 [,$subtract]);

**Mode in delta-delta calculations**- When doing calculations with two deltas:
$delta3 = $delta1->calc($delta2 [,$subtract]);

**date-date calculations**- When doing a business calculation, both dates must be in
the same time zone or an error is produced.

**date-delta calculations**- When adding a delta to a date, the resulting date will be in the same time zone as the original date.

**delta-delta calculations**- No timezone information applies.

Saturday at noon + 1 business day = Tuesday at 9:00 Saturday at noon - 1 business day = Friday at 9:00What 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. It should be noted that when adding years, months, and weeks, the business day is ignored. Once they've been added, the resulting date is forced to be a business time (i.e. it moves to the start of the next business day if it wasn't one already) before proceeding with the days, hours, minutes, and seconds part.

1 year = 12 months 1 week = 7 days 1 hour = 60 minutes 1 minute = 60 secondsThis leaves two relationships which are not exact:

1 month = ? days 1 day = ? hoursFor non-business calculations, a day is usually 24 hours long. Due to daylight saving time transitions which might make a day be 23 or 25 hours long (or in some cases, some other length), the relation is not exact. Whenever possible, a day is actually measured as the same time on two days (i.e. Tuesday at noon to Wednesday at noon) even if that period is not precisely 24 hours. For business calculations, a days length is determined by the length of the work day and is known exactly. Exact calculations involve ONLY quantities of time with a known length, so there is no ambiguity in them. Approximate and semi-exact calculations involve variable length fields, and so they must be treated specially. In order to do an approximate or semi-exact calculation, the delta is added to a date in pieces, where the fields in each piece have an exact and known relationship. For a non-business calculation, a calculation occurs in the following steps:

year/month fields added week/day fields added hour/minute/second fields addedFor a business calculation, the steps are:

year/month fields added week field added day field added hour/minute/second fields addedAfter each step, a valid date must be present, or it will be adjusted before proceeding to the next step. Note however that for business calculations, the first step must produce a valid date, but not necessarily a business date. The second step will produce a valid business date. A series of examples will illustrate this.

**A date and non-business approximate delta**-
date = Mar 31 2001 at 12:00:00 delta = 1 year, 1 month, 1 day, 1 hour

Apr 31, 2002 at 12:00

Apr 30, 2002 at 12:00

May 1, 2002 at 12:00

May 1, 2002 at 13:00

**A simple business calculation**- Assuming a normal Monday-Friday work week from 8:00 -
17:00:
date = Wed, Nov 23, 2011 at 12:00 delta = 1 week, 1 day, 1 hour

Wed, Nov 30, 2011 at 12:00

Thu, Dec 1, 2011 at 12:00

Thu, Dec 1, 2011 at 13:00

**A business example where a holiday impacts it**- In America, Jul 4 is a holiday, so Mon, Jul 4, 2011 is not
a work day.
date = Mon, Jun 27, 2011 at 12:00 delta = 1 week, 1 day, 1 hour

Mon, Jul 4, 2011 at 12:00

Tue, Jul 5, 2011 at 8:00

Wed, Jul 6, 2011 at 8:00

Wed, Jul 6, 2011 at 9:00

**Calculation where daylight savings time impacts it (fall example)**- In the America/New_York timezone (Eastern time), on
November 6, 2011, the following time change occurred:
2011-11-06 02:00 EDT => 2011-11-06 01:00 EST

date = 2011-11-05 02:30 EDT delta = 1 day

2011-11-06 02:30 EDT

date = 2011-11-07 02:30 EST delta = -1 day

2011-11-06 02:30 EST

date = 2011-11-05 02:30 EDT delta = 2 days

2011-11-07 02:30 EST

**Calculation where daylight savings time impacts it (spring example)**- In the America/New_York timezone (Eastern time), on March
13, the following time change occurred:
2011-03-13 02:00 EST => 2011-03-13 03:00 EDT

date = 2011-03-12 02:30 EST delta = 1 day

2011-03-13 02:30 EST

2011-03-13 02:30 EDT

date = 2011-03-12 02:30 EST delta = 24 hours

2011-03-13 03:30 EDT

**$subtract****in approximate date-date calculations**- In the call:
$delta = $date1->calc($date2,$subtract,"approx");

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

**$subtract****in approximate date-delta calculations**- In the call:
$date2 = $date1->calc($delta,$subtract);

Jan 10 1996 noon Jan 7 1998 noonwas 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, date, and week parts will be done approximately, and the remainder will be done exactly.

2017-10-14 | perl v5.26.0 |