File: //usr/local/share/man/man3/DateTime::Duration.3pm
.\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings. \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote. \*(C+ will
.\" give a nicer C++. Capital omega is used to do unbreakable dashes and
.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
. ds -- \(*W-
. ds PI pi
. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
. ds L" ""
. ds R" ""
. ds C` ""
. ds C' ""
'br\}
.el\{\
. ds -- \|\(em\|
. ds PI \(*p
. ds L" ``
. ds R" ''
. ds C`
. ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD. Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
. if \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
. \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "DateTime::Duration 3"
.TH DateTime::Duration 3 "2020-12-04" "perl v5.26.3" "User Contributed Perl Documentation"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
DateTime::Duration \- Duration objects for date math
.SH "VERSION"
.IX Header "VERSION"
version 1.54
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& 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 => \*(Aqlimit\*(Aq,
\& );
\&
\& my ( $days, $hours, $seconds )
\& = $dur\->in_units( \*(Aqdays\*(Aq, \*(Aqhours\*(Aq, \*(Aqseconds\*(Aq );
\&
\& # 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 ) {...}
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This is a simple class for representing duration objects. These objects are
used whenever you do date math with DateTime.
.PP
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.
.SH "METHODS"
.IX Header "METHODS"
Like DateTime itself, \f(CW\*(C`DateTime::Duration\*(C'\fR returns the object from
mutator methods in order to make method chaining possible.
.PP
\&\f(CW\*(C`DateTime::Duration\*(C'\fR has the following methods:
.SS "DateTime::Duration\->new( ... )"
.IX Subsection "DateTime::Duration->new( ... )"
This class method accepts the following parameters:
.IP "\(bu" 4
year
.Sp
An integer containing the number of years in the duration. This is optional.
.IP "\(bu" 4
month
.Sp
An integer containing the number of months in the duration. This is optional.
.IP "\(bu" 4
weeks
.Sp
An integer containing the number of weeks in the duration. This is optional.
.IP "\(bu" 4
days
.Sp
An integer containing the number of days in the duration. This is optional.
.IP "\(bu" 4
hours
.Sp
An integer containing the number of hours in the duration. This is optional.
.IP "\(bu" 4
minutes
.Sp
An integer containing the number of minutes in the duration. This is optional.
.IP "\(bu" 4
seconds
.Sp
An integer containing the number of seconds in the duration. This is optional.
.IP "\(bu" 4
nanoseconds
.Sp
An integer containing the number of nanoseconds in the duration. This is
optional.
.IP "\(bu" 4
end_of_month
.Sp
This must be either \f(CW"wrap"\fR, \f(CW"limit"\fR, or \f(CW"preserve"\fR. This parameter
specifies how date math that crosses the end of a month is handled.
.Sp
In \f(CW"wrap"\fR 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.
.Sp
If you specify \f(CW"limit"\fR, 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.
.Sp
If you specify \f(CW"preserve"\fR, the same calculation is done as for \f(CW"limit"\fR
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.
.Sp
For positive durations, this parameter defaults to \f(CW"wrap"\fR. For negative
durations, the default is \f(CW"preserve"\fR. This should match how most people
\&\*(L"intuitively\*(R" expect datetime math to work.
.PP
All of the duration units can be positive or negative. However, if any of the
numbers are negative, the entire duration is negative.
.PP
All of the numbers \fBmust be integers\fR.
.PP
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.
.ie n .SS "$dur\->clone"
.el .SS "\f(CW$dur\fP\->clone"
.IX Subsection "$dur->clone"
Returns a new object with the same properties as the object on which
this method was called.
.ie n .SS "$dur\->in_units( ... )"
.el .SS "\f(CW$dur\fP\->in_units( ... )"
.IX Subsection "$dur->in_units( ... )"
Returns the length of the duration in the units (any of those that can be
passed to \f(CW\*(C`DateTime::Duration\->new\*(C'\fR) 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:
.PP
.Vb 1
\& my $dur = DateTime::Duration\->new( years => 1, months => 15 );
\&
\& $dur\->in_units(\*(Aqyears\*(Aq); # 2
\& $dur\->in_units(\*(Aqmonths\*(Aq); # 27
\& $dur\->in_units( \*(Aqyears\*(Aq, \*(Aqmonths\*(Aq ); # (2, 3)
\& $dur\->in_units( \*(Aqweeks\*(Aq, \*(Aqdays\*(Aq ); # (0, 0) !
.Ve
.PP
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:
.IP "\(bu" 4
years <=> months
.IP "\(bu" 4
weeks <=> days
.IP "\(bu" 4
hours <=> minutes
.IP "\(bu" 4
seconds <=> nanoseconds
.PP
For the explanation of why this is the case, please see the How DateTime
Math Works section of the DateTime
documentation
.PP
Note that the numbers returned by this method may not match the values
given to the constructor.
.PP
In list context, \f(CW\*(C`$dur\->in_units\*(C'\fR 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).
.PP
If you need more flexibility in presenting information about durations, please
take a look a DateTime::Format::Duration.
.ie n .SS "$dur\->is_positive, $dur\->is_zero, $dur\->is_negative"
.el .SS "\f(CW$dur\fP\->is_positive, \f(CW$dur\fP\->is_zero, \f(CW$dur\fP\->is_negative"
.IX Subsection "$dur->is_positive, $dur->is_zero, $dur->is_negative"
Indicates whether or not the duration is positive, zero, or negative.
.PP
If the duration contains both positive and negative units, then it
will return false for \fBall\fR of these methods.
.ie n .SS "$dur\->is_wrap_mode, $dur\->is_limit_mode, $dur\->is_preserve_mode"
.el .SS "\f(CW$dur\fP\->is_wrap_mode, \f(CW$dur\fP\->is_limit_mode, \f(CW$dur\fP\->is_preserve_mode"
.IX Subsection "$dur->is_wrap_mode, $dur->is_limit_mode, $dur->is_preserve_mode"
Indicates what mode is used for end of month wrapping.
.ie n .SS "$dur\->end_of_month_mode"
.el .SS "\f(CW$dur\fP\->end_of_month_mode"
.IX Subsection "$dur->end_of_month_mode"
Returns one of \f(CW"wrap"\fR, \f(CW"limit"\fR, or \f(CW"preserve"\fR.
.ie n .SS "$dur\->calendar_duration"
.el .SS "\f(CW$dur\fP\->calendar_duration"
.IX Subsection "$dur->calendar_duration"
Returns a new object with the same \fIcalendar\fR delta (months and days
only) and end of month mode as the current object.
.ie n .SS "$dur\->clock_duration"
.el .SS "\f(CW$dur\fP\->clock_duration"
.IX Subsection "$dur->clock_duration"
Returns a new object with the same \fIclock\fR deltas (minutes, seconds,
and nanoseconds) and end of month mode as the current object.
.ie n .SS "$dur\->inverse( ... )"
.el .SS "\f(CW$dur\fP\->inverse( ... )"
.IX Subsection "$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.
.PP
You can set the end of month mode in the inverted duration explicitly by
passing an \f(CW\*(C`end_of_month\*(C'\fR parameter to the \f(CW\*(C`$dur\->inverse\*(C'\fR method.
.ie n .SS "$dur\->add_duration($duration_object), $dur\->subtract_duration($duration_object)"
.el .SS "\f(CW$dur\fP\->add_duration($duration_object), \f(CW$dur\fP\->subtract_duration($duration_object)"
.IX Subsection "$dur->add_duration($duration_object), $dur->subtract_duration($duration_object)"
Adds or subtracts one duration from another.
.ie n .SS "$dur\->add( ... ), $dur\->subtract( ... )"
.el .SS "\f(CW$dur\fP\->add( ... ), \f(CW$dur\fP\->subtract( ... )"
.IX Subsection "$dur->add( ... ), $dur->subtract( ... )"
These accept either constructor parameters for a new \f(CW\*(C`DateTime::Duration\*(C'\fR
object or an already-constructed duration object.
.ie n .SS "$dur\->multiply($number)"
.el .SS "\f(CW$dur\fP\->multiply($number)"
.IX Subsection "$dur->multiply($number)"
Multiplies each unit in the \f(CW\*(C`DateTime::Duration\*(C'\fR object by the specified
integer number.
.ie n .SS "DateTime::Duration\->compare( $duration1, $duration2, $base_datetime )"
.el .SS "DateTime::Duration\->compare( \f(CW$duration1\fP, \f(CW$duration2\fP, \f(CW$base_datetime\fP )"
.IX Subsection "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.
.PP
If no base datetime is given, then the result of \f(CW\*(C`DateTime\->now\*(C'\fR
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.
.PP
However, if you know that both objects only consist of one type of
unit (months \fIor\fR days \fIor\fR hours, etc.), and each duration contains
the same type of unit, then the results of the comparison will be
repeatable.
.ie n .SS "$dur\->delta_months, $dur\->delta_days, $dur\->delta_minutes, $dur\->delta_seconds, $dur\->delta_nanoseconds"
.el .SS "\f(CW$dur\fP\->delta_months, \f(CW$dur\fP\->delta_days, \f(CW$dur\fP\->delta_minutes, \f(CW$dur\fP\->delta_seconds, \f(CW$dur\fP\->delta_nanoseconds"
.IX Subsection "$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.
.ie n .SS "$dur\->deltas"
.el .SS "\f(CW$dur\fP\->deltas"
.IX Subsection "$dur->deltas"
Returns a hash with the keys \*(L"months\*(R", \*(L"days\*(R", \*(L"minutes\*(R", \*(L"seconds\*(R", and
\&\*(L"nanoseconds\*(R", containing all the delta information for the object. This is
mostly useful for doing date math in DateTime.
.ie n .SS "$dur\->years, $dur\->months, $dur\->weeks, $dur\->days, $dur\->hours, $dur\->minutes, $dur\->seconds, $dur\->nanoseconds"
.el .SS "\f(CW$dur\fP\->years, \f(CW$dur\fP\->months, \f(CW$dur\fP\->weeks, \f(CW$dur\fP\->days, \f(CW$dur\fP\->hours, \f(CW$dur\fP\->minutes, \f(CW$dur\fP\->seconds, \f(CW$dur\fP\->nanoseconds"
.IX Subsection "$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.
.PP
Here's what each method returns:
.PP
.Vb 8
\& $dur\->years == abs( $dur\->in_units(\*(Aqyears\*(Aq) )
\& $dur\->months == abs( ( $dur\->in_units( \*(Aqmonths\*(Aq, \*(Aqyears\*(Aq ) )[0] )
\& $dur\->weeks == abs( $dur\->in_units( \*(Aqweeks\*(Aq ) )
\& $dur\->days == abs( ( $dur\->in_units( \*(Aqdays\*(Aq, \*(Aqweeks\*(Aq ) )[0] )
\& $dur\->hours == abs( $dur\->in_units( \*(Aqhours\*(Aq ) )
\& $dur\->minutes == abs( ( $dur\->in_units( \*(Aqminutes\*(Aq, \*(Aqhours\*(Aq ) )[0] )
\& $dur\->seconds == abs( $dur\->in_units( \*(Aqseconds\*(Aq ) )
\& $dur\->nanoseconds == abs( ( $dur\->in_units( \*(Aqnanoseconds\*(Aq, \*(Aqseconds\*(Aq ) )[0] )
.Ve
.PP
If this seems confusing, remember that you can always use the \f(CW\*(C`$dur\->in_units\*(C'\fR method to specify exactly what you want.
.PP
Better yet, if you are trying to generate output suitable for humans,
use the \f(CW\*(C`DateTime::Format::Duration\*(C'\fR module.
.SS "Overloading"
.IX Subsection "Overloading"
This class overloads addition, subtraction, and mutiplication.
.PP
Comparison is \fBnot\fR overloaded. If you attempt to compare durations
using \f(CW\*(C`<=>\*(C'\fR or \f(CW\*(C`cmp\*(C'\fR, then an exception will be thrown! Use the
\&\f(CW\*(C`compare\*(C'\fR class method instead.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
datetime@perl.org mailing list
.PP
http://datetime.perl.org/
.SH "SUPPORT"
.IX Header "SUPPORT"
Support for this module is provided via the datetime@perl.org email
list. See http://lists.perl.org/ for more details.
.PP
Bugs may be submitted at <https://github.com/houseabsolute/DateTime.pm/issues>.
.PP
There is a mailing list available for users of this distribution,
<mailto:datetime@perl.org>.
.PP
I am also usually active on \s-1IRC\s0 as 'autarch' on \f(CW\*(C`irc://irc.perl.org\*(C'\fR.
.SH "SOURCE"
.IX Header "SOURCE"
The source code repository for DateTime can be found at <https://github.com/houseabsolute/DateTime.pm>.
.SH "AUTHOR"
.IX Header "AUTHOR"
Dave Rolsky <autarch@urth.org>
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
This software is Copyright (c) 2003 \- 2020 by Dave Rolsky.
.PP
This is free software, licensed under:
.PP
.Vb 1
\& The Artistic License 2.0 (GPL Compatible)
.Ve
.PP
The full text of the license can be found in the
\&\fI\s-1LICENSE\s0\fR file included with this distribution.