NAME

DateTime::Set - Date/time sets math

SYNOPSIS

use DateTime;
use DateTime::Set;

$date1 = DateTime->new( year => 2002, month => 3, day => 11 );
$set1 = DateTime::Set->new( dates => [ $date1 ] );
#  set1 = 2002-03-11

$date2 = DateTime->new( year => 2003, month => 4, day => 12 );
$set2 = DateTime::Set->new( dates => [ $date1, $date2 ] );
#  set2 = 2002-03-11, and 2003-04-12

# a 'monthly' recurrence:
$set = DateTime::Set->new( 
    recurrence => sub {
        $_[0]->truncate( to => 'month' )->add( months => 1 )
    },
    start => $date1,    # optional
    end => $date2,      # optional
);

$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 ) {
    print $dt->ymd;
};

DESCRIPTION

DateTime::Set is a module for date/time sets. It can be used to handle two different types of sets.

The first is a fixed set of predefined datetime objects. For example, if we wanted to create a set of dates containing the birthdays of people in our family.

The second type of set that it can handle is one based on the idea of a recurrence, such as "every Wednesday", or "noon on the 15th day of every month". This type of set can be have a fixed start and end datetime, but neither is required. So our "every Wednesday set" could be "every Wednesday from the beginning of time until the end of time", or "every Wednesday after 2003-03-05 until the end of time", or "every Wednesday between 2003-03-05 and 2004-01-07".

METHODS

• new

  Creates a new set. The set can either be a list of dates, or it can be specified via a "recurrence" callback.

  To create a set from a list of dates:

  $dates = DateTime::Set->new( dates => [ $dt1, $dt2, $dt3 ] );

  To create a set as a recurrence:

  $months = DateTime::Set->new( 
      start => $today, 
      end => $today_plus_one_year,
      recurrence => sub { $_[0]->truncate( to => 'month' )->add( months => 1 ) }, 
  );

  The "start" and "end" parameters are both optional. If no "start" parameter is given then the set is assumed to start at negative infinity. Similarly, if no "end" parameter is given then the set is assumed to end at infinity.

• add

  $new_set = $set->add( year => 1 );
  
  $dtd = new DateTime::Duration( year => 1 );
  $new_set = $set->add( duration => $dtd );

  This method returns a new set which is the same as the existing set plus the specified duration.

  $meetings_2004 = $meetings_2003->add( years => 1 );

  This method takes the same parameters as allowed by DateTime-add()>. It can also take a "duration" parameter, which should be a DateTime::Duration object. If this parameter is given then all others are ignored.

• min / max

  First or last dates in the set.

• span

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

• iterator / next

  These methods can be used to iterate over the dates in a set.

  $iter = $set1->iterator;
  while ( $dt = $iter->next ) {
      print $dt->ymd;
  }

  The next() or previous() return undef when there are no more datetimes in the iterator.

  Obviously, if a set is specified as a recurrence and has no fixed end datetime, then it may never stop returning datetimes. User beware!

• union / intersection / complement

  These set operations result in a DateTime::Set.

  $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 operations result in a boolean value.

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

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.