--- /dev/null
+.\" Automatically generated by Pod::Man 2.22 (Pod::Simple 3.10)
+.\"
+.\" 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" ''
+'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 turned on, 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.
+.ie \nF \{\
+. de IX
+. tm Index:\\$1\t\\n%\t"\\$2"
+..
+. nr % 0
+. rr F
+.\}
+.el \{\
+. de IX
+..
+.\}
+.\"
+.\" 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 "2009-12-09" "perl v5.8.7" "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 "SYNOPSIS"
+.IX Header "SYNOPSIS"
+.Vb 1
+\& use DateTime::Duration;
+\&
+\& $d = DateTime::Duration\->new( years => 3,
+\& months => 5,
+\& weeks => 1,
+\& days => 1,
+\& hours => 6,
+\& minutes => 15,
+\& seconds => 45,
+\& nanoseconds => 12000 );
+\&
+\& # Convert to different units
+\& $d\->in_units(\*(Aqdays\*(Aq, \*(Aqhours\*(Aq, \*(Aqseconds\*(Aq);
+\&
+\& # The important parts for date math
+\& $d\->delta_months
+\& $d\->delta_days
+\& $d\->delta_minutes
+\& $d\->delta_seconds
+\& $d\->delta_nanoseconds
+\&
+\& my %deltas = $d\->deltas
+\&
+\& $d\->is_wrap_mode
+\& $d\->is_limit_mode
+\& $d\->is_preserve_mode
+\&
+\& print $d\->end_of_month_mode;
+\&
+\& # Multiple all deltas by \-1
+\& my $opposite = $d\->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;
+\&
+\& # 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;
+\&
+\& 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 "\(bu" 4
+new( ... )
+.Sp
+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 "\(bu" 4
+clone
+.Sp
+Returns a new object with the same properties as the object on which
+this method was called.
+.IP "\(bu" 4
+in_units( ... )
+.Sp
+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 );
+\&
+\& $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
+.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 "\(bu" 8
+years <=> months
+.IP "\(bu" 8
+weeks <=> days
+.IP "\(bu" 8
+hours <=> minutes
+.IP "\(bu" 8
+seconds <=> nanoseconds
+.RE
+.RS 4
+.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 "\(bu" 4
+delta_months, delta_days, delta_minutes, delta_seconds, delta_nanoseconds
+.Sp
+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 "\(bu" 4
+deltas
+.Sp
+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 "\(bu" 4
+is_positive, is_zero, is_negative
+.Sp
+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 "\(bu" 4
+is_wrap_mode, is_limit_mode, is_preserve_mode
+.Sp
+Indicates what mode is used for end of month wrapping.
+.IP "\(bu" 4
+end_of_month_mode
+.Sp
+Returns one of \*(L"wrap\*(R", \*(L"limit\*(R", or \*(L"preserve\*(R".
+.IP "\(bu" 4
+calendar_duration
+.Sp
+Returns a new object with the same \fIcalendar\fR delta (months and days
+only) and end of month mode as the current object.
+.IP "\(bu" 4
+clock_duration
+.Sp
+Returns a new object with the same \fIclock\fR deltas (minutes, seconds,
+and nanoseconds) and end of month mode as the current object.
+.IP "\(bu" 4
+inverse
+.Sp
+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.
+.IP "\(bu" 4
+add_duration( \f(CW$duration_object\fR ), subtract_duration( \f(CW$duration_object\fR )
+.Sp
+Adds or subtracts one duration from another.
+.IP "\(bu" 4
+add( ... ), subtract( ... )
+.Sp
+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.
+.IP "\(bu" 4
+multiply( \f(CW$number\fR )
+.Sp
+Multiplies each unit in the by the specified number.
+.IP "\(bu" 4
+DateTime::Duration\->compare( \f(CW$duration1\fR, \f(CW$duration2\fR, \f(CW$base_datetime\fR )
+.Sp
+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 or 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 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.
+.IP "\(bu" 4
+years, months, weeks, days, hours, minutes, seconds, nanoseconds
+.Sp
+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\->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
+.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.
+.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 "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\-2009 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/
projects / catagits/Gitalist.git / blobdiff