DateTime::Duration man page on Scientific

Man page or keyword search:  
man Server   26626 pages
apropos Keyword Search (all sections)
Output format
Scientific logo
[printable version]

DateTime::Duration(3) User Contributed Perl DocumentationDateTime::Duration(3)

NAME
       DateTime::Duration - Duration objects for date math

SYNOPSIS
	 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
	 $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 ) { ... }

DESCRIPTION
       This is a simple class for representing duration objects.  These
       objects are used whenever you do date math with DateTime.pm.

       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
       "DateTime.pm" object.

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

       "DateTime::Duration" has the following methods:

       ·   new( ... )

	   This method takes the parameters "years", "months", "weeks",
	   "days", "hours", "minutes", "seconds", "nanoseconds", 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.  Similarly, weeks
	   are treated as 7 days, and hours are converted 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, 2004.

	   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 conversion rate.  The only
	   conversions possible are:

	   ·	   years <=> 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 DateTime.pm documentation

	   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::Format::Duration".

       ·   delta_months, delta_days, delta_minutes, delta_seconds,
	   delta_nanoseconds

	   These methods provide the information "DateTime.pm" needs for doing
	   date math.  The numbers returned may be positive 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 methods.

       ·   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 object.

       ·   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 negative.

       ·   add_duration( $duration_object ), subtract_duration(
	   $duration_object )

	   Adds or subtracts one duration from another.

       ·   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 "add_duration()" or "subtract_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 duration to the
	   specified "DateTime.pm" 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.

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

	   Here's what each method returns:

	    $dur->years()	== 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' ) )[0] )

	   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.

   Overloading
       This class overloads addition, subtraction, and mutiplication.

       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
       Support for this module is provided via the datetime@perl.org email
       list.  See http://lists.perl.org/ for more details.

AUTHOR
       Dave Rolsky <autarch@urth.org>

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

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.

       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
       datetime@perl.org mailing list

       http://datetime.perl.org/

perl v5.10.1			  2013-11-21		 DateTime::Duration(3)
[top]

List of man pages available for Scientific

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net