1DateTime::Format::DuratUisoenr(3C)ontributed Perl DocumeDnattaetTiiomne::Format::Duration(3)
2
6 DateTime::Format::Duration - Format and parse DateTime::Durations
7
9 version 1.04
10
12 use DateTime::Format::Duration;
13 $d = DateTime::Format::Duration->new(
15 pattern => '%Y years, %m months, %e days, '.
16 '%H hours, %M minutes, %S seconds'
17 );
18 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 $duration = $d->parse_duration(
34 '3 years, 5 months, 1 days, 6 hours, 15 minutes, 45 seconds'
35 );
36 # Returns DateTime::Duration object
37 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 %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 • "new( ... )"
64 The "new" constructor takes the following attributes:
66 • "pattern => $string"
68 This is a strf type pattern detailing the format of the
70 duration. See the "Patterns" sections below for more
71 information.
72 • "normalise => $one_or_zero_or_ISO"
74 • "normalize => $one_or_zero_or_ISO"
76 This determines whether durations are 'normalised'. For
78 example, does 120 seconds become 2 minutes?
79 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 • "base => $datetime_object"
85 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 • "format_duration( $datetime_duration_object )"
94 • "format_duration( duration => $dt_duration, pattern => $pattern )"
96 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 • "format_duration_from_deltas( %deltas )"
103 • "format_duration_from_deltas( %deltas, pattern => $pattern )"
105 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 • "parse_duration( $string )"
114 This method takes a string and returns a DateTime::Duration object
116 that is the equivalent according to the pattern.
117 • "parse_duration_as_deltas( $string )"
119 Once again, this method is the same as above, however it returns a
121 hash rather than an object.
122 • "normalise( $duration_object )"
124 • "normalize( %deltas )"
126 Returns a hash of deltas after normalising the input. See the
128 "NORMALISE" section below for more information.
129
131 • "pattern()"
132 Returns the current pattern.
134 • "base()"
136 Returns the current base.
138 • "normalising()"
140 Indicates whether or not the durations are being normalised.
142
144 All setters return the object so that they can be strung together.
145 • "set_pattern( $new_pattern )"
147 Sets the pattern and returns the object.
149 • "set_base( $new_DateTime )"
151 Sets the base DateTime and returns the object.
153 • "set_normalising( $true_or_false_or_ISO )"
155 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 • %C
165 The number of hundreds of years in the duration. 400 years would
167 return 4. This is similar to centuries.
168 • %d
170 The number of days zero-padded to two digits. 2 days returns 02. 22
172 days returns 22 and 220 days returns 220.
173 • %e
175 The number of days.
177 • %F
179 Equivalent of %Y-%m-%d
181 • %H
183 The number of hours zero-padded to two digits.
185 • %I
187 Same as %H
189 • %j
191 The duration expressed in whole days. 36 hours returns 1
193 • %k
195 The hours without any padding
197 • %l
199 Same as %k
201 • %m
203 The months, zero-padded to two digits
205 • %M
207 The minutes, zero-padded to two digits
209 • %n
211 A linebreak when formatting and any whitespace when parsing
213 • %N
215 Nanoseconds - see note on precision at end
217 • %p
219 Either a '+' or a '-' indicating the positiveness of the duration
221 • %P
223 A '-' for negative durations and nothing for positive durations.
225 • %r
227 Equivalent of %H:%M:%S
229 • %R
231 Equivalent of %H:%M
233 • %s
235 Returns the value as seconds. 1 day, 5 seconds return 86405
237 • %S
239 Returns the seconds, zero-padded to two digits
241 • %t
243 A tab character when formatting or any whitespace when parsing
245 • %T
247 Equivalent of %P%H:%M:%S
249 • %u
251 Days after weeks are removed. 4 days returns 4, but 22 days returns
253 1 (22 days is three weeks, 1 day)
254 • %V
256 Duration expressed as weeks. 355 days returns 52.
258 • %W
260 Duration expressed as floating weeks. 10 days, 12 hours returns 1.5
262 weeks.
263 • %y
265 Years in the century. 145 years returns 45.
267 • %Y
269 Years, zero-padded to four digits
271 • %%
273 A '%' symbol
275 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 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 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 The complexity comes from three places:
293 • Mixed positive and negative components
295 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 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 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 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 • Months of unequal length.
317 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 • The order of components
328 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 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 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 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 Figure 2 illustrates the above problem on timelines.
348 • Leap years and leap seconds
350 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 Figure 3 shows how leaps are calculated on timelines.
360 Normalising without a base
362 This module includes two ways to normalise without a base.
363 • Standard Normalisation
365 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 • ISO Normalisation
372 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 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 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 $one = $o->format_duration(
391 DateTime::Duration->new(
392 years => -2,
393 days => 13,
394 hours => -1
395 )
396 );
397 $two = $o->format_duration_from_deltas(
399 years => -2,
400 days => 13,
401 hours => -1
402 );
403 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 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 There is also a mailing list available for users of this distribution,
419 at <http://lists.perl.org/list/datetime.html>.
420 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 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.
434perl v5.34.0 2022-01-21 DateTime::Format::Duration(3)