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

# a 'monthly' recurrence:
$set = DateTime::Set->from_recurrence( 
    recurrence => sub {
        $_[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 date/time 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 dates 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

• from_datetimes

  Creates a new set from a list of dates.

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

• 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 { 
          $_[0]->truncate( to => 'month' )->add( months => 1 ) 
      }, 
  );

  The span parameter is optional. It must be a DateTime::Span object.

  The span can also be specified using begin / after and before / end parameters, as in the DateTime::Span constructor. In this case, if there is a span parameter it will be ignored.

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

  The recurrence will be passed a single parameter, a DateTime.pm object. The recurrence must generate the next event before or after that object. There is no guarantee as to what the object will be set to, only that it will be greater or lesser than the last object passed to the recurrence.

  For example, if you wanted a recurrence that generated datetimes in increments of 30 seconds would look like this:

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

  Of course, this recurrence ignores leap seconds, but we'll leave that as an exercise for the reader ;)

  It is also possible to create a recurrence by specifying both 'next' and 'previous' callbacks.

  See also DateTime::Event::Recurrence and the other DateTime::Event modules for generating specialized recurrences, such as sunrise and sunset time, and holidays.

• empty_set

  Creates a new empty set.

• add_duration( $duration )

  $dtd = new DateTime::Duration( year => 1 );
  $new_set = $set->add( duration => $dtd );

  This method returns a new set which is the same as the existing set with the specified duration added to every element of the set.

• add

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

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

• subtract_duration( $duration_object )

  When given a DateTime::Duration object, this method simply calls invert() on that object and passes that new duration to the add_duration method.

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

  Like add(), this is syntactic sugar for the subtract_duration() method.

• min / max

  The first and last dates in the set. These methods may return undef if the set is empty. It is also possible that these methods may return a scalar containing infinity or negative infinity.

• span

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

• iterator / next / previous

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

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

  The boundaries of the iterator can be limited by passing it a span parameter. This should be a DateTime::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 DateTime::Span class's constructors, and an object will be created for you.

  Obviously, if the span you specify does 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 next() or previous() method will return undef when there are no more datetimes in the iterator.

• as_list

  Returns a list of DateTime objects.

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

  Just as with the iterator() method, the as_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 as_list will return undef 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!

• union / intersection / complement

  Set operations may be performed not only with DateTime::Set objects, but also with DateTime::Span, DateTime::SpanSet, and DateTime objects.

  $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 union of a DateTime::Set with a DateTime::Span or a DateTime::SpanSet object returns a DateTime::SpanSet object.

  All other operations will always return a DateTime::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 DateTime, DateTime::Set, DateTime::Span, or DateTime::SpanSet object as an argument.

• previous / next / current / closest

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

  These methods are used to find a set member relative to a given datetime.

  The current() method returns $dt if $dt is an event, otherwise it returns the previous event.

  The closest() method returns $dt if $dt is an event, otherwise it returns the closest event (previous or next).

  All of these methods may return undef if there is no matching datetime in the set.

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 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.