1DateTime::Duration(3) User Contributed Perl DocumentationDateTime::Duration(3)
2
3
4

NAME

6       DateTime::Duration - Duration objects for date math
7

VERSION

9       version 1.59
10

SYNOPSIS

12           use DateTime::Duration;
13
14           $dur = DateTime::Duration->new(
15               years        => 3,
16               months       => 5,
17               weeks        => 1,
18               days         => 1,
19               hours        => 6,
20               minutes      => 15,
21               seconds      => 45,
22               nanoseconds  => 12000,
23               end_of_month => 'limit',
24           );
25
26           my ( $days, $hours, $seconds )
27               = $dur->in_units( 'days', 'hours', 'seconds' );
28
29           # Human-readable accessors, always positive, but consider using
30           # DateTime::Format::Duration instead
31           $dur->years;
32           $dur->months;
33           $dur->weeks;
34           $dur->days;
35           $dur->hours;
36           $dur->minutes;
37           $dur->seconds;
38           $dur->nanoseconds;
39
40           $dur->is_wrap_mode;
41           $dur->is_limit_mode;
42           $dur->is_preserve_mode;
43
44           print $dur->end_of_month_mode;
45
46           # Multiply all values by -1
47           my $opposite = $dur->inverse;
48
49           my $bigger  = $dur1 + $dur2;
50           my $smaller = $dur1 - $dur2;    # the result could be negative
51           my $bigger  = $dur1 * 3;
52
53           my $base_dt = DateTime->new( year => 2000 );
54           my @sorted
55               = sort { DateTime::Duration->compare( $a, $b, $base_dt ) } @durations;
56
57           if ( $dur->is_positive ) {...}
58           if ( $dur->is_zero )     {...}
59           if ( $dur->is_negative ) {...}
60

DESCRIPTION

62       This is a simple class for representing duration objects. These objects
63       are used whenever you do date math with DateTime.
64
65       See the How DateTime Math Works section of the DateTime documentation
66       for more details. The short course: One cannot in general convert
67       between seconds, minutes, days, and months, so this class will never do
68       so. Instead, create the duration with the desired units to begin with,
69       for example by calling the appropriate subtraction/delta method on a
70       DateTime object.
71

METHODS

73       Like DateTime itself, "DateTime::Duration" returns the object from
74       mutator methods in order to make method chaining possible.
75
76       "DateTime::Duration" has the following methods:
77
78   DateTime::Duration->new( ... )
79       This class method accepts the following parameters:
80
81       •   years
82
83           An integer containing the number of years in the duration. This is
84           optional.
85
86       •   months
87
88           An integer containing the number of months in the duration. This is
89           optional.
90
91       •   weeks
92
93           An integer containing the number of weeks in the duration. This is
94           optional.
95
96       •   days
97
98           An integer containing the number of days in the duration. This is
99           optional.
100
101       •   hours
102
103           An integer containing the number of hours in the duration. This is
104           optional.
105
106       •   minutes
107
108           An integer containing the number of minutes in the duration. This
109           is optional.
110
111       •   seconds
112
113           An integer containing the number of seconds in the duration. This
114           is optional.
115
116       •   nanoseconds
117
118           An integer containing the number of nanoseconds in the duration.
119           This is optional.
120
121       •   end_of_month
122
123           This must be either "wrap", "limit", or "preserve". This parameter
124           specifies how date math that crosses the end of a month is handled.
125
126           In "wrap" mode, adding months or years that result in days beyond
127           the end of the new month will roll over into the following month.
128           For instance, adding one year to Feb 29 will result in Mar 1.
129
130           If you specify "limit", the end of the month is never crossed.
131           Thus, adding one year to Feb 29, 2000 will result in Feb 28, 2001.
132           If you were to then add three more years this will result in Feb
133           28, 2004.
134
135           If you specify "preserve", the same calculation is done as for
136           "limit" except that if the original date is at the end of the month
137           the new date will also be. For instance, adding one month to Feb
138           29, 2000 will result in Mar 31, 2000.
139
140           For positive durations, this parameter defaults to "wrap". For
141           negative durations, the default is "preserve". This should match
142           how most people "intuitively" expect datetime math to work.
143
144       All of the duration units can be positive or negative. However, if any
145       of the numbers are negative, the entire duration is negative.
146
147       All of the numbers must be integers.
148
149       Internally, years as just treated as 12 months. Similarly, weeks are
150       treated as 7 days, and hours are converted to minutes. Seconds and
151       nanoseconds are both treated separately.
152
153   $dur->clone
154       Returns a new object with the same properties as the object on which
155       this method was called.
156
157   $dur->in_units( ... )
158       Returns the length of the duration in the units (any of those that can
159       be passed to "DateTime::Duration->new") given as arguments. All lengths
160       are integral, but may be negative. Smaller units are computed from what
161       remains after taking away the larger units given, so for example:
162
163           my $dur = DateTime::Duration->new( years => 1, months => 15 );
164
165           $dur->in_units('years');                # 2
166           $dur->in_units('months');               # 27
167           $dur->in_units( 'years', 'months' );    # (2, 3)
168           $dur->in_units( 'weeks', 'days' );      # (0, 0) !
169
170       The last example demonstrates that there will not be any conversion
171       between units which don't have a fixed conversion rate. The only
172       conversions possible are:
173
174       •   years <=> months
175
176       •   weeks <=> days
177
178       •   hours <=> minutes
179
180       •   seconds <=> nanoseconds
181
182       For the explanation of why this is the case, please see the How
183       DateTime Math Works section of the DateTime documentation
184
185       Note that the numbers returned by this method may not match the values
186       given to the constructor.
187
188       In list context, "$dur->in_units" returns the lengths in the order of
189       the units given. In scalar context, it returns the length in the first
190       unit (but still computes in terms of all given units).
191
192       If you need more flexibility in presenting information about durations,
193       please take a look a DateTime::Format::Duration.
194
195   $dur->is_positive, $dur->is_zero, $dur->is_negative
196       Indicates whether or not the duration is positive, zero, or negative.
197
198       If the duration contains both positive and negative units, then it will
199       return false for all of these methods.
200
201   $dur->is_wrap_mode, $dur->is_limit_mode, $dur->is_preserve_mode
202       Indicates what mode is used for end of month wrapping.
203
204   $dur->end_of_month_mode
205       Returns one of "wrap", "limit", or "preserve".
206
207   $dur->calendar_duration
208       Returns a new object with the same calendar delta (months and days
209       only) and end of month mode as the current object.
210
211   $dur->clock_duration
212       Returns a new object with the same clock deltas (minutes, seconds, and
213       nanoseconds) and end of month mode as the current object.
214
215   $dur->inverse( ... )
216       Returns a new object with the same deltas as the current object, but
217       multiplied by -1. The end of month mode for the new object will be the
218       default end of month mode, which depends on whether the new duration is
219       positive or negative.
220
221       You can set the end of month mode in the inverted duration explicitly
222       by passing an "end_of_month" parameter to the "$dur->inverse" method.
223
224   $dur->add_duration($duration_object),
225       $dur->subtract_duration($duration_object)
226       Adds or subtracts one duration from another.
227
228   $dur->add( ... ), $dur->subtract( ... )
229       These accept either constructor parameters for a new
230       "DateTime::Duration" object or an already-constructed duration object.
231
232   $dur->multiply($number)
233       Multiplies each unit in the "DateTime::Duration" object by the
234       specified integer number.
235
236   DateTime::Duration->compare( $duration1, $duration2, $base_datetime )
237       This is a class method that can be used to compare or sort durations.
238       Comparison is done by adding each duration to the specified DateTime
239       object and comparing the resulting datetimes. This is necessary because
240       without a base, many durations are not comparable. For example, 1 month
241       may or may not be longer than 29 days, depending on what datetime it is
242       added to.
243
244       If no base datetime is given, then the result of "DateTime->now" is
245       used instead. Using this default will give non-repeatable results if
246       used to compare two duration objects containing different units. It
247       will also give non-repeatable results if the durations contain multiple
248       types of units, such as months and days.
249
250       However, if you know that both objects only consist of one type of unit
251       (months or days or hours, etc.), and each duration contains the same
252       type of unit, then the results of the comparison will be repeatable.
253
254   $dur->delta_months, $dur->delta_days, $dur->delta_minutes,
255       $dur->delta_seconds, $dur->delta_nanoseconds
256       These methods provide the information DateTime needs for doing date
257       math.  The numbers returned may be positive or negative. This is mostly
258       useful for doing date math in DateTime.
259
260   $dur->deltas
261       Returns a hash with the keys "months", "days", "minutes", "seconds",
262       and "nanoseconds", containing all the delta information for the object.
263       This is mostly useful for doing date math in DateTime.
264
265   $dur->years, $dur->months, $dur->weeks, $dur->days, $dur->hours,
266       $dur->minutes, $dur->seconds, $dur->nanoseconds
267       These methods return numbers indicating how many of the given unit the
268       object represents, after having done a conversion to any larger units.
269       For example, days are first converted to weeks, and then the remainder
270       is returned. These numbers are always positive.
271
272       Here's what each method returns:
273
274           $dur->years       == abs( $dur->in_units('years') )
275           $dur->months      == abs( ( $dur->in_units( 'months', 'years' ) )[0] )
276           $dur->weeks       == abs( $dur->in_units( 'weeks' ) )
277           $dur->days        == abs( ( $dur->in_units( 'days', 'weeks' ) )[0] )
278           $dur->hours       == abs( $dur->in_units( 'hours' ) )
279           $dur->minutes     == abs( ( $dur->in_units( 'minutes', 'hours' ) )[0] )
280           $dur->seconds     == abs( $dur->in_units( 'seconds' ) )
281           $dur->nanoseconds == abs( ( $dur->in_units( 'nanoseconds', 'seconds' ) )[0] )
282
283       If this seems confusing, remember that you can always use the
284       "$dur->in_units" method to specify exactly what you want.
285
286       Better yet, if you are trying to generate output suitable for humans,
287       use the "DateTime::Format::Duration" module.
288
289   Overloading
290       This class overloads addition, subtraction, and mutiplication.
291
292       Comparison is not overloaded. If you attempt to compare durations using
293       "<=>" or "cmp", then an exception will be thrown!  Use the "compare"
294       class method instead.
295

SEE ALSO

297       datetime@perl.org mailing list
298

SUPPORT

300       Support for this module is provided via the datetime@perl.org email
301       list. See http://lists.perl.org/ for more details.
302
303       Bugs may be submitted at
304       <https://github.com/houseabsolute/DateTime.pm/issues>.
305
306       There is a mailing list available for users of this distribution,
307       <mailto:datetime@perl.org>.
308

SOURCE

310       The source code repository for DateTime can be found at
311       <https://github.com/houseabsolute/DateTime.pm>.
312

AUTHOR

314       Dave Rolsky <autarch@urth.org>
315
317       This software is Copyright (c) 2003 - 2022 by Dave Rolsky.
318
319       This is free software, licensed under:
320
321         The Artistic License 2.0 (GPL Compatible)
322
323       The full text of the license can be found in the LICENSE file included
324       with this distribution.
325
326
327
328perl v5.36.0                      2023-01-20             DateTime::Duration(3)
Impressum