text: 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 ); ->min; # first date of the set $date = $set1->max; # last date of the set $iter = $set1->iterator; while ( $dt = $iter->next ) { print $dt->ymd; }; for the current year.
  The second type of set that it can handle is one based".
  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
  spanparameter is optional. It must be a
  DateTime::Spanobject.
  The span can also be specified using
  start/
  afterand
  end/
  beforeparameters, as in the
  DateTime::Spanconstructor. In this case, if there is a
  spanparameter 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::Futureor a
  DateTime::Infinite::Pastobject.
  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::Futureand
  DateTime::Infinite::Pastobjects, 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
  spanparameters. See above.
  See also
  DateTime::Event::Recurrenceand 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.
  cloneis 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::Durationobject, this method simply calls
  invert()on that object and passes that new duration to the
  add_durationmethod.
  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_zonemethod to every datetime in the set.
  set( locale => .. )
  This method can be used to change the
  localeof a datetime set.
  start, min
  end, max
  The first and last
  DateTimein the set.
  These methods may return
  undefif the set is empty.
  It is also possible that these methods may return a
  DateTime::Infinite::Pastor
  DateTime::Infinite::Futureobject.
  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::Spanobject.
  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
  spanparameter. This should be a
  DateTime::Spanobject 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::Spanclass'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
  undefwhen there are no more datetimes in the iterator.
  as_list
  Returns the set elements as a list of
  DateTimeobjects. 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
  DateTimeobjects 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
  DateTimelist, a
  DateTime::Set, a
  DateTime::Span, or a
  DateTime::SpanSetobject 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
  unionof a
  DateTime::Setwith a
  DateTime::Spanor a
  DateTime::SpanSetobject returns a
  DateTime::SpanSetobject.
  If
  complementis called without any arguments, then the result is a
  DateTime::SpanSetobject representing the spans between each of the set's elements. If complement is given an argument, then the return value is a
  DateTime::Setobject 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
  DateTimelist, a
  DateTime::Set, a
  DateTime::Span, or a
  DateTime::SpanSetobject 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.
  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
  $dtif $dt is an event, otherwise it returns the previous event.
  The
  closest()method returns
  $dtif $dt is an event, otherwise it returns the closest event (previous or next).
  All of these methods may return
  undefif 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
  The callback return value is expected to be within the span of the
  previousand the
  nextelement in the original set. This is a limitation of the backtracking algorithm used in the
  Set::Infinitelibrary.
  For example: given the set
  [ 2001, 2010, 2015 ], the callback result for the value
  2010is 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
  iterate ( sub { ... } )
  deprecated method - please use "map" or "grep" instead..