1Date::Manip::Calc(3) User Contributed Perl Documentation Date::Manip::Calc(3)
2
6 Date::Manip::Calc - describes date calculations
7
9 Two objects (both of which are either Date::Manip::Date or
10 Date::Manip::Delta objects) may be used to creates a third object based
11 on those two.
12 $delta = $date->calc($date2 [,$subtract] [,$mode]);
14 $date2 = $date->calc($delta [,$subtract]);
16 $date2 = $delta->calc($date1 [,$subtract]);
17 $delta3 = $delta1->calc($delta2 [,$subtract] [,$no_normalize]);
19
21 This document describes the different types of calculations that can be
22 done using dates and deltas. Date calculations are much more
23 complicated than they initially appear, so this document is fairly
24 large.
25 The complication in date calculations is due to the fact that it is
27 impossible to express some parts of a delta as an exact length. Some
28 examples will illustrate this:
29 As an example, let's take two dates and determine how much time elapsed
31 between them:
32 Nov 3 2016 11:00:00
34 Dec 5 2016 12:00:00
35 Elapsed time: 770 hours
37 There are several ways to describe the time that elapsed. The first
39 way is to give the difference exactly. This is the exact delta.
40 An exact delta is always described in terms of hours, minutes, and
42 seconds.
43 The problem with this is that we don't think in terms of exact deltas.
45 We think in terms which cannot be expressed exactly.
46 For example, most people would look at those two dates and think:
48 Perceived: 1 month, 2 days, 1 hour
50 But the two dates:
52 Feb 3 2016 11:00:00
54 Mar 5 2016 12:00:00
55 Elapsed time: 745 hours
57 Perceived: 1 month, 2 days, 1 hour
58 Some fields in a delta do not have an exact length. A year is usually
60 365 days long, but sometimes it is 366. A month might be 28, 29, 30,
61 or 31 days long.
62 Perhaps the most unexpected difficulty is that days are not of constant
64 length. Most people would define a day as 24 hours, but when you take
65 daylight saving time into account that definition produces unexpected
66 results. The following calculation illustrates this:
67 Nov 5, 2011 02:30 EDT
69 + 24 hour
70 Result: Nov 6, 2011 01:30 EST
72 This immediately causes most people to redefine a day as the amount of
74 time between the same wall clock time. For example, the amount of time
75 between noon one day and noon the next (regardless of daylight saving
76 time changes).
77 This definition doesn't work either. For example:
79 Mar 12, 2011 02:30 EST
81 + 1 day (same time next day)
82 Result: Mar 13 02:30 EST
84 But that date does not exist! Neither does:
86 Result: Mar 13 02:30 EDT
88 An alternate calculation could be:
90 Nov 5, 2011 01:30 EDT
92 + 1 day (same time next day)
93 Result: Nov 6, 01:30 EDT
95 Result: Nov 6, 01:30 EST
96 Both of those results exist. Which result did you mean? The first one
98 is probably correct (since it is 24 hours later), but an hour later,
99 you will have the same clock time again.
100 So, the same time next day definition doesn't work at all for some
102 dates (during a 'spring forward' type daylight saving time transition)
103 and is ambiguous for others (during a 'fall back' type daylight saving
104 time transition).
105 Calculations involving exact deltas are unambiguous in all cases.
107 A second class of delta is called a semi-exact delta, and these add
109 days (and weeks) to the delta, and treats days as a "same time next
110 day" at all times except the two cases where the resulting date falls
111 in the period where a daylight saving time transition is occurring.
112 Then it falls back to the 24 hour definition.
113 A final class of delta is an approximate delta which includes all of
115 the fields (years and months). This allows Date::Manip to handle
116 deltas in a way that is consistent with how most people perceive the
117 elapsed time. It should be noted that there is some uncertaintly there
118 as not everyone's definition of how a delta is perceived is the same,
119 but in general, they should be closer to what most people think of.
120
122 This document describes the different types of calculations.
123 Calculations involve two types of Date::Manip objects: dates and
124 deltas. These are described in the Date::Manip::Date and
125 Date::Manip::Delta manuals respectively.
126 Two objects (two dates, two deltas, or one of each) are used. In all
128 cases, if a second object is not passed in, undef is returned.
129 There are 3 types of calculations:
131 Date/Date calculations
133 A calculation involving 2 dates is used to determine the amount of
134 time (the delta) between them.
135 $delta = $date1->calc($date2 [,$subtract] [,$mode]);
137 Two dates can be worked with and a delta will be produced which is
139 the amount of time between the two dates.
140 $date1 and $date2 are Date::Manip::Date objects with valid dates.
142 The Date::Manip::Delta object returned is the amount of time
143 between them. If $subtract is not passed in (or is 0), the delta
144 produced is:
145 DELTA = DATE2 - DATE1
147 If $subtract is non-zero, the delta produced is:
149 DELTA = DATE1 - DATE2
151 The $subtract argument has special importance when doing
153 approximate calculations, and this is described below.
154 If either date is invalid, a delta object will be returned which
156 has an error associated with it.
157 The $mode argument describes the type of delta that is produced and
159 is described below in "MODE".
160 Date/Delta calculations
162 Date/delta calculations can be performed using either a
163 Date::Manip::Date or Date::Manip::Delta object as the primary
164 object:
165 $date2 = $date1->calc($delta [,$subtract]);
167 $date2 = $delta->calc($date1 [,$subtract]);
168 A date and delta can be combined to yield a date that is the given
170 amount of time before or after it.
171 $date1 and $delta are Date::Manip::Date and Date::Manip::Delta
173 objects respectively. A new Date::Manip::Date object is produced.
174 If either $date1 or $delta are invalid, the new date object will
175 have an error associated with it.
176 Both of the calls above perform the same function and produce
178 exactly the same results.
179 If $subtract is not passed in, or is 0, the resulting date is
181 formed as:
182 DATE2 = DATE1 + DELTA
184 If $subtract is non-zero, the resulting date is:
186 DATE2 = DATE1 - DELTA
188 The $subtract argument has special importance when doing
190 approximate calculations, and this is described below in
191 "SUBTRACTION".
192 Delta/Delta calculations
194 Delta/delta calculations can be performed to add two amounts of
195 time together, or subtract them.
196 $delta3 = $delta1->calc($delta2 [,$subtract] [,$no_normalize]);
198 If $subtract is not passed in, or is 0, the resulting delta formed
200 is:
201 DELTA3 = DELTA1 + DELTA2
203 If $subtract is non-zero, then the resulting delta is:
205 DELTA3 = DELTA1 - DELTA2
207 $delta1 and $delta2 are valid Date::Manip::Delta objects, and a new
209 Date::Manip::Delta object is produced.
210 $no_normalize can be the string 'nonormalize' or a non-zero value
212 (in which case $subtract MUST be entered, even if it is 0).
213
215 Date::Manip calculations can be divided into two different categories:
216 business and non-business; and within those are three sub-categories:
217 exact, semi-exact, and approximate.
218 Business and non-business calculations
220 A business calculation is one where the length of the day is
221 determined by the length of the work day, and only business days
222 (i.e. days in which business is conducted) count. Holidays and
223 weekends are omitted (though there is some flexibility in defining
224 what exactly constitutes the work week as described in the
225 Date::Manip::Config manual). This is described in more detail below
226 in "BUSINESS MODE CONSIDERATIONS".
227 A non-business mode calculation is the normal type of calculation
229 where no days are ignored, and all days are full length.
230 Exact, semi-exact, and approximate calculations
232 An exact calculation is one in which the delta used (or produced)
233 is an exact delta. An exact delta is described in more detail in
234 the Date::Manip::Delta manual, but the short explanation is that it
235 is a delta which only involves fields of an exactly known length
236 (hours, minutes, and seconds). Business deltas also include days
237 in the exact part. The value of all other fields in the delta will
238 be zero.
239 A semi-exact calculation is one in which the deltas used (or
241 produced) is a semi-exact delta. This is also described in the
242 Date::Manip::Delta manual, but the short explanation is that it
243 includes days and weeks (for standard calculations) or weeks (for
244 business calculations) in addition to the exact fields. A semi-
245 exact day is defined as the same clock time on two successive days.
246 So noon to noon is 1 day (even though it may not be exactly 24
247 hours due to a daylight saving time transition). A week is defined
248 as 7 days. This is described in more detail below.
249 An approximate calculation is one in which the deltas used (or
251 produced) are approximate, and may include any of the fields.
252 In date-delta and delta-delta calculations, the mode of the calculation
254 will be determined automatically by the delta. In the case of date-date
255 calculations, the mode is supplied as an argument.
256 Mode in date-date calculations
258 When doing a date-date calculation, the following call is used:
259 $delta = $date1->calc($date2 [,$subtract] [,$mode]);
261 $mode defaults to "exact". The delta produced will be be either a
263 business or non-business delta; exact, semi-exact, or approximate,
264 as specified by $mode.
265 Currently, the possible values that $mode can have are:
267 exact : an exact, non-business calculation
269 semi : a semi-exact, non-business calculation
270 approx : an approximate, non-business calculation
271 business : an exact, business calculation
273 bsemi : a semi-exact, business calculation
274 bapprox : an approximate, business calculation
275 Mode in date-delta calculations
277 When doing calculations of a date and a delta:
278 $date2 = $date1->calc($delta [,$subtract]);
280 $date2 = $delta->calc($date1 [,$subtract]);
281 the mode is not passed in. It is determined exclusively by the
283 delta. If $delta is a business delta, A business calculation is
284 done. If $delta is a non-business delta, a non-business calculation
285 will be done.
286 The $delta will also be classified as exact, semi-exact, or
288 approximate based on which fields are non-zero.
289 Mode in delta-delta calculations
291 When doing calculations with two deltas:
292 $delta3 = $delta1->calc($delta2 [,$subtract]);
294 the mode is not passed in. It is determined by the two deltas.
296 If both deltas are business mode, or both are non-business mode, a
298 new delta will be produced of the same type.
299 It one of the deltas is a business mode and the other is not, the
301 resulting delta will have an error condition since there is no
302 direct correlation between the two types of deltas. Even though it
303 would be easy to add the two together, it would be impossible to
304 come up with a result that is meaningful.
305 If both deltas are exact, semi-exact, or approximate, the resulting
307 delta is the same. If one delta is approximate and one is not, then
308 the resulting delta is approximate. It is NOT treated as an error.
309 Likewise, if one is semi-exact and the other exact, a semi-exact
310 delta is produced.
311
313 date-date calculations
314 When doing a business calculation, both dates must be in the same
315 time zone or an error is produced.
316 For non-business calculations, when calculating the difference
318 between two dates in different time zones, $date2 will be converted
319 to the same timezone as $date1 and the returned date will be in
320 this timezone.
321 date-delta calculations
323 When adding a delta to a date, the resulting date will be in the
324 same time zone as the original date.
325 delta-delta calculations
327 No timezone information applies.
328 It should also be noted that daylight saving time considerations are
330 currently ignored when doing business calculations. In common usage,
331 daylight saving time changes occurs outside of the business day, so the
332 business day length is constant. As a result, daylight saving time is
333 ignored.
334
336 In order to correctly do business mode calculations, a config file
337 should exist which contains the section defining holidays (otherwise,
338 weekends will be ignored, but all other days will be counted as
339 business days). This is documented below, and in the
340 Date::Manip::Config section of the documentation. Some config
341 variables (namely WorkWeekBeg, WorkWeekEnd, WorkDayBeg, WorkDayEnd, and
342 WorkDay24Hr) defined the length of the work week and work day.
343 If the workday is defined as 08:00 to 18:00, a work week consisting of
345 Mon-Sat, and the standard (American) holidays, then from Tuesday at
346 12:00 to the following Monday at 14:00 is 5 days and 2 hours. If the
347 "end" of the day is reached in a calculation, it automatically switches
348 to the next day. So, Tuesday at 12:00 plus 6 hours is Wednesday at
349 08:00 (provided Wed is not a holiday). Also, a date that is not during
350 a workday automatically becomes the start of the next workday. So,
351 Sunday 12:00 and Monday at 03:00 both automatically becomes Monday at
352 08:00 (provided Monday is not a holiday).
353 Note that a business week is treated the same as an exact week (i.e.
355 from Tuesday to Tuesday, regardless of holidays). Because this means
356 that the relationship between days and weeks is NOT unambiguous, when a
357 semi-exact delta is produced from two dates, it will be in terms of
358 d/h/mn/s (i.e. no week field).
359 Anyone using business mode is going to notice a few quirks about it
361 which should be explained. When I designed business mode, I had in
362 mind what a business which promises 1 business day turnaround really
363 means.
364 If you do a business calculation (with the workday set to 9:00-17:00),
366 you will get the following:
367 Saturday at noon + 1 business day = Tuesday at 9:00
369 Saturday at noon - 1 business day = Friday at 9:00
370 What does this mean?
372 As an example, say I use a business that works 9-5 and they have a drop
374 box so I can drop things off over the weekend and they promise 1
375 business day turnaround. If I drop something off Friday night,
376 Saturday, or Sunday, it doesn't matter. They're going to get started
377 on it Monday morning. It'll be 1 business day to finish the job, so
378 the earliest I can expect it to be done is around 17:00 Monday or 9:00
379 Tuesday morning. Unfortunately, there is some ambiguity as to what day
380 17:00 really falls on, similar to the ambiguity that occurs when you
381 ask what day midnight falls on. Although it's not the only answer,
382 Date::Manip treats midnight as the beginning of a day rather than the
383 end of one. In the same way, 17:00 is equivalent to 9:00 the next day
384 and any time the date calculations encounter 17:00, it automatically
385 switch to 9:00 the next day. Although this introduces some quirks, I
386 think this is justified. I also think that it is the way most people
387 think of it. If I drop something off first thing Monday morning, I
388 would expect to pick it up first thing Tuesday if there is 1 business
389 day turnaround.
390 Equivalently, if I want a job to be finished on Saturday (despite the
392 fact that I cannot pick it up since the business is closed), I have to
393 drop it off no later than Friday at 9:00. That gives them a full
394 business day to finish it off. Of course, I could just as easily drop
395 it off at 17:00 Thursday, or any time between then and 9:00 Friday.
396 Again, it's a matter of treating 17:00 as ambiguous.
397 So Saturday + 1 business day = Tuesday at 9:00 (which means anything
399 from Monday 17:00 to Tuesday 9:00), but Monday at 9:01 + 1 business day
400 = Tuesday at 9:01 which is unambiguous.
401 It should be noted that when adding years, months, and weeks, the
403 business day is ignored. Once they've been added, the resulting date
404 is forced to be a business time (i.e. it moves to the start of the next
405 business day if it wasn't one already) before proceeding with the days,
406 hours, minutes, and seconds part.
407
409 This section contains more details about exactly how exact, semi-exact,
410 and approximate calculations are performed for date/delta calculations.
411 All calculations make use of some exact quantities, including:
413 1 year = 12 months
415 1 week = 7 days
416 1 hour = 60 minutes
417 1 minute = 60 seconds
418 This leaves two relationships which are not exact:
420 1 month = ? days
422 1 day = ? hours
423 For non-business calculations, a day is usually 24 hours long. Due to
425 daylight saving time transitions which might make a day be 23 or 25
426 hours long (or in some cases, some other length), the relation is not
427 exact. Whenever possible, a day is actually measured as the same time
428 on two days (i.e. Tuesday at noon to Wednesday at noon) even if that
429 period is not precisely 24 hours. For business calculations, a days
430 length is determined by the length of the work day and is known
431 exactly.
432 Exact calculations involve ONLY quantities of time with a known length,
434 so there is no ambiguity in them.
435 Approximate and semi-exact calculations involve variable length fields,
437 and so they must be treated specially.
438 In order to do an approximate or semi-exact calculation, the delta is
440 added to a date in pieces, where the fields in each piece have an exact
441 and known relationship.
442 For a non-business calculation, a calculation occurs in the following
444 steps:
445 year/month fields added
447 week/day fields added
448 hour/minute/second fields added
449 For a business calculation, the steps are:
451 year/month fields added
453 week field added
454 day field added
455 hour/minute/second fields added
456 After each step, a valid date must be present, or it will be adjusted
458 before proceeding to the next step. Note however that for business
459 calculations, the first step must produce a valid date, but not
460 necessarily a business date. The second step will produce a valid
461 business date.
462 A series of examples will illustrate this.
464 A date and non-business approximate delta
466 date = Mar 31 2001 at 12:00:00
467 delta = 1 year, 1 month, 1 day, 1 hour
468 First, the year/month fields are added without modifying any other
470 field. This would produce:
471 Apr 31, 2002 at 12:00
473 which is not valid. Any time the year/month fields produce a day
475 past the end of the month, the result is 'truncated' to the last
476 day of the month, so this produces:
477 Apr 30, 2002 at 12:00
479 Next the week/day fields are added producing:
481 May 1, 2002 at 12:00
483 and finally, the exact fields (hour/minute/second) are added to
485 produce:
486 May 1, 2002 at 13:00
488 A simple business calculation
490 Assuming a normal Monday-Friday work week from 8:00 - 17:00:
491 date = Wed, Nov 23, 2011 at 12:00
493 delta = 1 week, 1 day, 1 hour
494 First, the week field is added:
496 Wed, Nov 30, 2011 at 12:00
498 Then the day field is added:
500 Thu, Dec 1, 2011 at 12:00
502 Then the exact fields are added:
504 Thu, Dec 1, 2011 at 13:00
506 A business example where a holiday impacts it
508 In America, Jul 4 is a holiday, so Mon, Jul 4, 2011 is not a work
509 day.
510 date = Mon, Jun 27, 2011 at 12:00
512 delta = 1 week, 1 day, 1 hour
513 First, the week field is added:
515 Mon, Jul 4, 2011 at 12:00
517 Since that is not a work day, it immediately becomes:
519 Tue, Jul 5, 2011 at 8:00
521 Then the day field is added:
523 Wed, Jul 6, 2011 at 8:00
525 and finally the remaining fields:
527 Wed, Jul 6, 2011 at 9:00
529 Calculation where daylight savings time impacts it (fall example)
531 In the America/New_York timezone (Eastern time), on November 6,
532 2011, the following time change occurred:
533 2011-11-06 02:00 EDT => 2011-11-06 01:00 EST
535 Three simple calculations illustrate how this is handled:
537 date = 2011-11-05 02:30 EDT
539 delta = 1 day
540 Adding the day produces:
542 2011-11-06 02:30 EDT
544 which is valid, so that is the result.
546 Similarly:
548 date = 2011-11-07 02:30 EST
550 delta = -1 day
551 produces:
553 2011-11-06 02:30 EST
555 which is valid.
557 Finally:
559 date = 2011-11-05 02:30 EDT
561 delta = 2 days
562 produces:
564 2011-11-07 02:30 EST
566 The calculation will preserve the savings time where possible so
568 the resulting day will have the same offset from UTC. If that is
569 not possible, but the resulting day is valid in the other offset,
570 that will be used instead.
571 Calculation where daylight savings time impacts it (spring example)
573 In the America/New_York timezone (Eastern time), on March 13, the
574 following time change occurred:
575 2011-03-13 02:00 EST => 2011-03-13 03:00 EDT
577 In this case, a calculation may produce an invalid date.
579 date = 2011-03-12 02:30 EST
581 delta = 1 day
582 produces:
584 2011-03-13 02:30 EST
586 This is not valid. Neither is:
588 2011-03-13 02:30 EDT
590 In this case, the calculation will be redone converting days to
592 24-hour periods, so the calculation becomes:
593 date = 2011-03-12 02:30 EST
595 delta = 24 hours
596 which will produce a valid date:
598 2011-03-13 03:30 EDT
600
602 This section contains more details about exactly how exact, semi-exact,
603 and approximate calculations are performed for date/date calculations.
604 When calculating the delta between two dates, the delta may take
606 different forms depending on the mode passed in. An exact calculation
607 will produce a delta which included only exact fields. A semi-exact
608 calculation may produce a semi-exact delta, and an approximate
609 calculation may produce an approximate delta. Note that if the two
610 dates are close enough together, an exact delta will be produced (even
611 if the mode is semi-exact or approximate), or it may produce a semi-
612 exact delta in approximate mode.
613 For example, the two dates "Mar 12 1995 12:00" and "Apr 13 1995 12:00"
615 would have an exact delta of "744 hours", and a semi-exact delta of "31
616 days". It would have an approximate delta of "1 month 1 day".
617 Two dates, "Mar 31 12:00" and "Apr 30 12:00" would have deltas "720
619 hours" (exact), "30 days" (semi-exact) or "1 month" (approximate).
620 Approximate mode is a more human way of looking at things (you'd say 1
622 month and 2 days more often then 33 days), but it is less meaningful in
623 terms of absolute time.
624 One thing to remember is that an exact delta is exactly the amount of
626 time that has passed, including all effects of daylight saving time.
627 Semi-exact and approximate deltas usually ignore the affects of
628 daylight saving time.
629
631 In exact and semi-exact calculations, and in delta-delta calculations,
632 the the $subtract argument is easy to understand. When working with an
633 approximate delta however (either when adding an approximate delta to a
634 date, or when taking two dates to get an approximate delta), there is a
635 degree of uncertainty in how the calculation is done, and the $subtract
636 argument is used to specify exactly how the approximate delta is to be
637 use. An example illustrates this quite well.
638 If you take the date Jan 4, 2000 and subtract a delta of "1 month 1
640 week" from it, you end up with Nov 27, 1999 (Jan 4, 2000 minus 1 month
641 is Dec 4, 1999; minus 1 week is Nov 27, 1999). But Nov 27, 1999 plus a
642 delta of "1 month 1 week" is Jan 3, 2000 (Nov 27, 1999 plus 1 month is
643 Dec 27, 1999; plus 1 week is Jan 3, 2000).
644 In other words the approximate delta (but NOT the exact or semi-exact
646 delta) is different depending on whether you move from earlier date to
647 the later date, or vice versa. And depending on what you are
648 calculating, both are useful.
649 In order to resolve this, the $subtract argument can take on the values
651 0, 1, or 2, and have different meanings.
652 $subtract in approximate date-date calculations
654 In the call:
655 $delta = $date1->calc($date2,$subtract,"approx");
657 if $subtract is 0, the resulting delta can be added to $date1 to
659 get $date2. Obviously $delta may still be negative (if $date2 comes
660 before $date1).
661 If $subtract is 1, the resulting delta can be subtracted from
663 $date1 to get $date2 (the deltas from these two are identical
664 except for having an opposite sign).
665 If $subtract is 2, the resulting delta can be added to $date2 to
667 get $date1. In other words, the following are identical:
668 $delta = $date1->calc($date2,2,"approx");
670 $delta = $date2->calc($date1,"approx");
671 $subtract in approximate date-delta calculations
673 In the call:
674 $date2 = $date1->calc($delta,$subtract);
676 If $subtract is 0, the resulting date is determined by adding
678 $delta to $date1.
679 If $subtract is 1, the resulting date is determined by subtracting
681 $delta from $date1.
682 If $subtract is 2, the resulting date is the date which $delta can
684 be added to to get $date1.
685 For business mode calculations, $date1 will first be adjusted to be
687 a valid work day (if it isn't already), so this may lead to non-
688 intuitive results.
689 In some cases, it is impossible to do a calculation with $subtract
691 = 2. As an example, if the date is "Dec 31" and the delta is "1
692 month", there is no date which you can add "1 month" to to get "Dec
693 31". When this occurs, the date returned has an error flag.
694
696 There are two different ways to look at the approximate delta between
697 two dates.
698 In Date::Manip 5.xx, the approximate delta between the two dates:
700 Jan 10 1996 noon
702 Jan 7 1998 noon
703 was 1:11:4:0:0:0:0 (or 1 year, 11 months, 4 weeks). In calculating
705 this, the first date was adjusted as far as it could go towards the
706 second date without going past it with each unit starting with the
707 years and ending with the seconds.
708 This gave a strictly positive or negative delta, but it isn't actually
710 how most people would think of the delta.
711 As of Date::Manip 6.0, the delta is 2:0:0:-3:0:0:0 (or 2 years minus 3
713 days). Although this leads to mixed-sign deltas, it is actually how
714 more people would think about the delta. It has the additional
715 advantage of being easier to calculate.
716 For non-business mode calculations, the year/month part of the
718 approximate delta will move a date from the year/month of the first
719 date into the year/month of the second date. The remainder of the delta
720 will adjust the days/hours/minutes/seconds as appropriate.
721 For approximate business mode calculations, the year, date, and week
723 parts will be done approximately, and the remainder will be done
724 exactly.
725
727 None known.
728
730 Please refer to the Date::Manip::Problems documentation for information
731 on submitting bug reports or questions to the author.
732
734 Date::Manip - main module documentation
735
737 This script is free software; you can redistribute it and/or modify it
738 under the same terms as Perl itself.
739
741 Sullivan Beck (sbeck@cpan.org)
742perl v5.34.0 2021-11-23 Date::Manip::Calc(3)