DateTime::Duration man page on Darwin

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

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

NAME
       DateTime::Duration - Duration objects for date math

VERSION
       version 0.77

SYNOPSIS
	 use DateTime::Duration;

	 $dur = DateTime::Duration->new(
	     years	 => 3,
	     months	 => 5,
	     weeks	 => 1,
	     days	 => 1,
	     hours	 => 6,
	     minutes	 => 15,
	     seconds	 => 45,
	     nanoseconds => 12000
	 );

	 my ( $days, $hours, $seconds ) = $dur->in_units('days', 'hours', 'seconds');

	 # Human-readable accessors, always positive, but consider using
	 # DateTime::Format::Duration instead
	 $dur->years;
	 $dur->months;
	 $dur->weeks;
	 $dur->days;
	 $dur->hours;
	 $dur->minutes;
	 $dur->seconds;
	 $dur->nanoseconds;

	 $dur->is_wrap_mode
	 $dur->is_limit_mode
	 $dur->is_preserve_mode

	 print $dur->end_of_month_mode;

	 # Multiply all values by -1
	 my $opposite = $dur->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;

	 if ( $dur->is_positive ) { ... }
	 if ( $dur->is_zero )	  { ... }
	 if ( $dur->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 DateTime Math Works 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:

   DateTime::Duration->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.

   $dur->clone()
       Returns a new object with the same properties as the object on which
       this method was called.

   $dur->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 is the case, please see the How
       DateTime Math Works 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".

   $dur->is_positive(), $dur->is_zero(), $dur->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.

   $dur->is_wrap_mode(), $dur->is_limit_mode(), $dur->is_preserve_mode()
       Indicates what mode is used for end of month wrapping.

   $dur->end_of_month_mode()
       Returns one of "wrap", "limit", or "preserve".

   $dur->calendar_duration()
       Returns a new object with the same calendar delta (months and days
       only) and end of month mode as the current object.

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

   $dur->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.

       You can set the end of month mode in the inverted duration explicitly
       by passing "end_of_month => ..." to the "inverse()" method.

   $dur->add_duration( $duration_object ), $dur->subtract_duration(
       $duration_object )
       Adds or subtracts one duration from another.

   $dur->add( ... ), $dur->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.

   $dur->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.

   $dur->delta_months(), $dur->delta_days(), $dur->delta_minutes(),
       $dur->delta_seconds(), $dur->delta_nanoseconds()
       These methods provide the information "DateTime.pm" needs for doing
       date math. The numbers returned may be positive or negative. This is
       mostly useful for doing date math in DateTime.

   $dur->deltas()
       Returns a hash with the keys "months", "days", "minutes", "seconds",
       and "nanoseconds", containing all the delta information for the object.
       This is mostly useful for doing date math in DateTime.

   $dur->years(), $dur->months(), $dur->weeks(), $dur->days(), $dur->hours(),
       $dur->minutes(), $dur->seconds(), $dur->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.

SEE ALSO
       datetime@perl.org mailing list

       http://datetime.perl.org/

AUTHOR
       Dave Rolsky <autarch@urth.org>

COPYRIGHT AND LICENSE
       This software is Copyright (c) 2012 by Dave Rolsky.

       This is free software, licensed under:

	 The Artistic License 2.0 (GPL Compatible)

perl v5.16.2			  2013-08-25		 DateTime::Duration(3)
[top]

List of man pages available for Darwin

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