1DateTime::Duration(3) User Contributed Perl DocumentationDateTime::Duration(3)
2
3
4

NAME

6       DateTime::Duration - Duration objects for date math
7

VERSION

9       version 1.50
10

SYNOPSIS

12         use DateTime::Duration;
13
14         $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
25         my ( $days, $hours, $seconds ) = $dur->in_units('days', 'hours', 'seconds');
26
27         # 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
38         $dur->is_wrap_mode
39         $dur->is_limit_mode
40         $dur->is_preserve_mode
41
42         print $dur->end_of_month_mode;
43
44         # Multiply all values by -1
45         my $opposite = $dur->inverse;
46
47         my $bigger  = $dur1 + $dur2;
48         my $smaller = $dur1 - $dur2; # the result could be negative
49         my $bigger  = $dur1 * 3;
50
51         my $base_dt = DateTime->new( year => 2000 );
52         my @sorted =
53             sort { DateTime::Duration->compare( $a, $b, $base_dt ) } @durations;
54
55         if ( $dur->is_positive ) { ... }
56         if ( $dur->is_zero )     { ... }
57         if ( $dur->is_negative ) { ... }
58

DESCRIPTION

60       This is a simple class for representing duration objects. These objects
61       are used whenever you do date math with DateTime.pm.
62
63       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

METHODS

71       Like "DateTime" itself, "DateTime::Duration" returns the object from
72       mutator methods in order to make method chaining possible.
73
74       "DateTime::Duration" has the following methods:
75
76   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
82       All of the numbers must be integers.
83
84       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
88       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
92       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
96       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
101       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
106       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
110   $dur->clone()
111       Returns a new object with the same properties as the object on which
112       this method was called.
113
114   $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
120         my $dur = DateTime::Duration->new( years => 1, months => 15 );
121
122         $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
127       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
131       ·       years <=> months
132
133       ·       weeks <=> days
134
135       ·       hours <=> minutes
136
137       ·       seconds <=> nanoseconds
138
139       For the explanation of why this is the case, please see the How
140       DateTime Math Works section of the DateTime.pm documentation
141
142       Note that the numbers returned by this method may not match the values
143       given to the constructor.
144
145       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
149       If you need more flexibility in presenting information about durations,
150       please take a look a "DateTime::Format::Duration".
151
152   $dur->is_positive(), $dur->is_zero(), $dur->is_negative()
153       Indicates whether or not the duration is positive, zero, or negative.
154
155       If the duration contains both positive and negative units, then it will
156       return false for all of these methods.
157
158   $dur->is_wrap_mode(), $dur->is_limit_mode(), $dur->is_preserve_mode()
159       Indicates what mode is used for end of month wrapping.
160
161   $dur->end_of_month_mode()
162       Returns one of "wrap", "limit", or "preserve".
163
164   $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
168   $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
172   $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
178       You can set the end of month mode in the inverted duration explicitly
179       by passing "end_of_month => ..." to the "inverse()" method.
180
181   $dur->add_duration( $duration_object ), $dur->subtract_duration(
182       $duration_object )
183       Adds or subtracts one duration from another.
184
185   $dur->add( ... ), $dur->subtract( ... )
186       These accept either constructor parameters for a new
187       "DateTime::Duration" object or an already-constructed duration object.
188
189   $dur->multiply( $number )
190       Multiplies each unit in the by the specified integer number.
191
192   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
200       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
206       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
210   $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
216   $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
221   $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
228       Here's what each method returns:
229
230        $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
239       If this seems confusing, remember that you can always use the
240       "in_units()" method to specify exactly what you want.
241
242       Better yet, if you are trying to generate output suitable for humans,
243       use the "DateTime::Format::Duration" module.
244
245   Overloading
246       This class overloads addition, subtraction, and mutiplication.
247
248       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

SEE ALSO

253       datetime@perl.org mailing list
254
255       http://datetime.perl.org/
256

SUPPORT

258       Support for this module is provided via the datetime@perl.org email
259       list. See http://lists.perl.org/ for more details.
260
261       Bugs may be submitted at
262       <https://github.com/houseabsolute/DateTime.pm/issues>.
263
264       There is a mailing list available for users of this distribution,
265       <mailto:datetime@perl.org>.
266
267       I am also usually active on IRC as 'autarch' on "irc://irc.perl.org".
268

SOURCE

270       The source code repository for DateTime can be found at
271       <https://github.com/houseabsolute/DateTime.pm>.
272

AUTHOR

274       Dave Rolsky <autarch@urth.org>
275
277       This software is Copyright (c) 2003 - 2018 by Dave Rolsky.
278
279       This is free software, licensed under:
280
281         The Artistic License 2.0 (GPL Compatible)
282
283       The full text of the license can be found in the LICENSE file included
284       with this distribution.
285
286
287
288perl v5.28.0                      2018-08-01             DateTime::Duration(3)
Impressum