NAME

DateTime::SpanSet - set of DateTime spans

SYNOPSIS

$set1 = DateTime::SpanSet->new( spans => [ $dt_span, $dt_span ] );

$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->min;           # first date of the set
$date = $set1->max;           # last date of the set

$iter = $set1->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 module for sets of date/time spans or time-ranges.

METHODS

• new

  Creates a new span set.

  $dates = DateTime::SpanSet->new( spans => [ $dt_span ] );  # from DateTime::Span
  
  $dates = DateTime::SpanSet->new( sets => [ $dt_set ] );    # from DateTime::Set

• min / max

  First or last dates in the set.

• size

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

  This is the sum of the durations of all spans.

• span

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

• union / intersection / complement

  These set operations return the resulting SpanSet.

  $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"

• intersects / contains

  These set functions return a boolean value.

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

• iterator / next

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

  $iter = $set1->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 next() returns undef when there are no more spans in the iterator. Obviously, if a span set is specified as a recurrence and has no fixed end, then it may never stop returning spans. User beware!

SUPPORT

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

Please report bugs using rt.cpan.org

AUTHOR

Flavio Soibelmann Glock <fglock@pucrs.br>

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

http://datetime.perl.org.

For details on the Perl DateTime Suite project please see http://perl-date-time.sf.net.