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, the term delta refers to an 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 There are two different modes for working with deltas: standard and
23 business. The mode used depends on how you treat the calendar.
24 Standard deltas use the full calendar without any modifications.
26 A business delta uses a calendar in the way a business might. In a
28 business calendar, anything outside of a business day is ignored.
29 Typically, this includes holidays and weekends. In addition, the
30 part of the day outside of business hours is also ignored, so a day
31 may only run from 08:00 to 17:00 and everything outside of this is
32 ignored.
33 The length of a work day is usually not 24 hours. It is defined by
35 the start and end of the work day and is set using the config
36 variables: WorkDayBeg and WorkDayEnd (WorkDay24Hr may be used to
37 specify a 24-hour work day). The work week is defined using the
38 config variables: WorkWeekBeg and WorkWeekEnd.
39 Daylight saving time are ignored with business calculations because
41 time changes occur at night (usually on the weekends) outside of
42 business hours. This may yield unexpected results if the work day
43 is defined to be 24-hours and the work week includes a day when a
44 time change occurs.
45 fields
47 A delta consists of 7 fields: years, months, weeks, days, hours,
48 minutes, and seconds, usually expressed as a colon-separated
49 string. For example:
50 1:2:3:4:5:6:7
52 refers to an elapsed amount of time 1 year, 2 months, 3 weeks, 4
54 days, 5 hours, 6 minutes, and 7 seconds long.
55 normalized
57 A delta can be normalized or not. A normalized delta has values
58 which have been simplified based on how a human would think of
59 them. As an example, the delta:
60 0:0:0:0:0:10:70
62 is not normalized since 70 seconds is typically thought of as 1
64 minute 10 seconds. The normalized form of this delta would be:
65 0:0:0:0:0:11:10
67 By default, deltas are converted to a normalized form in most
69 functions that create/modify a delta, but this can be overridden.
70 Types of deltas
72 There are 4 type of deltas that are available.
73 Exact deltas
75 The most common type (and the default in most situations)
76 is an exact delta. An exact delta is one where only fields
77 which have exactly known lengths are allowed to be non-
78 zero.
79 For standard calculations, there are only three exactly
81 known fields (hours, minutes, and seconds). The lengths
82 are defined as:
83 1 hour = 3600 seconds
85 1 minute = 60 seconds
86 Note that since a day is NOT always 24 hours (due to
88 daylight saving time changes), a day is not an exactly
89 known field.
90 For business calculations, a day IS an exactly known field.
92 Since business mode ignores daylight saving time, the
93 length of the day can be calculated based on the config
94 variables listed above. So, for example, if the work day
95 is 08:00-17:00, the length of the day is 9 hours. The
96 length of the week is still unknown since some work weeks
97 may have fewer days than others due to holidays.
98 All fields which are not exactly known will always have
100 zero value.
101 Semi-exact deltas
103 A semi-exact delta treats the day/week fields as if they
104 were exactly known.
105 For standard calculations, this is done by using the
107 relationships:
108 1 day = 24 hours
110 1 week = 7 days
111 For business calculations, it is done by treating a week as
113 a constant length (determined by the config variables
114 listed above) ignoring holidays. So if a typical work week
115 is Mon-Fri, the length of the week is 5 days.
116 For semi-exact deltas, the value of the year/month must be
118 zero.
119 Although this may yield some values that are not exactly
121 accurate around daylight saving time transitions, strictly
122 speaking, they yield results that are useful in terms of
123 how humans think of deltas.
124 Approximate deltas
126 An approximate delta can have non-zero values for all
127 fields. When normalizing the fields, the year/month fields
128 are treated as one set using the relationship
129 1 year = 12 months
131 The remaining fields are normalized using the semi-exact
133 relationships.
134 Estimated deltas
136 The final type of delta are estimated deltas. These are
137 deltas where an estimated length is applied to all the
138 approximate fields.
139 For standard deltas, the additional relationship:
141 1 year = 365.2425 days
143 is used. For business deltas, the additional relationship:
145 1 year = X/7 * 365.2425 days
147 (where X is the number of work days in a week) is used.
149 Fractional seconds will be discarded (not rounded).
151 NOTE: it is not possible to look at a delta and determine what type
153 it is. For example, a standard delta with a non-zero day value
154 might be approximate or semi-exact. The type will need to be
155 explicitly selected, or determined by the context of the operation.
156 signs
158 Each field has a sign associated with it. For example, the delta "1
159 year ago" is written as:
160 -1:0:0:0:0:0:0
162 The sign of any field is optional, and if omitted, it is the same
164 as the next higher field. So, the following are identical:
165 +1:2:3:4:5:6:7
167 +1:+2:+3:+4:+5:+6:+7
168 In a normalized delta, all fields in a set will have the same sign.
170 So the standard delta:
171 0:0:+3:-2:0:0:0:0 (3 weeks -2 days)
173 is not normalized. The normalized version would be:
175 0:0:+2:5:0:0:0:0 (2 weeks, 5 days)
177 Since an approximate delta has two sets (the y/m set and the
179 w/d/h/mn/s set), these deltas may have two signs. So, the following
180 is a fully normalized approximate delta:
181 +1:0:-3:3:1:0:0
183 fractional values
185 Fractional fields are allowed such as:
186 1.25 days
188 1.1 years
189 but whenever parsing a delta with fractional fields, the delta will
191 be normalized using the estimated relationships described above.
192 Fractional seconds will be discarded.
193
195 new
196 new_config
197 new_date
198 new_delta
199 new_recur
200 base
201 tz
202 is_date
203 is_delta
204 is_recur
205 config
206 err Please refer to the Date::Manip::Obj documentation for these
207 methods.
208 parse
210 $err = $delta->parse($string, \%opts);
211 $err = $delta->parse($string [,$business] [,$no_normalize]);
212 The second format is supported for backward compatibility, but is
214 deprecated and will be removed in Date::Manip 7.00. The second
215 form is equivalent to:
216 $err = $delta->parse($string, { business => $business,
218 nonorm => $no_normalize });
219 This takes a string and parses it to see if it is a valid delta. If
221 it is, an error code of 0 is returned and $delta now contains the
222 value of the delta. Otherwise, an error code of 1 is returned and
223 an error condition is set in the delta.
224 Recognized options are:
226 mode : standard/business
228 to specify if it is a business delta or a standard delta
229 nonorm : 0/1
230 1 if the delta should not be normalized
231 type : exact, semi, approx, estimated
232 When specifying the type, the delta given must satisfy the
234 requirements of the type (i.e. no year field for an exact delta).
235 A delta string is usually specified in compact notation which
237 consists of a colon separated list of numbers (with optional
238 signs):
239 Examples:
241 0:0:0:0:4:3:-2
242 +4:3:-2
243 +4::3
244 In compact notation, from 1 to 7 of the fields may be given. For
246 example D:H:MN:S may be given to specify only four of the fields.
247 No spaces may be present in the string, but it is allowed to omit
248 some of the fields. For example 5::3:30 is valid. In this case,
249 missing fields default to the value 0.
250 The delta string may also be specified using common field
252 abbreviations. This is described below in the "ADDITIONAL DELTA
253 NOTATIONS" section.
254 input
256 $str = $delta->input();
257 This returns the string that was parsed to form the delta.
259 set
261 $err = $delta->set(\%opts);
262 $err = $delta->set($field,$val [,$no_normalize]);
263 The second format is supported for backward compatibility, but is
265 deprecated and will be removed in Date::Manip 7.00. The second
266 form is equivalent to:
267 $err = $delta->set( $field => $val, 'nonorm' => $no_normalize );
269 This explicitly sets one or more parts of a delta. %opts is a set
271 of key/value pairs:
272 $key $val
274 delta [Y,M,W,D,H,MN,S] sets the entire delta
276 business [Y,M,W,D,H,MN,S] sets the entire delta
277 standard [Y,M,W,D,H,MN,S] sets the entire delta
278 y YEAR sets one field
279 M MONTH
280 w WEEK
281 d DAY
282 h HOUR
283 m MINUTE
284 s SECOND
285 nonorm 0/1
287 mode business, standard
288 type exact, semi, estimated, approx
289 An error is returned if an invalid data is passed in.
291 %opts can only include a single key that affects each field (i.e.
293 you can set delta or business but not both, and you cannot set both
294 delta and y, but you CAN set both y and w).
295 When setting the entire delta with business or standard, it flags
297 the delta as a business or standard mode delta respectively. In
298 those cases, you are not allowed to set the mode option. Partial
299 deltas are allowed (i.e. [H,MN,S]) in which case zeros are added
300 for all fields not specified.
301 When setting the entire delta with delta, the flag is left
303 unchanged (unless the mode option is also passed in).
304 Also, when setting the entire delta, signs are not carried from one
306 field to another, so [-1,2,...] is equivalent to [-1,+2,...].
307 By default, a delta is normalized, but setting the nonorm key to a
309 true value will not do that.
310 For backwards compatibility, normal can be used in place of
312 standard, both as $field or as $val. This is deprecated and will
313 be removed in Date::Manip 7.00.
314 When setting any field in the delta, the type of delta will be
316 determined automatically as either exact (if only fields that are
317 exactly known are have non-zero fields), semi (if only fields that
318 are semi-exact or exact are included), or approx otherwise. If the
319 type option is set, it will be used provided it is valid (i.e. you
320 cannot set it to exact if fields that are not exactly known are
321 set).
322 printf
324 $out = $delta->printf($in);
325 @out = $delta->printf(@in);
326 This takes a string or list of strings which may contain any number
328 of special formatting directives. These directives are replaced
329 with information contained in the delta. Everything else in the
330 string is returned unmodified.
331 A directive always begins with '%'. They are described in the
333 section below in the section "PRINTF DIRECTIVES".
334 calc
336 Please refer to the Date::Manip::Calc documentation for details.
337 type
339 $flag = $delta->type($op);
340 This tests to see if a delta is of a certain type. $op can be;
342 business : returns 1 if it is a business delta
344 standard : returns 1 if it is a standard (non-business delta)
345 exact : returns 1 if it is exact
347 semi : returns 1 if it is semi-exact
348 approx : returns 1 if it is approximate
349 estimated : returns 1 if it is estimated
350 value
352 $val = $delta->value();
353 @val = $delta->value();
354 This returns the value of the delta. In scalar context, it returns
356 the printable string (equivalent to the printf directive '%Dt'). In
357 list context, it returns a list of fields.
358 An empty string/list is returned if there is no valid delta stored
360 in $delta.
361 convert
363 $delta->convert($to);
364 This converts a delta from one type to another. $to can be
366 'exact', 'semi', or 'approx'. The conversion uses the approximate
367 and estimated relationships listed above to convert the delta.
368 For example, if the exact non-business delta $delta contains:
370 0:0:0:0:44:0:0
372 then the following call:
374 $delta->convert('semi')
376 would produce the semi-exact delta:
378 0:0:0:1:20:0:0
380 The result will always be normalized.
382 Converting from one type to another that is less exact (i.e. exact
384 to semi-exact or semi-exact to approx) is supported. Converting
385 the other direction is supported for backward compatibility, but
386 will be removed in 7.00 because that operation is not one that is
387 well defined.
388 There is currently no support for converting business to non-
390 business (or vice-versa).
391 cmp
393 $flag = $delta1->cmp($delta2);
394 This compares two deltas (using the approximate relationships
396 listed above) and returns -1, 0, or 1 which could be used to sort
397 them by length of time.
398 Both deltas must be valid, and both must be either business or non-
400 business deltas. They do not need to be the same out of exact,
401 semi-exact, and approximate.
402 undef will be returned if either delta is invalid, or you try to
404 compare a business and non-business delta.
405
407 When parsing a delta, the string may be specified with the field
408 spelled out, rather than using the colon separated fields.
409 This expanded notation has the fields spelled out in some language
411 specific form:
412 Examples:
414 +4 hours +3mn -2second
415 + 4 hr 3 minutes -2
416 4 hour + 3 min -2 s
417 4 hr 2 s
418 A field in the expanded notation has an optional sign, a number, and a
420 string specifying the type of field. If the sign is absent, it
421 defaults to the sign of the next larger element. So the following are
422 equivalent:
423 -4 hr 3 min 2 sec
425 -4 hr -3 min -2 sec
426 The valid strings describing each of the fields is contained in "Delta
428 field names" section of the appropriate Date::Manip::Lang::<LANGUAGE>
429 document. Refer to the Date::Manip::Lang document for a list of
430 languages.
431 For example, for English, the document is Date::Manip::Lang::English
433 and the field names include strings like:
434 y: y, yr, year, years
436 m: m, mon, mons, month, months
437 w: w, wk, ws, wks, week, weeks
438 d: d, day, days
439 h: h, hr, hrs, hour, hours
440 mn: mn, min, mins, minute, minutes
441 s: s, sec, secs, second, seconds
442 This list may not be complete. You should refer to the language
444 document for the full list.
445 The "seconds" string may be omitted. The sign, number, and string may
447 all be separated from each other by any amount of whitespace. The
448 string specifying the unit must be separated from a following number by
449 whitespace or a comma, so the following example will NOT work:
450 4hours3minutes
452 At minimum, it must be expressed as:
454 4hours 3minutes
456 4 hours, 3 minutes
457 In the the expanded format, all fields must be given in the order: Y M
459 W D H MN S. Any number of them may be omitted provided the rest remain
460 in the correct order. Small numbers may be spelled out, so
461 in two weeks
463 in 2 weeks
464 both work (but do not rely on this to work for large numbers).
466 Most languages also allow a word to specify whether the delta is an
468 amount of time after or before a fixed point. In English, the word "in"
469 refers to a time after a fixed point, and "ago" refers to a point
470 before a fixed point. So, the following deltas are equivalent:
471 1:0:0:0:0:0:0
473 in 1 year
474 and the following are equivalent
476 -1:0:0:0:0:0:0
478 1 year ago
479 The word "in" is completely ignored. The word "ago" has the affect of
481 reversing all signs that appear in front of the components of the
482 delta. In other words, the following two strings are identical:
483 -12 yr 6 mon ago
485 +12 yr +6 mon
486 (don't forget that there is an implied minus sign in front of the 6 in
488 the first string because when no sign is explicitly given, it carries
489 the previously entered sign).
490 The in/ago words only apply to the expanded format, so the following is
492 invalid:
493 1:0:0 ago
495 A delta may be standard (non-business) or business. By default, a delta
497 is treated as a non-business delta, but this can be changed in two
498 different ways.
499 The first way to make a delta be business is to pass in the appropriate
501 option. For example:
502 $delta->parse($string, { 'mode' => 'business' });
504 $delta->parse($string, { 'mode' => 'standard' });
505 The second way to specify whether a delta is business or non-business
507 is to include a key word in the string that is parsed. If this string
508 is included, it should not conflict with the value of a 'mode' option.
509 Most languages include a word like "business" which can be used to
511 specify that the resulting delta is a business delta or a non-business
512 delta. Other languages have equivalent words. The placement of the word
513 is not important. Also, the "business" word can be included with all
514 types of deltas, and in both compact and expanded notation, so the
515 following are valid and equivalent:
516 in 4 hours business
518 4:0:0 business
519 business 0:0:0:0:4:0:0
520 There are also words "exact" or "approximate" which may be included in
522 the delta for backward compatibility. However, they will be ignored.
523 They will be removed in Date::Manip 7.00. The accuracy of delta
524 (exact, semi-exact, approximate) will be determined only by what fields
525 are present in the delta and the options passed in. When a delta is
526 parsed, it is automatically normalized, unless the 'nonorm' option is
527 passed in.
528
530 The following printf directives are replaced with information from the
531 delta. Directives may be replaced by the values of a single field in
532 the delta (i.e. the hours or weeks field), the value of several fields
533 expressed in terms of one of them (i.e. the number of years and months
534 expressed in terms of months), or the directive may format either the
535 entire delta, or portions of it.
536 Simple directives
538 These are directives which print simple characters. Currently, the
539 only one is:
540 %% Replaced by a single '%'
542 As an example:
544 $delta->printf('|%%|');
546 => |%|
547 Directives to print out a single field
549 The following directive is used to print out the value of a single
550 field. Spaces are included here for clarity, but are not in the
551 actual directive.
552 % [+] [pad] [width] Xv
554 Here, X is one of (y,M,w,d,h,m,s). The directive will print out the
556 value for that field.
557 If a '+' is included immediately after the '%', a sign will always
559 be included. By default, only negative values will include a sign.
560 'width' and 'pad' are used to set the width of the string
562 containing the field as well as how it is padded.
563 'width' is any positive integer (without a sign). If 'width' is
565 included, it sets the length of the output string (unless the
566 string is already longer than that, in which case the 'width' is
567 ignored).
568 If 'pad' is included, it may be the character '<', '>', or '0'. It
570 will be ignored if 'width' is not included, or the string is
571 already longer than 'width'. If the formatted delta field is
572 shorter than 'width', it will be padded with spaces on the left (if
573 'pad' is '<'), or right (if 'pad' is '>'), or it will be padded on
574 the left (after any sign) with zeroes (if 'pad' is '0').
575 In the following examples, $delta contains the delta: 1:2:3:4:5:6:7
577 $delta->printf('|Month: %Mv|');
579 => |Month: 2|
580 $delta->printf('|Day: %+05dv|');
582 => |Day: +0004|
583 $delta->printf('|Day: %+<5dv|');
585 => |Day: +4|
586 $delta->printf('|Day: %>5sv|');
588 => |Day: 7 |
589 Directives to print out several fields in terms of one of them
591 The following directive is used to print out the value of several
592 different fields, expressed in terms of a single field.
593 % [+] [pad] [width] [.precision] XYZ
595 Here, X, Y, and Z are each one of (y,M,w,d,h,m,s). The directive
597 will print out the value for fields Y through Z expressed in terms
598 of field X.
599 Y must come before Z in the sequence (y,M,w,d,h,m,s) or it can be
601 the same as Z.
602 So, to print the day and hour fields in terms of seconds, use the
604 directive:
605 %sdh
607 Any time all of X, Y, and Z are from a single set of fields, exact
609 relationships are used.
610 If the X, Y, and Z fields do not all belong to the same set of
612 fields, approximate relationships are used.
613 For non-business deltas, an approximate relationship is needed to
615 link the Y/M part of the delta to the W/D part and a semi-
616 approximate relationship is needed to link the W/D part with the
617 H/MN/S part. These relationships are:
618 1 day = 24 hours
620 1 year = 365.2425
621 For business deltas, the approximate and semi-approximate
623 relationships used to link the fields together are:
624 1 week = X (length of business week in days)
626 1 year = X/7 * 365.2425
627 For business deltas, the length of the day is defined using
629 WorkDayStart and WorkDayEnd. For non-business deltas, a day is 24
630 hours long (i.e. daylight saving time is ignored).
631 If 'precision' is included, it is the number of decimal places to
633 print. If it is not included, but 'width' is included, precision
634 will be set automatically to display the maximum number of decimal
635 places given 'width'.
636 If 'pad' is included, it may be the character '<', '>', or '0', and
638 is used in the same way as printing out a single field.
639 In the following examples, $delta contains the delta: 1:2:3:4:5:6:7
641 $delta->printf('|%.4Myw|');
643 => |14.6900|
644 1 year, 2 months, 3 weeks is approximately
645 14.6900 months
646 Directives to print out portions of the delta
648 The following directives may be used to print out some or all of a
649 delta.
650 % [+] [pad] [width] Dt
652 % [+] [pad] [width] DXY
653 The first directive will print out the entire delta.
655 The second will print out the delta from the X to Y fields
657 inclusive (where X and Y are each one of (y,M,w,d,h,m,s) and X must
658 come before Y in the sequence).
659 'pad' is optional and can be either '<' or '>' meaning to pad on
661 the left or right with spaces. It defaults to '<'.
662 If a '+' is included immediately following the '%', every field
664 will have a sign attached. Otherwise, only the leftmost field in
665 each set of fields will include a sign.
666 $delta->printf('|%Dt|');
668 => |+1:2:+3:+4:5:6:7|
669 $delta->printf('|%+Dyd|');
671 => |+1:+2:+3:+4|
672
674 None known.
675
677 Please refer to the Date::Manip::Problems documentation for information
678 on submitting bug reports or questions to the author.
679
681 Date::Manip - main module documentation
682
684 This script is free software; you can redistribute it and/or modify it
685 under the same terms as Perl itself.
686
688 Sullivan Beck (sbeck@cpan.org)
689perl v5.36.0 2023-03-08 Date::Manip::Delta(3)