DateTime::Duration - Duration objects for date math

  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 ) { ... }

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 CWDateTime.pm object.

Like CWDateTime itself, CWDateTime::Duration returns the object from mutator methods in order to make method chaining possible.

CWDateTime::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:

* 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 durations, please take a look a CWDateTime::Format::Duration.

* delta_months, delta_days, delta_minutes, delta_seconds, delta_nanoseconds

These methods provide the information CWDateTime.pm needs 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. 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.

* 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. 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 CWadd_duration() or CWsubtract_duration(), as appropriate. Multiplies each unit in the by the specified number. This is a class method that can be used to compare or sort durations. Comparison is done by adding each duration to the specified CWDateTime.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 CWDateTime->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 contain the same units, and just a single type, 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 positive. 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 CWin_units() method to specify exactly what you want. Better yet, if you are trying to generate output suitable for humans, use the CWDateTime::Format::Duration module.

This class overloads addition, subtraction, and mutiplication.

Comparison is not overloaded. If you attempt to compare durations using CW<=> or CWcmp, then an exception will be thrown! Use the CWcompare() class method instead.

Support for this module is provided via the datetime@perl.org email list. See http://lists.perl.org/ for more details.

Dave Rolsky <autarch@urth.org>

However, please see the CREDITS file for more details on who I really stole all the code from.

Copyright (c) 2003-2005 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.

datetime@perl.org mailing list

http://datetime.perl.org/