# cf.TimeDuration.interval

`TimeDuration.``interval`(dt, calendar=None, end=False, iso=None)

  Return a time interval of exactly the time duration.

  The start (or end, if the end parameter is True) date-time of the time interval is determined by the year, month, day, hour, minute and second parameters, but if any of these is unset then its default value is taken from the attribute of the same name (i.e. the `year`, `month`, `day`, `hour`, `minute` and `second` attributes respectively).

  See also

  `bounds`

  New in version 1.0.

  Examples 1: |

      >>> cf.TimeDuration(1, 'calendar_years').interval(1999)
      (<CF Datetime: 1999-01-01 00:00:00>, <CF Datetime: 2000-01-01 00:00:00>)

    > Parameters: | year, month, day, hour, minute, second: `int`, optional The date-time of the start (or end) of the time interval. If any parameter is unset then its value defaults to the attribute of the same name. The time interval calculation requires that all of the parameters have numerical values, so if an unset parameter has a corresponding attribute whose value is `None` then an exception will be raised. Example: `t.interval(year=1999, day=16)` is equivalent to `t.interval(1999, t.month, 16, t.hour, t.minute, t.second)`. end: `bool`, optional If True then the date-time given by the year, month, day, hour, minute and second parameters defines the end of the time interval. By default it defines the start of the time interval. calendar: `str`, optional Define the CF calendar for the input date-time and output time interval. By default the calendar of the input date-time is used. If calendar is set, then the calendar of the input date-time is overridden. Example: To set a calendar without leap years: `calendar='noleap'`. iso: `str`, optional Return the time interval as an ISO 8601 time interval string rather than the default of a tuple of date-time objects. Valid values are (with example outputs for the time interval “3 years from 2007-03-01 13:00:00”):
    > iso | Example output
    > --- | ---
    > `'start and end'` | `'2007-03-01 13:00:00/2010-03-01 13:00:00'`
    > `'start and duration'` | `'2007-03-01 13:00:00/P3Y'`
    > `'duration and end'` | `'P3Y/2010-03-01 13:00:00'`
  Returns: | out: 2-tuple of `cf.Datetime` or `datetime.datetime`; or `str` The date-times at each end of the time interval. The first date-time is always earlier than or equal to the second date-time. If iso has been set then an ISO 8601 time interval string is returned instead of a tuple.
  Examples 2: |

      >>> cf.TimeDuration(1, 'calendar_months').interval(1999, 12)
      (<CF Datetime: 1999-12-01 00:00:00>, <CF Datetime: 2000-01-01 00:00:00>)

      >>> cf.TimeDuration(2, 'calendar_years').interval(2000, 2, end=True)
      (<CF Datetime: 1998-02-01 00:00:00>, <CF Datetime: 2000-02-01 00:00:00>)

      >>> cf.TimeDuration(30, 'days').interval(1983, 12, 1, 6)
      (<CF Datetime: 1983-12-01 06:00:00>, <CF Datetime: 1983-12-31 06:00:00>)

      >>> cf.TimeDuration(30, 'days').interval(1983, 12, 1, 6, end=True)
      (<CF Datetime: 1983-11-01 06:00:00>, <CF Datetime: 1983-12-01 06:00:00>)

      >>> cf.TimeDuration(0, 'days').interval(1984, 2, 3)
      (<CF Datetime: 1984-02-03 00:00:00>, <CF Datetime: 1984-02-03 00:00:00>)

      >>> cf.TimeDuration(5, 'days', hour=6).interval(2004, 3, 2, end=True)
      (<CF Datetime: 2004-02-26 06:00:00>, <CF Datetime: 2004-03-02 06:00:00>)

      >>> cf.TimeDuration(5, 'days', hour=6).interval(2004, 3, 2, end=True, calendar='noleap')
      (<CF Datetime: 2004-02-25 06:00:00>, <CF Datetime: 2004-03-02 06:00:00>)

      >>> cf.TimeDuration(5, 'days', hour=6).interval(2004, 3, 2, end=True, calendar='360_day')
      (<CF Datetime: 2004-02-27 06:00:00>, <CF Datetime: 2004-03-02 06:00:00>)

      >>> cf.TimeDuration(5, 'days', hour=6).interval(2004, 3, 2, 13, end=True)
      (datetime.datetime(2004, 2, 26, 13, 0), <CF Datetime: 2004-03-02 13:00:00>)

      >>> cf.TimeDuration(19897.546, 'hours').interval(1984, 2, 3, 0)
      (<CF Datetime: 1984-02-03 00:00:00>, <CF Datetime: 1986-05-12 01:32:46>)

      >>> cf.TimeDuration(19897.546, 'hours').interval(1984, 2, 3, 0, end=True)
      (<CF Datetime: 1981-10-26 22:27:14>, <CF Datetime: 1984-02-03 00:00:00>)

  Create `cf.Query` objects for a time interval - one including both bounds and one which excludes the upper bound:

      >>> t = cf.TimeDuration(2, 'calendar_years')
      >>> interval = t.interval(1999, 12)
      >>> c = cf.wi(*interval)
      >>> c
      <CF Query: (wi [<CF Datetime: 1999-12-01 00:00:00>, <CF Datetime: 2001-01-01 00:00:00>])>
      >>> d = cf.ge(interval[0]) & cf.lt(interval[1])
      >>> d
      <CF Query: [(ge <CF Datetime: 1999-12-01 00:00:00>) & (lt <CF Datetime: 2000-01-01 00:00:00>)]>
      >>> c == cf.dt('2001-1-1')
      True
      >>> d == cf.dt('2001-1-1')
      False

  Create a `cf.Query` object which may be used to test where a time coordinate object’s bounds lie inside a time interval:

      >>> t = cf.TimeDuration(1, 'calendar_months')
      >>> c = cf.cellwi(*t.interval(2000, 1, end=True))
      >>> c
      <CF Query: [lower_bounds(ge <CF Datetime: 1999-12-01 00:00:00>) & upper_bounds(le <CF Datetime: 2000-01-01 00:00:00>)]>

  Create ISO 8601 time interval strings:

      >>> t = cf.TimeDuration(6, 'calendar_years')
      >>> t.interval(1999, 12, end=True, iso='start and end')
      '1993-12-01 00:00:00/1999-12-01 00:00:00'
      >>> t.interval(1999, 12, end=True, iso='start and duration')
      '1993-12-01 00:00:00/P6Y'
      >>> t.interval(1999, 12, end=True, iso='duration and end')
      'P6Y/1999-12-01 00:00:00'