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 date calculations. Date calculations involve
22 two types of Date::Manip objects: dates and deltas. These are described
23 in the Date::Manip::Date and Date::Manip::Delta manuals respectively.
24 Two objects (two dates, two deltas, or one of each) are used. In all
26 cases, if a second object is not passed in, undef is returned.
27 There are 3 types of date calculations:
29 Date-Date calculations
31 $delta = $date1->calc($date2 [,$subtract] [,$mode]);
32 Two dates can be worked with and a delta will be produced which is
34 the amount of time between the two dates.
35 $date1 and $date2 are Date::Manip::Date objects with valid dates.
37 The Date::Manip::Delta object returned is the amount of time
38 between them. If $subtract is not passed in (or is 0), the delta
39 produced is:
40 DELTA = DATE2 - DATE1
42 If $subtract is non-zero, the delta produced is:
44 DELTA = DATE1 - DATE2
46 The $subtract argument has special importance when doing
48 approximate calculations, and this is described below.
49 If either date is invalid, a delta object will be returned which
51 has an error associated with it.
52 The $mode argument describes the type of delta is produced and is
54 described below.
55 Date-Delta calculations
57 Date-delta calculations can be performed using either a
58 Date::Manip::Date or Date::Manip::Delta object as the primary
59 object:
60 $date2 = $date1->calc($delta [,$subtract]);
62 $date2 = $delta->calc($date1 [,$subtract]);
63 A date and delta can be combined to yield a date that is the given
65 amount of time before or after it.
66 $date1 and $delta are Date::Manip::Date and Date::Manip::Delta
68 objects respectively. A new Date::Manip::Date object is produced.
69 If either $date1 or $delta are invalid, the new date object will
70 have an error associated with it.
71 Both of the calls above perform the same function and produce
73 exactly the same results.
74 If $subtract is not passed in, or is 0, the resulting date is
76 formed as:
77 DATE2 = DATE1 + DELTA
79 If $subtract is non-zero, the resulting date is:
81 DATE2 = DATE1 - DELTA
83 The $subtract argument has special importance when doing
85 approximate calculations, and this is described below.
86 Delta-Delta calculations
88 Delta-delta calculations can be performed to add two amounts of
89 time together, or subtract them.
90 $delta3 = $delta1->calc($delta2 [,$subtract] [,$no_normalize]);
92 If $subtract is not passed in, or is 0, the resulting delta formed
94 is:
95 DELTA3 = DELTA1 + DELTA2
97 If $subtract is non-zero, then the resulting delta is:
99 DELTA3 = DELTA1 - DELTA2
101 $delta1 and $delta2 are valid Date::Manip::Delta objects, and a new
103 Date::Manip::Delta object is produced.
104 $no_normalize can be the string 'nonormalize' or a non-zero value
106 (in which case $subtract MUST be entered).
107
109 Date::Manip calculations can be divide into two different categories:
110 business and non-business; and within those are three sub-categories:
111 exact, semi-exact, and approximate.
112 Business and non-business calculations
114 A business calculation is one where the length of the day is
115 determined by the length of the work day, and only business days
116 (i.e. days in which business is conducted) count. Holidays and
117 weekends are omitted (though there is some flexibility in defining
118 what exactly constitutes the work week as described in the
119 Date::Manip::Config manual). This is described in more detail
120 below.
121 A non-business mode calculation is the normal type of calculation
123 where no days are ignored, and all days are full length.
124 Exact, semi-exact, and approximate calculations
126 An exact calculation is one in which the delta used (or produced)
127 is an exact delta. An exact delta is described in the
128 Date::Manip::Delta manual, but the short explanation is that it is
129 a delta which only involves fields of an exactly known length
130 (hours, minutes, and seconds). Business deltas also include days
131 in the exact part. The value of all other fields in the delta will
132 be zero.
133 A semi-exact calculation is one in which the deltas used (or
135 produced) is a semi-exact delta. This is also described in the
136 Date::Manip::Delta manual, but the short explanation is that it
137 includes days and weeks (for standard calculations) or weeks (for
138 business calculations) in addition to the exact fields.
139 A semi-exact day is defined as the same clock time on two
141 successive days. So noon to noon is 1 day (even though it may not
142 be exactly 24 hours due to a daylight saving time transition). A
143 week is defined as 7 days. This is described in more detail below.
144 An approximate calculation is one in which the deltas used (or
146 produced) are approximate, and may include any of the fields.
147 In date-delta and delta-delta calculations, the mode of the calculation
149 will be determined automatically by the delta. In the case of date-date
150 calculations, the mode is supplied as an argument.
151 Mode in date-date calculations
153 When doing a date-date calculation, the following call is used:
154 $delta = $date1->calc($date2 [,$subtract] [,$mode]);
156 $mode defaults to "exact". The delta produced will be be either a
158 business or non-business delta; exact, semi-exact, or approximate,
159 as specified by $mode.
160 Currently, the possible values that $mode can have are:
162 exact : an exact, non-business calculation
164 semi : a semi-exact, non-business calculation
165 approx : an approximate, non-business calculation
166 business : an exact, business alculation
168 bsemi : a semi-exact, business calculation
169 bapprox : an approximate, business calculation
170 Mode in date-delta calculations
172 When doing calculations of a date and a delta:
173 $date2 = $date1->calc($delta [,$subtract]);
175 $date2 = $delta->calc($date1 [,$subtract]);
176 the mode is not passed in. It is determined exclusively by the
178 delta. If $delta is a business delta, A business calculation is
179 done. If $delta is a non-business delta, a non-business calculation
180 will be done.
181 The $delta will also be classified as exact, semi-exact, or
183 approximate based on which fields are non-zero.
184 Mode in delta-delta calculations
186 When doing calculations with two deltas:
187 $delta3 = $delta1->calc($delta2 [,$subtract]);
189 the mode is not passed in. It is determined by the two deltas.
191 If both deltas are business mode, or both are non-business mode, a
193 new delta will be produced of the same type.
194 It one of the deltas is a business mode and the other is not, the
196 resulting delta will have an error condition since there is no
197 direct correlation between the two types of deltas. Even though it
198 would be easy to add the two together, it would be impossible to
199 come up with a result that is meaningful.
200 If both deltas are exact, semi-exact, or approximate, the resulting
202 delta is the same. If one delta is approximate and one is not, then
203 the resulting delta is approximate. It is NOT treated as an error.
204 Likewise, if one is semi-exact and the other exact, a semi-exact
205 delta is produced.
206
208 date-date calculations
209 When doing a business calculation, both dates must be in the same
210 time zone or an error is produced.
211 For the exact, semi-exact, and approx calculations, when
213 calculating the difference between two dates in different time
214 zones, $date2 will be converted to the same timezone as $date1 and
215 the returned date will be in this timezone.
216 date-delta calculations
218 When adding a delta to a date, the resulting date will be in the
219 same time zone as the original date.
220 delta-delta calculations
222 No timezone information applies.
223 It should also be noted that daylight saving time considerations are
225 currently ignored when doing business calculations. In common usage,
226 daylight saving time changes occurs outside of the business day, so the
227 business day length is constant. As a result, daylight saving time is
228 ignored.
229
231 In order to correctly do business mode calculations, a config file
232 should exist which contains the section defining holidays (otherwise,
233 weekends will be ignored, but all other days will be counted as
234 business days). This is documented below, and in the
235 Date::Manip::Config section of the documentation. Some config
236 variables (namely WorkWeekBeg, WorkWeekEnd, WorkDayBeg, WorkDayEnd, and
237 WorkDay24Hr) defined the length of the work week and work day.
238 If the workday is defined as 08:00 to 18:00, a work week consisting of
240 Mon-Sat, and the standard (American) holidays, then from Tuesday at
241 12:00 to the following Monday at 14:00 is 5 days and 2 hours. If the
242 "end" of the day is reached in a calculation, it automatically switches
243 to the next day. So, Tuesday at 12:00 plus 6 hours is Wednesday at
244 08:00 (provided Wed is not a holiday). Also, a date that is not during
245 a workday automatically becomes the start of the next workday. So,
246 Sunday 12:00 and Monday at 03:00 both automatically becomes Monday at
247 08:00 (provided Monday is not a holiday).
248 Note that a business week is treated the same as an exact week (i.e.
250 from Tuesday to Tuesday, regardless of holidays). Because this means
251 that the relationship between days and weeks is NOT unambiguous, when a
252 semi-exact delta is produced from two dates, it will be in terms of
253 d/h/mn/s (i.e. no week field).
254 Anyone using business mode is going to notice a few quirks about it
256 which should be explained. When I designed business mode, I had in
257 mind what a business which promises 1 business day turnaround really
258 means.
259 If you do a business calculation (with the workday set to 9:00-17:00),
261 you will get the following:
262 Saturday at noon + 1 business day = Tuesday at 9:00
264 Saturday at noon - 1 business day = Friday at 9:00
265 What does this mean?
267 As an example, say I use a business that works 9-5 and they have a drop
269 box so I can drop things off over the weekend and they promise 1
270 business day turnaround. If I drop something off Friday night,
271 Saturday, or Sunday, it doesn't matter. They're going to get started
272 on it Monday morning. It'll be 1 business day to finish the job, so
273 the earliest I can expect it to be done is around 17:00 Monday or 9:00
274 Tuesday morning. Unfortunately, there is some ambiguity as to what day
275 17:00 really falls on, similar to the ambiguity that occurs when you
276 ask what day midnight falls on. Although it's not the only answer,
277 Date::Manip treats midnight as the beginning of a day rather than the
278 end of one. In the same way, 17:00 is equivalent to 9:00 the next day
279 and any time the date calculations encounter 17:00, it automatically
280 switch to 9:00 the next day. Although this introduces some quirks, I
281 think this is justified. I also think that it is the way most people
282 think of it. If I drop something off first thing Monday morning, I
283 would expect to pick it up first thing Tuesday if there is 1 business
284 day turnaround.
285 Equivalently, if I want a job to be finished on Saturday (despite the
287 fact that I cannot pick it up since the business is closed), I have to
288 drop it off no later than Friday at 9:00. That gives them a full
289 business day to finish it off. Of course, I could just as easily drop
290 it off at 17:00 Thursday, or any time between then and 9:00 Friday.
291 Again, it's a matter of treating 17:00 as ambiguous.
292 So Saturday + 1 business day = Tuesday at 9:00 (which means anything
294 from Monday 17:00 to Tuesday 9:00), but Monday at 9:01 + 1 business day
295 = Tuesday at 9:01 which is unambiguous.
296 It should be noted that when adding years, months, and weeks, the
298 business day is ignored. Once they've been added, the resulting date
299 is forced to be a business time (i.e. it moves to the start of the next
300 business day if it wasn't one already) before proceeding with the days,
301 hours, minutes, and seconds part.
302
304 In many cases, it is somewhat ambiguous what amount of time a delta
305 actually refers to. Some relationships between fields in the delta are
306 known. These include:
307 1 year = 12 months
309 1 week = 7 days
310 1 hour = 60 minutes
311 1 minute = 60 seconds
312 Other relationships are not known. These include:
314 1 month = ? days
316 1 day = ? hours
317 For non-business calculations, a day is usually 24 hours long. Due to
319 daylight saving time transitions which might make a day be 23 or 25
320 hours long (or in some cases, some other length), the relation is not
321 exact. Whenever possible, a day is actually measured as the same time
322 on two days (i.e. Tuesday at noon to Wednesday at noon) even if that
323 period is not precisely 24 hours. For business calculations, a days
324 length is determined by the length of the work day and is known
325 exactly.
326 Exact calculations involve ONLY quantities of time with a known length,
328 so there is no ambiguity in them.
329 Approximate and semi-exact calculations involve variable length fields,
331 and so they must be treated specially.
332 In order to do an approximate or semi-exact calculation, the delta is
334 added to a date in pieces, where the fields in each piece have an exact
335 and known relationship.
336 For a non-business calculation, a calculation occurs in the following
338 steps:
339 year/month fields added
341 week/day fields added
342 hour/minute/second fields added
343 For a business calculation, the steps are:
345 year/month fields added
347 week field added
348 day field added
349 hour/minute/second fields added
350 After each step, a valid date must be present, or it will be adjusted
352 before proceeding to the next step. Note however that for business
353 calculations, the first step must produce a valid date, but not
354 necessarily a business date. The second step will produce a valid
355 business date.
356 A series of examples will illustrate this.
358 A date and non-business approximate delta
360 date = Mar 31 2001 at 12:00:00
361 delta = 1 year, 1 month, 1 day, 1 hour
362 First, the year/month fields are added without modifying any other
364 field. This would produce:
365 Apr 31, 2002 at 12:00
367 which is not valid. Any time the year/month fields produce a day
369 past the end of the month, the result is 'truncated' to the last
370 day of the month, so this produces:
371 Apr 30, 2002 at 12:00
373 Next the week/day fields are added producing:
375 May 1, 2002 at 12:00
377 and finally, the exact fields (hour/minute/second) are added to
379 produce:
380 May 1, 2002 at 13:00
382 A simple business calculation
384 Assuming a normal Monday-Friday work week from 8:00 - 17:00:
385 date = Wed, Nov 23, 2011 at 12:00
387 delta = 1 week, 1 day, 1 hour
388 First, the week field is added:
390 Wed, Nov 30, 2011 at 12:00
392 Then the day field is added:
394 Thu, Dec 1, 2011 at 12:00
396 Then the exact fields are added:
398 Thu, Dec 1, 2011 at 13:00
400 A business example where a holiday impacts it
402 In America, Jul 4 is a holiday, so Mon, Jul 4, 2011 is not a work
403 day.
404 date = Mon, Jun 27, 2011 at 12:00
406 delta = 1 week, 1 day, 1 hour
407 First, the week field is added:
409 Mon, Jul 4, 2011 at 12:00
411 Since that is not a work day, it immediately becomes:
413 Tue, Jul 5, 2011 at 8:00
415 Then the day field is added:
417 Wed, Jul 6, 2011 at 8:00
419 and finally the remaining fields:
421 Wed, Jul 6, 2011 at 9:00
423 Calculation where daylight savings time impacts it (fall example)
425 In the America/New_York timezone (Eastern time), on November 6,
426 2011, the following time change occurred:
427 2011-11-06 02:00 EDT => 2011-11-06 01:00 EST
429 Three simple calculations illustrate how this is handled:
431 date = 2011-11-05 02:30 EDT
433 delta = 1 day
434 Adding the day produces:
436 2011-11-06 02:30 EDT
438 which is valid, so that is the result.
440 Similarly:
442 date = 2011-11-07 02:30 EST
444 delta = -1 day
445 produces:
447 2011-11-06 02:30 EST
449 which is valid.
451 Finally:
453 date = 2011-11-05 02:30 EDT
455 delta = 2 days
456 produces:
458 2011-11-07 02:30 EST
460 The calculation will preserve the savings time where possible so
462 the resulting day will have the same offset from UTC. If that is
463 not possible, but the resulting day is valid in the other offset,
464 that will be used instead.
465 Calculation where daylight savings time impacts it (spring example)
467 In the America/New_York timezone (Eastern time), on March 13, the
468 following time change occurred:
469 2011-03-13 02:00 EST => 2011-03-13 03:00 EDT
471 In this case, a calculation may produce an invalid date.
473 date = 2011-03-12 02:30 EST
475 delta = 1 day
476 produces:
478 2011-03-13 02:30 EST
480 This is not valid. Neither is:
482 2011-03-13 02:30 EDT
484 In this case, the calculation will be redone converting days to
486 24-hour periods, so the calculation becomes:
487 date = 2011-03-12 02:30 EST
489 delta = 24 hours
490 which will produce a valid date:
492 2011-03-13 03:30 EDT
494
496 When calculating the delta between two dates, the delta may take
497 different forms depending on the mode passed in. An exact calculation
498 will produce a delta which included only exact fields. A semi-exact
499 calculation may produce a semi-exact delta, and an approximate
500 calculation may produce an approximate delta. Note that if the two
501 dates are close enough together, an exact delta will be produced (even
502 if the mode is semi-exact or approximate), or it may produce a semi-
503 exact delta in approximate mode.
504 For example, the two dates "Mar 12 1995 12:00" and "Apr 13 1995 12:00"
506 would have an exact delta of "744 hours", and a semi-exact delta of "31
507 days". It would have an approximate delta of "1 month 1 day".
508 Two dates, "Mar 31 12:00" and "Apr 30 12:00" would have deltas "720
510 hours" (exact), "30 days" (semi-exact) or "1 month" (approximate).
511 Approximate mode is a more human way of looking at things (you'd say 1
513 month and 2 days more often then 33 days), but it is less meaningful in
514 terms of absolute time.
515 One thing to remember is that an exact delta is exactly the amount of
517 time that has passed, including all effects of daylight saving time.
518 Semi-exact and approximate deltas usually ignore the affects of
519 daylight saving time.
520
522 In exact calculations, and in delta-delta calculations, the the
523 $subtract argument is easy to understand. When working with an
524 approximate delta however (either when adding an approximate delta to a
525 date, or when taking two dates to get an approximate delta), there is a
526 degree of uncertainty in how the calculation is done, and the $subtract
527 argument is used to specify exactly how the approximate delta is to be
528 use. An example illustrates this quite well.
529 If you take the date Jan 4, 2000 and subtract a delta of "1 month 1
531 week" from it, you end up with Nov 27, 1999 (Jan 4, 2000 minus 1 month
532 is Dec 4, 1999; minus 1 week is Nov 27, 1999). But Nov 27, 1999 plus a
533 delta of "1 month 1 week" is Jan 3, 2000 (Nov 27, 1999 plus 1 month is
534 Dec 27, 1999; plus 1 week is Jan 3, 2000).
535 In other words the approximate delta (but NOT the exact delta) is
537 different depending on whether you move from earlier date to the later
538 date, or vice versa. And depending on what you are calculating, both
539 are useful.
540 In order to resolve this, the $subtract argument can take on the values
542 0, 1, or 2, and have the meanings described next.
543 $subtract in approximate date-date calculations
545 In the call:
546 $delta = $date1->calc($date2,$subtract,"approx");
548 if $subtract is 0, the resulting delta can be added to $date1 to
550 get $date2. Obviously $delta may still be negative (if $date2 comes
551 before $date1).
552 If $subtract is 1, the resulting delta can be subtracted from
554 $date1 to get $date2 (the deltas from these two are identical
555 except for having an opposite sign).
556 If $subtract is 2, the resulting delta can be added to $date2 to
558 get $date1. In other words, the following are identical:
559 $delta = $date1->calc($date2,2,"approx");
561 $delta = $date2->calc($date1,"approx");
562 $subtract in approximate date-delta calculations
564 In the call:
565 $date2 = $date1->calc($delta,$subtract);
567 If $subtract is 0, the resulting date is determined by adding
569 $delta to $date1.
570 If $subtract is 1, the resulting date is determined by subtracting
572 $delta from $date1.
573 If $subtract is 2, the resulting date is the date which $delta can
575 be added to to get $date1.
576 For business mode calculations, $date1 will first be adjusted to be
578 a valid work day (if it isn't already), so this may lead to non-
579 intuitive results.
580 In some cases, it is impossible to do a calculation with $subtract
582 = 2. As an example, if the date is "Dec 31" and the delta is "1
583 month", there is no date which you can add "1 month" to to get "Dec
584 31". When this occurs, the date returned has an error flag.
585
587 There are two different ways to look at the approximate delta between
588 two dates.
589 In Date::Manip 5.xx, the approximate delta between the two dates:
591 Jan 10 1996 noon
593 Jan 7 1998 noon
594 was 1:11:4:0:0:0:0 (or 1 year, 11 months, 4 weeks). In calculating
596 this, the first date was adjusted as far as it could go towards the
597 second date without going past it with each unit starting with the
598 years and ending with the seconds.
599 This gave a strictly positive or negative delta, but it isn't actually
601 how most people would think of the delta.
602 As of Date::Manip 6.0, the delta is 2:0:0:-3:0:0:0 (or 2 years minus 3
604 days). Although this leads to mixed-sign deltas, it is actually how
605 more people would think about the delta. It has the additional
606 advantage of being easier to calculate.
607 For non-business mode calculations, the year/month part of the
609 approximate delta will move a date from the year/month of the first
610 date into the year/month of the second date. The remainder of the delta
611 will adjust the days/hours/minutes/seconds as appropriate.
612 For approximate business mode calculations, the year, date, and week
614 parts will be done approximately, and the remainder will be done
615 exactly.
616
618 None known.
619
621 Please refer to the Date::Manip::Problems documentation for information
622 on submitting bug reports or questions to the author.
623
625 Date::Manip - main module documentation
626
628 This script is free software; you can redistribute it and/or modify it
629 under the same terms as Perl itself.
630
632 Sullivan Beck (sbeck@cpan.org)
633perl v5.16.3 2014-06-09 Date::Manip::Calc(3)