DateTime::Set - Datetime sets and set math

    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;
    };

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.

* from_datetimes

Creates a new set from a list of datetimes.

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

The datetimes can be objects from class CWDateTime, or from a CWDateTime::Calendar::* class. CWDateTime::Infinite::* objects are not valid set members. However, these datetimes are very useful as set boundaries.

* from_recurrence

Creates a new set specified via a recurrence callback.

    $months = DateTime::Set->from_recurrence( 
        span => $dt_span_this_year,    # optional span
        recurrence => sub { 
            return $_[0]->truncate( to => 'month' )->add( months => 1 ) 
        }, 
    );

The CWspan parameter is optional. It must be a CWDateTime::Span object. The span can also be specified using CWbegin / CWafter and CWbefore / CWend parameters, as in the CWDateTime::Span constructor. In this case, if there is a CWspan parameter it will be ignored.

    $months = DateTime::Set->from_recurrence(
        after => $dt_now,
        recurrence => sub {
            return $_[0]->truncate( to => 'month' )->add( months => 1 );
        },
    );

The recurrence function will be passed a single parameter, a datetime object. The parameter can be an object from class CWDateTime, or from one of the CWDateTime::Calendar::* classes. The parameter can also be a CWDateTime::Infinite::Future or a CWDateTime::Infinite::Past object. The recurrence must return the next event after that object. There is no guarantee as to what the returned object will be set to, only that it will be greater than the object passed to the recurrence. If there are no more datetimes after the given parameter, then the recurrence function should return CWDateTime::Infinite::Future. It is ok to modify the parameter CW$_[0] inside the recurrence function. There are no side-effects. For example, if you wanted a recurrence that generated datetimes in increments of 30 seconds, it would look like this:

  sub every_30_seconds {
      my $dt = shift;
      if ( $dt->second < 30 ) {
          return $dt->truncate( to => 'minute' )->add( seconds => 30 );
      } else {
          return $dt->truncate( to => 'minute' )->add( minutes => 1 );
      }
  }

Note that this recurrence takes leap seconds into account. You should use datetime calendar methods whenever possible, in order to avoid complicated arithmetic problems! It is also possible to create a recurrence by specifying either or both of 'next' and 'previous' callbacks. The callbacks can return CWDateTime::Infinite::Future and CWDateTime::Infinite::Past objects, in order to define bounded recurrences. In this case, both 'next' and 'previous' callbacks must be defined:

    # "monthly from $dt until forever"

    my $months = DateTime::Set->from_recurrence(
        next => sub {
            return $dt if $_[0] < $dt;
            $_[0]->truncate( to => 'month' );
            $_[0]->add( months => 1 );
            return $_[0];
        },
        previous => sub {
            my $param = $_[0]->clone;
            $_[0]->truncate( to => 'month' );
            $_[0]->subtract( months => 1 ) if $_[0] == $param;
            return $_[0] if $_[0] >= $dt;
            return DateTime::Infinite::Past->new;
        },
    );

Bounded recurrences are easier to write using CWspan parameters. See above. See also CWDateTime::Event::Recurrence and the other CWDateTime::Event::* factory modules for generating specialized recurrences, such as sunrise and sunset times, and holidays.

* empty_set

Creates a new empty set.

    $set = DateTime::Set->empty_set;
    print "empty set" unless defined $set->max;

* clone

This object method returns a replica of the given object. CWclone is useful if you want to apply a transformation to a set, but you want to keep the previous value:

    $set2 = $set1->clone;
    $set2->add_duration( year => 1 );  # $set1 is unaltered

This method adds the specified duration to every element of the set.

    $dt_dur = new DateTime::Duration( year => 1 );
    $set->add_duration( $dt_dur );

The original set is modified. If you want to keep the old values use:

    $new_set = $set->clone->add_duration( $dt_dur );

* add

This method is syntactic sugar around the CWadd_duration() method.

    $meetings_2004 = $meetings_2003->clone->add( years => 1 );

When given a CWDateTime::Duration object, this method simply calls CWinvert() on that object and passes that new duration to the CWadd_duration method.

* subtract( DateTime::Duration->new parameters )

Like CWadd(), this is syntactic sugar for the CWsubtract_duration() method. This method will attempt to apply the CWset_time_zone method to every datetime in the set.

* set( locale => .. )

This method can be used to change the CWlocale of a datetime set.

* min

* max

The first and last datetimes in the set. These methods may return CWundef if the set is empty. It is also possible that these methods may return a CWDateTime::Infinite::Past or CWDateTime::Infinite::Future object.

* span

Returns the total span of the set, as a CWDateTime::Span object.

* iterator / next / previous

These methods can be used to iterate over the datetimes in a set.

    $iter = $set1->iterator;
    while ( $dt = $iter->next ) {
        print $dt->ymd;
    }

    # iterate backwards
    $iter = $set1->iterator;
    while ( $dt = $iter->previous ) {
        print $dt->ymd;
    }

The boundaries of the iterator can be limited by passing it a CWspan parameter. This should be a CWDateTime::Span object which delimits the iterator's boundaries. Optionally, instead of passing an object, you can pass any parameters that would work for one of the CWDateTime::Span class's constructors, and an object will be created for you. Obviously, if the span you specify is not restricted both at the start and end, then your iterator may iterate forever, depending on the nature of your set. User beware! The CWnext() or CWprevious() method will return CWundef when there are no more datetimes in the iterator.

* as_list

Returns the set elements as a list of CWDateTime objects.

  my @dt = $set->as_list( span => $span );

Just as with the CWiterator() method, the CWas_list() method can be limited by a span. If a set is specified as a recurrence and has no fixed begin and end datetimes, then CWas_list will return CWundef unless you limit it with a span. Please note that this is explicitly not an empty list, since an empty list is a valid return value for empty sets!

* count

Returns a count of CWDateTime objects in the set.

  my $n = $set->count( span => $span );

Just as with the CWiterator() method, the CWcount() method can be limited by a span. If a set is specified as a recurrence and has no fixed begin and end datetimes, then CWcount will return CWundef, unless you limit it with a span. Please note that this is explicitly not a scalar CWzero, since a zero count is a valid return value for empty sets!

* union

* intersection

* complement

These set operation methods can accept a CWDateTime list, a CWDateTime::Set, a CWDateTime::Span, or a CWDateTime::SpanSet object as an argument.

    $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"

The CWunion of a CWDateTime::Set with a CWDateTime::Span or a CWDateTime::SpanSet object returns a CWDateTime::SpanSet object. If CWcomplement is called without any arguments, then the result is a CWDateTime::SpanSet object representing the spans between each of the set's elements. If complement is given an argument, then the return value is a CWDateTime::Set object representing the set difference between the sets. All other operations will always return a CWDateTime::Set.

* intersects

* contains

These set operations result in a boolean value.

    if ( $set1->intersects( $set2 ) ) { ...  # like "touches", "interferes"
    if ( $set1->contains( $dt ) ) { ...    # like "is-fully-inside"

These methods can accept a CWDateTime list, a CWDateTime::Set, a CWDateTime::Span, or a CWDateTime::SpanSet object as an argument.

* previous

* next

* current

* closest

  my $dt = $set->next( $dt );
  my $dt = $set->previous( $dt );
  my $dt = $set->current( $dt );
  my $dt = $set->closest( $dt );

These methods are used to find a set member relative to a given datetime. The CWcurrent() method returns CW$dt if CW$dt is an event, otherwise it returns the previous event. The CWclosest() method returns CW$dt if CW$dt is an event, otherwise it returns the closest event (previous or next). All of these methods may return CWundef if there is no matching datetime in the set. These methods will try to set the returned value to the same time zone as the argument, unless the argument has a 'floating' time zone.

* map ( sub { ... } )

    # example: remove the hour:minute:second information
    $set = $set2->map( 
        sub {
            return $_->truncate( to => day );
        }
    );

    # example: postpone or antecipate events which 
    #          match datetimes within another set
    $set = $set2->map(
        sub {
            return $_->add( days => 1 ) while $holidays->contains( $_ );
        }
    );

This method is the set version of Perl map. It evaluates a subroutine for each element of the set (locally setting $_ to each datetime) and returns the set composed of the results of each such evaluation. Like Perl map, each element of the set may produce zero, one, or more elements in the returned value. Unlike Perl map, changing $_ does not change the original set. This means that calling map in void context has no effect. The callback subroutine may be called later in the program, due to lazy evaluation. So don't count on subroutine side-effects. For example, a CWprint inside the subroutine may happen later than you expect. The callback return value is expected to be within the span of the CWprevious and the CWnext element in the original set. This is a limitation of the backtracking algorithm used in the CWSet::Infinite library. For example: given the set CW[ 2001, 2010, 2015 ], the callback result for the value CW2010 is expected to be within the span CW[ 2001 .. 2015 ].

* grep ( sub { ... } )

    # example: filter out any sundays
    $set = $set2->grep( 
        sub {
            return ( $_->day_of_week != 7 );
        }
    );

This method is the set version of Perl grep. It evaluates a subroutine for each element of the set (locally setting $_ to each datetime) and returns the set consisting of those elements for which the expression evaluated to true. Unlike Perl grep, changing $_ does not change the original set. This means that calling grep in void context has no effect. Changing $_ does change the resulting set. The callback subroutine may be called later in the program, due to lazy evaluation. So don't count on subroutine side-effects. For example, a CWprint inside the subroutine may happen later than you expect.

* iterate ( sub { ... } )

deprecated method - please use map or grep instead.

Support is offered through the CWdatetime@perl.org mailing list.

Please report bugs using rt.cpan.org

Flavio Soibelmann Glock <fglock@pucrs.br>

The API was developed together with Dave Rolsky and the DateTime Community.

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.

Set::Infinite

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