local-lib5/man/man3/DateTime::Duration.3pm

   1 .\" Automatically generated by Pod::Man 2.22 (Pod::Simple 3.10)
   2 .\"
   3 .\" Standard preamble:
   4 .\" ========================================================================
   5 .de Sp \" Vertical space (when we can't use .PP)
   6 .if t .sp .5v
   7 .if n .sp
   8 ..
   9 .de Vb \" Begin verbatim text
  10 .ft CW
  11 .nf
  12 .ne \\$1
  13 ..
  14 .de Ve \" End verbatim text
  15 .ft R
  16 .fi
  17 ..
  18 .\" Set up some character translations and predefined strings.  \*(-- will
  19 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  20 .\" double quote, and \*(R" will give a right double quote.  \*(C+ will
  21 .\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
  22 .\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
  23 .\" nothing in troff, for use with C<>.
  24 .tr \(*W-
  25 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  26 .ie n \{\
  27 .    ds -- \(*W-
  28 .    ds PI pi
  29 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  30 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  31 .    ds L" ""
  32 .    ds R" ""
  33 .    ds C` ""
  34 .    ds C' ""
  35 'br\}
  36 .el\{\
  37 .    ds -- \|\(em\|
  38 .    ds PI \(*p
  39 .    ds L" ``
  40 .    ds R" ''
  41 'br\}
  42 .\"
  43 .\" Escape single quotes in literal strings from groff's Unicode transform.
  44 .ie \n(.g .ds Aq \(aq
  45 .el       .ds Aq '
  46 .\"
  47 .\" If the F register is turned on, we'll generate index entries on stderr for
  48 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
  49 .\" entries marked with X<> in POD.  Of course, you'll have to process the
  50 .\" output yourself in some meaningful fashion.
  51 .ie \nF \{\
  52 .    de IX
  53 .    tm Index:\\$1\t\\n%\t"\\$2"
  54 ..
  55 .    nr % 0
  56 .    rr F
  57 .\}
  58 .el \{\
  59 .    de IX
  60 ..
  61 .\}
  62 .\"
  63 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  64 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  65 .    \" fudge factors for nroff and troff
  66 .if n \{\
  67 .    ds #H 0
  68 .    ds #V .8m
  69 .    ds #F .3m
  70 .    ds #[ \f1
  71 .    ds #] \fP
  72 .\}
  73 .if t \{\
  74 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  75 .    ds #V .6m
  76 .    ds #F 0
  77 .    ds #[ \&
  78 .    ds #] \&
  79 .\}
  80 .    \" simple accents for nroff and troff
  81 .if n \{\
  82 .    ds ' \&
  83 .    ds ` \&
  84 .    ds ^ \&
  85 .    ds , \&
  86 .    ds ~ ~
  87 .    ds /
  88 .\}
  89 .if t \{\
  90 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
  91 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
  92 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
  93 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
  94 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
  95 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
  96 .\}
  97 .    \" troff and (daisy-wheel) nroff accents
  98 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
  99 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 100 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 101 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 102 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 103 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 104 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 105 .ds ae a\h'-(\w'a'u*4/10)'e
 106 .ds Ae A\h'-(\w'A'u*4/10)'E
 107 .    \" corrections for vroff
 108 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 109 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 110 .    \" for low resolution devices (crt and lpr)
 111 .if \n(.H>23 .if \n(.V>19 \
 112 \{\
 113 .    ds : e
 114 .    ds 8 ss
 115 .    ds o a
 116 .    ds d- d\h'-1'\(ga
 117 .    ds D- D\h'-1'\(hy
 118 .    ds th \o'bp'
 119 .    ds Th \o'LP'
 120 .    ds ae ae
 121 .    ds Ae AE
 122 .\}
 123 .rm #[ #] #H #V #F C
 124 .\" ========================================================================
 125 .\"
 126 .IX Title "DateTime::Duration 3"
 127 .TH DateTime::Duration 3 "2009-12-09" "perl v5.8.7" "User Contributed Perl Documentation"
 128 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
 129 .\" way too many mistakes in technical documents.
 130 .if n .ad l
 131 .nh
 132 .SH "NAME"
 133 DateTime::Duration \- Duration objects for date math
 134 .SH "SYNOPSIS"
 135 .IX Header "SYNOPSIS"
 136 .Vb 1
 137 \&  use DateTime::Duration;
 138 \&
 139 \&  $d = DateTime::Duration\->new( years   => 3,
 140 \&                                months  => 5,
 141 \&                                weeks   => 1,
 142 \&                                days    => 1,
 143 \&                                hours   => 6,
 144 \&                                minutes => 15,
 145 \&                                seconds => 45,
 146 \&                                nanoseconds => 12000 );
 147 \&
 148 \&  # Convert to different units
 149 \&  $d\->in_units(\*(Aqdays\*(Aq, \*(Aqhours\*(Aq, \*(Aqseconds\*(Aq);
 150 \&
 151 \&  # The important parts for date math
 152 \&  $d\->delta_months
 153 \&  $d\->delta_days
 154 \&  $d\->delta_minutes
 155 \&  $d\->delta_seconds
 156 \&  $d\->delta_nanoseconds
 157 \&
 158 \&  my %deltas = $d\->deltas
 159 \&
 160 \&  $d\->is_wrap_mode
 161 \&  $d\->is_limit_mode
 162 \&  $d\->is_preserve_mode
 163 \&
 164 \&  print $d\->end_of_month_mode;
 165 \&
 166 \&  # Multiple all deltas by \-1
 167 \&  my $opposite = $d\->inverse;
 168 \&
 169 \&  my $bigger  = $dur1 + $dur2;
 170 \&  my $smaller = $dur1 \- $dur2; # the result could be negative
 171 \&  my $bigger  = $dur1 * 3;
 172 \&
 173 \&  my $base_dt = DateTime\->new( year => 2000 );
 174 \&  my @sorted =
 175 \&      sort { DateTime::Duration\->compare( $a, $b, $base_dt ) } @durations;
 176 \&
 177 \&  # Human\-readable accessors, always positive, but use
 178 \&  # DateTime::Format::Duration instead
 179 \&  $d\->years;
 180 \&  $d\->months;
 181 \&  $d\->weeks;
 182 \&  $d\->days;
 183 \&  $d\->hours;
 184 \&  $d\->minutes;
 185 \&  $d\->seconds;
 186 \&  $d\->nanoseconds;
 187 \&
 188 \&  if ( $d\->is_positive ) { ... }
 189 \&  if ( $d\->is_zero )     { ... }
 190 \&  if ( $d\->is_negative ) { ... }
 191 .Ve
 192 .SH "DESCRIPTION"
 193 .IX Header "DESCRIPTION"
 194 This is a simple class for representing duration objects.  These
 195 objects are used whenever you do date math with DateTime.pm.
 196 .PP
 197 See the How Date Math is Done
 198 section of the DateTime.pm documentation for more details.  The short
 199 course:  One cannot in general convert between seconds, minutes, days,
 200 and months, so this class will never do so.  Instead, create the
 201 duration with the desired units to begin with, for example by calling
 202 the appropriate subtraction/delta method on a \f(CW\*(C`DateTime.pm\*(C'\fR object.
 203 .SH "METHODS"
 204 .IX Header "METHODS"
 205 Like \f(CW\*(C`DateTime\*(C'\fR itself, \f(CW\*(C`DateTime::Duration\*(C'\fR returns the object from
 206 mutator methods in order to make method chaining possible.
 207 .PP
 208 \&\f(CW\*(C`DateTime::Duration\*(C'\fR has the following methods:
 209 .IP "\(bu" 4
 210 new( ... )
 211 .Sp
 212 This method takes the parameters \*(L"years\*(R", \*(L"months\*(R", \*(L"weeks\*(R", \*(L"days\*(R",
 213 \&\*(L"hours\*(R", \*(L"minutes\*(R", \*(L"seconds\*(R", \*(L"nanoseconds\*(R", and \*(L"end_of_month\*(R".  All
 214 of these except \*(L"end_of_month\*(R" are numbers.  If any of the numbers are
 215 negative, the entire duration is negative.
 216 .Sp
 217 All of the numbers \fBmust be integers\fR.
 218 .Sp
 219 Internally, years as just treated as 12 months.  Similarly, weeks are
 220 treated as 7 days, and hours are converted to minutes.  Seconds and
 221 nanoseconds are both treated separately.
 222 .Sp
 223 The \*(L"end_of_month\*(R" parameter must be either \*(L"wrap\*(R", \*(L"limit\*(R", or
 224 \&\*(L"preserve\*(R".  This parameter specifies how date math that crosses the
 225 end of a month is handled.
 226 .Sp
 227 In \*(L"wrap\*(R" mode, adding months or years that result in days beyond the
 228 end of the new month will roll over into the following month.  For
 229 instance, adding one year to Feb 29 will result in Mar 1.
 230 .Sp
 231 If you specify \*(L"end_of_month\*(R" mode as \*(L"limit\*(R", the end of the month is
 232 never crossed.  Thus, adding one year to Feb 29, 2000 will result in
 233 Feb 28, 2001.  If you were to then add three more years this will
 234 result in Feb 28, 2004.
 235 .Sp
 236 If you specify \*(L"end_of_month\*(R" mode as \*(L"preserve\*(R", the same calculation
 237 is done as for \*(L"limit\*(R" except that if the original date is at the end
 238 of the month the new date will also be.  For instance, adding one
 239 month to Feb 29, 2000 will result in Mar 31, 2000.
 240 .Sp
 241 For positive durations, the \*(L"end_of_month\*(R" parameter defaults to wrap.
 242 For negative durations, the default is \*(L"limit\*(R".  This should match how
 243 most people \*(L"intuitively\*(R" expect datetime math to work.
 244 .IP "\(bu" 4
 245 clone
 246 .Sp
 247 Returns a new object with the same properties as the object on which
 248 this method was called.
 249 .IP "\(bu" 4
 250 in_units( ... )
 251 .Sp
 252 Returns the length of the duration in the units (any of those that can
 253 be passed to new) given as arguments.  All lengths are integral,
 254 but may be negative.  Smaller units are computed from what remains
 255 after taking away the larger units given, so for example:
 256 .Sp
 257 .Vb 1
 258 \&  my $dur = DateTime::Duration\->new( years => 1, months => 15 );
 259 \&
 260 \&  $dur\->in_units( \*(Aqyears\*(Aq );            # 2
 261 \&  $dur\->in_units( \*(Aqmonths\*(Aq );           # 27
 262 \&  $dur\->in_units( \*(Aqyears\*(Aq, \*(Aqmonths\*(Aq );  # (2, 3)
 263 \&  $dur\->in_units( \*(Aqweeks\*(Aq, \*(Aqdays\*(Aq );    # (0, 0) !
 264 .Ve
 265 .Sp
 266 The last example demonstrates that there will not be any conversion
 267 between units which don't have a fixed conversion rate.  The only
 268 conversions possible are:
 269 .RS 4
 270 .IP "\(bu" 8
 271 years <=> months
 272 .IP "\(bu" 8
 273 weeks <=> days
 274 .IP "\(bu" 8
 275 hours <=> minutes
 276 .IP "\(bu" 8
 277 seconds <=> nanoseconds
 278 .RE
 279 .RS 4
 280 .Sp
 281 For the explanation of why this happens, please see the How Date
 282 Math is Done section of the
 283 DateTime.pm documentation
 284 .Sp
 285 Note that the numbers returned by this method may not match the values
 286 given to the constructor.
 287 .Sp
 288 In list context, in_units returns the lengths in the order of the units
 289 given.  In scalar context, it returns the length in the first unit (but
 290 still computes in terms of all given units).
 291 .Sp
 292 If you need more flexibility in presenting information about
 293 durations, please take a look a \f(CW\*(C`DateTime::Format::Duration\*(C'\fR.
 294 .RE
 295 .IP "\(bu" 4
 296 delta_months, delta_days, delta_minutes, delta_seconds, delta_nanoseconds
 297 .Sp
 298 These methods provide the information \f(CW\*(C`DateTime.pm\*(C'\fR needs for doing
 299 date math.  The numbers returned may be positive or negative.
 300 .IP "\(bu" 4
 301 deltas
 302 .Sp
 303 Returns a hash with the keys \*(L"months\*(R", \*(L"days\*(R", \*(L"minutes\*(R", \*(L"seconds\*(R",
 304 and \*(L"nanoseconds\*(R", containing all the delta information for the
 305 object.
 306 .IP "\(bu" 4
 307 is_positive, is_zero, is_negative
 308 .Sp
 309 Indicates whether or not the duration is positive, zero, or negative.
 310 .Sp
 311 If the duration contains both positive and negative units, then it
 312 will return false for \fBall\fR of these methods.
 313 .IP "\(bu" 4
 314 is_wrap_mode, is_limit_mode, is_preserve_mode
 315 .Sp
 316 Indicates what mode is used for end of month wrapping.
 317 .IP "\(bu" 4
 318 end_of_month_mode
 319 .Sp
 320 Returns one of \*(L"wrap\*(R", \*(L"limit\*(R", or \*(L"preserve\*(R".
 321 .IP "\(bu" 4
 322 calendar_duration
 323 .Sp
 324 Returns a new object with the same \fIcalendar\fR delta (months and days
 325 only) and end of month mode as the current object.
 326 .IP "\(bu" 4
 327 clock_duration
 328 .Sp
 329 Returns a new object with the same \fIclock\fR deltas (minutes, seconds,
 330 and nanoseconds) and end of month mode as the current object.
 331 .IP "\(bu" 4
 332 inverse
 333 .Sp
 334 Returns a new object with the same deltas as the current object, but
 335 multiple by \-1.  The end of month mode for the new object will be the
 336 default end of month mode, which depends on whether the new duration
 337 is positive or negative.
 338 .IP "\(bu" 4
 339 add_duration( \f(CW$duration_object\fR ), subtract_duration( \f(CW$duration_object\fR )
 340 .Sp
 341 Adds or subtracts one duration from another.
 342 .IP "\(bu" 4
 343 add( ... ), subtract( ... )
 344 .Sp
 345 Syntactic sugar for addition and subtraction.  The parameters given to
 346 these methods are used to create a new object, which is then passed to
 347 \&\f(CW\*(C`add_duration()\*(C'\fR or \f(CW\*(C`subtract_duration()\*(C'\fR, as appropriate.
 348 .IP "\(bu" 4
 349 multiply( \f(CW$number\fR )
 350 .Sp
 351 Multiplies each unit in the by the specified number.
 352 .IP "\(bu" 4
 353 DateTime::Duration\->compare( \f(CW$duration1\fR, \f(CW$duration2\fR, \f(CW$base_datetime\fR )
 354 .Sp
 355 This is a class method that can be used to compare or sort durations.
 356 Comparison is done by adding each duration to the specified
 357 \&\f(CW\*(C`DateTime.pm\*(C'\fR object and comparing the resulting datetimes.  This is
 358 necessary because without a base, many durations are not comparable.
 359 For example, 1 month may or may not be longer than 29 days, depending
 360 on what datetime it is added to.
 361 .Sp
 362 If no base datetime is given, then the result of \f(CW\*(C`DateTime\->now\*(C'\fR
 363 is used instead.  Using this default will give non-repeatable results
 364 if used to compare two duration objects containing different units.
 365 It will also give non-repeatable results if the durations contain
 366 multiple types of units, such as months and days.
 367 .Sp
 368 However, if you know that both objects only consist of one type of
 369 unit (months \fIor\fR days \fIor\fR hours, etc.), and each duration contains
 370 the same type of unit, then the results of the comparison will be
 371 repeatable.
 372 .IP "\(bu" 4
 373 years, months, weeks, days, hours, minutes, seconds, nanoseconds
 374 .Sp
 375 These methods return numbers indicating how many of the given unit the
 376 object represents, after having done a conversion to any larger units.
 377 For example, days are first converted to weeks, and then the remainder
 378 is returned.  These numbers are always positive.
 379 .Sp
 380 Here's what each method returns:
 381 .Sp
 382 .Vb 8
 383 \& $dur\->years()       == abs( $dur\->in_units(\*(Aqyears\*(Aq) )
 384 \& $dur\->months()      == abs( ( $dur\->in_units( \*(Aqmonths\*(Aq, \*(Aqyears\*(Aq ) )[0] )
 385 \& $dur\->weeks()       == abs( $dur\->in_units( \*(Aqweeks\*(Aq ) )
 386 \& $dur\->days()        == abs( ( $dur\->in_units( \*(Aqdays\*(Aq, \*(Aqweeks\*(Aq ) )[0] )
 387 \& $dur\->hours()       == abs( $dur\->in_units( \*(Aqhours\*(Aq ) )
 388 \& $dur\->minutes       == abs( ( $dur\->in_units( \*(Aqminutes\*(Aq, \*(Aqhours\*(Aq ) )[0] )
 389 \& $dur\->seconds       == abs( $dur\->in_units( \*(Aqseconds\*(Aq ) )
 390 \& $dur\->nanoseconds() == abs( ( $dur\->in_units( \*(Aqnanoseconds\*(Aq, \*(Aqseconds\*(Aq ) )[0] )
 391 .Ve
 392 .Sp
 393 If this seems confusing, remember that you can always use the
 394 \&\f(CW\*(C`in_units()\*(C'\fR method to specify exactly what you want.
 395 .Sp
 396 Better yet, if you are trying to generate output suitable for humans,
 397 use the \f(CW\*(C`DateTime::Format::Duration\*(C'\fR module.
 398 .SS "Overloading"
 399 .IX Subsection "Overloading"
 400 This class overloads addition, subtraction, and mutiplication.
 401 .PP
 402 Comparison is \fBnot\fR overloaded.  If you attempt to compare durations
 403 using \f(CW\*(C`<=>\*(C'\fR or \f(CW\*(C`cmp\*(C'\fR, then an exception will be thrown!  Use the
 404 \&\f(CW\*(C`compare()\*(C'\fR class method instead.
 405 .SH "SUPPORT"
 406 .IX Header "SUPPORT"
 407 Support for this module is provided via the datetime@perl.org email
 408 list.  See http://lists.perl.org/ for more details.
 409 .SH "AUTHOR"
 410 .IX Header "AUTHOR"
 411 Dave Rolsky <autarch@urth.org>
 412 .PP
 413 However, please see the \s-1CREDITS\s0 file for more details on who I really
 414 stole all the code from.
 415 .SH "COPYRIGHT"
 416 .IX Header "COPYRIGHT"
 417 Copyright (c) 2003\-2009 David Rolsky.  All rights reserved.  This
 418 program is free software; you can redistribute it and/or modify it
 419 under the same terms as Perl itself.
 420 .PP
 421 Portions of the code in this distribution are derived from other
 422 works.  Please see the \s-1CREDITS\s0 file for more details.
 423 .PP
 424 The full text of the license can be found in the \s-1LICENSE\s0 file included
 425 with this module.
 426 .SH "SEE ALSO"
 427 .IX Header "SEE ALSO"
 428 datetime@perl.org mailing list
 429 .PP
 430 http://datetime.perl.org/