1Date::Manip::Delta(3) User Contributed Perl DocumentationDate::Manip::Delta(3)
2
6 Date::Manip::Delta - Methods for working with deltas
7
9 use Date::Manip::Delta;
10 $date = new Date::Manip::Delta;
11
13 This module contains functions useful in parsing and manipulating
14 deltas. As used in this module, a delta refers only to the amount of
15 time elapsed. It includes no information about a starting or ending
16 time.
17 There are several concepts involved in understanding the properties of
19 a delta.
20 standard and business delta
22 Deltas can refer to changes in either the full calendar (standard
23 deltas), or they can refer to a business calendar.
24 With a business delta, non-business days are ignored. Typically,
26 this includes holidays and weekends. In addition, the part of the
27 day outside of business hours is also ignored, so a day may only
28 run from 08:00 to 17:00 and everything outside of this is ignored.
29 The length of a work day is usually not 24 hours. It is defined by
31 the start and end of the work day and is set using the config
32 variables: WorkDayBeg and WorkDayEnd (WorkDay24Hr may be used to
33 specify a 24-hour work day). The work week is defined using the
34 config variables: WorkWeekBeg and WorkWeekEnd.
35 Daylight saving time will have no impact on business calculations
37 because time changes occur at night (usually on the weekends)
38 outside of business hours. As such, they are ignored in business
39 calculations.
40 fields
42 A delta consists of 7 fields: years, months, weeks, days, hours,
43 minutes, and seconds, usually expressed as a colon-separated
44 string. For example:
45 1:2:3:4:5:6:7
47 refers to an elapsed amount of time 1 year, 2 months, 3 weeks, 4
49 days, 5 hours, 6 minutes, and 7 seconds long.
50 normalized
52 A delta can be normalized or not. A normalized delta has values
53 which have been made consistent with the type of data they
54 represent. For example, a delta of:
55 0:0:0:0:0:10:70
57 is not normalized since 70 seconds is better expressed as 1 minute
59 10 seconds. The normalized form of this delta would be:
60 0:0:0:0:0:11:10
62 By default, deltas are converted to a normalized form in most
64 functions that create/modify a delta, but this can be overridden.
65 sets of fields
67 When normalizing a delta, fields are grouped together in sets where
68 the exact relationship is known between all fields in the set.
69 For example, there is an exactly known relationship between seconds
71 and minutes (Date::Manip ignores leap seconds, so there are always
72 60 seconds in a minute), so they will be in one set.
73 Likewise, the relationship between years and months is known, so
75 they will be in one set. There is no known relationship between
76 months and weeks though, so they will be in separate sets.
77 A standard (i.e. non-business) delta contains 3 sets of fields:
79 approximate: year, month
81 semi-exact: week, day
82 exact: hour, minute, second
83 The following known relationships exist:
85 1 year = 12 months
87 1 week = 7 days
88 1 hour = 60 minutes
89 1 minute = 60 seconds
90 The following semi-approximate relationships are used to link the
92 semi-exact and exact fields when required:
93 1 day = 24 hours
95 The following approximate relationship is used to link the
97 approximate fields to the semi-exact fields when required:
98 1 year = 365.2425
100 Business deltas differ slightly, Since daylight saving times
102 effects are ignored, the length of the work day is constant, but
103 due to there being holidays, the length of a week is not known, so
104 a business delta has the following sets of fields:
105 approximate: year, month
107 semi-exact: week
108 exact: day, hour, minute, second
109 and the relationships used are:
111 1 year = 12 months
113 1 day = length of business day
114 1 hour = 60 minutes
115 1 minute = 60 seconds
116 The semi-approximate relationship may be used to link the semi-
118 approximate and exact fields together:
119 1 week = X (length of business week in days)
121 and the following approximate relationship may be used:
123 1 year = X/7 * 365.2425
125 When normalizing a delta, no data from one set will ever be mixed
127 with data from another set.
128 As a result, the following delta is normalized:
130 0:3:8:0:0:0:0
132 Although 8 weeks is clearly more than 1 month, we don't know the
134 relationship between the two, so they don't mix.
135 exact, semi-exact, and approximate deltas
137 An exact delta is one which every value is of an exactly known
138 length (i.e. it only includes the exact fields listed above).
139 A semi-exact delta is a delta which includes the exact fields as
141 well as semi-exact ones.
142 An approximate delta can include any of the fields.
144 So, the delta:
146 0:3:8:0:0:0:0
148 is approximate. The delta:
150 0:0:0:0:30:0:0
152 is exact. The delta:
154 0:0:0:1:30:0:0
156 is semi-exact (if it is non-business) or exact (if it is business).
158 The term "semi-exact" needs a little explanation. Date::Manip
160 tries to do things in a way which humans think of them. It is
161 immediately recognized that the approximate fields are of
162 completely unknown length, and the exact fields are of known
163 length. The "semi-exact" fields are termed such since humans have a
164 way of looking at them which is consistent, even if it is not
165 exact.
166 For example, a day is thought of as the same wall clock time on two
168 successive days, so from noon on one day to noon the next day is
169 one day. Usually that is 24 hours (for standard deltas), but if
170 you cross a daylight saving time change, it might be 23 or 25 hours
171 (or something different if a very irregular time change occurs).
172 So where possible, in a standard delta, a day field will change the
173 date, but leave the time alone.
174 Likewise, a business week is thought of as 7 days (i.e. Wednesday
176 to Wednesday) regardless of whether there was a holiday in there.
177 signs
179 Each field has a sign associated with it. For example, the delta "1
180 year ago" is written as:
181 -1:0:0:0:0:0:0
183 The sign of any field is optional, and if omitted, it is the same
185 as the next higher field. So, the following are identical:
186 +1:2:3:4:5:6:7
188 +1:+2:+3:+4:+5:+6:+7
189 Since there is no mixing of data between sets of fields, you can
191 end up with a delta with as many as four signs. So, the following
192 is a fully normalized business delta:
193 +1:0:-3:+3:1:0:0
195 fractional values
197 Fractional fields are allowed such as:
198 1.25 days
200 1.1 years
201 When parsing a delta with fractional fields, the delta will ALWAY
203 be normalized using the exact, semi-exact, and approximate
204 relationships described above.
205 For example, for a non-business delta, a delta of 1.1 years will
207 use the following relationships:
208 1 year = 365.2425 days
210 1 year = 12 months
211 1 day = 24 hours
212 Since the delta includes approximate fields, as much of the 1.1
214 year portion of the delta will be stored in the approximate fields
215 as possible.
216 Using the above approximate relationships, we can see that:
218 1 month = 365.2425/12 days = 30.436875 days
220 so
222 1.1 years
224 = 1 year, 1.2 months
225 = 1 year, 1 month, 6.087375 days
226 = 1 year, 1 month, 6 days, 2 hours, 5 minutes, 49 seconds
227 Fractional seconds will be discarded (no rounding).
229
231 new
232 new_config
233 new_date
234 new_delta
235 new_recur
236 base
237 tz
238 is_date
239 is_delta
240 is_recur
241 config
242 err Please refer to the Date::Manip::Obj documentation for these
243 methods.
244 parse
246 $err = $delta->parse($string [,$business] [,$no_normalize]);
247 This takes a string and parses it to see if it is a valid delta. If
249 it is, an error code of 0 is returned and $delta now contains the
250 value of the delta. Otherwise, an error code of 1 is returned and
251 an error condition is set in the delta.
252 A valid delta is in one of two forms: compact or expanded.
254 The compact format is a colon separated list of numbers (with
256 optional signs):
257 Examples:
259 0:0:0:0:4:3:-2
260 +4:3:-2
261 +4::3
262 In the compact format, from 1 to 7 of the fields may be given. For
264 example D:H:MN:S may be given to specify only four of the fields.
265 No spaces may be present in the compact format. It is allowed to
266 omit some of the fields. For example 5::3:30 is valid. In this
267 case, missing fields default to the value 0.
268 The expanded format has the fields spelled out in some language
270 specific form:
271 Examples:
273 +4 hours +3mn -2second
274 + 4 hr 3 minutes -2
275 4 hour + 3 min -2 s
276 4 hr 2 s
277 A field in the expanded format has an optional sign, a number, and
279 a string specifying the type of field. If the sign is absent, it
280 defaults to the sign of the next larger element. So the following
281 are equivalent:
282 -4 hr 3 min 2 sec
284 -4 hr -3 min -2 sec
285 The valid strings (in English) specifying the field type are:
287 y: y, yr, year, years
289 m: m, mon, month, months
290 w: w, wk, ws, wks, week, weeks
291 d: d, day, days
292 h: h, hr, hour, hours
293 mn: mn, min, minute, minutes
294 s: s, sec, second, seconds
295 Other languages have similar abbreviations.
297 The "seconds" string may be omitted. The sign, number, and string
299 may all be separated from each other by any amount of whitespace.
300 The string specifying the unit must be separated from a following
301 number by whitespace or a comma, so the following example will NOT
302 work:
303 4hours3minutes
305 At minimum, it must be expressed as:
307 4hours 3minutes
309 4 hours, 3 minutes
310 In the the expanded format, all fields must be given in the order:
312 Y M W D H MN S. Any number of them may be omitted provided the
313 rest remain in the correct order. Numbers may be spelled out, so
314 in two weeks
316 in 2 weeks
317 both work.
319 Most languages also allow a word to specify whether the delta is an
321 amount of time after or before a fixed point. In English, the word
322 "in" refers to a time after a fixed point, and "ago" refers to a
323 point before a fixed point. So, the following deltas are
324 equivalent:
325 1:0:0:0:0:0:0
327 in 1 year
328 and the following are equivalent
330 -1:0:0:0:0:0:0
332 1 year ago
333 The word "in" is completely ignored. The word "ago" has the affect
335 of reversing all signs that appear in front of the components of
336 the delta. In other words, the following two strings are
337 identical:
338 -12 yr 6 mon ago
340 +12 yr +6 mon
341 (don't forget that there is an implied minus sign in front of the 6
343 in the first string because when no sign is explicitly given, it
344 carries the previously entered sign).
345 The in/ago words only apply to the expanded format, so the
347 following is invalid:
348 1:0:0 ago
350 A delta may be standard (non-business) or business. By default, a
352 delta is treated as a non-business delta, but this can be changed
353 in two different ways.
354 The first way to make a delta be business is to pass in the 2nd
356 argument to the function. The $business argument may be a string
357 'standard' or 'business' to explicitly set the type of delta.
358 Alternately, any non-zero value for $business will force the delta
359 to be a business delta.
360 So the following are identical:
362 $delta->parse($string,'business');
364 $delta->parse($string,1);
365 and the following are identical:
367 $delta->parse($string);
369 $delta->parse($string,'standard');
370 $delta->parse($string,0);
371 The second way to specify whether a delta is business or non-
373 business is to include a key word in the string that is parsed.
374 When this is done, these strings override any value of the
375 $business argument.
376 Most languages include a word like "business" which can be used to
378 specify that the resulting delta is a business delta or a non-
379 business delta. Other languages have equivalent words. The
380 placement of the word is not important. Also, the "business" word
381 can be included with both types of deltas, so the following are
382 valid and equivalent:
383 in 4 hours business
385 4:0:0 business
386 business 0:0:0:0:4:0:0
387 There are also words "exact" or "approximate" which may be included
389 in the delta for backward compatibility. However, they will be
390 ignored. The accuracy of delta (exact, semi-exact, approximate)
391 will be determined only by what fields are present in the delta.
392 When a delta is parsed, it is automatically normalized, unless the
394 $no_normalize argument is passed in. It can be the string
395 'nonormalize' or any non-zero value. If passing it as a non-zero
396 value, the $business argument MUST be included (though it can be
397 zero) in order to avoid ambiguity.
398 So the following are equivalent:
400 $delta->parse($string,'nonormalize');
402 $delta->parse($string,$business,1);
403 input
405 $str = $delta->input();
406 This returns the string that was parsed to form the delta.
408 set
410 $err = $delta->set($field,$val [,$no_normalize]);
411 This explicitly sets one or more fields in a delta.
413 $field can be any of the following:
415 $field $val
417 delta [Y,M,W,D,H,MN,S] sets the entire delta
419 business [Y,M,W,D,H,MN,S] sets the entire delta
420 standard [Y,M,W,D,H,MN,S] sets the entire delta
421 y YEAR sets one field
422 M MONTH
423 w WEEK
424 d DAY
425 h HOUR
426 m MINUTE
427 s SECOND
428 mode business, standard
430 An error is returned if an invalid value is passed in.
432 When setting the entire delta with "business" or "normal", it flags
434 the delta as a business or non-business delta respectively. When
435 setting the entire delta with "delta", the flag is left unchanged.
436 Also, when setting the entire delta, signs are not carried from one
437 field to another.
438 By default, a delta is normalized, but passing $no_normalize as any
440 true value, this will not be done.
441 If $no_normalize is not passed in, the current value for the delta
443 (which defaults to 0) will be used.
444 For backwards compatibility, 'normal' can be used in place of
446 'standard', both as $field or as $val.
447 printf
449 $out = $delta->printf($in);
450 @out = $delta->printf(@in);
451 This takes a string or list of strings which may contain any number
453 of special formatting directives. These directives are replaced
454 with information contained in the delta. Everything else in the
455 string is returned unmodified.
456 A directive always begins with '%'. They are described in the
458 section below in the section PRINTF DIRECTIVES.
459 calc
461 $date2 = $delta->calc($date1 [,$subtract]);
462 $delta3 = $delta1->calc($delta2 [,$subtract]);
463 Please refer to the Date::Manip::Calc documentation for details.
465 type
467 $flag = $delta->type($op);
468 This tests to see if a delta is of a certain type. $op can be;
470 business : returns 1 if it is a business delta
472 standard : returns 1 if it is a standard (non-business delta)
473 exact : returns 1 if it is exact
475 semi : returns 1 if it is semi-exact
476 approx : returns 1 if it is approximate
477 value
479 $val = $delta->value();
480 @val = $delta->value();
481 This returns the value of the delta. In scalar context, it returns
483 the printable string (equivalent to the printf directive '%Dt'). In
484 list context, it returns a list of fields.
485 undef is returned if there is no valid delta stored in $delta.
487 convert
489 $delta->convert($to);
490 This converts a delta from one type to another. $to can be
492 'exact', 'semi', or 'approx'. The conversion uses the approximate
493 relationships listed above to convert the delta.
494 For example, if the exact non-business delta $delta contains:
496 0:0:0:0:44:0:0
498 then the following call:
500 $delta->convert('semi')
502 would produce the semi-exact delta:
504 0:0:0:1:20:0:0
506 The result will always be normalized, and will be strictly positive
508 or negative (i.e. all fields will have the same sign).
509 This function can be used to take an exact delta and turn it into a
511 semi-exact delta (with a day being treated as 24 hours in non-
512 business mode).
513 There is currently no support for converting business to non-
515 business (or vice-versa).
516 cmp
518 $flag = $delta1->cmp($delta2);
519 This compares two deltas (using the approximate relationships
521 listed above) and returns -1, 0, or 1 which could be used to sort
522 them by length of time.
523 Both deltas must be valid, and both must be either business or non-
525 business deltas. They do not need to be the same out of exact,
526 semi-exact, and approximate.
527 undef will be returned if either delta is invalid, or you try to
529 compare a business and non-business delta.
530
532 The following printf directives are replaced with information from the
533 delta. Directives may be replaced by the values of a single field in
534 the delta (i.e. the hours or weeks field), the value of several fields
535 expressed in terms of one of them (i.e. the number of years and months
536 expressed in terms of months), or the directive may format either the
537 entire delta, or portions of it.
538 Simple directives
540 These are directives which print simple characters. Currently, the
541 only one is:
542 %% Replaced by a single '%'
544 As an example:
546 $delta->printf('|%%|');
548 => |%|
549 Directives to print out a single field
551 The following directive is used to print out the value of a single
552 field. Spaces are included here for clarity, but are not in the
553 actual directive.
554 % [+] [pad] [width] Xv
556 Here, X is one of (y,M,w,d,h,m,s). The directive will print out the
558 value for that field (in the normalized delta).
559 If a '+' is included immediately after the '%', a sign will always
561 be included. By default, only negative values will include a sign.
562 'width' is any positive integer (without a sign). If 'width' is
564 included, it sets the length of the output string (unless the
565 string is already longer than that, in which case the 'width' is
566 ignored).
567 If 'pad' is included, it may be the character '<', '>', or '0'. It
569 will be ignored unless 'width' is included. If the formatted delta
570 field is shorter than 'width', it will be padded with spaces on the
571 left (if 'pad' is '<'), or right (if 'pad' is '>'), or it will be
572 padded on the left (after any sign) with zeroes (if 'pad' is '0').
573 In the following examples, $delta contains the delta: 1:2:3:4:5:6:7
575 $delta->printf('|Month: %Mv|');
577 => |Month: 2|
578 $delta->printf('|Day: %+05dv|');
580 => |Day: +0004|
581 $delta->printf('|Day: %+<5dv|');
583 => |Day: +4|
584 $delta->printf('|Day: %>5sv|');
586 => |Day: 7 |
587 Directives to print out several fields in terms of one of them
589 The following directive is used to print out the value of several
590 different fields, expressed in terms of a single field.
591 % [+] [pad] [width] [.precision] XYZ
593 Here, X, Y, and Z are each one of (y,M,w,d,h,m,s). The directive
595 will print out the value for fields Y through Z expressed in terms
596 of field X.
597 Y must come before Z in the sequence (y,M,w,d,h,m,s) or it can be
599 the same as Z.
600 So, to print the day and hour fields in terms of seconds, use the
602 directive:
603 %sdh
605 Any time all of X, Y, and Z are from a single set of fields, exact
607 relationships are used.
608 If the X, Y, and Z fields do not all belong to the same set of
610 fields, approximate relationships are used.
611 For non-business deltas, an approximate relationship is needed to
613 link the Y/M part of the delta to the W/D part and a semi-
614 approximate relationship is needed to link the W/D part with the
615 H/MN/S part. These relationships are:
616 1 day = 24 hours
618 1 year = 365.2425
619 For business deltas, the approximate and semi-approximate
621 relationships used to link the fields together are:
622 1 week = X (length of business week in days)
624 1 year = X/7 * 365.2425
625 For business deltas, the length of the day is defined using
627 WorkDayStart and WorkDayEnd. For non-business deltas, a day is 24
628 hours long (i.e. daylight saving time is ignored).
629 If 'precision' is included, it is the number of decimal places to
631 print. If it is not included, but 'width' is included, precision
632 will be set automatically to display the maximum number of decimal
633 places given 'width'.
634 If 'pad' is included, it may be the character '<', '>', or '0', and
636 is used in the same way as printing out a single field.
637 In the following examples, $delta contains the delta: 1:2:3:4:5:6:7
639 $delta->printf('|%.4Myw|');
641 => |14.6900|
642 1 year, 2 months, 3 weeks is approximately
643 14.6900 months
644 Directives to print out portions of the delta
646 The following directives may be used to print out some or all of a
647 delta.
648 % [+] [pad] [width] Dt
650 % [+] [pad] [width] DXY
651 The first directive will print out the entire delta.
653 The second will print out the delta from the X to Y fields
655 inclusive (where X and Y are each one of (y,M,w,d,h,m,s) and X must
656 come before Y in the sequence).
657 'pad' is optional and can be either '<' or '>' meaning to pad on
659 the left or right with spaces. It defaults to '<'.
660 If a '+' is included immediately following the '%', every field
662 will have a sign attached. Otherwise, only the leftmost field in
663 each set of fields will include a sign.
664 $delta->printf('|%Dt|');
666 => |+1:2:+3:+4:5:6:7|
667 $delta->printf('|%+Dyd|');
669 => |+1:+2:+3:+4|
670
672 None known.
673
675 Please refer to the Date::Manip::Problems documentation for information
676 on submitting bug reports or questions to the author.
677
679 Date::Manip - main module documentation
680
682 This script is free software; you can redistribute it and/or modify it
683 under the same terms as Perl itself.
684
686 Sullivan Beck (sbeck@cpan.org)
687perl v5.16.3 2014-06-09 Date::Manip::Delta(3)