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

FreeBSD Manual Pages

  
 
  

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

NAME
       DateTime::SpanSet - set of DateTime spans

SYNOPSIS
	   $spanset = DateTime::SpanSet->from_spans( spans => [	$dt_span, $dt_span ] );

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

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

	   # data extraction
	   $date = $spanset->min;	    # first date of the	set
	   $date = $spanset->max;	    # last date	of the set

	   $iter = $spanset->iterator;
	   while ( $dt = $iter->next ) {
	       # $dt is	a DateTime::Span
	       print $dt->start->ymd;	# first	date of	span
	       print $dt->end->ymd;	# last date of span
	   };

DESCRIPTION
       "DateTime::SpanSet" is a	class that represents sets of datetime spans.
       An example would	be a recurring meeting that occurs from	13:00-15:00
       every Friday.

       This is different from a	"DateTime::Set", which is made of individual
       datetime	points as opposed to ranges.

METHODS
       o   from_spans

	   Creates a new span set from one or more "DateTime::Span" objects.

	      $spanset = DateTime::SpanSet->from_spans(	spans => [ $dt_span ] );

       o   from_set_and_duration

	   Creates a new span set from one or more "DateTime::Set" objects and
	   a duration.

	   The duration	can be a "DateTime::Duration" object, or the
	   parameters to create	a new "DateTime::Duration" object, such	as
	   "days", "months", etc.

	      $spanset =
		  DateTime::SpanSet->from_set_and_duration
		      (	set => $dt_set,	days =>	1 );

       o   from_sets

	   Creates a new span set from two "DateTime::Set" objects.

	   One set defines the starting	dates, and the other defines the end
	   dates.

	      $spanset =
		  DateTime::SpanSet->from_sets
		      (	start_set => $dt_set1, end_set => $dt_set2 );

	   The spans have the starting date "closed", and the end date "open",
	   like	in "[$dt1, $dt2)".

	   If an end date comes	without	a starting date	before it, then	it
	   defines a span like "(-inf, $dt)".

	   If a	starting date comes without an end date	after it, then it
	   defines a span like "[$dt, inf)".

       o   empty_set

	   Creates a new empty set.

       o   is_empty_set

	   Returns true	is the set is empty; false otherwise.

	       print "nothing" if $set->is_empty_set;

       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   start, min

       o   end,	max

	   First or last dates in the set.

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

	   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 may return "undef" if the set is empty.

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

       o   duration

	   The total size of the set, as a "DateTime::Duration"	object.

	   The duration	may be infinite.

	   Also	available as "size()".

       o   span

	   The total span of the set, as a "DateTime::Span" object.

       o   next

	     my	$span =	$set->next( $dt	);

	   This	method is used to find the next	span in	the set, after a given
	   datetime or span.

	   The return value is a "DateTime::Span", or "undef" if there is no
	   matching span in the	set.

       o   previous

	     my	$span =	$set->previous(	$dt );

	   This	method is used to find the previous span in the	set, before a
	   given datetime or span.

	   The return value is a "DateTime::Span", or "undef" if there is no
	   matching span in the	set.

       o   current

	     my	$span =	$set->current( $dt );

	   This	method is used to find the "current" span in the set, that
	   intersects a	given datetime or span.	If no current span is found,
	   then	the "previous" span is returned.

	   The return value is a "DateTime::SpanSet", or "undef" if there is
	   no matching span in the set.

	   If a	span parameter is given, it may	happen that "current" returns
	   more	than one span.

	   See also: "intersected_spans()" method.

       o   closest

	     my	$span =	$set->closest( $dt );

	   This	method is used to find the "closest" span in the set, given a
	   datetime or span.

	   The return value is a "DateTime::SpanSet", or "undef" if the	set is
	   empty.

	   If a	span parameter is given, it may	happen that "closest" returns
	   more	than one span.

       o   as_list

	   Returns a list of "DateTime::Span" objects.

	     my	@dt_span = $set->as_list( span => $span	);

	   Just	as with	the "iterator()" method, the "as_list()" method	can be
	   limited by a	span.

	   Applying "as_list()"	to a large recurring spanset is	a very
	   expensive operation,	both in	CPU time and in	the memory used.

	   For this reason, when "as_list()" operates on large recurrence
	   sets, it will return	at most	approximately 200 spans. For larger
	   sets, and for infinite sets,	"as_list()" will return	"undef".

	   Please note that this is explicitly not an empty list, since	an
	   empty list is a valid return	value for empty	sets!

	   If you really need to extract spans from a large set, you can:

	   - limit the set with	a shorter span:

	       my @short_list =	$large_set->as_list( span => $short_span );

	   - use an iterator:

	       my @large_list;
	       my $iter	= $large_set->iterator;
	       push @large_list, $dt while $dt = $iter->next;

       o   union

       o   intersection

       o   complement

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

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

       o   intersected_spans

	   This	method can accept a "DateTime" list, a "DateTime::Set",	a
	   "DateTime::Span", or	a "DateTime::SpanSet" object as	an argument.

	       $set = $set1->intersected_spans(	$set2 );

	   The method always returns a "DateTime::SpanSet" object, containing
	   all spans that are intersected by the given set.

	   Unlike the "intersection" method, the spans are not modified.  See
	   diagram below:

			  set1	 [....]	  [....]   [....]   [....]
			  set2	    [................]

		  intersection	    [.]	  [....]   [.]

	     intersected_spans	 [....]	  [....]   [....]

       o   intersects

       o   contains

	   These set functions return a	boolean	value.

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

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

	   intersects()	returns	1 for true, and	0 for false. In	a few cases
	   the algorithm can't decide if the sets intersect at all, and
	   intersects()	will return "undef".

       o   iterator / next / previous

	   This	method can be used to iterate over the spans in	a set.

	       $iter = $spanset->iterator;
	       while ( $dt = $iter->next ) {
		   # $dt is a DateTime::Span
		   print $dt->min->ymd;	  # first date of span
		   print $dt->max->ymd;	  # last date of span
	       }

	   The boundaries of the iterator can be limited by passing it a
	   "span" parameter.  This should be a "DateTime::Span"	object which
	   delimits the	iterator's boundaries.	Optionally, instead of passing
	   an object, you can pass any parameters that would work for one of
	   the "DateTime::Span"	class's	constructors, and an object will be
	   created for you.

	   Obviously, if the span you specify does is not restricted both at
	   the start and end, then your	iterator may iterate forever,
	   depending on	the nature of your set.	 User beware!

	   The "next()"	or "previous()"	methods	will return "undef" when there
	   are no more spans in	the iterator.

       o   start_set

       o   end_set

	   These methods do the	inverse	of the "from_sets" method:

	   "start_set" retrieves a DateTime::Set with the start	datetime of
	   each	span.

	   "end_set" retrieves a DateTime::Set with the	end datetime of	each
	   span.

       o   map ( sub { ... } )

	       # example: enlarge the spans
	       $set = $set2->map(
		   sub {
		       my $start = $_->start;
		       my $end = $_->end;
		       return DateTime::Span->from_datetimes(
			   start => $start,
			   before => $end,
		       );
		   }
	       );

	   This	method is the "set" version of Perl "map".

	   It evaluates	a subroutine for each element of the set (locally
	   setting "$_"	to each	DateTime::Span)	and returns the	set composed
	   of the results of each such evaluation.

	   Like	Perl "map", each element of the	set may	produce	zero, one, or
	   more	elements in the	returned value.

	   Unlike Perl "map", changing "$_" does not change the	original set.
	   This	means that calling map in void context has no effect.

	   The callback	subroutine may not be called immediately.  Don't count
	   on subroutine side-effects. For example, a "print" inside the
	   subroutine may happen later than you	expect.

	   The callback	return value is	expected to be within the span of the
	   "previous" and the "next" element in	the original set.

	   For example:	given the set "[ 2001, 2010, 2015 ]", the callback
	   result for the value	2010 is	expected to be within the span "[ 2001
	   .. 2015 ]".

       o   grep	( sub {	... } )

	       # example: filter out all spans happening today
	       my $today = DateTime->today;
	       $set = $set2->grep(
		   sub {
		       return (	! $_->contains(	$today ) );
		   }
	       );

	   This	method is the "set" version of Perl "grep".

	   It evaluates	a subroutine for each element of the set (locally
	   setting "$_"	to each	DateTime::Span)	and returns the	set consisting
	   of those elements for which the expression evaluated	to true.

	   Unlike Perl "grep", changing	"$_" does not change the original set.
	   This	means that calling grep	in void	context	has no effect.

	   Changing "$_" does change the resulting set.

	   The callback	subroutine may not be called immediately.  Don't count
	   on subroutine side-effects. For example, a "print" inside the
	   subroutine may happen later than you	expect.

       o   iterate

	   Internal method - use "map" or "grep" instead.

	   This	function apply a callback subroutine to	all elements of	a set
	   and returns the resulting set.

	   The parameter $_[0] to the callback subroutine is a
	   "DateTime::Span" object.

	   If the callback returns "undef", the	datetime is removed from the
	   set:

	       sub remove_sundays {
		   $_[0] unless	$_[0]->start->day_of_week == 7;
	       }

	   The callback	return value is	expected to be within the span of the
	   "previous" and the "next" element in	the original set.

	   For example:	given the set "[ 2001, 2010, 2015 ]", the callback
	   result for the value	2010 is	expected to be within the span "[ 2001
	   .. 2015 ]".

	   The callback	subroutine may not be called immediately.  Don't count
	   on subroutine side-effects. For example, a "print" inside the
	   subroutine may happen later than you	expect.

SUPPORT
       Support is offered through the "datetime@perl.org" mailing list.

       Please report bugs using	rt.cpan.org

AUTHOR
       Flavio Soibelmann Glock <fglock@gmail.com>

       The API was developed together with Dave	Rolsky and the DateTime
       Community.

COPYRIGHT
       Copyright (c) 2003 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.

SEE ALSO
       Set::Infinite

       For details on the Perl DateTime	Suite project please see
       <http://datetime.perl.org>.

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

NAME | SYNOPSIS | DESCRIPTION | METHODS | SUPPORT | AUTHOR | COPYRIGHT | SEE ALSO

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

home | help