1DateTime::Duration(3) User Contributed Perl DocumentationDateTime::Duration(3)
2
6 DateTime::Duration - Duration objects for date math
7
9 version 0.70
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 Date Math is Done section of the DateTime.pm documentation
64 for more details. The short course: One cannot in general convert
65 between seconds, minutes, days, and months, so this class will never do
66 so. Instead, create the duration with the desired units to begin with,
67 for example by calling the appropriate subtraction/delta method on a
68 "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 · new( ... )
77 This method takes the parameters "years", "months", "weeks",
79 "days", "hours", "minutes", "seconds", "nanoseconds", and
80 "end_of_month". All of these except "end_of_month" are numbers. If
81 any of the numbers are negative, the entire duration is negative.
82 All of the numbers must be integers.
84 Internally, years as just treated as 12 months. Similarly, weeks
86 are treated as 7 days, and hours are converted to minutes. Seconds
87 and nanoseconds are both treated separately.
88 The "end_of_month" parameter must be either "wrap", "limit", or
90 "preserve". This parameter specifies how date math that crosses the
91 end of a month is handled.
92 In "wrap" mode, adding months or years that result in days beyond
94 the end of the new month will roll over into the following month.
95 For instance, adding one year to Feb 29 will result in Mar 1.
96 If you specify "end_of_month" mode as "limit", the end of the month
98 is never crossed. Thus, adding one year to Feb 29, 2000 will result
99 in Feb 28, 2001. If you were to then add three more years this will
100 result in Feb 28, 2004.
101 If you specify "end_of_month" mode as "preserve", the same
103 calculation is done as for "limit" except that if the original date
104 is at the end of the month the new date will also be. For instance,
105 adding one month to Feb 29, 2000 will result in Mar 31, 2000.
106 For positive durations, the "end_of_month" parameter defaults to
108 wrap. For negative durations, the default is "limit". This should
109 match how most people "intuitively" expect datetime math to work.
110 · clone
112 Returns a new object with the same properties as the object on
114 which this method was called.
115 · in_units( ... )
117 Returns the length of the duration in the units (any of those that
119 can be passed to new) given as arguments. All lengths are integral,
120 but may be negative. Smaller units are computed from what remains
121 after taking away the larger units given, so for example:
122 my $dur = DateTime::Duration->new( years => 1, months => 15 );
124 $dur->in_units( 'years' ); # 2
126 $dur->in_units( 'months' ); # 27
127 $dur->in_units( 'years', 'months' ); # (2, 3)
128 $dur->in_units( 'weeks', 'days' ); # (0, 0) !
129 The last example demonstrates that there will not be any conversion
131 between units which don't have a fixed conversion rate. The only
132 conversions possible are:
133 · years <=> months
135 · weeks <=> days
137 · hours <=> minutes
139 · seconds <=> nanoseconds
141 For the explanation of why this is the case, please see the How
143 Datetime Math Works 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
153 durations, please take a look a "DateTime::Format::Duration".
154 · is_positive, is_zero, is_negative
156 Indicates whether or not the duration is positive, zero, or
158 negative.
159 If the duration contains both positive and negative units, then it
161 will return false for all of these methods.
162 · is_wrap_mode, is_limit_mode, is_preserve_mode
164 Indicates what mode is used for end of month wrapping.
166 · end_of_month_mode
168 Returns one of "wrap", "limit", or "preserve".
170 · calendar_duration
172 Returns a new object with the same calendar delta (months and days
174 only) and end of month mode as the current object.
175 · clock_duration
177 Returns a new object with the same clock deltas (minutes, seconds,
179 and nanoseconds) and end of month mode as the current object.
180 · inverse( ... )
182 Returns a new object with the same deltas as the current object,
184 but multiple by -1. The end of month mode for the new object will
185 be the default end of month mode, which depends on whether the new
186 duration is positive or negative.
187 You can set the end of month mode in the inverted duration
189 explicitly by passing "end_of_month => ..." to the "inverse()"
190 method.
191 · add_duration( $duration_object ), subtract_duration(
193 $duration_object )
194 Adds or subtracts one duration from another.
196 · add( ... ), subtract( ... )
198 Syntactic sugar for addition and subtraction. The parameters given
200 to these methods are used to create a new object, which is then
201 passed to "add_duration()" or "subtract_duration()", as
202 appropriate.
203 · multiply( $number )
205 Multiplies each unit in the by the specified number.
207 · DateTime::Duration->compare( $duration1, $duration2, $base_datetime
209 )
210 This is a class method that can be used to compare or sort
212 durations. Comparison is done by adding each duration to the
213 specified "DateTime.pm" object and comparing the resulting
214 datetimes. This is necessary because without a base, many durations
215 are not comparable. For example, 1 month may or may not be longer
216 than 29 days, depending on what datetime it is added to.
217 If no base datetime is given, then the result of "DateTime->now" is
219 used instead. Using this default will give non-repeatable results
220 if used to compare two duration objects containing different units.
221 It will also give non-repeatable results if the durations contain
222 multiple types of units, such as months and days.
223 However, if you know that both objects only consist of one type of
225 unit (months or days or hours, etc.), and each duration contains
226 the same type of unit, then the results of the comparison will be
227 repeatable.
228 · delta_months, delta_days, delta_minutes, delta_seconds,
230 delta_nanoseconds
231 These methods provide the information "DateTime.pm" needs for doing
233 date math. The numbers returned may be positive or negative. This
234 is mostly useful for doing date math in DateTime.
235 · deltas
237 Returns a hash with the keys "months", "days", "minutes",
239 "seconds", and "nanoseconds", containing all the delta information
240 for the object. This is mostly useful for doing date math in
241 DateTime.
242 · years, months, weeks, days, hours, minutes, seconds, nanoseconds
244 These methods return numbers indicating how many of the given unit
246 the object represents, after having done a conversion to any larger
247 units. For example, days are first converted to weeks, and then
248 the remainder is returned. These numbers are always positive.
249 Here's what each method returns:
251 $dur->years() == abs( $dur->in_units('years') )
253 $dur->months() == abs( ( $dur->in_units( 'months', 'years' ) )[0] )
254 $dur->weeks() == abs( $dur->in_units( 'weeks' ) )
255 $dur->days() == abs( ( $dur->in_units( 'days', 'weeks' ) )[0] )
256 $dur->hours() == abs( $dur->in_units( 'hours' ) )
257 $dur->minutes == abs( ( $dur->in_units( 'minutes', 'hours' ) )[0] )
258 $dur->seconds == abs( $dur->in_units( 'seconds' ) )
259 $dur->nanoseconds() == abs( ( $dur->in_units( 'nanoseconds', 'seconds' ) )[0] )
260 If this seems confusing, remember that you can always use the
262 "in_units()" method to specify exactly what you want.
263 Better yet, if you are trying to generate output suitable for
265 humans, use the "DateTime::Format::Duration" module.
266 Overloading
268 This class overloads addition, subtraction, and mutiplication.
269 Comparison is not overloaded. If you attempt to compare durations using
271 "<=>" or "cmp", then an exception will be thrown! Use the "compare()"
272 class method instead.
273
275 Support for this module is provided via the datetime@perl.org email
276 list. See http://lists.perl.org/ for more details.
277
279 datetime@perl.org mailing list
280 http://datetime.perl.org/
282
284 Dave Rolsky <autarch@urth.org>
285
287 This software is Copyright (c) 2011 by Dave Rolsky.
288 This is free software, licensed under:
290 The Artistic License 2.0 (GPL Compatible)
292perl v5.12.3 2011-08-30 DateTime::Duration(3)