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.
