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.52
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 "DateTime::Duration" object by the
191       specified integer number.
192
193   DateTime::Duration->compare( $duration1, $duration2, $base_datetime )
194       This is a class method that can be used to compare or sort durations.
195       Comparison is done by adding each duration to the specified
196       "DateTime.pm" object and comparing the resulting datetimes. This is
197       necessary because without a base, many durations are not comparable.
198       For example, 1 month may or may not be longer than 29 days, depending
199       on what datetime it is added to.
200
201       If no base datetime is given, then the result of "DateTime->now" is
202       used instead. Using this default will give non-repeatable results if
203       used to compare two duration objects containing different units.  It
204       will also give non-repeatable results if the durations contain multiple
205       types of units, such as months and days.
206
207       However, if you know that both objects only consist of one type of unit
208       (months or days or hours, etc.), and each duration contains the same
209       type of unit, then the results of the comparison will be repeatable.
210
211   $dur->delta_months(), $dur->delta_days(), $dur->delta_minutes(),
212       $dur->delta_seconds(), $dur->delta_nanoseconds()
213       These methods provide the information "DateTime.pm" needs for doing
214       date math. The numbers returned may be positive or negative. This is
215       mostly useful for doing date math in DateTime.
216
217   $dur->deltas()
218       Returns a hash with the keys "months", "days", "minutes", "seconds",
219       and "nanoseconds", containing all the delta information for the object.
220       This is mostly useful for doing date math in DateTime.
221
222   $dur->years(), $dur->months(), $dur->weeks(), $dur->days(), $dur->hours(),
223       $dur->minutes(), $dur->seconds(), $dur->nanoseconds()
224       These methods return numbers indicating how many of the given unit the
225       object represents, after having done a conversion to any larger units.
226       For example, days are first converted to weeks, and then the remainder
227       is returned. These numbers are always positive.
228
229       Here's what each method returns:
230
231        $dur->years()       == 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' ) )[0] )
239
240       If this seems confusing, remember that you can always use the
241       "in_units()" method to specify exactly what you want.
242
243       Better yet, if you are trying to generate output suitable for humans,
244       use the "DateTime::Format::Duration" module.
245
246   Overloading
247       This class overloads addition, subtraction, and mutiplication.
248
249       Comparison is not overloaded. If you attempt to compare durations using
250       "<=>" or "cmp", then an exception will be thrown!  Use the "compare()"
251       class method instead.
252

SEE ALSO

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

SUPPORT

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

SOURCE

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

AUTHOR

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