view release on metacpan or  search on metacpan

DateTime-ISO8601-Interval-0.003/lib/DateTimeX/ISO8601/Interval.pm  view on Meta::CPAN

an argument to this method. If this interval has an explicit L</"end">
date specified, any existing relative L</"duration"> will be cleared.

=head2 end

Returns a L<DateTime> object representing the end of this interval. This
value is B<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 C<09:38:43> and end at C<10:38:43>. The
C<10:38:43> instant is not a part of this interval. Stated another way,
C<$interval-E<gt>contains($interval-E<gt>end)> always returns false.

This interval can be changed by providing a new L<DateTime> object as
an argument to this method. If this interval has an explicit L</"start">
date specified, any existing relative L</"duration"> will be cleared.

B<Note:> if the interval doesn't include a time component, the end
time will actually be C<00:00:00.000> of the following day (since the
interval covers the entire day). If L<DateTime> supported a time of day
like C<24:00:00.000> that would be used instead.

=head2 duration

Returns a L<DateTime::Duration> object representing this interval.

=head2 repeat

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

=head2 iterator

Provides an iterator (as a code ref) that returns new
L<DateTimeX::ISO8601::Interval> objects for each repitition as defined
by this interval object. Once all the intervals have been returned, the
iterator will return C<undef> for each subsequent call.

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

=over 4

=item * skip - specify the number of intervals to skip for the first
call to the iterator

=item * after - skip all intervals that are before this L<DateTime>
object if this L<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.

=item * until - specify a specific L<DateTime> to stop returning new
intervals.  Similar to L</end>, this attribute is B<exclusive>.  That is,
once the iterator reaches a point where the interval being returned
L</contains> this value, an C<undef> is returned and the iterator stops
returning new intervals.

=back

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
	}

=head2 contains

Returns a boolean indicating whether the provided date (either an C<ISO
8601> formatted string or a L<DateTime> object) is between the L</"start">
or L</"end"> dates as defined by this interval.

=head2 abbreviate

Enables abbreviated formatting where duplicate portions of the interval
are eliminated in the second half of the formatted string. To disable,
call C<$interval->abbreviate(0)>.  See the L</format> method for more information

=head2 format

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

=head2 set_time_zone

Sets the time_zone on the underlying L<DateTime> objects contained in
this interval (see L<DateTime/set_time_zone>). Also stores the time zone
in C<$self> for future use by L</contains>.

=head1 CAVEATS

=head3 Partial dates and date/times

The C<ISO 8601> spec is very complex.  This module relies on
L<DateTime::Format::ISO8601> for parsing the necessary date strings and
should work well in most cases but some specific aspects of C<ISO 8601>
are not well supported, specifically as it relates to partial
representations of dates.

For example, C<2013-01/12> should last from January through December
of 2013.  This is parsed correctly but since L<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, C<2013/2014> should last from the beginning of the year
2013 through the entire year of 2014. The interval is actually parsed
as C<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. C<yyyy-MM-dd>
or C<yyyy-MM-ddTHH:mm::ss>).

=head3 Representing dates with L<DateTime> objects

The L<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