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 class that represents sets of datetime spans. An example would be a recurring meeting that occurs from 13:00-15:00 every Friday.

METHODS

• from_spans

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

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

• 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.

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

• 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.

  $dates = 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).

• empty_set

  Creates a new empty set.

• min / max

  First or last dates in the set. These methods may return undef if the set is empty. It is also possible that these methods may return a scalar containing infinity or negative infinity.

• duration

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

  Also available as size().

• span

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

• union / intersection / complement

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

  $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

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