1DateTime::Duration(3) User Contributed Perl DocumentationDateTime::Duration(3)
2
6 DateTime::Duration - Duration objects for date math
7
9 use DateTime::Duration;
10 $d = DateTime::Duration->new( years => 3,
12 months => 5,
13 weeks => 1,
14 days => 1,
15 hours => 6,
16 minutes => 15,
17 seconds => 45,
18 nanoseconds => 12000 );
19 # Convert to different units
21 $d->in_units('days', 'hours', 'seconds');
22 # The important parts for date math
24 $d->delta_months
25 $d->delta_days
26 $d->delta_minutes
27 $d->delta_seconds
28 $d->delta_nanoseconds
29 my %deltas = $d->deltas
31 $d->is_wrap_mode
33 $d->is_limit_mode
34 $d->is_preserve_mode
35 print $d->end_of_month_mode;
37 # Multiple all deltas by -1
39 my $opposite = $d->inverse;
40 my $bigger = $dur1 + $dur2;
42 my $smaller = $dur1 - $dur2; # the result could be negative
43 my $bigger = $dur1 * 3;
44 my $base_dt = DateTime->new( year => 2000 );
46 my @sorted =
47 sort { DateTime::Duration->compare( $a, $b, $base_dt ) } @durations;
48 # Human-readable accessors, always positive, but use
50 # DateTime::Format::Duration instead
51 $d->years;
52 $d->months;
53 $d->weeks;
54 $d->days;
55 $d->hours;
56 $d->minutes;
57 $d->seconds;
58 $d->nanoseconds;
59 if ( $d->is_positive ) { ... }
61 if ( $d->is_zero ) { ... }
62 if ( $d->is_negative ) { ... }
63
65 This is a simple class for representing duration objects. These
66 objects are used whenever you do date math with DateTime.pm.
67 See the How Date Math is Done section of the DateTime.pm documentation
69 for more details. The short course: One cannot in general convert
70 between seconds, minutes, days, and months, so this class will never do
71 so. Instead, create the duration with the desired units to begin with,
72 for example by calling the appropriate subtraction/delta method on a
73 "DateTime.pm" object.
74
76 Like "DateTime" itself, "DateTime::Duration" returns the object from
77 mutator methods in order to make method chaining possible.
78 "DateTime::Duration" has the following methods:
80 · new( ... )
82 This method takes the parameters "years", "months", "weeks",
84 "days", "hours", "minutes", "seconds", "nanoseconds", and
85 "end_of_month". All of these except "end_of_month" are numbers.
86 If any of the numbers are negative, the entire duration is
87 negative.
88 All of the numbers must be integers.
90 Internally, years as just treated as 12 months. Similarly, weeks
92 are treated as 7 days, and hours are converted to minutes. Seconds
93 and nanoseconds are both treated separately.
94 The "end_of_month" parameter must be either "wrap", "limit", or
96 "preserve". This parameter specifies how date math that crosses
97 the end of a month is handled.
98 In "wrap" mode, adding months or years that result in days beyond
100 the end of the new month will roll over into the following month.
101 For instance, adding one year to Feb 29 will result in Mar 1.
102 If you specify "end_of_month" mode as "limit", the end of the month
104 is never crossed. Thus, adding one year to Feb 29, 2000 will
105 result in Feb 28, 2001. If you were to then add three more years
106 this will result in Feb 28, 2004.
107 If you specify "end_of_month" mode as "preserve", the same
109 calculation is done as for "limit" except that if the original date
110 is at the end of the month the new date will also be. For
111 instance, adding one month to Feb 29, 2000 will result in Mar 31,
112 2000.
113 For positive durations, the "end_of_month" parameter defaults to
115 wrap. For negative durations, the default is "limit". This should
116 match how most people "intuitively" expect datetime math to work.
117 · clone
119 Returns a new object with the same properties as the object on
121 which this method was called.
122 · in_units( ... )
124 Returns the length of the duration in the units (any of those that
126 can be passed to new) given as arguments. All lengths are
127 integral, but may be negative. Smaller units are computed from
128 what remains after taking away the larger units given, so for
129 example:
130 my $dur = DateTime::Duration->new( years => 1, months => 15 );
132 $dur->in_units( 'years' ); # 2
134 $dur->in_units( 'months' ); # 27
135 $dur->in_units( 'years', 'months' ); # (2, 3)
136 $dur->in_units( 'weeks', 'days' ); # (0, 0) !
137 The last example demonstrates that there will not be any conversion
139 between units which don't have a fixed conversion rate. The only
140 conversions possible are:
141 · years <=> months
143 · weeks <=> days
145 · hours <=> minutes
147 · seconds <=> nanoseconds
149 For the explanation of why this happens, please see the How Date
151 Math is Done section of the DateTime.pm documentation
152 Note that the numbers returned by this method may not match the
154 values given to the constructor.
155 In list context, in_units returns the lengths in the order of the
157 units given. In scalar context, it returns the length in the first
158 unit (but still computes in terms of all given units).
159 If you need more flexibility in presenting information about
161 durations, please take a look a "DateTime::Format::Duration".
162 · delta_months, delta_days, delta_minutes, delta_seconds,
164 delta_nanoseconds
165 These methods provide the information "DateTime.pm" needs for doing
167 date math. The numbers returned may be positive or negative.
168 · deltas
170 Returns a hash with the keys "months", "days", "minutes",
172 "seconds", and "nanoseconds", containing all the delta information
173 for the object.
174 · is_positive, is_zero, is_negative
176 Indicates whether or not the duration is positive, zero, or
178 negative.
179 If the duration contains both positive and negative units, then it
181 will return false for all of these methods.
182 · is_wrap_mode, is_limit_mode, is_preserve_mode
184 Indicates what mode is used for end of month wrapping.
186 · end_of_month_mode
188 Returns one of "wrap", "limit", or "preserve".
190 · calendar_duration
192 Returns a new object with the same calendar delta (months and days
194 only) and end of month mode as the current object.
195 · clock_duration
197 Returns a new object with the same clock deltas (minutes, seconds,
199 and nanoseconds) and end of month mode as the current object.
200 · inverse
202 Returns a new object with the same deltas as the current object,
204 but multiple by -1. The end of month mode for the new object will
205 be the default end of month mode, which depends on whether the new
206 duration is positive or negative.
207 · add_duration( $duration_object ), subtract_duration(
209 $duration_object )
210 Adds or subtracts one duration from another.
212 · add( ... ), subtract( ... )
214 Syntactic sugar for addition and subtraction. The parameters given
216 to these methods are used to create a new object, which is then
217 passed to "add_duration()" or "subtract_duration()", as
218 appropriate.
219 · multiply( $number )
221 Multiplies each unit in the by the specified number.
223 · DateTime::Duration->compare( $duration1, $duration2, $base_datetime
225 )
226 This is a class method that can be used to compare or sort
228 durations. Comparison is done by adding each duration to the
229 specified "DateTime.pm" object and comparing the resulting
230 datetimes. This is necessary because without a base, many
231 durations are not comparable. For example, 1 month may or may not
232 be longer than 29 days, depending on what datetime it is added to.
233 If no base datetime is given, then the result of "DateTime->now" is
235 used instead. Using this default will give non-repeatable results
236 if used to compare two duration objects containing different units.
237 It will also give non-repeatable results if the durations contain
238 multiple types of units, such as months and days.
239 However, if you know that both objects only consist of one type of
241 unit (months or days or hours, etc.), and each duration contains
242 the same type of unit, then the results of the comparison will be
243 repeatable.
244 · years, months, weeks, days, hours, minutes, seconds, nanoseconds
246 These methods return numbers indicating how many of the given unit
248 the object represents, after having done a conversion to any larger
249 units. For example, days are first converted to weeks, and then
250 the remainder is returned. These numbers are always positive.
251 Here's what each method returns:
253 $dur->years() == abs( $dur->in_units('years') )
255 $dur->months() == abs( ( $dur->in_units( 'months', 'years' ) )[0] )
256 $dur->weeks() == abs( $dur->in_units( 'weeks' ) )
257 $dur->days() == abs( ( $dur->in_units( 'days', 'weeks' ) )[0] )
258 $dur->hours() == abs( $dur->in_units( 'hours' ) )
259 $dur->minutes == abs( ( $dur->in_units( 'minutes', 'hours' ) )[0] )
260 $dur->seconds == abs( $dur->in_units( 'seconds' ) )
261 $dur->nanoseconds() == abs( ( $dur->in_units( 'nanoseconds', 'seconds' ) )[0] )
262 If this seems confusing, remember that you can always use the
264 "in_units()" method to specify exactly what you want.
265 Better yet, if you are trying to generate output suitable for
267 humans, use the "DateTime::Format::Duration" module.
268 Overloading
270 This class overloads addition, subtraction, and mutiplication.
271 Comparison is not overloaded. If you attempt to compare durations
273 using "<=>" or "cmp", then an exception will be thrown! Use the
274 "compare()" class method instead.
275
277 Support for this module is provided via the datetime@perl.org email
278 list. See http://lists.perl.org/ for more details.
279
281 Dave Rolsky <autarch@urth.org>
282 However, please see the CREDITS file for more details on who I really
284 stole all the code from.
285
287 Copyright (c) 2003-2009 David Rolsky. All rights reserved. This
288 program is free software; you can redistribute it and/or modify it
289 under the same terms as Perl itself.
290 Portions of the code in this distribution are derived from other works.
292 Please see the CREDITS file for more details.
293 The full text of the license can be found in the LICENSE file included
295 with this module.
296
298 datetime@perl.org mailing list
299 http://datetime.perl.org/
301perl v5.10.1 2017-03-21 DateTime::Duration(3)