DateTime::Duration
DateTime::Duration(3)User Contributed Perl DocumentationDateTime::Duration(3)
NAME
DateTime::Duration - Duration objects for date math
SYNOPSIS
use DateTime::Duration;
$d = DateTime::Duration->new( years => 3,
months => 5,
weeks => 1,
days => 1,
hours => 6,
minutes => 15,
seconds => 45,
nanoseconds => 12000 );
# Convert to different units
$d->in_units(’days’, ’hours’, ’seconds’);
# The important parts for date math
$d->delta_months
$d->delta_days
$d->delta_minutes
$d->delta_seconds
$d->delta_nanoseconds
my %deltas = $d->deltas
$d->is_wrap_mode
$d->is_limit_mode
$d->is_preserve_mode
print $d->end_of_month_mode;
# Multiple all deltas by -1
my $opposite = $d->inverse;
my $bigger = $dur1 + $dur2;
my $smaller = $dur1 - $dur2; # the result could be negative
my $bigger = $dur1 * 3;
my $base_dt = DateTime->new( year => 2000 );
my @sorted =
sort { DateTime::Duration->compare( $a, $b, $base_dt ) } @durations;
# Human-readable accessors, always positive, but use
# DateTime::Format::Duration instead
$d->years;
$d->months;
$d->weeks;
$d->days;
$d->hours;
$d->minutes;
$d->seconds;
$d->nanoseconds;
if ( $d->is_positive ) { ... }
if ( $d->is_zero ) { ... }
if ( $d->is_negative ) { ... }
DESCRIPTION
This is a simple class for representing duration objects. These
objects are used whenever you do date math with DateTime.pm.
See the How Date Math is Done section of the DateTime.pm documentation
for more details. The short course: One cannot in general convert
between seconds, minutes, days, and months, so this class will never
do so. Instead, create the duration with the desired units to begin
with, for example by calling the appropriate subtraction/delta method
on a "DateTime.pm" object.
METHODS
Like "DateTime" itself, "DateTime::Duration" returns the object from
mutator methods in order to make method chaining possible.
"DateTime::Duration" has the following methods:
* new( ... )
This method takes the parameters "years", "months", "weeks",
"days", "hours", "minutes", "seconds", "nanoseconds", and
"end_of_month". All of these except "end_of_month" are numbers.
If any of the numbers are negative, the entire duration is nega-
tive.
All of the numbers must be integers.
Internally, years as just treated as 12 months. Similarly, weeks
are treated as 7 days, and hours are converted to minutes. Sec-
onds and nanoseconds are both treated separately.
The "end_of_month" parameter must be either "wrap", "limit", or
"preserve". This parameter specifies how date math that crosses
the end of a month is handled.
In "wrap" mode, adding months or years that result in days beyond
the end of the new month will roll over into the following month.
For instance, adding one year to Feb 29 will result in Mar 1.
If you specify "end_of_month" mode as "limit", the end of the
month is never crossed. Thus, adding one year to Feb 29, 2000
will result in Feb 28, 2001. If you were to then add three more
years this will result in Feb 28, 2004.
If you specify "end_of_month" mode as "preserve", the same calcu-
lation is done as for "limit" except that if the original date is
at the end of the month the new date will also be. For instance,
adding one month to Feb 29, 2000 will result in Mar 31, 2000.
For positive durations, the "end_of_month" parameter defaults to
wrap. For negative durations, the default is "limit". This
should match how most people "intuitively" expect datetime math to
work.
* clone
Returns a new object with the same properties as the object on
which this method was called.
* in_units( ... )
Returns the length of the duration in the units (any of those that
can be passed to new) given as arguments. All lengths are inte-
gral, but may be negative. Smaller units are computed from what
remains after taking away the larger units given, so for example:
my $dur = DateTime::Duration->new( years => 1, months => 15 );
$dur->in_units( ’years’ ); # 2
$dur->in_units( ’months’ ); # 27
$dur->in_units( ’years’, ’months’ ); # (2, 3)
$dur->in_units( ’weeks’, ’days’ ); # (0, 0) !
The last example demonstrates that there will not be any conver-
sion between units which don’t have a fixed conversion rate. The
only conversions possible are:
* year <=> months
* weeks <=> days
* hours <=> minutes
* seconds <=> nanoseconds
For the explanation of why this happens, please see the How Date
Math is Done section of the DateTime.pm documentation
Note that the numbers returned by this method may not match the
values given to the constructor.
In list context, in_units returns the lengths in the order of the
units given. In scalar context, it returns the length in the
first unit (but still computes in terms of all given units).
If you need more flexibility in presenting information about dura-
tions, please take a look a "DateTime::Format::Duration".
* delta_months, delta_days, delta_minutes, delta_seconds,
delta_nanoseconds
These methods provide the information "DateTime.pm" needs for
doing date math. The numbers returned may be positive or nega-
tive.
* deltas
Returns a hash with the keys "months", "days", "minutes", "sec-
onds", and "nanoseconds", containing all the delta information for
the object.
* is_positive, is_zero, is_negative
Indicates whether or not the duration is positive, zero, or nega-
tive.
If the duration contains both positive and negative units, then it
will return false for all of these methods.
* is_wrap_mode, is_limit_mode, is_preserve_mode
Indicates what mode is used for end of month wrapping.
* end_of_month_mode
Returns one of "wrap", "limit", or "preserve".
* calendar_duration
Returns a new object with the same calendar delta (months and days
only) and end of month mode as the current object.
* clock_duration
Returns a new object with the same clock deltas (minutes, seconds,
and nanoseconds) and end of month mode as the current object.
* inverse
Returns a new object with the same deltas as the current object,
but multiple by -1. The end of month mode for the new object will
be the default end of month mode, which depends on whether the new
duration is positive or negative.
* add_duration( $duration_object ), subtract_duration( $dura-
tion_object )
Adds or subtracts one duration from another.
* add( ... ), subtract( ... )
Syntactic sugar for addition and subtraction. The parameters
given to these methods are used to create a new object, which is
then passed to "add_duration()" or "subtract_duration()", as
appropriate.
* multiply( $number )
Multiplies each unit in the by the specified number.
* DateTime::Duration->compare( $duration1, $duration2, $base_datetime
)
This is a class method that can be used to compare or sort dura-
tions. Comparison is done by adding each duration to the speci-
fied "DateTime.pm" object and comparing the resulting datetimes.
This is necessary because without a base, many durations are not
comparable. For example, 1 month may otr may not be longer than
29 days, depending on what datetime it is added to.
If no base datetime is given, then the result of "DateTime->now"
is used instead. Using this default will give non-repeatable
results if used to compare two duration objects containing differ-
ent units. It will also give non-repeatable results if the dura-
tions contain multiple types of units, such as months and days.
However, if you know that both objects only consist of one type of
unit (months or days or hours, etc.), and each duration contains
the same type of unit, then the results of the comparison will be
repeatable.
* years, months, weeks, days, hours, minutes, seconds, nanoseconds
These methods return numbers indicating how many of the given unit
the object represents, after having done a conversion to any
larger units. For example, days are first converted to weeks, and
then the remainder is returned. These numbers are always posi-
tive.
Here’s what each method returns:
$dur->year() == abs( $dur->in_units(’years’) )
$dur->months() == ( abs( $dur->in_units( ’months’, ’years’ ) ) )[0]
$dur->weeks() == abs( $dur->in_units( ’weeks’ ) )
$dur->days() == ( abs( $dur->in_units( ’days’, ’weeks’ ) ) )[0]
$dur->hours() == abs( $dur->in_units( ’hours’ ) )
$dur->minutes == ( abs( $dur->in_units( ’minutes’, ’hours’ ) ) )[0]
$dur->seconds == abs( $dur->in_units( ’seconds’ ) )
$dur->nanoseconds() == abs( $dur->in_units( ’nanoseconds’, ’seconds’ ) )
If this seems confusing, remember that you can always use the
"in_units()" method to specify exactly what you want.
Better yet, if you are trying to generate output suitable for
humans, use the "DateTime::Format::Duration" module.
Overloading
This class overloads addition, subtraction, and mutiplication.
Comparison is not overloaded. If you attempt to compare durations
using "<=>" or "cmp", then an exception will be thrown! Use the "com-
pare()" class method instead.
SUPPORT
Support for this module is provided via the datetime@perl.org email
list. See http://lists.perl.org/ for more details.
AUTHOR
Dave Rolsky <autarch@urth.org>
However, please see the CREDITS file for more details on who I really
stole all the code from.
COPYRIGHT
Copyright (c) 2003-2006 David Rolsky. All rights reserved. This pro-
gram is free software; you can redistribute it and/or modify it under
the same terms as Perl itself.
Portions of the code in this distribution are derived from other
works. Please see the CREDITS file for more details.
The full text of the license can be found in the LICENSE file included
with this module.
SEE ALSO
datetime@perl.org mailing list
http://datetime.perl.org/
perl v5.8.8 2007-06-19 DateTime::Duration(3)
