phpman > perldoc > DateTime::Duration(3pm)

NAME
    DateTime::Duration - Duration objects for date math

VERSION
    version 1.55

SYNOPSIS
        use DateTime::Duration;

        $dur = DateTime::Duration->new(
            years        => 3,
            months       => 5,
            weeks        => 1,
            days         => 1,
            hours        => 6,
            minutes      => 15,
            seconds      => 45,
            nanoseconds  => 12000,
            end_of_month => 'limit',
        );

        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.

    See the How DateTime Math Works section of the DateTime 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 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 class method accepts the following parameters:

    *   years

        An integer containing the number of years in the duration. This is optional.

    *   months

        An integer containing the number of months in the duration. This is optional.

    *   weeks

        An integer containing the number of weeks in the duration. This is optional.

    *   days

        An integer containing the number of days in the duration. This is optional.

    *   hours

        An integer containing the number of hours in the duration. This is optional.

    *   minutes

        An integer containing the number of minutes in the duration. This is optional.

    *   seconds

        An integer containing the number of seconds in the duration. This is optional.

    *   nanoseconds

        An integer containing the number of nanoseconds in the duration. This is optional.

    *   end_of_month

        This 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 "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 "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, this parameter defaults to "wrap". For negative durations, the
        default is "preserve". This should match how most people "intuitively" expect datetime math
        to work.

    All of the duration units can be positive or negative. However, 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.

  $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
    "DateTime::Duration->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 documentation

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

    In list context, "$dur->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 multiplied 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 an
    "end_of_month" parameter to the "$dur->inverse" method.

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

  $dur->add( ... ), $dur->subtract( ... )
    These accept either constructor parameters for a new "DateTime::Duration" object or an
    already-constructed duration object.

  $dur->multiply($number)
    Multiplies each unit in the "DateTime::Duration" object by the specified integer 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 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 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 "$dur->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.

SEE ALSO
    datetime AT perl.org mailing list

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

    Bugs may be submitted at <https://github.com/houseabsolute/DateTime.pm/issues>.

    There is a mailing list available for users of this distribution, <mailto:datetime AT perl.org>.

SOURCE
    The source code repository for DateTime can be found at
    <https://github.com/houseabsolute/DateTime.pm>.

AUTHOR
    Dave Rolsky <autarch AT urth.org>

COPYRIGHT AND LICENSE
    This software is Copyright (c) 2003 - 2021 by Dave Rolsky.

    This is free software, licensed under:

      The Artistic License 2.0 (GPL Compatible)

    The full text of the license can be found in the LICENSE file included with this distribution.