NAME

DateTime::Lite::Duration - Duration objects for use with DateTime::Lite

SYNOPSIS

use DateTime::Lite::Duration;

my $dur = DateTime::Lite::Duration->new(
    years   => 1,
    months  => 6,
    days    => 15,
    hours   => 3,
    minutes => 10,
    seconds => 30,
) || die( DateTime::Lite::Duration->error );

my $dur = DateTime::Lite::Duration->new(
    years       => 1,
    months      => 6,
    weeks       => 2,
    days        => 15,
    hours       => 3,
    minutes     => 10,
    seconds     => 30,
    nanoseconds => 500_000_000,
    end_of_month => 'limit',  # 'wrap' (default), 'limit', 'preserve'
) || die( DateTime::Lite::Duration->error );

# Introspection
printf( "Years: %d, Months: %d\n", $dur->years, $dur->months );

# Use with DateTime::Lite
$dt->add_duration( $dur );
$dt->subtract_duration( $dur );
my $diff = $dt1->subtract_datetime( $dt2 );  # returns a Duration

# Absolute-value accessors (strip larger units)
$dur->years;         # full years
$dur->months;        # months after stripping years
$dur->weeks;         # full weeks
$dur->days;          # days after stripping weeks
$dur->hours;         # full hours
$dur->minutes;       # minutes after stripping hours
$dur->seconds;       # seconds after stripping minutes
$dur->nanoseconds;   # nanoseconds after stripping seconds

# Signed raw delta accessors
$dur->delta_months;       # signed months (years * 12 + months)
$dur->delta_days;         # signed days
$dur->delta_minutes;      # signed minutes (hours * 60 + minutes)
$dur->delta_seconds;      # signed seconds
$dur->delta_nanoseconds;  # signed nanoseconds

# All signed components at once
my %d = $dur->deltas;  # keys: months days minutes seconds nanoseconds

# Calendar / clock sub-durations
my $cal   = $dur->calendar_duration;  # months + days only
my $clock = $dur->clock_duration;     # minutes + seconds + nanoseconds only

# Arithmetic on durations
$dur->add( months => 1, days => 7 );
$dur->subtract( hours => 2 );
$dur->add_duration( $other_dur );
$dur->subtract_duration( $other_dur );

my $inverse = $dur->inverse;                          # negate all components
my $neg     = $dur->inverse( end_of_month => 'wrap' );

# Conversion
# Express as a combination of requested units:
my ( $h, $m ) = $dur->in_units( 'hours', 'minutes' );  # e.g. (3, 10)
my $total_min = $dur->in_units('minutes');             # scalar form

# Comparison
my $cmp = DateTime::Lite::Duration->compare( $dur1, $dur2 );  # -1, 0, 1

# Predicates
$dur->is_positive;          # true if any component > 0, none < 0
$dur->is_negative;          # true if any component < 0, none > 0
$dur->is_zero;              # true if all components are 0
$dur->is_wrap_mode;         # end_of_month eq 'wrap'
$dur->is_limit_mode;        # end_of_month eq 'limit'
$dur->is_preserve_mode;     # end_of_month eq 'preserve'
$dur->end_of_month_mode;    # 'wrap', 'limit', or 'preserve'

# Cloning
my $copy = $dur->clone;

# Constants
DateTime::Lite::Duration::MAX_NANOSECONDS();  # 1_000_000_000

# Error handling
my $dur2 = DateTime::Lite::Duration->new( %bad_args ) ||
    die( DateTime::Lite::Duration->error );
$dur->fatal(1);  # make all errors fatal (die instead of warn+return undef)
my $err = $dur->error;

VERSION

v0.1.0

DESCRIPTION

DateTime::Lite::Duration is a lightweight port of DateTime::Duration, used exclusively with DateTime::Lite. It stores durations in five independent "buckets": months, days, minutes, seconds, and nanoseconds.

The month/day buckets are calendar units, whose real length depends on the date to which the duration is applied. The minute/second/nanosecond buckets are absolute (clock) units.

Unlike DateTime, DateTime::Lite never calls die() unexpectedly.

Errors set an exception object accessible via $dur->error and return undef in scalar context, or an empty list in list context. In chaining (object context), it returns a dummy object (DateTime::Lite::Null) to avoid the typical Can't call method '%s' on an undefined value

CONSTRUCTOR

new( %args )

Accepted keys:

years, months: Calendar time. years is converted to months on construction (1 year = 12 months).
weeks, days: Calendar time. weeks is converted to days (1 week = 7 days).
hours, minutes: Clock time. hours is converted to minutes (1 hour = 60 minutes).
seconds, nanoseconds: Clock time.
end_of_month: How to handle month-end arithmetic when adding/subtracting months. One of wrap (default), limit, or preserve.

METHODS

Accessors (absolute values)

years, months, weeks, days, hours, minutes, seconds, nanoseconds all return the absolute (unsigned) portion of the duration in the given unit, after stripping larger units. For instance months() returns the months component after dividing out full years.

Signed delta accessors

delta_months, delta_days, delta_minutes, delta_seconds, delta_nanoseconds return the raw signed internal values.

calendar_duration / clock_duration

Return new duration objects containing only the calendar (months, days) or clock (minutes, seconds, nanoseconds) components respectively.

clone

Returns a shallow copy.

compare( $dur1, $dur2 )

Class method. Compares two durations unit by unit. Returns -1, 0, or 1.

deltas

Returns a hash of all five raw signed values.

end_of_month_mode

Returns wrap, limit, or preserve.

in_units( @units )

Returns the duration expressed as a combination of the given units.

For example: $dur->in_units( 'hours', 'minutes' ) returns (3, 10) for a 190-minute duration. If only one unit is requested, returns a scalar.

inverse

$dur->inverse;
$dur->inverse( end_of_month => $mode );

Returns a new duration with all components negated. Optionally overrides end_of_month.

is_negative / is_positive / is_zero

Predicate methods.

is_wrap_mode / is_limit_mode / is_preserve_mode

Return true if the end_of_month mode matches.

add

$dur->add( months => 1, days => 15 );

Adds a duration specified as key-value pairs (same keys as "new") to this duration in-place. Returns $self.

add_duration

$dur->add_duration( $other_dur );

Adds another DateTime::Lite::Duration object to this duration in-place. Returns $self.

subtract

$dur->subtract( days => 1 );

Subtracts a duration specified as key-value pairs from this duration in-place. Equivalent to adding the inverse. Returns $self.

subtract_duration

$dur->subtract_duration( $other_dur );

Subtracts another DateTime::Lite::Duration object from this duration in-place. Returns $self.

delta_months

my $m = $dur->delta_months;  # may be negative

Returns the raw signed months component.

delta_days

my $d = $dur->delta_days;

Returns the raw signed days component.

delta_minutes

my $min = $dur->delta_minutes;

Returns the raw signed minutes component.

delta_seconds

my $s = $dur->delta_seconds;

Returns the raw signed seconds component.

delta_nanoseconds

my $ns = $dur->delta_nanoseconds;

Returns the raw signed nanoseconds component.

MAX_NANOSECONDS

my $max = DateTime::Lite::Duration::MAX_NANOSECONDS();

Returns 1_000_000_000 (10^9), the number of nanoseconds in one second. Used internally for nanosecond normalisation.

error

my $dur = DateTime::Lite::Duration->new( %bad_args ) ||
    die( DateTime::Lite::Duration->error );

Instance and class method. When called with a message, creates a DateTime::Lite::Exception, stores it, warns or dies (depending on "fatal"), and returns undef. When called without arguments, returns the last error object.

fatal

$dur->fatal(1);  # enable fatal mode

Gets or sets the fatal flag. When true, any call to "error" will die instead of warn-and-return-undef.

pass_error

sub my_op
{
    my $self = shift( @_ );
    my $res = $self->_inner_op ||
        return( $self->pass_error );
    return( $res );
}

Propagates the error from a lower-level call into this object's error slot without constructing a new exception. Used internally and in subclasses.

ERROR HANDLING

On error, methods return undef

add

$dur->add( months => 1, days => 15 );

Adds a duration specified as key-value pairs (same keys as "new") to this duration in-place. Returns $self.

add_duration

$dur->add_duration( $other_dur );

Adds another DateTime::Lite::Duration object to this duration in-place. Returns $self.

subtract

$dur->subtract( days => 1 );

Subtracts a duration specified as key-value pairs from this duration in-place. Equivalent to adding the inverse. Returns $self.

subtract_duration

$dur->subtract_duration( $other_dur );

Subtracts another DateTime::Lite::Duration object from this duration in-place. Returns $self.

delta_months

my $m = $dur->delta_months;  # may be negative

Returns the raw signed months component.

delta_days

my $d = $dur->delta_days;

Returns the raw signed days component.

delta_minutes

my $min = $dur->delta_minutes;

Returns the raw signed minutes component.

delta_seconds

my $s = $dur->delta_seconds;

Returns the raw signed seconds component.

delta_nanoseconds

my $ns = $dur->delta_nanoseconds;

Returns the raw signed nanoseconds component.

error

my $dur = DateTime::Lite::Duration->new( %bad_args ) ||
    die( DateTime::Lite::Duration->error );

fatal

$dur->fatal(1);  # enable fatal mode

Gets or sets the fatal flag. When true, any call to "error" will die instead of warn-and-return-undef.

pass_error

sub my_op
{
    my $self = shift( @_ );
    my $res = $self->_inner_op ||
        return( $self->pass_error );
    return( $res );
}

Propagates the error from a lower-level call into this object's error slot without constructing a new exception. Used internally and in subclasses.

ERROR HANDLING

On error, methods return undef in scalar context, or an empty list in list context. The exception is accessible via $obj->error or DateTime::Lite::Duration->error.

The exception object stringifies to a human-readable message including file and line number.

error detects the context is chaining, or object, and thus instead of returning undef, it will return a dummy instance of DateTime::Lite::Null to avoid the typical perl error Can't call method '%s' on an undefined value.

If the instance option fatal has been enabled, then any error triggered will be fatal.

AUTHOR

Jacques Deguest <jack@deguest.jp>

COPYRIGHT & LICENSE

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

To install DateTime::Lite, copy and paste the appropriate command in to your terminal.

cpanm

cpanm DateTime::Lite

CPAN shell

perl -MCPAN -e shell
install DateTime::Lite

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	Go to GitHub issues (only if GitHub is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

SYNOPSIS

VERSION

DESCRIPTION

CONSTRUCTOR

new( %args )

METHODS

Accessors (absolute values)

Signed delta accessors

calendar_duration / clock_duration

clone

compare( $dur1, $dur2 )

deltas

end_of_month_mode

in_units( @units )

inverse

is_negative / is_positive / is_zero

is_wrap_mode / is_limit_mode / is_preserve_mode

add

add_duration

subtract

subtract_duration

delta_months

delta_days

delta_minutes

delta_seconds

delta_nanoseconds

MAX_NANOSECONDS

error

fatal

pass_error

ERROR HANDLING

add

add_duration

subtract

subtract_duration

delta_months

delta_days

delta_minutes

delta_seconds

delta_nanoseconds

error

fatal

pass_error

ERROR HANDLING

SEE ALSO

AUTHOR

COPYRIGHT & LICENSE

Module Install Instructions

Keyboard Shortcuts