# cf.TimeDuration

class `cf.``TimeDuration`(duration, units=None, month=1, day=1, hour=0, minute=0, second=0)

  Bases: `object`

  A duration of time.

  The duration of time is a number of either calendar years, calender months, days, hours, minutes or seconds.

  A calendar year (or month) is an arbitrary year (or month) in an arbitrary calendar. A calendar is as part of the time duration, but will be taken from the context in which the time duration instance is being used. For example, a calendar may be specified when creating time intervals (see below for examples).

  A default offset is specified that may be used by some applications to temporally position the time duration. For example, setting `cf.TimeDuration(1, 'calendar_month', day=16, hour=12)` will define a duration of one calendar month which, by default, starts at 12:00 on the 16th of the month. Note that the offset

  Changing the units

  The time duration’s units may be changed in place by assigning equivalent units to the `Units` attribute:

      >>> t = cf.TimeDuration(1, 'day')
      >>> t
      <CF TimeDuration: 1 day (from Y-M-D 00:00:00)>
      >>> t.Units = 's'
      >>> t
      <CF TimeDuration: 86400.0 s (from Y-M-D h:m:s)>
      >>> t.Units = cf.Units('minutes')
      >>> t
      <CF TimeDuration: 1440.0 minutes (from Y-M-D h:m:00)>
      >>> t.Units = 'calendar_months'
      ValueError: Can't set units to non-equivalent units

  Creating time intervals

  A time interval of exactly the time duration, starting or ending at a particular date-time, may be produced with the `interval` method. If elements of the start or end date-time are not specified, then default values are taken from the `year`, `month`, `day`, `hour`, `minute`, and `second` attributes of the time duration instance:

      >>> t = cf.TimeDuration(6, 'calendar_months')
      >>> t
      <CF TimeDuration: 6 calendar_months (from Y-M-01 00:00:00)>
      >>> t.interval(1999, 12)
      (<CF Datetime: 1999-12-01 00:00:00>, <CF Datetime: 2000-06-01 00:00:00>)
      >>> t = cf.TimeDuration(5, 'days', hour=6)
      >>> t
      <CF TimeDuration: 5 days (from Y-M-D 06:00:00)>
      >>> t.interval(2004, 3, 2, end=True)
      (datetime.datetime(2004, 2, 26, 6, 0), <CF Datetime: 2004-03-02 06:00:00>)
      >>> t.interval(2004, 3, 2, end=True, calendar='noleap')
      (<CF Datetime: 2004-02-25 06:00:00>, <CF Datetime: 2004-03-02 06:00:00>)
      >>> t.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>)
      >>> t.interval(2004, 3, 2, end=True, calendar='360_day', iso='start and duration')
      '2004-02-27 06:00:00/P5D'

  Comparison operations

  Comparison operations are defined for `cf.TimeDuration` objects, ``cf.Data` objects, `numpy` arrays and numbers:

      >>> cf.TimeDuration(2, 'calendar_years') > cf.TimeDuration(1, 'calendar_years')
      True
      >>> cf.TimeDuration(2, 'calendar_years') < cf.TimeDuration(25, 'calendar_months')
      True
      >>> cf.TimeDuration(2, 'hours') <= cf.TimeDuration(1, 'days')
      True
      >>> cf.TimeDuration(2, 'hours') == cf.TimeDuration(1/12.0, 'days')
      True
      >>> cf.TimeDuration(2, 'days') == cf.TimeDuration(48, 'hours')
      True

      >>> cf.TimeDuration(2, 'hours') <= 2
      True
      >>> 30.5 != cf.TimeDuration(2, 'days')
      True

      >>> cf.TimeDuration(2, 'calendar_years') > numpy.array(1.5)
      True
      >>> type(cf.TimeDuration(2, 'calendar_years') > numpy.array(1.5))
      numpy.bool_
      >>> cf.TimeDuration(2, 'calendar_years') > numpy.array([1.5])
      array([ True], dtype=bool)
      >>> numpy.array([[1, 12]]) > cf.TimeDuration(2, 'calendar_months')
      array([[False,  True]], dtype=bool)

      >>> cf.TimeDuration(2, 'days') == cf.Data(2)
      <CF Data: True>
      >>> cf.TimeDuration(2, 'days') == cf.Data([2.], 'days')
      <CF Data: [True]>
      >>> cf.Data([[60]], 'seconds') < cf.TimeDuration(2, 'days')
      <CF Data: [[True]]>
      >>> cf.Data([1, 12], 'calendar_months') < cf.TimeDuration(6, 'calendar_months')
      <CF Data: [True, False]>

  Arithmetic operations

  Arithmetic operations are defined for `cf.TimeDuration` objects, date-time-like objects (such as `cf.Datetime`, `datetime.datetime`, etc.), ``cf.Data` objects, `numpy` arrays and numbers:

      >>> cf.TimeDuration(64, 'days') + cf.TimeDuration(28, 'days')
      <CF TimeDuration: P92D (Y-M-D 00:00:00)>
      >>> cf.TimeDuration(64, 'days') + cf.TimeDuration(12, 'hours')
      <CF TimeDuration: P65.0D (Y-M-D 00:00:00)>
      >>> cf.TimeDuration(64, 'days') + cf.TimeDuration(24, 'hours')
      <CF TimeDuration: P64.5D (Y-M-D 00:00:00)>
      >>> cf.TimeDuration(64, 'calendar_years') + cf.TimeDuration(21, 'calendar_months')
      <CF TimeDuration: P65.75Y (Y-01-01 00:00:00)>

      >>> cf.TimeDuration(30, 'days') + 2
      <CF TimeDuration: P32D (Y-M-D 00:00:00)>
      >>> 4.5 + cf.TimeDuration(30, 'days')
      <CF TimeDuration: P34.5D (Y-M-D 00:00:00)>
      >>> cf.TimeDuration(64, 'calendar_years') - 2.5
      <CF TimeDuration: P61.5Y (Y-01-01 00:00:00)>

      >>> cf.TimeDuration(36, 'hours') / numpy.array(8)
      <CF TimeDuration: 4 hours (from Y-M-D h:00:00)>
      >>> cf.TimeDuration(36, 'hours') / numpy.array(8.0)
      <CF TimeDuration: 4.5 hours (from Y-M-D h:00:00)>
      >>> cf.TimeDuration(36, 'hours') // numpy.array(8.0)
      <CF TimeDuration: 4.0 hours (from Y-M-D h:00:00)>
      >>> cf.TimeDuration(36, 'calendar_months') * cf.Data([[2.25]])
      <CF TimeDuration: 81.0 calendar_months (from Y-M-01 00:00:00)>
      >>> cf.TimeDuration(36, 'calendar_months') // cf.Data([0.825], '10')
      <CF TimeDuration: 4.3 calendar_months (from Y-M-01 00:00:00)>
      >>> cf.TimeDuration(36, 'calendar_months') % 10
      <CF Data: 6 calendar_months>
      >>> cf.TimeDuration(36, 'calendar_months') % cf.Data(1, 'calendar_year')
      <CF Data: 0.0 calendar_months>
      >>> cf.TimeDuration(36, 'calendar_months') % cf.Data(2, 'calendar_year')
      <CF Data: 12.0 calendar_months>

  The in place operators (`+=`, `//=`, etc.) are supported in a similar manner.

  Attributes

  Attribute | Description
  --- | ---
  `duration` | The length of the time duration in a `cf.Data` object with units.
  `year` | The default year for time interval creation.
  `month` | The default month for time interval creation.
  `day` | The default day for time interval creation.
  `hour` | The default hour for time interval creation.
  `minute` | The default minute for time interval creation.
  `second` | The default second for time interval creation.

  Constructors

  For convenience, the following functions may also be used to create time duration objects:

  Function | Description
  --- | ---
  `cf.Y` | Create a time duration of calendar years.
  `cf.M` | Create a time duration of calendar months.
  `cf.D` | Create a time duration of days.
  `cf.h` | Create a time duration of hours.
  `cf.m` | Create a time duration of minutes.
  `cf.s` | Create a time duration of seconds.

  See also

  `cf.Data`, `cf.Datetime`

  New in version 1.0.

  Initialization

      >   Parameters: | duration: data-like The length of the time duration. A data-like object is any object containing array-like or scalar data which could be used to create a `cf.Data` object. Example: Instances, `x`, of following types are all examples of data-like objects (because `cf.Data(x)` creates a valid `cf.Data` object), `int`, `float`, `str`, `tuple`, `list`, `numpy.ndarray`, `cf.Data`, `cf.Coordinate`, `cf.Field`. units: `str` or `cf.Units`, optional The units of the time duration. Required if, and only if, duration is not a `cf.Data` object which already contains the units. Units must be one of calendar years, calendar months, days, hours, minutes or seconds. Example: `units='calendar_months'` Example: `units='days'` Example: `units=cf.Units('calendar_years')` month, day, hour, minute, second: `int` or `None`, optional The offset used when creating, with the `bounds` method, a time interval containing a given date-time. Only the offset elements for units smaller that of the time duration are used. Example:
      >       >>> cf.TimeDuration(1, 'calendar_month').bounds(cf.dt('2000-1-8'))
      >       (<CF Datetime: 2000-01-01 00:00:00>, <CF Datetime: 2000-02-01 00:00:00>)
      >       >>> cf.TimeDuration(1, 'calendar_month', day=15).bounds(cf.dt('2000-1-8'))
      >       (<CF Datetime: 1999-12-15 00:00:00>, <CF Datetime: 2000-01-15 00:00:00>)
      >       >>> cf.TimeDuration(1, 'calendar_month', month=4, day=30).bounds(cf.dt('2000-1-8'))
      >       (<CF Datetime: 1999-12-30 00:00:00>, <CF Datetime: 2000-01-30 00:00:00>)
  Examples: |

      >>> t = cf.TimeDuration(cf.Data(3 , 'calendar_years'))
      >>> t = cf.TimeDuration(cf.Data(12 , 'hours'))
      >>> t = cf.TimeDuration(18 , 'calendar_months')
      >>> t = cf.TimeDuration(30 , 'days')
      >>> t = cf.TimeDuration(1 , 'day', hour=6)

## Attributes

`Units` | The units of the time duration.
`isint` | True if the time duration is a whole number.
`iso` | Return the time duration as an ISO 8601-like time duration string.

## Methods

`bounds` | Return a time interval containing a date-time.
`copy` | Return a deep copy.
`equals` | True if two time durations are equal.
`equivalent` | True if two time durations are logically equivalent.
`inspect` | Inspect the attributes.
`interval` | Return a time interval of exactly the time duration.
`is_day_factor` | Return True if an integer multiple of the time duration is equal to one day.