1DateTime::Duration(3) User Contributed Perl DocumentationDateTime::Duration(3)
2
6 DateTime::Duration - Duration objects for date math
7
9 version 1.52
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 );
24 my ( $days, $hours, $seconds ) = $dur->in_units('days', 'hours', 'seconds');
26 # Human-readable accessors, always positive, but consider using
28 # DateTime::Format::Duration instead
29 $dur->years;
30 $dur->months;
31 $dur->weeks;
32 $dur->days;
33 $dur->hours;
34 $dur->minutes;
35 $dur->seconds;
36 $dur->nanoseconds;
37 $dur->is_wrap_mode
39 $dur->is_limit_mode
40 $dur->is_preserve_mode
41 print $dur->end_of_month_mode;
43 # Multiply all values by -1
45 my $opposite = $dur->inverse;
46 my $bigger = $dur1 + $dur2;
48 my $smaller = $dur1 - $dur2; # the result could be negative
49 my $bigger = $dur1 * 3;
50 my $base_dt = DateTime->new( year => 2000 );
52 my @sorted =
53 sort { DateTime::Duration->compare( $a, $b, $base_dt ) } @durations;
54 if ( $dur->is_positive ) { ... }
56 if ( $dur->is_zero ) { ... }
57 if ( $dur->is_negative ) { ... }
58
60 This is a simple class for representing duration objects. These objects
61 are used whenever you do date math with DateTime.pm.
62 See the How DateTime Math Works section of the DateTime.pm
64 documentation for more details. The short course: One cannot in general
65 convert between seconds, minutes, days, and months, so this class will
66 never do so. Instead, create the duration with the desired units to
67 begin with, for example by calling the appropriate subtraction/delta
68 method on a "DateTime.pm" object.
69
71 Like "DateTime" itself, "DateTime::Duration" returns the object from
72 mutator methods in order to make method chaining possible.
73 "DateTime::Duration" has the following methods:
75 DateTime::Duration->new( ... )
77 This method takes the parameters "years", "months", "weeks", "days",
78 "hours", "minutes", "seconds", "nanoseconds", and "end_of_month". All
79 of these except "end_of_month" are numbers. If any of the numbers are
80 negative, the entire duration is negative.
81 All of the numbers must be integers.
83 Internally, years as just treated as 12 months. Similarly, weeks are
85 treated as 7 days, and hours are converted to minutes. Seconds and
86 nanoseconds are both treated separately.
87 The "end_of_month" parameter must be either "wrap", "limit", or
89 "preserve". This parameter specifies how date math that crosses the end
90 of a month is handled.
91 In "wrap" mode, adding months or years that result in days beyond the
93 end of the new month will roll over into the following month. For
94 instance, adding one year to Feb 29 will result in Mar 1.
95 If you specify "end_of_month" mode as "limit", the end of the month is
97 never crossed. Thus, adding one year to Feb 29, 2000 will result in Feb
98 28, 2001. If you were to then add three more years this will result in
99 Feb 28, 2004.
100 If you specify "end_of_month" mode as "preserve", the same calculation
102 is done as for "limit" except that if the original date is at the end
103 of the month the new date will also be. For instance, adding one month
104 to Feb 29, 2000 will result in Mar 31, 2000.
105 For positive durations, the "end_of_month" parameter defaults to wrap.
107 For negative durations, the default is "preserve". This should match
108 how most people "intuitively" expect datetime math to work.
109 $dur->clone()
111 Returns a new object with the same properties as the object on which
112 this method was called.
113 $dur->in_units( ... )
115 Returns the length of the duration in the units (any of those that can
116 be passed to "new") given as arguments. All lengths are integral, but
117 may be negative. Smaller units are computed from what remains after
118 taking away the larger units given, so for example:
119 my $dur = DateTime::Duration->new( years => 1, months => 15 );
121 $dur->in_units( 'years' ); # 2
123 $dur->in_units( 'months' ); # 27
124 $dur->in_units( 'years', 'months' ); # (2, 3)
125 $dur->in_units( 'weeks', 'days' ); # (0, 0) !
126 The last example demonstrates that there will not be any conversion
128 between units which don't have a fixed conversion rate. The only
129 conversions possible are:
130 · years <=> months
132 · weeks <=> days
134 · hours <=> minutes
136 · seconds <=> nanoseconds
138 For the explanation of why this is the case, please see the How
140 DateTime Math Works section of the DateTime.pm documentation
141 Note that the numbers returned by this method may not match the values
143 given to the constructor.
144 In list context, in_units returns the lengths in the order of the units
146 given. In scalar context, it returns the length in the first unit (but
147 still computes in terms of all given units).
148 If you need more flexibility in presenting information about durations,
150 please take a look a "DateTime::Format::Duration".
151 $dur->is_positive(), $dur->is_zero(), $dur->is_negative()
153 Indicates whether or not the duration is positive, zero, or negative.
154 If the duration contains both positive and negative units, then it will
156 return false for all of these methods.
157 $dur->is_wrap_mode(), $dur->is_limit_mode(), $dur->is_preserve_mode()
159 Indicates what mode is used for end of month wrapping.
160 $dur->end_of_month_mode()
162 Returns one of "wrap", "limit", or "preserve".
163 $dur->calendar_duration()
165 Returns a new object with the same calendar delta (months and days
166 only) and end of month mode as the current object.
167 $dur->clock_duration()
169 Returns a new object with the same clock deltas (minutes, seconds, and
170 nanoseconds) and end of month mode as the current object.
171 $dur->inverse( ... )
173 Returns a new object with the same deltas as the current object, but
174 multiple by -1. The end of month mode for the new object will be the
175 default end of month mode, which depends on whether the new duration is
176 positive or negative.
177 You can set the end of month mode in the inverted duration explicitly
179 by passing "end_of_month => ..." to the "inverse()" method.
180 $dur->add_duration( $duration_object ), $dur->subtract_duration(
182 $duration_object )
183 Adds or subtracts one duration from another.
184 $dur->add( ... ), $dur->subtract( ... )
186 These accept either constructor parameters for a new
187 "DateTime::Duration" object or an already-constructed duration object.
188 $dur->multiply( $number )
190 Multiplies each unit in the "DateTime::Duration" object by the
191 specified integer number.
192 DateTime::Duration->compare( $duration1, $duration2, $base_datetime )
194 This is a class method that can be used to compare or sort durations.
195 Comparison is done by adding each duration to the specified
196 "DateTime.pm" object and comparing the resulting datetimes. This is
197 necessary because without a base, many durations are not comparable.
198 For example, 1 month may or may not be longer than 29 days, depending
199 on what datetime it is added to.
200 If no base datetime is given, then the result of "DateTime->now" is
202 used instead. Using this default will give non-repeatable results if
203 used to compare two duration objects containing different units. It
204 will also give non-repeatable results if the durations contain multiple
205 types of units, such as months and days.
206 However, if you know that both objects only consist of one type of unit
208 (months or days or hours, etc.), and each duration contains the same
209 type of unit, then the results of the comparison will be repeatable.
210 $dur->delta_months(), $dur->delta_days(), $dur->delta_minutes(),
212 $dur->delta_seconds(), $dur->delta_nanoseconds()
213 These methods provide the information "DateTime.pm" needs for doing
214 date math. The numbers returned may be positive or negative. This is
215 mostly useful for doing date math in DateTime.
216 $dur->deltas()
218 Returns a hash with the keys "months", "days", "minutes", "seconds",
219 and "nanoseconds", containing all the delta information for the object.
220 This is mostly useful for doing date math in DateTime.
221 $dur->years(), $dur->months(), $dur->weeks(), $dur->days(), $dur->hours(),
223 $dur->minutes(), $dur->seconds(), $dur->nanoseconds()
224 These methods return numbers indicating how many of the given unit the
225 object represents, after having done a conversion to any larger units.
226 For example, days are first converted to weeks, and then the remainder
227 is returned. These numbers are always positive.
228 Here's what each method returns:
230 $dur->years() == abs( $dur->in_units('years') )
232 $dur->months() == abs( ( $dur->in_units( 'months', 'years' ) )[0] )
233 $dur->weeks() == abs( $dur->in_units( 'weeks' ) )
234 $dur->days() == abs( ( $dur->in_units( 'days', 'weeks' ) )[0] )
235 $dur->hours() == abs( $dur->in_units( 'hours' ) )
236 $dur->minutes == abs( ( $dur->in_units( 'minutes', 'hours' ) )[0] )
237 $dur->seconds == abs( $dur->in_units( 'seconds' ) )
238 $dur->nanoseconds() == abs( ( $dur->in_units( 'nanoseconds', 'seconds' ) )[0] )
239 If this seems confusing, remember that you can always use the
241 "in_units()" method to specify exactly what you want.
242 Better yet, if you are trying to generate output suitable for humans,
244 use the "DateTime::Format::Duration" module.
245 Overloading
247 This class overloads addition, subtraction, and mutiplication.
248 Comparison is not overloaded. If you attempt to compare durations using
250 "<=>" or "cmp", then an exception will be thrown! Use the "compare()"
251 class method instead.
252
254 datetime@perl.org mailing list
255 http://datetime.perl.org/
257
259 Support for this module is provided via the datetime@perl.org email
260 list. See http://lists.perl.org/ for more details.
261 Bugs may be submitted at
263 <https://github.com/houseabsolute/DateTime.pm/issues>.
264 There is a mailing list available for users of this distribution,
266 <mailto:datetime@perl.org>.
267 I am also usually active on IRC as 'autarch' on "irc://irc.perl.org".
269
271 The source code repository for DateTime can be found at
272 <https://github.com/houseabsolute/DateTime.pm>.
273
275 Dave Rolsky <autarch@urth.org>
276
278 This software is Copyright (c) 2003 - 2020 by Dave Rolsky.
279 This is free software, licensed under:
281 The Artistic License 2.0 (GPL Compatible)
283 The full text of the license can be found in the LICENSE file included
285 with this distribution.
286perl v5.32.0 2020-07-28 DateTime::Duration(3)