1DateTime::Format::DuratUisoenr(3C)ontributed Perl DocumeDnattaetTiiomne::Format::Duration(3)
2
3
4
6 DateTime::Format::Duration - Format and parse DateTime::Durations
7
9 version 1.04
10
12 use DateTime::Format::Duration;
13
14 $d = DateTime::Format::Duration->new(
15 pattern => '%Y years, %m months, %e days, '.
16 '%H hours, %M minutes, %S seconds'
17 );
18
19 print $d->format_duration(
20 DateTime::Duration->new(
21 years => 3,
22 months => 5,
23 days => 1,
24 hours => 6,
25 minutes => 15,
26 seconds => 45,
27 nanoseconds => 12000
28 )
29 );
30 # 3 years, 5 months, 1 days, 6 hours, 15 minutes, 45 seconds
31
32
33 $duration = $d->parse_duration(
34 '3 years, 5 months, 1 days, 6 hours, 15 minutes, 45 seconds'
35 );
36 # Returns DateTime::Duration object
37
38
39 print $d->format_duration_from_deltas(
40 years => 3,
41 months => 5,
42 days => 1,
43 hours => 6,
44 minutes => 15,
45 seconds => 45,
46 nanoseconds => 12000
47 );
48 # 3 years, 5 months, 1 days, 6 hours, 15 minutes, 45 seconds
49
50 %deltas = $d->parse_duration_as_deltas(
51 '3 years, 5 months, 1 days, 6 hours, 15 minutes, 45 seconds'
52 );
53 # Returns hash:
54 # (years=>3, months=>5, days=>1, hours=>6, minutes=>15, seconds=>45)
55
57 This module formats and parses DateTime::Duration objects as well as
58 other durations representations.
59
61 This module contains a single constructor:
62
63 · "new( ... )"
64
65 The "new" constructor takes the following attributes:
66
67 · "pattern => $string"
68
69 This is a strf type pattern detailing the format of the
70 duration. See the "Patterns" sections below for more
71 information.
72
73 · "normalise => $one_or_zero_or_ISO"
74
75 · "normalize => $one_or_zero_or_ISO"
76
77 This determines whether durations are 'normalised'. For
78 example, does 120 seconds become 2 minutes?
79
80 Setting this value to true without also setting a "base" means
81 we will normalise without a base. See the "Normalising without
82 a base" section below.
83
84 · "base => $datetime_object"
85
86 If a base DateTime is given then that is the normalisation
87 date. Setting this attribute overrides the above option and
88 sets normalise to true.
89
91 DateTime::Format::Duration has the following methods:
92
93 · "format_duration( $datetime_duration_object )"
94
95 · "format_duration( duration => $dt_duration, pattern => $pattern )"
96
97 Returns a string representing a DateTime::Duration object in the
98 format set by the pattern. If the first form is used, the pattern
99 is taken from the object. If the object has no pattern then this
100 method will croak.
101
102 · "format_duration_from_deltas( %deltas )"
103
104 · "format_duration_from_deltas( %deltas, pattern => $pattern )"
105
106 As above, this method returns a string representing a duration in
107 the format set by the pattern. However this method takes a hash of
108 values. Permissible hash keys are "years, months, days, hours,
109 minutes, seconds" and "nanoseconds" as well as "negative" which, if
110 true, inverses the duration. ("years => -1" is the same as "years
111 => 1, negative=>1")
112
113 · "parse_duration( $string )"
114
115 This method takes a string and returns a DateTime::Duration object
116 that is the equivalent according to the pattern.
117
118 · "parse_duration_as_deltas( $string )"
119
120 Once again, this method is the same as above, however it returns a
121 hash rather than an object.
122
123 · "normalise( $duration_object )"
124
125 · "normalize( %deltas )"
126
127 Returns a hash of deltas after normalising the input. See the
128 "NORMALISE" section below for more information.
129
131 · "pattern()"
132
133 Returns the current pattern.
134
135 · "base()"
136
137 Returns the current base.
138
139 · "normalising()"
140
141 Indicates whether or not the durations are being normalised.
142
144 All setters return the object so that they can be strung together.
145
146 · "set_pattern( $new_pattern )"
147
148 Sets the pattern and returns the object.
149
150 · "set_base( $new_DateTime )"
151
152 Sets the base DateTime and returns the object.
153
154 · "set_normalising( $true_or_false_or_ISO )"
155
156 Turns normalising on or off and returns the object.
157
159 Patterns
160 This module uses a similar set of patterns to strftime. These patterns
161 have been kept as close as possible to the original time-based
162 patterns.
163
164 · %C
165
166 The number of hundreds of years in the duration. 400 years would
167 return 4. This is similar to centuries.
168
169 · %d
170
171 The number of days zero-padded to two digits. 2 days returns 02. 22
172 days returns 22 and 220 days returns 220.
173
174 · %e
175
176 The number of days.
177
178 · %F
179
180 Equivalent of %Y-%m-%d
181
182 · %H
183
184 The number of hours zero-padded to two digits.
185
186 · %I
187
188 Same as %H
189
190 · %j
191
192 The duration expressed in whole days. 36 hours returns 1
193
194 · %k
195
196 The hours without any padding
197
198 · %l
199
200 Same as %k
201
202 · %m
203
204 The months, zero-padded to two digits
205
206 · %M
207
208 The minutes, zero-padded to two digits
209
210 · %n
211
212 A linebreak when formatting and any whitespace when parsing
213
214 · %N
215
216 Nanoseconds - see note on precision at end
217
218 · %p
219
220 Either a '+' or a '-' indicating the positiveness of the duration
221
222 · %P
223
224 A '-' for negative durations and nothing for positive durations.
225
226 · %r
227
228 Equivalent of %H:%M:%S
229
230 · %R
231
232 Equivalent of %H:%M
233
234 · %s
235
236 Returns the value as seconds. 1 day, 5 seconds return 86405
237
238 · %S
239
240 Returns the seconds, zero-padded to two digits
241
242 · %t
243
244 A tab character when formatting or any whitespace when parsing
245
246 · %T
247
248 Equivalent of %P%H:%M:%S
249
250 · %u
251
252 Days after weeks are removed. 4 days returns 4, but 22 days returns
253 1 (22 days is three weeks, 1 day)
254
255 · %V
256
257 Duration expressed as weeks. 355 days returns 52.
258
259 · %W
260
261 Duration expressed as floating weeks. 10 days, 12 hours returns 1.5
262 weeks.
263
264 · %y
265
266 Years in the century. 145 years returns 45.
267
268 · %Y
269
270 Years, zero-padded to four digits
271
272 · %%
273
274 A '%' symbol
275
276 Precision can be changed for any and all the above values. For all but
277 nanoseconds (%N), the precision is the zero-padding. To change the
278 precision insert a number between the '%' and the letter. For example:
279 1 year formatted with %6Y would return 000001 rather than the default
280 0001. Likewise, to remove padding %1Y would just return a 1.
281
282 Nanosecond precision is the other way (nanoseconds are fractional and
283 thus should be right padded). 123456789 nanoseconds formatted with %3N
284 would return 123 and formatted as %12N would return 123456789000.
285
286 Normalisation
287 This module contains a complex method for normalising durations. The
288 method ensures that the values for all components are as close to zero
289 as possible. Rather than returning 68 minutes, it is normalised to 1
290 hour, 8 minutes.
291
292 The complexity comes from three places:
293
294 · Mixed positive and negative components
295
296 The duration of 1 day, minus 2 hours is easy to normalise in your
297 head to 22 hours. However consider something more complex such as
298 -2 years, +1 month, +22 days, +11 hours, -9 minutes.
299
300 This module works from lowest to highest precision to calculate the
301 duration. So, based on a "base" of 2004-03-28T00:00:00 the
302 following transformations take place:
303
304 2003-01-01T00:00:00 - 2 years = 2001-01-01T00:00:00 === -2 years
305 2001-01-01T00:00:00 + 1 month = 2001-02-01T00:00:00 === -1 year, 11 months
306 2001-02-01T00:00:00 + 22 days = 2001-02-23T00:00:00 === -1yr, 10mths, 6days
307 2001-02-22T00:00:00 + 11 hours = 2001-02-23T11:00:00 === -1y, 10m, 6d, 13h
308 2001-02-22T11:00:00 - 9 minutes = 2001-02-23T10:51:00 === -1y, 10m, 6d, 13h, 9m
309 See: file:///usr/share/doc/perl-DateTime-Format-
310 Duration/docs/figure1.gif
311
312 Figure 1 illustrates that, with the given base, -2 years, +1 month,
313 +22 days, +11 hours, -9 minutes is normalised to -1 year, 10
314 months, 6 days, 13 hours and 9 minutes.
315
316 · Months of unequal length.
317
318 Unfortunately months can have 28, 29, 30 or 31 days and it can
319 change from year to year. Thus if I wanted to normalise 2 months it
320 could be any of 59 (Feb-Mar), 60 (Feb-Mar in a leap year), 61 (Mar-
321 Apr, Apr-May, May-Jun, Jun-Jul, Aug-Sep, Sep-Oct, Oct-Nov or Nov-
322 Dec) or 62 days (Dec-Jan or Jul-Aug). Because of this the module
323 uses a base datetime for its calculations. If we use the base
324 2003-01-01T00:00:00 then two months would be 59 days (2003-03-01 -
325 2003-01-01)
326
327 · The order of components
328
329 Components will always be assessed from lowest to highest precision
330 (years, months, days, hours, minutes, seconds, nanoseconds). This
331 can really change things.
332
333 Consider the duration of 1 day, 24 hours. Normally this will
334 normalise to 2 days. However, consider changes to Daylight
335 Savings. On the changes to and from DST days have 25 and 23 hours.
336
337 If we take the base DateTime as midnight on the day DST ends (when
338 there's 25 hours in the day), and add 1 day, 24 hours we end up at
339 midnight 2 days later. So our duration normalises to two days.
340
341 However, if we add 24 hours, 1 day we end up at 11pm on the next
342 day! Why is this? Because midnight + 24 hours = 11pm (there's 25
343 hours on this day!), then we add 1 day and end up at 11pm on the
344 following day. See: file:///usr/share/doc/perl-DateTime-Format-
345 Duration/docs/figure2.gif
346
347 Figure 2 illustrates the above problem on timelines.
348
349 · Leap years and leap seconds
350
351 Leap years and seconds further add to the confusion in
352 normalisation. Leap seconds mean there are minutes that are 61
353 seconds long, thus 130 seconds can be 2 minutes, 10 seconds or 2
354 minutes 9 seconds, depending on the base DateTime. Similarly leap
355 years mean a day can have 23, 24 or 25 hours. See:
356 file:///usr/share/doc/perl-DateTime-Format-
357 Duration/docs/figure3.gif
358
359 Figure 3 shows how leaps are calculated on timelines.
360
361 Normalising without a base
362 This module includes two ways to normalise without a base.
363
364 · Standard Normalisation
365
366 Using standard normalisation without a base, 45 days will stay as
367 45 days as there is no way to accurately convert to months. However
368 the following assumptions will be made: There are 24 hours in a day
369 and there are 60 seconds in a minute.
370
371 · ISO Normalisation
372
373 In ISO8601v2000, Section 5.5.3.2 says that "The values used must
374 not exceed the 'carry-over points' of 12 months, 30 days, 24 hours,
375 60 minutes and 60 seconds". Thus if you set the normalise option
376 of the constructor, or use set_normalising to 'ISO', months will be
377 normalised to 30 days.
378
379 Deltas vs Duration Objects
380 This module can bypass duration objects and just work with delta
381 hashes. This used to be of greatest value with earlier versions of
382 DateTime::Duration when DateTime::Duration assumed a duration with one
383 negative component was a negative duration (that is, -2 hours, 34
384 minutes was assumed to be -2 hours, -34 minutes).
385
386 These extra methods have been left in here firstly for backwards-
387 compatibility but also as an added 'syntactic sugar'. Consider these
388 two equivalent expressions:
389
390 $one = $o->format_duration(
391 DateTime::Duration->new(
392 years => -2,
393 days => 13,
394 hours => -1
395 )
396 );
397
398 $two = $o->format_duration_from_deltas(
399 years => -2,
400 days => 13,
401 hours => -1
402 );
403
404 These both create the same string in $one and $two, but if you don't
405 already have a DateTime::Duration object, the later looks cleaner.
406
408 datetime@perl.org mailing list
409
410 http://datetime.perl.org/
411
413 Bugs may be submitted through the RT bug tracker
414 <https://rt.cpan.org/Public/Dist/Display.html?Name=DateTime-Format-
415 Duration> (or bug-DateTime-Format-Duration@rt.cpan.org <mailto:bug-
416 DateTime-Format-Duration@rt.cpan.org>).
417
418 There is also a mailing list available for users of this distribution,
419 at <http://lists.perl.org/list/datetime.html>.
420
421 I am also usually active on irc, as 'ether' at "irc.perl.org".
422
424 Rick Measham <rickm@cpan.org>
425
427 Karen Etheridge <ether@cpan.org>
428
430 This software is copyright (c) 2003 by Rick Measham.
431
432 This is free software; you can redistribute it and/or modify it under
433 the same terms as the Perl 5 programming language system itself.
434
435
436
437perl v5.30.0 2019-07-26 DateTime::Format::Duration(3)