X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?p=catagits%2FGitalist.git;a=blobdiff_plain;f=local-lib5%2Fman%2Fman3%2FDateTime%3A%3ADuration.3pm;fp=local-lib5%2Fman%2Fman3%2FDateTime%3A%3ADuration.3pm;h=7ea1e1c2c1b0ba1e853a57d38ffea8b0a31d204d;hp=0000000000000000000000000000000000000000;hb=3fea05b9fbf95091f4522528b9980a33e0235603;hpb=af746827daa7a8feccee889e1d12ebc74cc9201e diff --git a/local-lib5/man/man3/DateTime::Duration.3pm b/local-lib5/man/man3/DateTime::Duration.3pm new file mode 100644 index 0000000..7ea1e1c --- /dev/null +++ b/local-lib5/man/man3/DateTime::Duration.3pm @@ -0,0 +1,430 @@ +.\" 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 +.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/