NAME¶
DateTime::Duration - Duration objects for date math
VERSION¶
version 0.75
SYNOPSIS¶
use DateTime::Duration;
$dur = DateTime::Duration->new(
years => 3,
months => 5,
weeks => 1,
days => 1,
hours => 6,
minutes => 15,
seconds => 45,
nanoseconds => 12000
);
my ( $days, $hours, $seconds ) = $dur->in_units('days', 'hours', 'seconds');
# Human-readable accessors, always positive, but consider using
# DateTime::Format::Duration instead
$dur->years;
$dur->months;
$dur->weeks;
$dur->days;
$dur->hours;
$dur->minutes;
$dur->seconds;
$dur->nanoseconds;
$dur->is_wrap_mode
$dur->is_limit_mode
$dur->is_preserve_mode
print $dur->end_of_month_mode;
# Multiply all values by -1
my $opposite = $dur->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;
if ( $dur->is_positive ) { ... }
if ( $dur->is_zero ) { ... }
if ( $dur->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 DateTime Math Works 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
negative.
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. Seconds 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 calculation 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 integral,
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 conversion between
units which don't have a fixed conversion rate. The only conversions
possible are:
- •
- years <=> months
- •
- weeks <=> days
- •
- hours <=> minutes
- •
- seconds <=> nanoseconds
For the explanation of why this is the case, please see the How DateTime Math
Works 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 durations, please
take a look a "DateTime::Format::Duration".
- •
- is_positive, is_zero, is_negative
Indicates whether or not the duration is positive, zero, or negative.
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.
You can set the end of month mode in the inverted duration explicitly by
passing "end_of_month => ..." to the "inverse()"
method.
- •
- add_duration( $duration_object ), subtract_duration(
$duration_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 durations.
Comparison is done by adding each duration to the specified
"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 or 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
different units. It will also give non-repeatable results if the durations
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.
- •
- 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 negative. This is
mostly useful for doing date math in DateTime.
- •
- deltas
Returns a hash with the keys "months", "days",
"minutes", "seconds", and "nanoseconds",
containing all the delta information for the object. This is mostly useful
for doing date math in DateTime.
- •
- 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 positive.
Here's what each method returns:
$dur->years() == 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' ) )[0] )
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 "compare()" 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.
SEE ALSO¶
datetime@perl.org mailing list
http://datetime.perl.org/
AUTHOR¶
Dave Rolsky <autarch@urth.org>
COPYRIGHT AND LICENSE¶
This software is Copyright (c) 2012 by Dave Rolsky.
This is free software, licensed under:
The Artistic License 2.0 (GPL Compatible)