1DateTime::Format::DuratUisoenr(3C)ontributed Perl DocumeDnattaetTiiomne::Format::Duration(3)
2
3
4

NAME

6       DateTime::Format::Duration - Format and parse DateTime::Durations
7

VERSION

9       version 1.04
10

SYNOPSIS

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

ABSTRACT

57       This module formats and parses DateTime::Duration objects as well as
58       other durations representations.
59

CONSTRUCTOR

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

METHODS

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

ACCESSORS

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

SETTERS

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

NOTES

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

SEE ALSO

408       datetime@perl.org mailing list
409
410       http://datetime.perl.org/
411

SUPPORT

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

AUTHOR

424       Rick Measham <rickm@cpan.org>
425

CONTRIBUTOR

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.34.0                      2021-07-22     DateTime::Format::Duration(3)
Impressum