Provided by: libdatetime-perl_1.06-1_amd64 bug

NAME

       DateTime::Duration - Duration objects for date math

VERSION

       version 1.06

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:

   DateTime::Duration->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.

   $dur->clone()
       Returns a new object with the same properties as the object on which this method was
       called.

   $dur->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".

   $dur->is_positive(), $dur->is_zero(), $dur->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.

   $dur->is_wrap_mode(), $dur->is_limit_mode(), $dur->is_preserve_mode()
       Indicates what mode is used for end of month wrapping.

   $dur->end_of_month_mode()
       Returns one of "wrap", "limit", or "preserve".

   $dur->calendar_duration()
       Returns a new object with the same calendar delta (months and days only) and end of month
       mode as the current object.

   $dur->clock_duration()
       Returns a new object with the same clock deltas (minutes, seconds, and nanoseconds) and
       end of month mode as the current object.

   $dur->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.

   $dur->add_duration( $duration_object ), $dur->subtract_duration( $duration_object )
       Adds or subtracts one duration from another.

   $dur->add( ... ), $dur->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.

   $dur->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.

   $dur->delta_months(), $dur->delta_days(), $dur->delta_minutes(), $dur->delta_seconds(),
       $dur->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.

   $dur->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.

   $dur->years(), $dur->months(), $dur->weeks(), $dur->days(), $dur->hours(), $dur->minutes(),
       $dur->seconds(), $dur->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) 2013 by Dave Rolsky.

       This is free software, licensed under:

         The Artistic License 2.0 (GPL Compatible)