1DateTime::Duration(3) User Contributed Perl DocumentationDateTime::Duration(3)
2
6 DateTime::Duration - Duration objects for date math
7
9 version 1.50
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 by the specified integer number.
191 DateTime::Duration->compare( $duration1, $duration2, $base_datetime )
193 This is a class method that can be used to compare or sort durations.
194 Comparison is done by adding each duration to the specified
195 "DateTime.pm" object and comparing the resulting datetimes. This is
196 necessary because without a base, many durations are not comparable.
197 For example, 1 month may or may not be longer than 29 days, depending
198 on what datetime it is added to.
199 If no base datetime is given, then the result of "DateTime->now" is
201 used instead. Using this default will give non-repeatable results if
202 used to compare two duration objects containing different units. It
203 will also give non-repeatable results if the durations contain multiple
204 types of units, such as months and days.
205 However, if you know that both objects only consist of one type of unit
207 (months or days or hours, etc.), and each duration contains the same
208 type of unit, then the results of the comparison will be repeatable.
209 $dur->delta_months(), $dur->delta_days(), $dur->delta_minutes(),
211 $dur->delta_seconds(), $dur->delta_nanoseconds()
212 These methods provide the information "DateTime.pm" needs for doing
213 date math. The numbers returned may be positive or negative. This is
214 mostly useful for doing date math in DateTime.
215 $dur->deltas()
217 Returns a hash with the keys "months", "days", "minutes", "seconds",
218 and "nanoseconds", containing all the delta information for the object.
219 This is mostly useful for doing date math in DateTime.
220 $dur->years(), $dur->months(), $dur->weeks(), $dur->days(), $dur->hours(),
222 $dur->minutes(), $dur->seconds(), $dur->nanoseconds()
223 These methods return numbers indicating how many of the given unit the
224 object represents, after having done a conversion to any larger units.
225 For example, days are first converted to weeks, and then the remainder
226 is returned. These numbers are always positive.
227 Here's what each method returns:
229 $dur->years() == abs( $dur->in_units('years') )
231 $dur->months() == abs( ( $dur->in_units( 'months', 'years' ) )[0] )
232 $dur->weeks() == abs( $dur->in_units( 'weeks' ) )
233 $dur->days() == abs( ( $dur->in_units( 'days', 'weeks' ) )[0] )
234 $dur->hours() == abs( $dur->in_units( 'hours' ) )
235 $dur->minutes == abs( ( $dur->in_units( 'minutes', 'hours' ) )[0] )
236 $dur->seconds == abs( $dur->in_units( 'seconds' ) )
237 $dur->nanoseconds() == abs( ( $dur->in_units( 'nanoseconds', 'seconds' ) )[0] )
238 If this seems confusing, remember that you can always use the
240 "in_units()" method to specify exactly what you want.
241 Better yet, if you are trying to generate output suitable for humans,
243 use the "DateTime::Format::Duration" module.
244 Overloading
246 This class overloads addition, subtraction, and mutiplication.
247 Comparison is not overloaded. If you attempt to compare durations using
249 "<=>" or "cmp", then an exception will be thrown! Use the "compare()"
250 class method instead.
251
253 datetime@perl.org mailing list
254 http://datetime.perl.org/
256
258 Support for this module is provided via the datetime@perl.org email
259 list. See http://lists.perl.org/ for more details.
260 Bugs may be submitted at
262 <https://github.com/houseabsolute/DateTime.pm/issues>.
263 There is a mailing list available for users of this distribution,
265 <mailto:datetime@perl.org>.
266 I am also usually active on IRC as 'autarch' on "irc://irc.perl.org".
268
270 The source code repository for DateTime can be found at
271 <https://github.com/houseabsolute/DateTime.pm>.
272
274 Dave Rolsky <autarch@urth.org>
275
277 This software is Copyright (c) 2003 - 2018 by Dave Rolsky.
278 This is free software, licensed under:
280 The Artistic License 2.0 (GPL Compatible)
282 The full text of the license can be found in the LICENSE file included
284 with this distribution.
285perl v5.28.0 2018-08-01 DateTime::Duration(3)