view release on metacpan or  search on metacpan

lib/DateTime/Duration.pm  view on Meta::CPAN

sub deltas {
    map { $_ => $_[0]->{$_} } @all_units;
}

sub in_units {
    my $self  = shift;
    my @units = @_;

    my %units = map { $_ => 1 } @units;

    my %ret;

    my ( $months, $days, $minutes, $seconds )
        = @{$self}{qw( months days minutes seconds )};

    if ( $units{years} ) {
        $ret{years} = int( $months / 12 );
        $months -= $ret{years} * 12;
    }

    if ( $units{months} ) {
        $ret{months} = $months;
    }

    if ( $units{weeks} ) {
        $ret{weeks} = int( $days / 7 );
        $days -= $ret{weeks} * 7;
    }

    if ( $units{days} ) {
        $ret{days} = $days;
    }

    if ( $units{hours} ) {
        $ret{hours} = int( $minutes / 60 );
        $minutes -= $ret{hours} * 60;
    }

    if ( $units{minutes} ) {
        $ret{minutes} = $minutes;
    }

    if ( $units{seconds} ) {
        $ret{seconds} = $seconds;
        $seconds = 0;
    }

    if ( $units{nanoseconds} ) {
        $ret{nanoseconds} = $seconds * MAX_NANOSECONDS + $self->{nanoseconds};
    }

    wantarray ? @ret{@units} : $ret{ $units[0] };
}

sub is_wrap_mode     { $_[0]->{end_of_month} eq 'wrap'     ? 1 : 0 }
sub is_limit_mode    { $_[0]->{end_of_month} eq 'limit'    ? 1 : 0 }
sub is_preserve_mode { $_[0]->{end_of_month} eq 'preserve' ? 1 : 0 }

sub end_of_month_mode { $_[0]->{end_of_month} }

sub calendar_duration {
    my $self = shift;

    return ( ref $self )
        ->new( map { $_ => $self->{$_} } qw( months days end_of_month ) );
}

sub clock_duration {
    my $self = shift;

    return ( ref $self )
        ->new( map { $_ => $self->{$_} }
            qw( minutes seconds nanoseconds end_of_month ) );
}

sub inverse {
    my $self = shift;
    my %p    = @_;

    my %new;
    foreach my $u (@all_units) {
        $new{$u} = $self->{$u};

        # avoid -0 bug
        $new{$u} *= -1 if $new{$u};
    }

    $new{end_of_month} = $p{end_of_month}
        if exists $p{end_of_month};

    return ( ref $self )->new(%new);
}

sub add_duration {
    my ( $self, $dur ) = @_;

    foreach my $u (@all_units) {
        $self->{$u} += $dur->{$u};
    }

    $self->_normalize_nanoseconds if $self->{nanoseconds};

    return $self;
}

sub add {
    my $self = shift;

    return $self->add_duration( $self->_duration_object_from_args(@_) );
}

sub subtract {
    my $self = shift;

    return $self->subtract_duration( $self->_duration_object_from_args(@_) );
}

# Syntactic sugar for add and subtract: use a duration object if it's
# supplied, otherwise build a new one from the arguments.
sub _duration_object_from_args {
    my $self = shift;

lib/DateTime/Duration.pm  view on Meta::CPAN

method was called.

=head2 $dur->in_units( ... )

Returns the length of the duration in the units (any of those that can be
passed to C<< 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:

=over 4

=item * years <=> months

=item * weeks <=> days

=item * hours <=> minutes

=item * seconds <=> nanoseconds

=back

For the explanation of why this is the case, please see the L<How DateTime Math
Works|DateTime/"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, C<< $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 L<DateTime::Format::Duration>.

=head2 $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 B<all> of these methods.

=head2 $dur->is_wrap_mode, $dur->is_limit_mode, $dur->is_preserve_mode

Indicates what mode is used for end of month wrapping.

=head2 $dur->end_of_month_mode

Returns one of C<"wrap">, C<"limit">, or C<"preserve">.

=head2 $dur->calendar_duration

Returns a new object with the same I<calendar> delta (months and days only) and
end of month mode as the current object.

=head2 $dur->clock_duration

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

=head2 $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 C<end_of_month> parameter to the C<< $dur->inverse >> method.

=head2 $dur->add_duration($duration_object), $dur->subtract_duration($duration_object)

Adds or subtracts one duration from another.

=head2 $dur->add( ... ), $dur->subtract( ... )

These accept either constructor parameters for a new C<DateTime::Duration>
object or an already-constructed duration object.

=head2 $dur->multiply($number)

Multiplies each unit in the C<DateTime::Duration> object by the specified
integer number.

=head2 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 L<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 C<< 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
I<or> days I<or> hours, etc.), and each duration contains the same type of
unit, then the results of the comparison will be repeatable.

=head2 $dur->delta_months, $dur->delta_days, $dur->delta_minutes, $dur->delta_seconds, $dur->delta_nanoseconds

These methods provide the information L<DateTime> needs for doing date math.
The numbers returned may be positive or negative. This is mostly useful for
doing date math in L<DateTime>.

=head2 $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 L<DateTime>.