view release on metacpan or  search on metacpan

README.mkdn  view on Meta::CPAN

interval. **Note:** if the interval doesn't include a time component,
the start time will actually be `00:00:00.000` of the following day
(since the interval covers the entire day). Intervals **include** the
`start` value (in contrast to the `end` value).

This interval can be changed by providing a new [DateTime](https://metacpan.org/pod/DateTime) object as
an argument to this method. If this interval has an explicit ["end"](#end)
date specified, any existing relative ["duration"](#duration) will be cleared.

## end

Returns a [DateTime](https://metacpan.org/pod/DateTime) object representing the end of this interval. This
value is **exclusive** meaning that the interval ends at exactly this time
and does not include this point in time. For instance, an interval that
is one hour long might begin at `09:38:43` and end at `10:38:43`. The
`10:38:43` instant is not a part of this interval. Stated another way,
`$interval->contains($interval->end)` always returns false.

This interval can be changed by providing a new [DateTime](https://metacpan.org/pod/DateTime) object as
an argument to this method. If this interval has an explicit ["start"](#start)
date specified, any existing relative ["duration"](#duration) will be cleared.

**Note:** if the interval doesn't include a time component, the end
time will actually be `00:00:00.000` of the following day (since the
interval covers the entire day). If [DateTime](https://metacpan.org/pod/DateTime) supported a time of day
like `24:00:00.000` that would be used instead.

## duration

Returns a [DateTime::Duration](https://metacpan.org/pod/DateTime::Duration) object representing this interval.

## repeat

Returns the number of times this interval should repeat. This value
can be changed by providing a new value.  A `repeat` value of `0`
means that the interval is not repeated. A `repeat` value of `-1`
means that the interval should be repeated indefinitely.

## iterator

Provides an iterator (as a code ref) that returns new
[DateTimeX::ISO8601::Interval](https://metacpan.org/pod/DateTimeX::ISO8601::Interval) objects for each repitition as defined
by this interval object. Once all the intervals have been returned, the
iterator will return `undef` for each subsequent call.

A few arguments may be specified to modify the behavior of the iterator:

- skip - specify the number of intervals to skip for the first
call to the iterator
- after - skip all intervals that are before this [DateTime](https://metacpan.org/pod/DateTime)
object if this [DateTimeX::ISO8601::Interval](https://metacpan.org/pod/DateTimeX::ISO8601::Interval) is defined only by a
duration (having neither an explicit start or end date) this parameter
will be used as the start date.
- until - specify a specific [DateTime](https://metacpan.org/pod/DateTime) to stop returning new
intervals.  Similar to ["end"](#end), this attribute is **exclusive**.  That is,
once the iterator reaches a point where the interval being returned
["contains"](#contains) this value, an `undef` is returned and the iterator stops
returning new intervals.

The iterator returned optionally accepts a single argument that can be used to indicate the
number of iterations to skip on that call.  For instance:

        my $monthly = DateTimeX::ISO8601::Interval->parse('R12/2013-01-01/P1M');
        my $iterator = $monthly->iterator;
        while(my $month = $iterator->(2)) {
                # $month would be Feb, Apr, Jun, etc
        }

## contains

Returns a boolean indicating whether the provided date (either an `ISO
8601` formatted string or a [DateTime](https://metacpan.org/pod/DateTime) object) is between the ["start"](#start)
or ["end"](#end) dates as defined by this interval.

## abbreviate

Enables abbreviated formatting where duplicate portions of the interval
are eliminated in the second half of the formatted string. To disable,
call `$interval-`abbreviate(0)>.  See the ["format"](#format) method for more information

## format

Returns the string representation of this object.  You may optionally
specify `abbreviate => 1` to abbreviate the interval if possible.  For
instance, `2013-12-01/2013-12-10` can be abbreviated to `2013-12-01/10`.
If the interval does not appear to be eligible for abbreviation, it will be
returned in its full form.

## set\_time\_zone

Sets the time\_zone on the underlying [DateTime](https://metacpan.org/pod/DateTime) objects contained in
this interval (see ["set\_time\_zone" in DateTime](https://metacpan.org/pod/DateTime#set_time_zone)). Also stores the time zone
in `$self` for future use by ["contains"](#contains).

# CAVEATS

### Partial dates and date/times

The `ISO 8601` spec is very complex.  This module relies on
[DateTime::Format::ISO8601](https://metacpan.org/pod/DateTime::Format::ISO8601) for parsing the necessary date strings and
should work well in most cases but some specific aspects of `ISO 8601`
are not well supported, specifically as it relates to partial
representations of dates.

For example, `2013-01/12` should last from January through December
of 2013.  This is parsed correctly but since [DateTime](https://metacpan.org/pod/DateTime) defaults
un-specified portions of a date to the first valid value, the
actual interval ends up being from 2013-01-01 through 2013-12-01.
Similarly, `2013/2014` should last from the beginning of the year
2013 through the entire year of 2014. The interval is actually parsed
as `2013-01-01/2014-01-01`.

Because of the above, it is recommended that you only use full date
and date/time representations with this module (i.e. `yyyy-MM-dd`
or `yyyy-MM-ddTHH:mm::ss`).

### Representing dates with [DateTime](https://metacpan.org/pod/DateTime) objects

The [DateTime](https://metacpan.org/pod/DateTime) set of modules is very robust and a great way of
handling date/times in Perl. However, one of the ambiguities is
that there is no way of representing a date without an explicit time