Devil Killer Is Here MiNi Shell
MiNi SheLL

Current Path : /proc/thread-self/root/usr/local/man/man3/
Linux boscustweb5001.eigbox.net 5.4.91 #1 SMP Wed Jan 20 18:10:28 EST 2021 x86_64
Current File : //proc/thread-self/root/usr/local/man/man3/DateTime::Duration.3
.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sh \" Subsection heading
.br
.if t .Sp
.ne 5
.PP
\fB\\$1\fR
.PP
..
.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.  | will give a
.\" real vertical bar.  \*(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-|\(bv\*(Tr
.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" ''
'br\}
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.if \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.\"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.hy 0
.if n .na
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "DateTime::Duration 3"
.TH DateTime::Duration 3 "2006-10-22" "perl v5.8.8" "User Contributed Perl Documentation"
.SH "NAME"
DateTime::Duration \- Duration objects for date math
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  use DateTime::Duration;
.Ve
.PP
.Vb 8
\&  $d = DateTime::Duration->new( years   => 3,
\&                                months  => 5,
\&                                weeks   => 1,
\&                                days    => 1,
\&                                hours   => 6,
\&                                minutes => 15,
\&                                seconds => 45, 
\&                                nanoseconds => 12000 );
.Ve
.PP
.Vb 2
\&  # Convert to different units
\&  $d->in_units('days', 'hours', 'seconds');
.Ve
.PP
.Vb 6
\&  # The important parts for date math
\&  $d->delta_months
\&  $d->delta_days
\&  $d->delta_minutes
\&  $d->delta_seconds
\&  $d->delta_nanoseconds
.Ve
.PP
.Vb 1
\&  my %deltas = $d->deltas
.Ve
.PP
.Vb 3
\&  $d->is_wrap_mode
\&  $d->is_limit_mode
\&  $d->is_preserve_mode
.Ve
.PP
.Vb 1
\&  print $d->end_of_month_mode;
.Ve
.PP
.Vb 2
\&  # Multiple all deltas by -1
\&  my $opposite = $d->inverse;
.Ve
.PP
.Vb 3
\&  my $bigger  = $dur1 + $dur2;
\&  my $smaller = $dur1 - $dur2; # the result could be negative
\&  my $bigger  = $dur1 * 3;
.Ve
.PP
.Vb 3
\&  my $base_dt = DateTime->new( year => 2000 );
\&  my @sorted =
\&      sort { DateTime::Duration->compare( $a, $b, $base_dt ) } @durations;
.Ve
.PP
.Vb 10
\&  # Human-readable accessors, always positive, but use
\&  # DateTime::Format::Duration instead
\&  $d->years;
\&  $d->months;
\&  $d->weeks;
\&  $d->days;
\&  $d->hours;
\&  $d->minutes;
\&  $d->seconds;
\&  $d->nanoseconds;
.Ve
.PP
.Vb 3
\&  if ( $d->is_positive ) { ... }
\&  if ( $d->is_zero )     { ... }
\&  if ( $d->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.pm.
.PP
See the How Date Math is Done
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 \f(CW\*(C`DateTime.pm\*(C'\fR object.
.SH "METHODS"
.IX Header "METHODS"
Like \f(CW\*(C`DateTime\*(C'\fR 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:
.IP "* new( ... )" 4
.IX Item "new( ... )"
This method takes the parameters \*(L"years\*(R", \*(L"months\*(R", \*(L"weeks\*(R", \*(L"days\*(R",
\&\*(L"hours\*(R", \*(L"minutes\*(R", \*(L"seconds\*(R", \*(L"nanoseconds\*(R", and \*(L"end_of_month\*(R".  All
of these except \*(L"end_of_month\*(R" are numbers.  If any of the numbers are
negative, the entire duration is negative.
.Sp
All of the numbers \fBmust be integers\fR.
.Sp
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.
.Sp
The \*(L"end_of_month\*(R" parameter must be either \*(L"wrap\*(R", \*(L"limit\*(R", or
\&\*(L"preserve\*(R".  This parameter specifies how date math that crosses the
end of a month is handled.
.Sp
In \*(L"wrap\*(R" 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 \*(L"end_of_month\*(R" mode as \*(L"limit\*(R", 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 \*(L"end_of_month\*(R" mode as \*(L"preserve\*(R", the same calculation
is done as for \*(L"limit\*(R" 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, the \*(L"end_of_month\*(R" parameter defaults to wrap.
For negative durations, the default is \*(L"limit\*(R".  This should match how
most people \*(L"intuitively\*(R" expect datetime math to work.
.IP "* clone" 4
.IX Item "clone"
Returns a new object with the same properties as the object on which
this method was called.
.IP "* in_units( ... )" 4
.IX Item "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:
.Sp
.Vb 1
\&  my $dur = DateTime::Duration->new( years => 1, months => 15 );
.Ve
.Sp
.Vb 4
\&  $dur->in_units( 'years' );            # 2
\&  $dur->in_units( 'months' );           # 27
\&  $dur->in_units( 'years', 'months' );  # (2, 3)
\&  $dur->in_units( 'weeks', 'days' );    # (0, 0) !
.Ve
.Sp
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:
.RS 4
.IP "* year <=> months" 8
.IX Item "year <=> months"
.PD 0
.IP "* weeks <=> days" 8
.IX Item "weeks <=> days"
.IP "* hours <=> minutes" 8
.IX Item "hours <=> minutes"
.IP "* seconds <=> nanoseconds" 8
.IX Item "seconds <=> nanoseconds"
.RE
.RS 4
.PD
.Sp
For the explanation of why this happens, please see the How Date Math is Done section of the
DateTime.pm documentation
.Sp
Note that the numbers returned by this method may not match the values
given to the constructor.
.Sp
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).
.Sp
If you need more flexibility in presenting information about
durations, please take a look a \f(CW\*(C`DateTime::Format::Duration\*(C'\fR.
.RE
.IP "* delta_months, delta_days, delta_minutes, delta_seconds, delta_nanoseconds" 4
.IX Item "delta_months, delta_days, delta_minutes, delta_seconds, delta_nanoseconds"
These methods provide the information \f(CW\*(C`DateTime.pm\*(C'\fR needs for doing
date math.  The numbers returned may be positive or negative.
.IP "* deltas" 4
.IX Item "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.
.IP "* is_positive, is_zero, is_negative" 4
.IX Item "is_positive, is_zero, is_negative"
Indicates whether or not the duration is positive, zero, or negative.
.Sp
If the duration contains both positive and negative units, then it
will return false for \fBall\fR of these methods.
.IP "* is_wrap_mode, is_limit_mode, is_preserve_mode" 4
.IX Item "is_wrap_mode, is_limit_mode, is_preserve_mode"
Indicates what mode is used for end of month wrapping.
.IP "* end_of_month_mode" 4
.IX Item "end_of_month_mode"
Returns one of \*(L"wrap\*(R", \*(L"limit\*(R", or \*(L"preserve\*(R".
.IP "* calendar_duration" 4
.IX Item "calendar_duration"
Returns a new object with the same \fIcalendar\fR delta (months only) and
end of month mode as the current object.
.IP "* clock_duration" 4
.IX Item "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.
.IP "* inverse" 4
.IX Item "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.
.ie n .IP "* add_duration( $duration_object\fR ), subtract_duration( \f(CW$duration_object )" 4
.el .IP "* add_duration( \f(CW$duration_object\fR ), subtract_duration( \f(CW$duration_object\fR )" 4
.IX Item "add_duration( $duration_object ), subtract_duration( $duration_object )"
Adds or subtracts one duration from another.
.IP "* add( ... ), subtract( ... )" 4
.IX Item "add( ... ), 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
\&\f(CW\*(C`add_duration()\*(C'\fR or \f(CW\*(C`subtract_duration()\*(C'\fR, as appropriate.
.ie n .IP "* multiply( $number )" 4
.el .IP "* multiply( \f(CW$number\fR )" 4
.IX Item "multiply( $number )"
Multiplies each unit in the by the specified number.
.ie n .IP "* DateTime::Duration\->compare( $duration1\fR, \f(CW$duration2\fR, \f(CW$base_datetime )" 4
.el .IP "* DateTime::Duration\->compare( \f(CW$duration1\fR, \f(CW$duration2\fR, \f(CW$base_datetime\fR )" 4
.IX Item "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
\&\f(CW\*(C`DateTime.pm\*(C'\fR object and comparing the resulting datetimes.  This is
necessary because without a base, many durations are not comparable.
For example, 1 month may otr may not be longer than 29 days, depending
on what datetime it is added to.
.Sp
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.
.Sp
However, if you know that both objects only contain the same units,
and just a single \fItype\fR, then the results of the comparison will be
repeatable.
.IP "* years, months, weeks, days, hours, minutes, seconds, nanoseconds" 4
.IX Item "years, months, weeks, days, hours, minutes, seconds, 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.
.Sp
Here's what each method returns:
.Sp
.Vb 8
\& $dur->year()    == 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' ) )
.Ve
.Sp
If this seems confusing, remember that you can always use the
\&\f(CW\*(C`in_units()\*(C'\fR method to specify exactly what you want.
.Sp
Better yet, if you are trying to generate output suitable for humans,
use the \f(CW\*(C`DateTime::Format::Duration\*(C'\fR module.
.Sh "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 "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.
.SH "AUTHOR"
.IX Header "AUTHOR"
Dave Rolsky <autarch@urth.org>
.PP
However, please see the \s-1CREDITS\s0 file for more details on who I really
stole all the code from.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright (c) 2003\-2006 David Rolsky.  All rights reserved.  This
program is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.
.PP
Portions of the code in this distribution are derived from other
works.  Please see the \s-1CREDITS\s0 file for more details.
.PP
The full text of the license can be found in the \s-1LICENSE\s0 file included
with this module.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
datetime@perl.org mailing list
.PP
http://datetime.perl.org/
Creat By MiNi SheLL
Email: devilkiller@gmail.com