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 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 { 
        return $_[0] if $_[0]->is_infinite;
        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 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 {
        return $_[0] if $_[0]->is_infinite;
        return $_[0]->truncate( to => 'month' )->add( months => 1 );
    },
);
```
The recurrence will be passed a single parameter, a DateTime.pm object. The recurrence must return the next event after that object. There is no guarantee as to what the object will be set to, only that it will be greater than the object passed to the recurrence.

The recurrence function must return a valid DateTime object.

The function must work if given DateTime::Infinite::Future and DateTime::Infinite::Past parameters.

It is ok to modify $_[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 would look like this:
```
sub every_30_seconds {
    my $dt = shift;
    return $dt if $dt->is_infinite;

    $dt->truncate( to => 'seconds' );

    if ( $dt->second < 30 ) {
        return $dt->add( seconds => 30 - $dt->second );
    } else {
        return $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 either or both 'next' and 'previous' callbacks.

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 is easier to write using span parameters:
```
# "monthly from $dt until forever"

$months = DateTime::Set->from_recurrence(
    start => $dt,
    recurrence => sub {
        return $_[0] if $_[0]->is_infinite;
        return $_[0]->truncate( to => 'month' )->add( months => 1 );
    },
);
```
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.

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

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 added to every element of the set.
```
$dtd = new DateTime::Duration( year => 1 );
$set->add_duration( $dtd );
```
The original set is not modified. The method returns a new set object.

Note: The result of adding a duration to a given set element is expected to be within the span of the previous and the next element in the original set.

For example: given the set [ 2001, 2010, 2015 ], the add_duration result for the value 2010 is expected to be within the span [ 2001 .. 2015 ].
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.

The original set is not modified. The method returns a new set object.
subtract( DateTime::Duration->new parameters )

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

This method accepts either a time zone object or a string that can be passed as the "name" parameter to DateTime::TimeZone->new(). If the new time zone's offset is different from the old time zone, then the local time is adjusted accordingly.

If the old time zone was a floating time zone, then no adjustments to the local time are made, except to account for leap seconds. If the new time zone is floating, then the UTC time is adjusted in order to leave the local time untouched.

The original set time zone is not modified. The method returns a new set object.
set( locale => .. )

This method can be used to change the locale of a date time set.

The original set locale is not modified. The method returns a new set object.
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 DateTime::Infinite::Past or DateTime::Infinite::Future object.
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;
}

# 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.
```
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!
count

Returns a count of DateTime objects in the set.
```
my $n = $set->count( span => $span );
```
Just as with the iterator() method, the count() method can be limited by a span.

If a set is specified as a recurrence and has no fixed begin and end datetimes, then count will return undef, unless you limit it with a span. 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.

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.
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.
map ( sub { ... } )
```
# example: remove the hour:minute:second information
$set = $set2->map( 
    sub {
        return $_->truncate( to => day );
    }
);
```
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 not be called immediately. 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.

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 not be called immediately. Don't count on subroutine side-effects. For example, a print inside the subroutine may happen later than you expect.
iterate ( sub { ... } )

Internal method - use "map" or "grep" instead.

This function apply a callback subroutine to all elements of a set and returns the resulting set.
```
sub callback {
    $_[0]->add( hours => 1 );
}

# $set2 elements are one hour after $set elements, and
# $set is unchanged
$set2 = $set->iterate( \&callback );  
```
If the callback returns undef, the datetime is removed from the set:
```
sub remove_sundays {
    $_[0] unless $_[0]->day_of_week == 7;
}
```
The callback can be used to postpone or anticipate events which collide with datetimes in another set:
```
sub after_holiday {
    $_[0]->add( days => 1 ) while $holidays->contains( $_[0] );
}
```
The callback return value is expected to be within the span of the previous and the next element in the original set.

For example: given the set [ 2001, 2010, 2015 ], the callback result for the value 2010 is expected to be within the span [ 2001 .. 2015 ].

The callback subroutine may not be called immediately. Don't count on subroutine side-effects. For example, a print inside the subroutine may happen later than you expect.

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

The full text of the license can be found in the LICENSE file included with this module.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)