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",
83 "days", "hours", "minutes", "seconds", "nanoseconds", and
84 "end_of_month". All of these except "end_of_month" are numbers.
85 If any of the numbers are negative, the entire duration is nega‐
86 tive.
87 All of the numbers must be integers.
89 Internally, years as just treated as 12 months. Similarly, weeks
91 are treated as 7 days, and hours are converted to minutes. Seconds
92 and nanoseconds are both treated separately.
93 The "end_of_month" parameter must be either "wrap", "limit", or
95 "preserve". This parameter specifies how date math that crosses
96 the end of a month is handled.
97 In "wrap" mode, adding months or years that result in days beyond
99 the end of the new month will roll over into the following month.
100 For instance, adding one year to Feb 29 will result in Mar 1.
101 If you specify "end_of_month" mode as "limit", the end of the month
103 is never crossed. Thus, adding one year to Feb 29, 2000 will
104 result in Feb 28, 2001. If you were to then add three more years
105 this will result in Feb 28, 2004.
106 If you specify "end_of_month" mode as "preserve", the same calcula‐
108 tion is done as for "limit" except that if the original date is at
109 the end of the month the new date will also be. For instance,
110 adding one month to Feb 29, 2000 will result in Mar 31, 2000.
111 For positive durations, the "end_of_month" parameter defaults to
113 wrap. For negative durations, the default is "limit". This should
114 match how most people "intuitively" expect datetime math to work.
115 * clone
117 Returns a new object with the same properties as the object on
118 which this method was called.
119 * in_units( ... )
121 Returns the length of the duration in the units (any of those that
122 can be passed to new) given as arguments. All lengths are inte‐
123 gral, but may be negative. Smaller units are computed from what
124 remains after taking away the larger units given, so for example:
125 my $dur = DateTime::Duration->new( years => 1, months => 15 );
127 $dur->in_units( 'years' ); # 2
129 $dur->in_units( 'months' ); # 27
130 $dur->in_units( 'years', 'months' ); # (2, 3)
131 $dur->in_units( 'weeks', 'days' ); # (0, 0) !
132 The last example demonstrates that there will not be any conversion
134 between units which don't have a fixed conversion rate. The only
135 conversions possible are:
136 * year <=> months
138 * weeks <=> days
139 * hours <=> minutes
140 * seconds <=> nanoseconds
141 For the explanation of why this happens, please see the How Date
143 Math is Done section of the DateTime.pm documentation
144 Note that the numbers returned by this method may not match the
146 values given to the constructor.
147 In list context, in_units returns the lengths in the order of the
149 units given. In scalar context, it returns the length in the first
150 unit (but still computes in terms of all given units).
151 If you need more flexibility in presenting information about dura‐
153 tions, please take a look a "DateTime::Format::Duration".
154 * delta_months, delta_days, delta_minutes, delta_seconds,
156 delta_nanoseconds
157 These methods provide the information "DateTime.pm" needs for doing
158 date math. The numbers returned may be positive or negative.
159 * deltas
161 Returns a hash with the keys "months", "days", "minutes", "sec‐
162 onds", and "nanoseconds", containing all the delta information for
163 the object.
164 * is_positive, is_zero, is_negative
166 Indicates whether or not the duration is positive, zero, or nega‐
167 tive.
168 If the duration contains both positive and negative units, then it
170 will return false for all of these methods.
171 * is_wrap_mode, is_limit_mode, is_preserve_mode
173 Indicates what mode is used for end of month wrapping.
174 * end_of_month_mode
176 Returns one of "wrap", "limit", or "preserve".
177 * calendar_duration
179 Returns a new object with the same calendar delta (months only) and
180 end of month mode as the current object.
181 * clock_duration
183 Returns a new object with the same clock deltas (minutes, seconds,
184 and nanoseconds) and end of month mode as the current object.
185 * inverse
187 Returns a new object with the same deltas as the current object,
188 but multiple by -1. The end of month mode for the new object will
189 be the default end of month mode, which depends on whether the new
190 duration is positive or negative.
191 * add_duration( $duration_object ), subtract_duration( $duration_object
193 )
194 Adds or subtracts one duration from another.
195 * add( ... ), subtract( ... )
197 Syntactic sugar for addition and subtraction. The parameters given
198 to these methods are used to create a new object, which is then
199 passed to "add_duration()" or "subtract_duration()", as appropri‐
200 ate.
201 * multiply( $number )
203 Multiplies each unit in the by the specified number.
204 * DateTime::Duration->compare( $duration1, $duration2, $base_datetime )
206 This is a class method that can be used to compare or sort dura‐
207 tions. Comparison is done by adding each duration to the specified
208 "DateTime.pm" object and comparing the resulting datetimes. This
209 is necessary because without a base, many durations are not compa‐
210 rable. For example, 1 month may otr may not be longer than 29
211 days, depending on what datetime it is added to.
212 If no base datetime is given, then the result of "DateTime->now" is
214 used instead. Using this default will give non-repeatable results
215 if used to compare two duration objects containing different units.
216 It will also give non-repeatable results if the durations contain
217 multiple types of units, such as months and days.
218 However, if you know that both objects only contain the same units,
220 and just a single type, then the results of the comparison will be
221 repeatable.
222 * years, months, weeks, days, hours, minutes, seconds, nanoseconds
224 These methods return numbers indicating how many of the given unit
225 the object represents, after having done a conversion to any larger
226 units. For example, days are first converted to weeks, and then
227 the remainder is returned. These numbers are always positive.
228 Here's what each method returns:
230 $dur->year() == 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' ) )
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
244 humans, use the "DateTime::Format::Duration" module.
245 Overloading
247 This class overloads addition, subtraction, and mutiplication.
249 Comparison is not overloaded. If you attempt to compare durations
251 using "<=>" or "cmp", then an exception will be thrown! Use the "com‐
252 pare()" class method instead.
253
255 Support for this module is provided via the datetime@perl.org email
256 list. See http://lists.perl.org/ for more details.
257
259 Dave Rolsky <autarch@urth.org>
260 However, please see the CREDITS file for more details on who I really
262 stole all the code from.
263
265 Copyright (c) 2003-2006 David Rolsky. All rights reserved. This pro‐
266 gram is free software; you can redistribute it and/or modify it under
267 the same terms as Perl itself.
268 Portions of the code in this distribution are derived from other works.
270 Please see the CREDITS file for more details.
271 The full text of the license can be found in the LICENSE file included
273 with this module.
274
276 datetime@perl.org mailing list
277 http://datetime.perl.org/
279perl v5.8.8 2007-03-30 DateTime::Duration(3)