NAME

DateTime::Set - Date/time sets math

SYNOPSIS

NOTE: this is just an example of how the API will look like when this module is finished.

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

DESCRIPTION

DateTime::Set is a module for date/time sets. It allows you to generate groups of dates, like "every wednesday", and then find all the dates matching that pattern, within a time range.

ERROR HANDLING

A method will return undef if it can't find a suitable representation for its result, such as when trying to list() a too complex set.

Programs that expect to generate empty sets or complex sets should check for the undef return value when extracting data.

Set elements must be either a DateTime or a +/- Infinity value. Scalar values, including date strings, are not expected and might cause strange results.

METHODS

• new

  Generates a new set. The set can be generated from a list of dates, or from a "recurrence" subroutine.

  From a list of dates:

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

  From a recurrence:

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

  The start and end parameters are optional.

• add

  $set->add( year => 1 );

  This method adds a value to the current datetime set. It moves the whole set values ahead or back in time.

  Example:

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

  See DateTime::add() for full syntax description.

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>

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.