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]);
15 $date2 = $delta->calc($date1 [,$subtract]);
16 $delta3 = $delta1->calc($delta2 [,$subtract]);
17
19 This document describes date calculations. Date calculations involve
20 two types of Date::Manip objects: dates and deltas. These are described
21 in the Date::Manip::Date and Date::Manip::Delta manuals respectively.
22 Two objects (two dates, two deltas, or one of each) are used. In all
24 cases, if a second object is not passed in, undef is returned.
25 There are 3 types of date calculations:
27 Date-Date calculations
29 $delta = $date->calc($date2 [,$subtract] [,$mode]);
30 Two dates can be worked with and a delta will be produced which is
32 the amount of time between the two dates.
33 $date1 and $date2 are Date::Manip::Date objects with valid dates.
35 The Date::Manip::Delta object returned is the amount of time
36 between them. If $subtract is not passed in (or is 0), the delta
37 produced is:
38 DELTA = DATE2 - DATE1
40 If $subtract is non-zero, the delta produced is:
42 DELTA = DATE1 - DATE2
44 The $subtract argument has special importance when doing
46 approximate calculations, and this is described below.
47 If either date is invalid, a delta object will be returned which
49 has an error associated with it.
50 The $mode argument describes the type of calculation and is
52 described below.
53 Date-Delta calculations
55 Date-delta calculations can be performed using either a
56 Date::Manip::Date or Date::Manip::Delta object as the primary
57 object:
58 $date2 = $date1->calc($delta [,$subtract]);
60 $date2 = $delta->calc($date1 [,$subtract]);
61 A date and delta can be worked with to yield a date that is the
63 given amount of time before or after it.
64 $date1 and $delta are valid Date::Manip::Date and
66 Date::Manip::Delta objects respectively. A new Date::Manip::Date
67 object is produced.
68 Both of the calls above perform the same function and produce
70 exactly the same results.
71 If $subtract is not passed in, or is 0, the resulting date is
73 formed as:
74 DATE2 = DATE1 + DELTA
76 If $subtract is non-zero, the resulting date is:
78 DATE2 = DATE1 - DELTA
80 The $subtract argument has special importance when doing
82 approximate calculations, and this is described below.
83 Delta-Delta calculations
85 Delta-delta calculations can be performed to add two amounts of
86 time together, or subtract them.
87 $delta3 = $delta1->calc($delta2 [,$subtract]);
89 If $subtract is not passed in, or is 0, the resulting delta formed
91 is:
92 DELTA3 = DELTA1 + DELTA2
94 If $subtract is non-zero, then the resulting delta is:
96 DELTA3 = DELTA1 - DELTA2
98 $delta1 and $delta2 are valid Date::Manip::Delta objects, and a new
100 Date::Manip::Delta object is produced.
101 Date calculations handle the time zones properly. When calculating the
103 difference between two dates in different time zones, they will first
104 be converted to a common time zone. Also, when adding a delta to a
105 date, the resulting date will be in the same time zone as the original
106 date.
107 If either of the objects are invalid, the error condition is set in the
109 object for which the method is called, and undef is returned instead of
110 a new object.
111 For example, if the following is called:
113 $date2 = $date1->calc($delta);
115 and $delta does not include a valid delta, then $date1 will have an
117 error condition set and $date2 will be undef.
118
120 Date::Manip calculations can be divide into two different types:
121 business and non-business. Within those types are two sub categories:
122 exact and approximate. These are described here.
123 Business and non-business calculations
125 A business mode calculation is one where the length of the day is
126 determined by the length of the work day, and only business days
127 (i.e. days in which business is conducted) count. Holidays and
128 weekends are omitted. This is described in more detail below.
129 A non-business mode calculation is the normal type of calculation
131 where no days are ignored, and all days are full length.
132 Exact and approximate calculations
134 An exact calculation is one in which all deltas involved (either
135 the delta produced by adding two dates or deltas together, or a
136 delta that is added to a date to produce a second date) is an exact
137 delta. An exact delta is described in the Date::Manip::Delta
138 manual, but the short explanation is that an exact delta tells
139 exactly how much time passed between two dates. Since there is no
140 definite relationship between months and days, an exact delta will
141 only include values for the day/hour/minute/second fields (the week
142 field is also allowed in non-business mode calculations). The
143 inexact fields (year, month, and week in the case of business mode)
144 will be 0.
145 An approximate delta is one which includes years and months (i.e.
147 fields for which an exact length are not known in general) but
148 which are used for human convenience.
149 In date-delta and delta-delta calculations, the mode of the calculation
151 will be determined automatically. In the case of date-date
152 calculations, the mode is supplied as an argument.
153 Mode in date-date calculations
155 When doing a date-date calculation, the following call is used:
156 $delta = $date1->calc($date2 [,$subtract] [,$mode]);
158 $mode defaults to "exact". The delta produced will be be either a
160 business or non-business delta, exact or approximate, as specified
161 by $mode.
162 Currently, the four possible values that $mode can have are:
164 exact : an exact, non-business mode calculation
166 approx : an approximate, non-business mode calculation
167 business : an exact, business mode calculation
168 bapprox : an approximate, business mode calculation
169 NOTE: When doing a "business" or "bapprox" calculation, both dates
171 must be in the same time zone or an error is produced.
172 Mode in date-delta calculations
174 When doing calculations of a date and a delta:
175 $date2 = $date1->calc($delta [,$subtract]);
177 $date2 = $delta->calc($date1 [,$subtract]);
178 the mode is not passed in. It is determined exclusively by the
180 delta. If $delta is a business delta, A business mode calculation
181 is done. If $delta is a non-business delta, a non-business mode
182 calculation will be done. If $delta has a non-zero value for either
183 the year or month field, an approximate calculation will be done.
184 Otherwise, an exact calculation will be done.
185 Mode in delta-delta calculations
187 When doing calculations with two deltas:
188 $delta3 = $delta1->calc($delta2 [,$subtract]);
190 the mode is not passed in. It is determined by the two deltas.
192 If both deltas are business mode, or both are non-business mode, a
194 new delta will be produced of the same type.
195 It one of the deltas is a business mode and the other is not, the
197 resulting delta will have an error condition since there is no
198 direct correlation between the two types of deltas. Even though it
199 would be easy to add the two together, it would be impossible to
200 come up with a result that is meaningful.
201 If both deltas are exact, the resulting delta is also exact. If
203 either or both of the deltas is approximate, the resulting delta is
204 also approximate. It is NOT treated as an error if one of the
205 deltas is exact and one is approximate.
206
208 In order to correctly do business mode calculations, a config file
209 should exist which contains the section defining holidays (otherwise,
210 weekends will be ignored, but all other days will be counted as
211 business days). This is documented below, and in the
212 Date::Manip::Config section of the documentation. Some config
213 variables (namely WorkWeekBeg, WorkWeekEnd, WorkDayBeg, WorkDayEnd, and
214 WorkDay24Hr) defined the length of the work week and work day.
215 If the workday is defined as 08:00 to 18:00, a work week consisting of
217 Mon-Sat, and the standard (American) holidays, then from Tuesday at
218 12:00 to the following Monday at 14:00 is 5 days and 2 hours. If the
219 "end" of the day is reached in a calculation, it automatically switches
220 to the next day. So, Tuesday at 12:00 plus 6 hours is Wednesday at
221 08:00 (provided Wed is not a holiday). Also, a date that is not during
222 a workday automatically becomes the start of the next workday. So,
223 Sunday 12:00 and Monday at 03:00 both automatically becomes Monday at
224 08:00 (provided Monday is not a holiday).
225 Note that a business week is treated the same as an exact week (i.e.
227 from Tuesday to Tuesday, regardless of holidays). Because this means
228 that the relationship between days and weeks is NOT unambiguous, when
229 an exact delta is produced from two dates, it will be in terms of
230 d/h/mn/s (i.e. no week field).
231 Also note that daylight saving time effects are ignored in business
233 mode calculations.
234 Anyone using business mode is going to notice a few quirks about it
236 which should be explained. When I designed business mode, I had in
237 mind what a business which promises 1 business day turnaround really
238 means.
239 If you do a business calculation (with the workday set to 9:00-17:00),
241 you will get the following:
242 Saturday at noon + 1 business day = Tuesday at 9:00
244 Saturday at noon - 1 business day = Friday at 9:00
245 What does this mean?
247 As an example, say I use a business that works 9-5 and they have a drop
249 box so I can drop things off over the weekend and they promise 1
250 business day turnaround. If I drop something off Friday night,
251 Saturday, or Sunday, it doesn't matter. They're going to get started
252 on it Monday morning. It'll be 1 business day to finish the job, so
253 the earliest I can expect it to be done is around 17:00 Monday or 9:00
254 Tuesday morning. Unfortunately, there is some ambiguity as to what day
255 17:00 really falls on, similar to the ambiguity that occurs when you
256 ask what day midnight falls on. Although it's not the only answer,
257 Date::Manip treats midnight as the beginning of a day rather than the
258 end of one. In the same way, 17:00 is equivalent to 9:00 the next day
259 and any time the date calculations encounter 17:00, it automatically
260 switch to 9:00 the next day. Although this introduces some quirks, I
261 think this is justified. I also think that it is the way most people
262 think of it. If I drop something off first thing Monday morning, I
263 would expect to pick it up first thing Tuesday if there is 1 business
264 day turnaround.
265 Equivalently, if I want a job to be finished on Saturday (despite the
267 fact that I cannot pick it up since the business is closed), I have to
268 drop it off no later than Friday at 9:00. That gives them a full
269 business day to finish it off. Of course, I could just as easily drop
270 it off at 17:00 Thursday, or any time between then and 9:00 Friday.
271 Again, it's a matter of treating 17:00 as ambiguous.
272 So Saturday + 1 business day = Tuesday at 9:00 (which means anything
274 from Monday 17:00 to Tuesday 9:00), but Monday at 9:01 + 1 business day
275 = Tuesday at 9:01 which is unambiguous.
276
278 In many cases, it is somewhat ambiguous what amount of time a delta
279 actually refers to. Although it is ALWAYS known how many months in a
280 year, hours in a day, etc., it is NOT known (in the general case) how
281 many days are in a month. As a result, the part of the delta
282 containing month/year and the part with sec/min/hr/day must be treated
283 separately. For example, "Mar 31, 12:00:00" plus a delta of "1 month 2
284 days" would yield "May 2 12:00:00". The year/month is first handled
285 while keeping the same date. Mar 31 plus one month is Apr 31 (but
286 since Apr only has 30 days, it becomes Apr 30). Apr 30 + 2 days is May
287 2.
288 Likewise, when calculating the delta between two dates, the delta may
290 take two different forms. The exact form is to use only the days,
291 hours, minutes, and seconds (weeks are also included, except in
292 business calculations) and expressing the delta exactly. In approximate
293 mode, the other fields (years and months; weeks in the case of business
294 calculations) are used to produce a more human format.
295 For example, the two dates "Mar 12 1995" and "Apr 13 1995" would have
297 an exact delta of "31 days" but in the approximate mode, it would be
298 returned as "1 month 1 day". Also, "Mar 31" and "Apr 30" would have
299 deltas of "30 days" or "1 month" (since Apr 31 doesn't exist, it drops
300 down to Apr 30). Approximate mode is a more human way of looking at
301 things (you'd say 1 month and 2 days more often then 33 days), but it
302 is less meaningful in terms of absolute time.
303 One other difference is that an exact delta is exactly the amount of
305 time that has passed, including all effects of daylight savings time.
306 Approximate deltas ignore the affects of daylight savings time. So,
307 for example, the approximate time between Jan 1 00:00:00 and Jun 1
308 00:00:00 in America/New_York is 0:5:0:0:0:0:0, but is exactly
309 0:0:21:4:23:0:0 .
310
312 In exact calculations, and in delta-delta calculations, the the
313 $subtract argument is easy to understand. When working with an
314 approximate delta however (either when adding an approximate delta to a
315 date, or when taking two dates to get an approximate delta), there is a
316 degree of uncertainty in how the calculation is done, and the $subtract
317 argument is used to specify exactly how the approximate delta is to be
318 use. An example illustrates this quite well.
319 If you take the date Jan 4, 2000 and subtract a delta of "1 month 1
321 week" from it, you end up with Nov 27, 1999 (Jan 4, 2000 minus 1 month
322 is Dec 4, 1999; minus 1 week is Nov 27, 1999). But Nov 27, 1999 plus a
323 delta of "1 month 1 week" is Jan 3, 2000 (Nov 27, 1999 plus 1 month is
324 Dec 27, 1999; plus 1 week is Jan 3, 2000).
325 In other words the approximate delta (but NOT the exact delta) is
327 different depending on whether you move from earlier date to the later
328 date, or vice versa. And depending on what you are calculating, both
329 are useful.
330 In order to resolve this, the $subtract argument can take on the values
332 0, 1, or 2, and have the following meaning.
333 $subtract in approximate date-date calculations
335 In the call:
336 $delta = $date1->calc($date2,$subtract,"approx");
338 if $subtract is 0, the resulting delta can be added to $date1 to
340 get $date2. Obviously $delta may still be negative (if $date2 comes
341 before $date1).
342 If $subtract is 1, the resulting delta can be subtracted from
344 $date1 to get $date2 (the deltas from these two are identical
345 except for having an opposite sign).
346 If $subtract is 2, the resulting delta can be added to $date2 to
348 get $date1. In other words, the following are identical:
349 $delta = $date1->calc($date2,2,"approx");
351 $delta = $date2->calc($date1,"approx");
352 $subtract in approximate date-delta calculations
354 In the call:
355 $date2 = $date1->calc($delta,$subtract);
357 If $subtract is 0, the resulting date is determined by adding
359 $delta to $date1.
360 If $subtract is 1, the resulting date is determined by subtracting
362 $delta from $date1.
363 If $subtract is 2, the resulting date is the date which $delta can
365 be added to to get $date1. This is NOT available with business
366 calculations (for them, this is treated the same as $subtract=1).
367 With business calculations, the $subtract=2 argument is ambiguous.
369 For example, the date 1997-11-26 17:00:00 plus a delta of "business
370 1 month 1 day" gives a date of 1998-01-05 08:00, and the date
371 1997-11-28 17:00:00 plus the same delta also gives the value of
372 1998-01-05 08:00. Since there is no single date which the delta
373 could be added to to get $date1, this option cannot be implemented.
374
376 There are two different ways to look at the approximate delta between
377 two dates.
378 In Date::Manip 5.xx, the approximate delta between the two dates:
380 Jan 10 1996 noon
382 Jan 7 1998 noon
383 was +1:11:4:0:0:0:0 (or 1 year, 11 months, 4 weeks). In calculating
385 this, the first date was adjusted as far as it could go towards the
386 second date without going past it with each unit starting with the
387 years and ending with the seconds.
388 This gave a strictly positive or negative delta, but it isn't actually
390 how most people would think of the delta.
391 As of Date::Manip 6.0, the delta is +2:0:-0:3:0:0:0 (or 2 years minus 3
393 days). Although this leads to mixed-sign deltas, it is actually how
394 more people would think about the delta. It has the additional
395 advantage of being MUCH easier to calculate.
396 For non-business mode calculations, the year/month part of the
398 approximate delta will move a date from the year/month of the first
399 date into the year/month of the second date. The remainder of the delta
400 will adjust the days/hours/minutes/seconds as appropriate.
401 For approximate business mode calculations, the year and date will be
403 done approximately, and the remainder will be done exactly. There will
404 be no value for the weeks field in the delta produced.
405
407 None known.
408
410 Please refer to the Date::Manip::Problems documentation for information
411 on submitting bug reports or questions to the author.
412
414 Date::Manip - main module documentation
415
417 This script is free software; you can redistribute it and/or modify it
418 under the same terms as Perl itself.
419
421 Sullivan Beck (sbeck@cpan.org)
422perl v5.12.0 2010-04-27 Date::Manip::Calc(3)