DateTime::Set - Datetime sets and set math


NAME

DateTime::Set - Datetime sets and set math


SYNOPSIS

    use DateTime;
    use DateTime::Set;
    $date1 = DateTime->new( year => 2002, month => 3, day => 11 );
    $set1 = DateTime::Set->from_datetimes( dates => [ $date1 ] );
    #  set1 = 2002-03-11
    $date2 = DateTime->new( year => 2003, month => 4, day => 12 );
    $set2 = DateTime::Set->from_datetimes( dates => [ $date1, $date2 ] );
    #  set2 = 2002-03-11, and 2003-04-12
    $date3 = DateTime->new( year => 2003, month => 4, day => 1 );
    print $set2->next( $date3 )->ymd;      # 2003-04-12
    print $set2->previous( $date3 )->ymd;  # 2002-03-11
    print $set2->current( $date3 )->ymd;   # 2002-03-11
    print $set2->closest( $date3 )->ymd;   # 2003-04-12
    # a 'monthly' recurrence:
    $set = DateTime::Set->from_recurrence( 
        recurrence => sub {
            return $_[0] if $_[0]->is_infinite;
            return $_[0]->truncate( to => 'month' )->add( months => 1 )
        },
        span => $date_span1,    # optional span
    );
    $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 datetime 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 datetimes 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 have fixed starting and ending datetimes, 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


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, 2004 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

For details on the Perl DateTime Suite project please see http://datetime.perl.org.

 DateTime::Set - Datetime sets and set math