1Date::Manip::Delta(3) User Contributed Perl DocumentationDate::Manip::Delta(3)
2
3
4

NAME

6       Date::Manip::Delta - Methods for working with deltas
7

SYNOPSIS

9          use Date::Manip::Delta;
10          $date = new Date::Manip::Delta;
11

DESCRIPTION

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
18       There are several concepts involved in understanding the properties of
19       a delta.
20
21       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
25           Standard deltas use the full calendar without any modifications.
26
27           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
34           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
40           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
46       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
51              1:2:3:4:5:6:7
52
53           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
56       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
61              0:0:0:0:0:10:70
62
63           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
66              0:0:0:0:0:11:10
67
68           By default, deltas are converted to a normalized form in most
69           functions that create/modify a delta, but this can be overridden.
70
71       Types of deltas
72           There are 4 type of deltas that are available.
73
74           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
80                   For standard calculations, there are only three exactly
81                   known fields (hours, minutes, and seconds).  The lengths
82                   are defined as:
83
84                      1 hour   = 3600 seconds
85                      1 minute = 60 seconds
86
87                   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
91                   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
99                   All fields which are not exactly known will always have
100                   zero value.
101
102           Semi-exact deltas
103                   A semi-exact delta treats the day/week fields as if they
104                   were exactly known.
105
106                   For standard calculations, this is done by using the
107                   relationships:
108
109                      1 day  = 24 hours
110                      1 week = 7 days
111
112                   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
117                   For semi-exact deltas, the value of the year/month must be
118                   zero.
119
120                   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
125           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
130                      1 year  = 12 months
131
132                   The remaining fields are normalized using the semi-exact
133                   relationships.
134
135           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
140                   For standard deltas, the additional relationship:
141
142                      1 year = 365.2425 days
143
144                   is used.  For business deltas, the additional relationship:
145
146                      1 year   = X/7 * 365.2425 days
147
148                   (where X is the number of work days in a week) is used.
149
150                   Fractional seconds will be discarded (not rounded).
151
152           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
157       signs
158           Each field has a sign associated with it. For example, the delta "1
159           year ago" is written as:
160
161              -1:0:0:0:0:0:0
162
163           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
166              +1:2:3:4:5:6:7
167              +1:+2:+3:+4:+5:+6:+7
168
169           In a normalized delta, all fields in a set will have the same sign.
170           So the standard delta:
171
172              0:0:+3:-2:0:0:0:0   (3 weeks -2 days)
173
174           is not normalized.  The normalized version would be:
175
176              0:0:+2:5:0:0:0:0    (2 weeks, 5 days)
177
178           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
182              +1:0:-3:3:1:0:0
183
184       fractional values
185           Fractional fields are allowed such as:
186
187              1.25 days
188              1.1 years
189
190           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

METHODS

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
209       parse
210              $err = $delta->parse($string, \%opts);
211              $err = $delta->parse($string [,$business] [,$no_normalize]);
212
213           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
217              $err = $delta->parse($string, { business => $business,
218                                              nonorm   => $no_normalize });
219
220           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
225           Recognized options are:
226
227              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
233           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
236           A delta string is usually specified in compact notation which
237           consists of a colon separated list of numbers (with optional
238           signs):
239
240              Examples:
241                 0:0:0:0:4:3:-2
242                 +4:3:-2
243                 +4::3
244
245           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
251           The delta string may also be specified using common field
252           abbreviations.  This is described below in the "ADDITIONAL DELTA
253           NOTATIONS" section.
254
255       input
256              $str = $delta->input();
257
258           This returns the string that was parsed to form the delta.
259
260       set
261              $err = $delta->set(\%opts);
262              $err = $delta->set($field,$val [,$no_normalize]);
263
264           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
268              $err = $delta->set( $field => $val, 'nonorm' => $no_normalize );
269
270           This explicitly sets one or more parts of a delta.  %opts is a set
271           of key/value pairs:
272
273              $key     $val
274
275              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
286              nonorm   0/1
287              mode     business, standard
288              type     exact, semi, estimated, approx
289
290           An error is returned if an invalid data is passed in.
291
292           %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
296           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
302           When setting the entire delta with delta, the flag is left
303           unchanged (unless the mode option is also passed in).
304
305           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
308           By default, a delta is normalized, but setting the nonorm key to a
309           true value will not do that.
310
311           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
315           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
323       printf
324              $out = $delta->printf($in);
325              @out = $delta->printf(@in);
326
327           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
332           A directive always begins with '%'. They are described in the
333           section below in the section "PRINTF DIRECTIVES".
334
335       calc
336           Please refer to the Date::Manip::Calc documentation for details.
337
338       type
339              $flag = $delta->type($op);
340
341           This tests to see if a delta is of a certain type. $op can be;
342
343              business  : returns 1 if it is a business delta
344              standard  : returns 1 if it is a standard (non-business delta)
345
346              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
351       value
352              $val = $delta->value();
353              @val = $delta->value();
354
355           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
359           An empty string/list is returned if there is no valid delta stored
360           in $delta.
361
362       convert
363              $delta->convert($to);
364
365           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
369           For example, if the exact non-business delta $delta contains:
370
371              0:0:0:0:44:0:0
372
373           then the following call:
374
375              $delta->convert('semi')
376
377           would produce the semi-exact delta:
378
379              0:0:0:1:20:0:0
380
381           The result will always be normalized.
382
383           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
389           There is currently no support for converting business to non-
390           business (or vice-versa).
391
392       cmp
393              $flag = $delta1->cmp($delta2);
394
395           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
399           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
403           undef will be returned if either delta is invalid, or you try to
404           compare a business and non-business delta.
405

ADDITIONAL DELTA NOTATIONS

407       When parsing a delta, the string may be specified with the field
408       spelled out, rather than using the colon separated fields.
409
410       This expanded notation has the fields spelled out in some language
411       specific form:
412
413          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
419       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
424          -4 hr 3 min 2 sec
425          -4 hr -3 min -2 sec
426
427       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
432       For example, for English, the document is Date::Manip::Lang::English
433       and the field names include strings like:
434
435          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
443       This list may not be complete.  You should refer to the language
444       document for the full list.
445
446       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
451          4hours3minutes
452
453       At minimum, it must be expressed as:
454
455          4hours 3minutes
456          4 hours, 3 minutes
457
458       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
462          in two weeks
463          in 2 weeks
464
465       both work (but do not rely on this to work for large numbers).
466
467       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
472         1:0:0:0:0:0:0
473         in 1 year
474
475       and the following are equivalent
476
477         -1:0:0:0:0:0:0
478         1 year ago
479
480       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
484          -12 yr  6 mon ago
485          +12 yr +6 mon
486
487       (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
491       The in/ago words only apply to the expanded format, so the following is
492       invalid:
493
494          1:0:0 ago
495
496       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
500       The first way to make a delta be business is to pass in the appropriate
501       option.  For example:
502
503         $delta->parse($string, { 'mode' => 'business' });
504         $delta->parse($string, { 'mode' => 'standard' });
505
506       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
510       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
517          in 4 hours business
518          4:0:0 business
519          business 0:0:0:0:4:0:0
520
521       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

PRINTF DIRECTIVES

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
537       Simple directives
538           These are directives which print simple characters. Currently, the
539           only one is:
540
541              %%    Replaced by a single '%'
542
543           As an example:
544
545             $delta->printf('|%%|');
546                => |%|
547
548       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
553              % [+] [pad] [width] Xv
554
555           Here, X is one of (y,M,w,d,h,m,s). The directive will print out the
556           value for that field.
557
558           If a '+' is included immediately after the '%', a sign will always
559           be included. By default, only negative values will include a sign.
560
561           'width' and 'pad' are used to set the width of the string
562           containing the field as well as how it is padded.
563
564           '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
569           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
576           In the following examples, $delta contains the delta: 1:2:3:4:5:6:7
577
578              $delta->printf('|Month: %Mv|');
579                 => |Month: 2|
580
581              $delta->printf('|Day: %+05dv|');
582                 => |Day: +0004|
583
584              $delta->printf('|Day: %+<5dv|');
585                 => |Day:    +4|
586
587              $delta->printf('|Day: %>5sv|');
588                 => |Day: 7    |
589
590       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
594              % [+] [pad] [width] [.precision] XYZ
595
596           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
600           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
603           So, to print the day and hour fields in terms of seconds, use the
604           directive:
605
606              %sdh
607
608           Any time all of X, Y, and Z are from a single set of fields, exact
609           relationships are used.
610
611           If the X, Y, and Z fields do not all belong to the same set of
612           fields, approximate relationships are used.
613
614           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
619              1 day    = 24 hours
620              1 year   = 365.2425
621
622           For business deltas, the approximate and semi-approximate
623           relationships used to link the fields together are:
624
625              1 week   = X    (length of business week in days)
626              1 year   = X/7 * 365.2425
627
628           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
632           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
637           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
640           In the following examples, $delta contains the delta: 1:2:3:4:5:6:7
641
642              $delta->printf('|%.4Myw|');
643                 => |14.6900|
644                 1 year, 2 months, 3 weeks is approximately
645                 14.6900 months
646
647       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
651              % [+] [pad] [width] Dt
652              % [+] [pad] [width] DXY
653
654           The first directive will print out the entire delta.
655
656           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
660           'pad' is optional and can be either '<' or '>' meaning to pad on
661           the left or right with spaces. It defaults to '<'.
662
663           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
667               $delta->printf('|%Dt|');
668                  => |+1:2:+3:+4:5:6:7|
669
670               $delta->printf('|%+Dyd|');
671                  => |+1:+2:+3:+4|
672

KNOWN BUGS

674       None known.
675

BUGS AND QUESTIONS

677       Please refer to the Date::Manip::Problems documentation for information
678       on submitting bug reports or questions to the author.
679

SEE ALSO

681       Date::Manip        - main module documentation
682

LICENSE

684       This script is free software; you can redistribute it and/or modify it
685       under the same terms as Perl itself.
686

AUTHOR

688       Sullivan Beck (sbeck@cpan.org)
689
690
691
692perl v5.36.0                      2023-03-08             Date::Manip::Delta(3)
Impressum