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 fields
22 A delta consists of 7 fields: years, months, weeks, days, hours,
23 minutes, and seconds, usually expressed as a colon-separated
24 string. For example:
25 1:2:3:4:5:6:7
27 refers to an elapsed amount of time 1 year, 2 months, 3 weeks, 4
29 days, 5 hours, 6 minutes, and 7 seconds long.
30 normalized
32 A delta can be normalized or not. A normalized delta has values
33 which have been made consistent with the type of data they
34 represent. For example, a delta of:
35 0:0:0:0:0:10:70
37 is not normalized since 70 seconds is better expressed as 1 minute
39 10 seconds. The normalized form of this delta would be:
40 0:0:0:0:0:11:10
42 Deltas are automatically converted to a normalized form in almost
44 all functions.
45 sets of fields
47 When normalizing a delta, fields are grouped together in sets where
48 the exact relationship is known between all fields in the set.
49 For example, in a normal delta, it is known that there are exactly
51 60 seconds in a minute, exactly 60 minutes in an hour, etc.
52 It is NOT known how many weeks are in a month however. So, the year
54 and month fields form one set, and the weeks, days, hours, minutes,
55 and seconds form a second set.
56 When normalizing a delta, no data from one set will ever be mixed
58 with data from another set.
59 As a result, the following delta is normalized:
61 0:3:8:0:0:0:0
63 Although 8 weeks is clearly more than 1 month, we don't know the
65 relationship between the two, so they don't mix.
66 exact deltas
68 An exact delta is one which does not include any fields which
69 cannot be exactly written in terms of seconds. For example, a delta
70 which includes a year or month field can never be exact since there
71 is no exact length for either.
72 So, the delta:
74 0:3:8:0:0:0:0
76 is not exact, but the delta:
78 0:0:0:12:30:0:0
80 is exact.
82 business delta
84 Deltas can refer to changes in either the full calendar, or they
85 can refer to a business calendar.
86 Business deltas have the added complexity that there is no definite
88 relationship between the number of work days in a work week (there
89 may be a holiday during the week). As a result, there are three
90 sets of fields: year/month, week, day/hour/minute/second. An exact
91 business delta will not have a year, month, or week field.
92 There IS a definite relationship between hours and days, but it is
94 probably not 24 hours = 1 day. Common definitions of a work day
95 include 8 hours long (09:00-17:00) or 9 hours long (08:00-17:00),
96 and any other definition may be included may be defined as long as
97 the start time is earlier in the day than the end time. The config
98 variables WorkDayBeg, WorkDayEnd, and WorkDay24Hr can be used to
99 defined the length of the work day.
100 signs
102 Each set of fields has a sign associated with it. For example, the
103 delta "1 year ago" is written as:
104 -1:0:0:0:0:0:0
106 Since there is no mixing of data between sets of fields, you can
108 end up with a delta with two (or three in the case of business
109 deltas) signs. So, the following is a fully normalized business
110 delta:
111 +1:0:-3:+3:0:0:0
113 Note that for a fully normalized delta, the leading field in each
115 set of fields will always have a sign, even when it is redundant or
116 unnecessary.
117 For example:
119 +2:1:+2:6:23:51:30
121 +0:0:+0:0:0:0:10
122 In a normalized delta, all fields in a set will have the same sign.
124
126 new
127 new_config
128 new_date
129 new_delta
130 new_recur
131 base
132 tz
133 is_date
134 is_delta
135 is_recur
136 config
137 err Please refer to the Date::Manip::Obj documentation for these
138 methods.
139 parse
141 $err = $delta->parse($string [,$business]);
142 This takes a string and parses it to see if it is a valid delta. If
144 it is, an error code of 0 is returned and $delta now contains the
145 value of the delta. Otherwise, an error code of 1 is returned.
146 A valid delta is in one of two forms: colon or expanded.
148 The colon format is:
150 +Y:+M:+W:+D:+H:+MN:+S
152 examples:
153 0:0:0:0:4:3:-2
154 +4:3:-2
155 +4::3
156 In the colon format, from 1 to 7 of the fields may be given. For
158 example +D:+H:+MN:+S may be given to specify only four of the
159 fields. No spaces may be present in the colon format. It is
160 allowed to omit some of the fields. For example 5::3:30 is valid.
161 In this case, missing fields default to the value 0.
162 The expanded format is:
164 +Yy +Mm +Ww +Dd +Hh +MNmn +Ss
166 examples:
167 +4 hours +3mn -2second
168 + 4 hr 3 minutes -2
169 4 hour + 3 min -2 s
170 4 hr 2 s (note that minutes are omitted)
171 A field in the expanded format (+Yy) is a sign, a number, and a
173 string specifying the type of field. The sign is "+", "-", or
174 absent (defaults to the next larger element). The valid strings
175 (in English) specifying the field type are:
176 y: y, yr, year, years
178 m: m, mon, month, months
179 w: w, wk, ws, wks, week, weeks
180 d: d, day, days
181 h: h, hr, hour, hours
182 mn: mn, min, minute, minutes
183 s: s, sec, second, seconds
184 Other languages have similar abbreviations.
186 Also, the "seconds" string may be omitted. The sign, number, and
188 string may all be separated from each other by any number of
189 whitespace. The string specifying the unit must be separated from a
190 following number by whitespace or a comma, so the following example
191 will NOT work:
192 4hours3minutes
194 At minimum, it must be expressed as:
196 4hours 3minutes
198 4 hours, 3 minutes
199 In the the expanded format, all fields must be given in the order:
201 Y M W D H MN S. Any number of them may be omitted provided the
202 rest remain in the correct order. Numbers may be spelled out, so
203 in two weeks
205 in 2 weeks
206 both work.
208 Most languages also allow a word to specify whether the delta is an
210 amount of time after or before a fixed point. In English, the word
211 "in" refers to a time after a fixed point, and "ago" refers to a
212 point before a fixed point. So, the following deltas are
213 equivalent:
214 1:0:0:0:0:0:0
216 in 1 year
217 and the following are equivalent
219 -1:0:0:0:0:0:0
221 1 year ago
222 The word "in" is completely ignored. The word "ago" has the affect
224 of reversing all signs that appear in front of the components of
225 the delta. In other words, the following two strings are
226 identical:
227 -12 yr 6 mon ago
229 +12 yr +6 mon
230 (don't forget that there is an implied minus sign in front of the 6
232 in the first string because when no sign is explicitly given, it
233 carries the previously entered sign).
234 The in/ago words only apply to the expanded format, so the
236 following is invalid:
237 1:0:0 ago
239 A delta may be business mode, or non-business mode. By default, a
241 delta is treated as a non-business mode delta, but this can be
242 changed in two different ways.
243 The first way to make a delta be business mode is to pass in the
245 2nd argument to the function that is non-zero. If this is done, the
246 delta will be a business delta by default.
247 The second way to specify whether a delta is business or non-
249 business is to include a key word in the string that is parsed.
250 When this is done, these strings override any value of the
251 $business argument.
252 Most languages include a word like "business" which can be used to
254 specify that the resulting delta is a business mode delta or a non-
255 business delta. Other languages have equivalent words. The
256 placement of the word is not important. Also, the "business" word
257 can be included with both types of deltas, so the following are
258 valid and equivalent:
259 in 4 hours business
261 4:0:0 business
262 business 0:0:0:0:4:0:0
263 There are also words "exact" or "approximate" which serve to force
265 the delta to be non-business mode. For backward compatibility, both
266 are available and serve the same purpose (they no longer determine
267 whether the delta is exact or not... that is determined only by the
268 fields that are included as described above).
269 input
271 $str = $delta->input();
272 This returns the string that was parsed to form the delta.
274 set
276 $err = $delta->set($field,$val);
277 This explicitly sets one or more fields in a delta.
279 $field can be any of the following:
281 $field $val
283 delta [Y,M,W,D,H,MN,S] sets the entire delta
285 business [Y,M,W,D,H,MN,S] sets the entire delta
286 normal [Y,M,W,D,H,MN,S] sets the entire delta
287 y YEAR sets one field
288 M MONTH
289 w WEEK
290 d DAY
291 h HOUR
292 m MINUTE
293 s SECOND
294 mode business, normal
296 An error is returned if an invalid value is passed in.
298 When setting the entire delta with "business" or "normal", it flags
300 the delta as a business or non-business delta respectively. When
301 setting the entire delta with "delta", the flag is left unchanged.
302 printf
304 $out = $delta->printf($in);
305 @out = $delta->printf(@in);
306 This takes a string or list of strings which may contain any number
308 of special formatting directives. These directives are replaced
309 with information contained in the delta. Everything else in the
310 string is returned unmodified.
311 A directive always begins with '%'. They are described in the
313 section below in the section PRINTF DIRECTIVES.
314 calc
316 $date2 = $delta->calc($date1 [,$subtract]);
317 $delta3 = $delta1->calc($delta2 [,$subtract]);
318 Please refer to the Date::Manip::Calc documentation for details.
320 type
322 $flag = $delta->type($op);
323 This tests to see if a delta is of a certain type. $op can be;
325 business : returns 1 if it is a business delta
327 exact : returns 1 if it is exact
328 value
330 $val = $delta->value();
331 @val = $delta->value();
332 This returns the value of the delta. In scalar context, it returns
334 the printable string (equivalent to the printf directive '%Dt'). In
335 list context, it returns a list of fields.
336 undef is returned if there is no valid delta stored in $delta.
338
340 The following printf directives are replaced with information from the
341 delta. Directives may be replaced by the values of a single field in
342 the delta (i.e. the hours or weeks field), the value of several fields
343 expressed in terms of one of them (i.e. the number of years and months
344 expressed in terms of months), or the directive may format either the
345 entire delta, or portions of it.
346 Simple directives
348 These are directives which print simple characters. Currently, the
349 only one is:
350 %% Replaced by a single '%'
352 As an example:
354 $delta->printf('|A %% B|');
356 => |A % B|
357 Directives to print out a single field
359 The following directive is used to print out the value of a single
360 field. Spaces are included here for clarity, but are not in the
361 actual directive.
362 % [+] [pad] [width] Xv
364 Here, X is one of (y,M,w,d,h,m,s). The directive will print out the
366 value for that field (in the normalized delta).
367 If a '+' is included immediately after the '%', a sign will always
369 be included. By default, only negative values will include a sign.
370 'width' is any positive integer (without a sign). If 'width' is
372 included, it sets the length of the output string (unless the
373 string is already longer than that, in which case the 'width' is
374 ignored).
375 If 'pad' is included, it may be the character '<', '>', or '0'. It
377 will be ignored unless 'width' is included. If the formatted delta
378 field is shorter than 'width', it will be padded with spaces on the
379 left (if 'pad' is '<'), or right (if 'pad' is '>'), or it will be
380 padded on the left (after any sign) with zeroes (if 'pad' is '0').
381 In the following examples, $delta contains the delta: 1:2:3:4:5:6:7
383 $delta->printf('|Month: %Mv|');
385 => |Month: 2|
386 $delta->printf('|Day: %+05dv|');
388 => |Day: +0004|
389 $delta->printf('|Day: %+<5dv|');
391 => |Day: +4|
392 $delta->printf('|Day: %>5sv|');
394 => |Day: 7 |
395 Directives to print out several fields in terms of one of them
397 The following directive is used to print out the value of several
398 different fields, expressed in terms of a single field.
399 % [+] [pad] [width] [.precision] XYZ
401 Here, X, Y, and Z are each one of (y,M,w,d,h,m,s). The directive
403 will print out the value for fields Y through Z expressed in terms
404 of field X.
405 Y must come before Z in the sequence (y,M,w,d,h,m,s) or it can be
407 the same as Z.
408 So, to print the day and hour fields in terms of seconds, use the
410 directive:
411 %sdh
413 Any time all of X, Y, and Z are from a single set of fields, exact
415 relationships are used.
416 If the X, Y, and Z fields do not all belong to the same set of
418 fields, approximate relationships are used.
419 For non-business deltas, an approximate relationship is needed to
421 link the Y/M part of the delta to the W/D/H/Mn/S part. The
422 relationship used is that a year is assigned a length of 365.2425
423 days.
424 For business deltas, the relationship between weeks and days is set
426 to be the length of the business week (as defined using the
427 WorkWeekBeg and WorkWeekEnd config variables). Also, a factor of
428 X/7 * 365.2425 (where X is the number of days in a work week) is
429 used to determine the number of work days in a year.
430 If 'precision' is included, it is the number of decimal places to
432 print. If it is not included, but 'width' is included, precision
433 will be set automatically to display the maximum number of decimal
434 places given 'width'.
435 If 'pad' is included, it may be the character '<', '>', or '0', and
437 is used in the same way as printing out a single field.
438 In the following examples, $delta contains the delta: 1:2:3:4:5:6:7
440 $delta->printf('|%.4Myw|');
442 => |14.6900|
443 1 year, 2 months, 3 weeks is approximately
444 14.6900 months
445 Directives to print out portions of the delta
447 The following directives may be used to print out some or all of a
448 delta.
449 % [+] [pad] [width] Dt
451 % [+] [pad] [width] DXY
452 The first directive will print out the entire delta.
454 The second will print out the delta from the X to Y fields
456 inclusive (where X and Y are each one of (y,M,w,d,h,m,s) and X must
457 come before Y in the sequence).
458 'pad' is optional and can be either '<' or '>' meaning to pad on
460 the left or right with spaces. It defaults to '<'.
461 If a '+' is included immediately following the '%', every field
463 will have a sign attached. Otherwise, only the leftmost field in
464 each set of fields will include a sign.
465 $delta->printf('|%Dt|');
467 => |+1:2:+3:+4:5:6:7|
468 $delta->printf('|%+Dyd|');
470 => |+1:+2:+3:+4|
471
473 None known.
474
476 Please refer to the Date::Manip::Problems documentation for information
477 on submitting bug reports or questions to the author.
478
480 Date::Manip - main module documentation
481
483 This script is free software; you can redistribute it and/or modify it
484 under the same terms as Perl itself.
485
487 Sullivan Beck (sbeck@cpan.org)
488perl v5.10.1 2011-12-07 Date::Manip::Delta(3)