Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
DateTime::Duration(3) User Contributed Perl DocumentationDateTime::Duration(3)

NAME
       DateTime::Duration - Duration objects for date math

VERSION
       version 1.54

SYNOPSIS
	   use DateTime::Duration;

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

	   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.

       See the How DateTime Math Works section of the DateTime 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	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 class method accepts the following parameters:

       o   year

	   An integer containing the number of years in	the duration. This is
	   optional.

       o   month

	   An integer containing the number of months in the duration. This is
	   optional.

       o   weeks

	   An integer containing the number of weeks in	the duration. This is
	   optional.

       o   days

	   An integer containing the number of days in the duration. This is
	   optional.

       o   hours

	   An integer containing the number of hours in	the duration. This is
	   optional.

       o   minutes

	   An integer containing the number of minutes in the duration.	This
	   is optional.

       o   seconds

	   An integer containing the number of seconds in the duration.	This
	   is optional.

       o   nanoseconds

	   An integer containing the number of nanoseconds in the duration.
	   This	is optional.

       o   end_of_month

	   This	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 "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 "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, this	parameter defaults to "wrap". For
	   negative durations, the default is "preserve". This should match
	   how most people "intuitively" expect	datetime math to work.

       All of the duration units can be	positive or negative. However, 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.

   $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 "DateTime::Duration->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:

       o   years <=> months

       o   weeks <=> days

       o   hours <=> minutes

       o   seconds <=> nanoseconds

       For the explanation of why this is the case, please see the How
       DateTime	Math Works section of the DateTime documentation

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

       In list context,	"$dur->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
       multiplied 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 an "end_of_month" parameter to the "$dur->inverse" method.

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

   $dur->add( ... ), $dur->subtract( ... )
       These accept either constructor parameters for a	new
       "DateTime::Duration" object or an already-constructed duration object.

   $dur->multiply($number)
       Multiplies each unit in the "DateTime::Duration"	object by the
       specified integer 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
       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 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
       "$dur->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.

SEE ALSO
       datetime@perl.org mailing list

       http://datetime.perl.org/

SUPPORT
       Support for this	module is provided via the datetime@perl.org email
       list. See http://lists.perl.org/	for more details.

       Bugs may	be submitted at
       <https://github.com/houseabsolute/DateTime.pm/issues>.

       There is	a mailing list available for users of this distribution,
       <mailto:datetime@perl.org>.

       I am also usually active	on IRC as 'autarch' on "irc://irc.perl.org".

SOURCE
       The source code repository for DateTime can be found at
       <https://github.com/houseabsolute/DateTime.pm>.

AUTHOR
       Dave Rolsky <autarch@urth.org>

COPYRIGHT AND LICENSE
       This software is	Copyright (c) 2003 - 2020 by Dave Rolsky.

       This is free software, licensed under:

	 The Artistic License 2.0 (GPL Compatible)

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

perl v5.32.1			  2020-12-04		 DateTime::Duration(3)

NAME | VERSION | SYNOPSIS | DESCRIPTION | METHODS | SEE ALSO | SUPPORT | SOURCE | AUTHOR | COPYRIGHT AND LICENSE

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=DateTime::Duration&sektion=3&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help