1DateTime::Duration(3) User Contributed Perl DocumentationDateTime::Duration(3)
2
6 DateTime::Duration - Duration objects for date math
7
9 version 1.57
10
12 use DateTime::Duration;
13 $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 my ( $days, $hours, $seconds )
27 = $dur->in_units( 'days', 'hours', 'seconds' );
28 # 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 $dur->is_wrap_mode;
41 $dur->is_limit_mode;
42 $dur->is_preserve_mode;
43 print $dur->end_of_month_mode;
45 # Multiply all values by -1
47 my $opposite = $dur->inverse;
48 my $bigger = $dur1 + $dur2;
50 my $smaller = $dur1 - $dur2; # the result could be negative
51 my $bigger = $dur1 * 3;
52 my $base_dt = DateTime->new( year => 2000 );
54 my @sorted
55 = sort { DateTime::Duration->compare( $a, $b, $base_dt ) } @durations;
56 if ( $dur->is_positive ) {...}
58 if ( $dur->is_zero ) {...}
59 if ( $dur->is_negative ) {...}
60
62 This is a simple class for representing duration objects. These objects
63 are used whenever you do date math with DateTime.
64 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
73 Like DateTime itself, "DateTime::Duration" returns the object from
74 mutator methods in order to make method chaining possible.
75 "DateTime::Duration" has the following methods:
77 DateTime::Duration->new( ... )
79 This class method accepts the following parameters:
80 • years
82 An integer containing the number of years in the duration. This is
84 optional.
85 • months
87 An integer containing the number of months in the duration. This is
89 optional.
90 • weeks
92 An integer containing the number of weeks in the duration. This is
94 optional.
95 • days
97 An integer containing the number of days in the duration. This is
99 optional.
100 • hours
102 An integer containing the number of hours in the duration. This is
104 optional.
105 • minutes
107 An integer containing the number of minutes in the duration. This
109 is optional.
110 • seconds
112 An integer containing the number of seconds in the duration. This
114 is optional.
115 • nanoseconds
117 An integer containing the number of nanoseconds in the duration.
119 This is optional.
120 • end_of_month
122 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 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 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 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 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 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 All of the numbers must be integers.
148 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 $dur->clone
154 Returns a new object with the same properties as the object on which
155 this method was called.
156 $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 my $dur = DateTime::Duration->new( years => 1, months => 15 );
164 $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 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 • years <=> months
175 • weeks <=> days
177 • hours <=> minutes
179 • seconds <=> nanoseconds
181 For the explanation of why this is the case, please see the How
183 DateTime Math Works section of the DateTime documentation
184 Note that the numbers returned by this method may not match the values
186 given to the constructor.
187 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 If you need more flexibility in presenting information about durations,
193 please take a look a DateTime::Format::Duration.
194 $dur->is_positive, $dur->is_zero, $dur->is_negative
196 Indicates whether or not the duration is positive, zero, or negative.
197 If the duration contains both positive and negative units, then it will
199 return false for all of these methods.
200 $dur->is_wrap_mode, $dur->is_limit_mode, $dur->is_preserve_mode
202 Indicates what mode is used for end of month wrapping.
203 $dur->end_of_month_mode
205 Returns one of "wrap", "limit", or "preserve".
206 $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 $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 $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 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 $dur->add_duration($duration_object),
225 $dur->subtract_duration($duration_object)
226 Adds or subtracts one duration from another.
227 $dur->add( ... ), $dur->subtract( ... )
229 These accept either constructor parameters for a new
230 "DateTime::Duration" object or an already-constructed duration object.
231 $dur->multiply($number)
233 Multiplies each unit in the "DateTime::Duration" object by the
234 specified integer number.
235 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 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 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 $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 $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 $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 Here's what each method returns:
273 $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 If this seems confusing, remember that you can always use the
284 "$dur->in_units" method to specify exactly what you want.
285 Better yet, if you are trying to generate output suitable for humans,
287 use the "DateTime::Format::Duration" module.
288 Overloading
290 This class overloads addition, subtraction, and mutiplication.
291 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
297 datetime@perl.org mailing list
298
300 Support for this module is provided via the datetime@perl.org email
301 list. See http://lists.perl.org/ for more details.
302 Bugs may be submitted at
304 <https://github.com/houseabsolute/DateTime.pm/issues>.
305 There is a mailing list available for users of this distribution,
307 <mailto:datetime@perl.org>.
308
310 The source code repository for DateTime can be found at
311 <https://github.com/houseabsolute/DateTime.pm>.
312
314 Dave Rolsky <autarch@urth.org>
315
317 This software is Copyright (c) 2003 - 2022 by Dave Rolsky.
318 This is free software, licensed under:
320 The Artistic License 2.0 (GPL Compatible)
322 The full text of the license can be found in the LICENSE file included
324 with this distribution.
325perl v5.34.0 2022-03-03 DateTime::Duration(3)