view release on metacpan or  search on metacpan

README  view on Meta::CPAN

  start
    Returns a DateTime object representing the beginning of this 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 object as an
    argument to this method. If this interval has an explicit "end" date
    specified, any existing relative "duration" will be cleared.

  end
    Returns a 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 object as an
    argument to this method. If this interval has an explicit "start" date
    specified, any existing relative "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 supported a time of day like
    "24:00:00.000" that would be used instead.

  duration
    Returns a 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 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 object if
        this 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 to stop returning new intervals.
        Similar to "end", this attribute is exclusive. That is, once the
        iterator reaches a point where the interval being returned
        "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 object) is between the "start" or
    "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" 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 objects contained in this
    interval (see "set_time_zone" in DateTime). Also stores the time zone in
    $self for future use by "contains".

CAVEATS
   Partial dates and date/times
    The "ISO 8601" spec is very complex. This module relies on
    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 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 objects
    The 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 as well. This is
    significant when parsing an interval that specifies only dates. For
    instance: "2013-12-01/2013-12-07" should represent an interval lasting
    from "2013-12-01" through the end of "2013-12-07". To accomplish this,
    the end date is adjusted by one day such that "$interval->end" returns
    the DateTime object that represents the time the interval ends:
    "2013-12-08T00:00:00"