view release on metacpan or  search on metacpan

lib/DateTime/Set.pm  view on Meta::CPAN

C<DateTime::Infinite::*> objects are not valid set members.

=item * 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 C<span> parameter is optional. It must be a C<DateTime::Span> object.

The span can also be specified using C<start> / C<after> and C<end> /
C<before> parameters, as in the C<DateTime::Span> constructor.  In
this case, if there is a C<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 C<DateTime>, or from
one of the C<DateTime::Calendar::*> classes.  The parameter can also
be a C<DateTime::Infinite::Future> or a C<DateTime::Infinite::Past>
object.

The recurrence must return the I<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 C<DateTime::Infinite::Future>.

It is ok to modify the parameter C<$_[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 C<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 C<DateTime::Infinite::Future> and
C<DateTime::Infinite::Past> objects, in order to define I<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 C<span> parameters. See above.

See also C<DateTime::Event::Recurrence> and the other
C<DateTime::Event::*> factory modules for generating specialized
recurrences, such as sunrise and sunset times, and holidays.

=item * empty_set

Creates a new empty set.

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

=item * is_empty_set

Returns true is the set is empty; false otherwise.

    print "nothing" if $set->is_empty_set;

=item * clone

This object method returns a replica of the given object.

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

=item * 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 );