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 );

# Human-readable accessors, always positive
$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 ) { ... }

# 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

# Multiple all deltas by -1
my $opposite = $d->inverse;

my $bigger  = $dur1 + $dur2;
my $smaller = $dur1 - $dur2; # the result could be 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.

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.

  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". These specify how changes across the end of a month are 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. However, adding three more years will result in Feb 28, 2004, not Feb 29.

  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.

• years, months, weeks, days, hours, minutes, seconds, nanoseconds

  These methods return numbers indicating how many of the given unit the object representations. These numbers are always positive.

  Note that the numbers returned by this method may not match the values given to the constructor. For example:

  my $dur = DateTime::Duration->new( years => 0, months => 15 );
  
  print $dur->years;  # prints 1
  print $dur->months; # prints 3

• delta_months, delta_days, delta_minutes, delta_seconds, delta_nanoseconds

  These methods provide the same information as those above, but in a way suitable for doing date math. The numbers returned may be positive or negative.

• deltas

  Returns a hash with the keys "months", "days", "minutes", "seconds", 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 negative.

• is_wrap_mode, is_limit_mode, is_preserve_mode

  Indicates what mode is used for end of month wrapping.

• 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( $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.

Overloading

This class overload addition, subtraction, and mutiplication.

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 David Rolsky. All rights reserved. This program 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/