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

FreeBSD Manual Pages


home | help
DateTime::Span(3)     User Contributed Perl Documentation    DateTime::Span(3)

       DateTime::Span -	Datetime spans

	   use DateTime;
	   use DateTime::Span;

	   $date1 = DateTime->new( year	=> 2002, month => 3, day => 11 );
	   $date2 = DateTime->new( year	=> 2003, month => 4, day => 12 );
	   $set2 = DateTime::Span->from_datetimes( start => $date1, end	=> $date2 );
	   #  set2 = 2002-03-11	until 2003-04-12

	   $set	= $set1->union(	$set2 );	 # like	"OR", "insert",	"both"
	   $set	= $set1->complement( $set2 );	 # like	"delete", "remove"
	   $set	= $set1->intersection( $set2 );	 # like	"AND", "while"
	   $set	= $set1->complement;		 # like	"NOT", "negate", "invert"

	   if (	$set1->intersects( $set2 ) ) { ...  # like "touches", "interferes"
	   if (	$set1->contains( $set2 ) ) { ...    # like "is-fully-inside"

	   # data extraction
	   $date = $set1->start;	   # first date	of the span
	   $date = $set1->end;		   # last date of the span

       "DateTime::Span"	is a module for	handling datetime spans, otherwise
       known as	ranges or periods ("from X to Y, inclusive of all datetimes in

       This is different from a	"DateTime::Set", which is made of individual
       datetime	points as opposed to a range. There is also a module
       "DateTime::SpanSet" to handle sets of spans.

       o   from_datetimes

	   Creates a new span based on a starting and ending datetime.

	   A 'closed' span includes its	end-dates:

	      $span = DateTime::Span->from_datetimes( start => $dt1, end => $dt2 );

	   An 'open' span does not include its end-dates:

	      $span = DateTime::Span->from_datetimes( after => $dt1, before => $dt2 );

	   A 'semi-open' span includes one of its end-dates:

	      $span = DateTime::Span->from_datetimes( start => $dt1, before => $dt2 );
	      $span = DateTime::Span->from_datetimes( after => $dt1, end => $dt2 );

	   A span might	have just a starting date, or just an ending date.
	   These spans end, or start, in an imaginary 'forever'	date:

	      $span = DateTime::Span->from_datetimes( start => $dt1 );
	      $span = DateTime::Span->from_datetimes( end => $dt2 );
	      $span = DateTime::Span->from_datetimes( after => $dt1 );
	      $span = DateTime::Span->from_datetimes( before =>	$dt2 );

	   You cannot give both	a "start" and "after" argument,	nor can	you
	   give	both an	"end" and "before" argument.  Either of	these
	   conditions will cause the "from_datetimes()"	method to die.

	   To summarize, a datetime passed as either "start" or	"end" is
	   included in the span.  A datetime passed as either "after" or
	   "before" is excluded	from the span.

       o   from_datetime_and_duration

	   Creates a new span.

	      $span = DateTime::Span->from_datetime_and_duration(
		  start	=> $dt1, duration => $dt_dur1 );
	      $span = DateTime::Span->from_datetime_and_duration(
		  after	=> $dt1, hours => 12 );

	   The new "end	of the set" is open by default.

       o   clone

	   This	object method returns a	replica	of the given object.

       o   set_time_zone( $tz )

	   This	method accepts either a	time zone object or a string that can
	   be passed as	the "name" parameter to	"DateTime::TimeZone->new()".
	   If the new time zone's offset is different from the old time	zone,
	   then	the local time is adjusted accordingly.

	   If the old time zone	was a floating time zone, then no adjustments
	   to the local	time are made, except to account for leap seconds.  If
	   the new time	zone is	floating, then the UTC time is adjusted	in
	   order to leave the local time untouched.

       o   duration

	   The total size of the set, as a "DateTime::Duration"	object,	or as
	   a scalar containing infinity.

	   Also	available as "size()".

       o   start, min

       o   end,	max

	   First or last dates in the span.

	   It is possible that the return value	from these methods may be a
	   "DateTime::Infinite::Future"	or a "DateTime::Infinite::Past"xs

	   If the set ends "before" a date $dt,	it returns $dt.	Note that in
	   this	case $dt is not	a set element -	but it is a set	boundary.

	   These methods return	just a copy of the actual boundary value.  If
	   you modify the result, the set will not be modified.

       o   start_is_closed

       o   end_is_closed

	   Returns true	if the first or	last dates belong to the span (	start
	   <= x	<= end ).

       o   start_is_open

       o   end_is_open

	   Returns true	if the first or	last dates are excluded	from the span
	   ( start < x < end ).

       o   union

       o   intersection

       o   complement

	   Set operations may be performed not only with "DateTime::Span"
	   objects, but	also with "DateTime::Set" and "DateTime::SpanSet"
	   objects.  These set operations always return	a "DateTime::SpanSet"

	       $set = $span->union( $set2 );	     # like "OR", "insert", "both"
	       $set = $span->complement( $set2 );    # like "delete", "remove"
	       $set = $span->intersection( $set2 );  # like "AND", "while"
	       $set = $span->complement;	     # like "NOT", "negate", "invert"

       o   intersects

       o   contains

	   These set functions return a	boolean	value.

	       if ( $span->intersects( $set2 ) ) { ...	# like "touches", "interferes"
	       if ( $span->contains( $dt ) ) { ...    #	like "is-fully-inside"

	   These methods can accept a "DateTime", "DateTime::Set",
	   "DateTime::Span", or	"DateTime::SpanSet" object as an argument.

       Support is offered through the "" mailing list.

       Please report bugs using

       Flavio Soibelmann Glock <>

       The API was developed together with Dave	Rolsky and the DateTime

       Copyright (c) 2003-2006 Flavio Soibelmann Glock.	All rights reserved.
       This program is free software; you can distribute it and/or modify it
       under the same terms as Perl itself.

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


       For details on the Perl DateTime	Suite project please see

perl v5.32.1			  2016-10-09		     DateTime::Span(3)


Want to link to this manual page? Use this URL:

home | help