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( $date1 );
#  set1 = 2002-03-11

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

$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;           # start date
$date = $set1->max;           # end date
# disjunct sets can be split into an array of simpler sets
@subsets = $set1->list;
$date = $subsets[1]->min;

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

All methods are inherited from Set::Infinite.

Set::Infinite methods offset() and quantize() are disabled. The module will die with an error string if one of these methods are called.

New Methods

• add_duration

  NOTE: this is an experimental feature.

  add_duration( at_start => $datetime_duration, 
                at_end =>   $datetime_duration );

  This method returns a new set, which is created by adding a DateTime::Duration to the current datetime set.

  It moves the whole set values ahead or back in time. It will affect the start, end, or both ends of the set intervals.

  Example:

  $one_year = DateTime::Duration( years => 1 );
  $meetings_2004 = $meetings_2003->add_duration( 
       at_start => $one_year,
       at_end   => $one_year );

• create_recurrence

  NOTE: this is an experimental feature.

  Generates recurrence intervals of "years", "months", "weeks", "days", "hours", "minutes", or "seconds".

  $months = DateTime::Set->create_recurrence( time_unit => 'months' );

  Recurrences can be filtered and combined, in order to build more complex recurrences.

  Example:

  $weeks = DateTime::Set->create_recurrence( time_unit => 'weeks' );
  $one_day =  DateTime::Duration( days => 1 );
  $two_days = DateTime::Duration( days => 2 );
  
  $tuesdays = $weeks->add_duration(
       at_start => $one_day,           # +24h from week start
       at_end   => $two_days );        # +48h from week start

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.