Provided by: libdatetime-set-perl_0.3900-2_all bug

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 for the current
       year.

       The second type of set that it can handle is one based on 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".

       This module also supports set math operations, so you do things like create a new set from
       the union or difference of two sets, check whether a datetime is a member of a given set,
       etc.

       This is different from a "DateTime::Span", which handles a continuous range as opposed to
       individual datetime points. There is also a module "DateTime::SpanSet" to handle sets of
       spans.

METHODS

       •   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 "DateTime", or from a "DateTime::Calendar::*"
           class.

           "DateTime::Infinite::*" objects are not valid set members.

       •   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 "span" parameter is optional. It must be a "DateTime::Span" object.

           The span can also be specified using "start" / "after" and "end" / "before"
           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 {
                       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 "DateTime", or from one of the
           "DateTime::Calendar::*" classes.  The parameter can also be a
           "DateTime::Infinite::Future" or a "DateTime::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 "DateTime::Infinite::Future".

           It is ok to modify the parameter $_[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.  Consider using
           "truncate()" in this manner 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 "DateTime::Infinite::Future" and "DateTime::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 "span" parameters. See above.

           See also "DateTime::Event::Recurrence" and the other "DateTime::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;

       •   is_empty_set

           Returns true is the set is empty; false otherwise.

               print "nothing" if $set->is_empty_set;

       •   clone

           This object method returns a replica of the given object.

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

       •   add_duration( $duration )

           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 "add_duration()" method.

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

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

       •   set_time_zone( $tz )

           This method will attempt to apply the "set_time_zone" method to every datetime in the
           set.

       •   set( locale => .. )

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

       •   start, min

       •   end, max

           The first and last "DateTime" in the set.

           These methods may return "undef" if the set is empty.

           It is also possible that these methods may return a "DateTime::Infinite::Past" or
           "DateTime::Infinite::Future" object.

           These methods return just a copy of the actual value.  If you modify the result, the
           set will not be modified.

       •   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 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 "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 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 the set elements as a list of "DateTime" objects.  Just as with the
           "iterator()" method, the "as_list()" method can be limited by a span.

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

           Applying "as_list()" to a large recurrence set is a very expensive operation, both in
           CPU time and in the memory used.  If you really need to extract elements from a large
           set, you can limit the set with a shorter span:

               my @short_list = $large_set->as_list( span => $short_span );

           For infinite sets, "as_list()" will return "undef".  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 "DateTime" objects in the set.  Just as with the "iterator()"
           method, the "count()" method can be limited by a span.

             defined( my $n = $set->count) or die "can't count";

             my $n = $set->count( span => $span );
             die "can't count" unless defined $n;

           Applying "count()" to a large recurrence set is a very expensive operation, both in
           CPU time and in the memory used.  If you really need to count elements from a large
           set, you can limit the set with a shorter span:

               my $count = $large_set->count( span => $short_span );

           For infinite sets, "count()" will return "undef".  Please note that this is explicitly
           not a scalar zero, since a zero count is a valid return value for empty sets!

       •   union

       •   intersection

       •   complement

           These set operation methods can accept a "DateTime" list, a "DateTime::Set", a
           "DateTime::Span", or a "DateTime::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 "union" of a "DateTime::Set" with a "DateTime::Span" or a "DateTime::SpanSet"
           object returns a "DateTime::SpanSet" object.

           If "complement" is called without any arguments, then the result is a
           "DateTime::SpanSet" object representing the spans between each of the set's elements.
           If complement is given an argument, then the return value is a "DateTime::Set" object
           representing the set difference between the sets.

           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" list, a "DateTime::Set", a "DateTime::Span", or
           a "DateTime::SpanSet" object as an argument.

           intersects() returns 1 for true, and 0 for false. In a few cases the algorithm can't
           decide if the sets intersect at all, and intersects() will return "undef".

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

           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 "print" inside the
           subroutine may happen later than you expect.

           The callback return value is expected to be within the span of the "previous" and the
           "next" element in the original set.  This is a limitation of the backtracking
           algorithm used in the "Set::Infinite" library.

           For example: given the set "[ 2001, 2010, 2015 ]", the callback result for the value
           2010 is expected to be within the span "[ 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 "print" inside the
           subroutine may happen later than you expect.

       •   iterate ( sub { ... } )

           deprecated method - please use "map" or "grep" instead.

SUPPORT

       Support is offered through the "datetime@perl.org" mailing list.

       Please report bugs using rt.cpan.org

AUTHOR

       Flavio Soibelmann Glock <fglock@gmail.com>

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

COPYRIGHT

       Copyright (c) 2003-2006 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>.