DateTime::Set 0.00_07 will soon be in CPAN. note: the API is not stable. - Flavio S. Glock
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 "[EMAIL PROTECTED]" mailing list. Please report bugs using rt.cpan.org AUTHOR Flavio Soibelmann Glock <[EMAIL PROTECTED]> 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.