nitypes.bintime.TimeDelta ========================= .. py:class:: nitypes.bintime.TimeDelta TimeDelta(value: _OtherTimeDelta, /) TimeDelta(seconds: SupportsIndex | decimal.Decimal | float) A duration, represented in NI Binary Time Format (NI-BTF). TimeDelta represents time as a 128-bit fixed point number with 64-bit whole seconds and 64-bit fractional seconds. .. warning:: The fractional seconds are represented as a binary fraction, which is a sum of inverse powers of 2. Values that are not exactly representable as binary fractions will display rounding error or "bruising" similar to a floating point number. TimeDelta instances are duck typing compatible with :any:`datetime.timedelta` and :any:`hightime.timedelta`. Constructing ^^^^^^^^^^^^ You can construct a :class:`TimeDelta` from a number of seconds, expressed as an :any:`int`, :any:`float`, or :any:`decimal.Decimal`. >>> TimeDelta(100) nitypes.bintime.TimeDelta(Decimal('100')) >>> TimeDelta(100.125) nitypes.bintime.TimeDelta(Decimal('100.125')) >>> from decimal import Decimal >>> TimeDelta(Decimal("100.125")) nitypes.bintime.TimeDelta(Decimal('100.125')) :class:`TimeDelta` has the same resolution and rounding behavior as :class:`DateTime`. >>> TimeDelta(Decimal("100.01234567890123456789")) nitypes.bintime.TimeDelta(Decimal('100.012345678901234567889')) Unlike other ``timedelta`` objects, you cannot construct a :class:`TimeDelta` from separate weeks, days, hours, etc. If you want to do that, construct a :any:`datetime.timedelta` or :any:`hightime.timedelta` and then use it to construct a :class:`TimeDelta`. >>> import datetime, hightime >>> TimeDelta(datetime.timedelta(days=1, microseconds=1)) nitypes.bintime.TimeDelta(Decimal('86400.0000010000000000000')) >>> TimeDelta(hightime.timedelta(days=1, femtoseconds=1)) nitypes.bintime.TimeDelta(Decimal('86400.0000000000000010000')) Math Operations ^^^^^^^^^^^^^^^ :class:`DateTime` and :class:`TimeDelta` support the same math operations as :any:`datetime.datetime` and :any:`datetime.timedelta`. For example, you can add or subtract :class:`TimeDelta` objects together: >>> TimeDelta(100.5) + TimeDelta(0.5) nitypes.bintime.TimeDelta(Decimal('101')) >>> TimeDelta(100.5) - TimeDelta(0.5) nitypes.bintime.TimeDelta(Decimal('100')) Or add/subtract a :class:`DateTime` with a :class:`TimeDelta`, :any:`datetime.timedelta`, or :any:`hightime.timedelta`: >>> DateTime(2025, 1, 1, tzinfo=datetime.timezone.utc) + TimeDelta(86400) nitypes.bintime.DateTime(2025, 1, 2, 0, 0, tzinfo=datetime.timezone.utc) >>> DateTime(2025, 1, 1, tzinfo=datetime.timezone.utc) + datetime.timedelta(days=1) nitypes.bintime.DateTime(2025, 1, 2, 0, 0, tzinfo=datetime.timezone.utc) >>> DateTime(2025, 1, 1, tzinfo=datetime.timezone.utc) + hightime.timedelta(femtoseconds=1) nitypes.bintime.DateTime(2025, 1, 1, 0, 0, 0, 0, 1, 13873, tzinfo=datetime.timezone.utc) Class members ^^^^^^^^^^^^^ .. py:attribute:: min :type: ClassVar[TimeDelta] The most negative :class:`TimeDelta` object, approximately -292 million years. .. py:attribute:: max :type: ClassVar[TimeDelta] The most positive :class:`TimeDelta` object, approximately 292 million years. .. py:attribute:: __slots__ :value: ['_ticks'] .. py:method:: from_ticks(ticks: SupportsIndex) -> typing_extensions.Self :classmethod: Create a TimeDelta from a 128-bit fixed point number expressed as an integer. .. py:method:: from_tuple(value: nitypes.bintime.TimeValueTuple) -> typing_extensions.Self :classmethod: Create a TimeDelta from 64-bit whole seconds and fractional seconds ints. .. py:property:: days :type: int The number of days in the time delta. .. py:property:: seconds :type: int The number of seconds in the time delta, up to the nearest day. .. py:property:: microseconds :type: int The number of microseconds in the time delta, up to the nearest second. .. py:property:: femtoseconds :type: int The number of femtoseconds in the time delta, up to the nearest microsecond. .. py:property:: yoctoseconds :type: int The number of yoctoseconds in the time delta, up to the nearest femtosecond. .. warning:: Because this class uses a 64-bit binary fraction, the smallest value it can represent is ``1.0 / (1 << 64)`` seconds, which is about 54210 yoctoseconds. .. py:property:: ticks :type: int The total ticks in the time delta as a 128-bit integer. .. py:method:: to_tuple() -> nitypes.bintime.TimeValueTuple The whole seconds and fractional seconds parts of the time delta as 64-bit ints. .. py:method:: total_seconds() -> float The total seconds in the time delta. .. warning:: Converting a time value to a floating point number loses precision. Consider using :any:`precision_total_seconds` instead. .. py:method:: precision_total_seconds() -> decimal.Decimal The precise total seconds in the time delta. Note: up to 64 significant digits are used in computation. .. py:method:: __neg__() -> TimeDelta Return -self. .. py:method:: __pos__() -> TimeDelta Return +self. .. py:method:: __abs__() -> TimeDelta Return abs(self). .. py:method:: __add__(value: TimeDelta | _OtherTimeDelta, /) -> TimeDelta __add__(value: hightime.datetime, /) -> hightime.datetime __add__(value: datetime.datetime, /) -> datetime.datetime Return self+value. .. py:attribute:: __radd__ .. py:method:: __sub__(value: TimeDelta | _OtherTimeDelta, /) -> TimeDelta Return self-value. .. py:method:: __rsub__(value: TimeDelta | _OtherTimeDelta, /) -> TimeDelta __rsub__(value: hightime.datetime, /) -> hightime.datetime __rsub__(value: datetime.datetime, /) -> datetime.datetime Return value-self. .. py:method:: __mul__(value: int | float | decimal.Decimal, /) -> TimeDelta Return self*value. .. py:attribute:: __rmul__ .. py:method:: __floordiv__(value: TimeDelta, /) -> int __floordiv__(value: int, /) -> TimeDelta Return self//value. .. py:method:: __truediv__(value: TimeDelta, /) -> float __truediv__(value: float, /) -> TimeDelta Return self/value. .. py:method:: __mod__(value: TimeDelta | _OtherTimeDelta, /) -> TimeDelta Return self%value. .. py:method:: __divmod__(value: TimeDelta | _OtherTimeDelta, /) -> tuple[int, TimeDelta] Return (self//value, self%value). .. py:method:: __lt__(value: TimeDelta | _OtherTimeDelta, /) -> bool Return self bool Return self<=value. .. py:method:: __eq__(value: object, /) -> bool Return self==value. .. py:method:: __gt__(value: TimeDelta | _OtherTimeDelta, /) -> bool Return self bool Return self>=value. .. py:method:: __bool__() -> bool Return bool(self). .. py:method:: __hash__() -> int Return hash(self). .. py:method:: __reduce__() -> tuple[Any, Ellipsis] Return object state for pickling. .. py:method:: __str__() -> str Return repr(self). .. py:method:: __repr__() -> str Return repr(self).