Filewatcher File Search File Search
Content Search
» » » » » » perl-DateTime-0.42-1.el4.rf.x86_64.rpm » Content »
pkg://perl-DateTime-0.42-1.el4.rf.x86_64.rpm:130489/usr/share/man/man3/  info  HEADER  downloads

perl-DateTime - Date and time objects…  more info»


DateTime::DuratioUser Contributed Perl DocumentDateTime::Duration(3)

       DateTime::Duration - Duration objects for date math

         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('days', 'hours', 'seconds');

         # The important parts for date math

         my %deltas = $d->deltas


         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

         if ( $d->is_positive ) { ... }
         if ( $d->is_zero )     { ... }
         if ( $d->is_negative ) { ... }

       This is a simple class for representing duration objects.
       These objects are used whenever you do date math with Date‐

       See the How Date Math is Done section of the doc‐
       umentation 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 "Date‐" object.

       Like "DateTime" itself, "DateTime::Duration" returns the
       object from mutator methods in order to make method chaining

       "DateTime::Duration" has the following methods:

       * new( ... )
           This method takes the parameters "years", "months",
           "weeks", "days", "hours", "minutes", "seconds", "nanosec‐
           onds", and "end_of_month".  All of these except
           "end_of_month" are numbers.  If any of the numbers are
           negative, the entire duration is negative.

           All of the numbers must be integers.

           Internally, years as just treated as 12 months.  Simi‐
           larly, weeks are treated as 7 days, and hours are con‐
           verted to minutes.  Seconds and nanoseconds are both
           treated separately.

           The "end_of_month" parameter must be either "wrap",
           "limit", or "preserve".  This parameter specifies how
           date math that crosses the end of a month is handled.

           In "wrap" 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.

           If you specify "end_of_month" mode as "limit", 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,

           If you specify "end_of_month" mode as "preserve", the
           same calculation is done as for "limit" 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.

           For positive durations, the "end_of_month" parameter
           defaults to wrap.  For negative durations, the default is
           "limit".  This should match how most people "intuitively"
           expect datetime math to work.

       * clone
           Returns a new object with the same properties as the
           object on which this method was called.

       * 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:

             my $dur = DateTime::Duration->new( years => 1, months => 15 );

             $dur->in_units( 'years' );            # 2
             $dur->in_units( 'months' );           # 27
             $dur->in_units( 'years', 'months' );  # (2, 3)
             $dur->in_units( 'weeks', 'days' );    # (0, 0) !

           The last example demonstrates that there will not be any
           conversion between units which don't have a fixed conver‐
           sion rate.  The only conversions possible are:

           * year <=> months
           * weeks <=> days
           * hours <=> minutes
           * seconds <=> nanoseconds

           For the explanation of why this happens, please see the
           How Date Math is Done section of the documen‐

           Note that the numbers returned by this method may not
           match the values given to the constructor.

           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).

           If you need more flexibility in presenting information
           about durations, please take a look a "DateTime::For‐

       * delta_months, delta_days, delta_minutes, delta_seconds,
           These methods provide the information "" needs
           for doing date math.  The numbers returned may be posi‐
           tive or negative.

       * deltas
           Returns a hash with the keys "months", "days", "minutes",
           "seconds", and "nanoseconds", containing all the delta
           information for the object.

       * is_positive, is_zero, is_negative
           Indicates whether or not the duration is positive, zero,
           or negative.

           If the duration contains both positive and negative
           units, then it will return false for all of these meth‐

       * is_wrap_mode, is_limit_mode, is_preserve_mode
           Indicates what mode is used for end of month wrapping.

       * end_of_month_mode
           Returns one of "wrap", "limit", or "preserve".

       * calendar_duration
           Returns a new object with the same calendar delta (months
           and days only) and end of month mode as the current

       * clock_duration
           Returns a new object with the same clock deltas (minutes,
           seconds, and nanoseconds) and end of month mode as the
           current object.

       * 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

       * add_duration( $duration_object ), subtract_duration( $dura‐
       tion_object )
           Adds or subtracts one duration from another.

       * add( ... ), subtract( ... )
           Syntactic sugar for addition and subtraction.  The param‐
           eters given to these methods are used to create a new
           object, which is then passed to "add_duration()" or "sub‐
           tract_duration()", as appropriate.

       * multiply( $number )
           Multiplies each unit in the by the specified number.

       * 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 dura‐
           tion to the specified "" object and comparing
           the resulting datetimes.  This is necessary because with‐
           out a base, many durations are not comparable.  For exam‐
           ple, 1 month may otr may not be longer than 29 days,
           depending on what datetime it is added to.

           If no base datetime is given, then the result of "Date‐
           Time->now" 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.

           However, if you know that both objects only consist of
           one type of unit (months or days or hours, etc.), and
           each duration contains the same type of unit, then the
           results of the comparison will be repeatable.

       * years, months, weeks, days, hours, minutes, seconds,
           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.

           Here's what each method returns:

            $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' ) )

           If this seems confusing, remember that you can always use
           the "in_units()" method to specify exactly what you want.

           Better yet, if you are trying to generate output suitable
           for humans, use the "DateTime::Format::Duration" module.


       This class overloads addition, subtraction, and mutiplica‐

       Comparison is not overloaded.  If you attempt to compare
       durations using "<=>" or "cmp", then an exception will be
       thrown!  Use the "compare()" class method instead.

       Support for this module is provided via the
       email list.  See for more details.

       Dave Rolsky <>

       However, please see the CREDITS file for more details on who
       I really stole all the code from.

       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.

       Portions of the code in this distribution are derived from
       other works.  Please see the CREDITS file for more details.

       The full text of the license can be found in the LICENSE file
       included with this module.

SEE ALSO mailing list

perl v5.8.5                  2008-02-29        DateTime::Duration(3)
Results 1 - 1 of 1
Help - FTP Sites List - Software Dir.
Search over 15 billion files
© 1997-2017