nitypes.bintime.TimeDelta

class nitypes.bintime.TimeDelta

class TimeDelta(value: _OtherTimeDelta, /)

class 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 datetime.timedelta and hightime.timedelta.

Constructing

You can construct a TimeDelta from a number of seconds, expressed as an int, float, or 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'))

TimeDelta has the same resolution and rounding behavior as DateTime.

>>> TimeDelta(Decimal("100.01234567890123456789"))
nitypes.bintime.TimeDelta(Decimal('100.012345678901234567889'))

Unlike other timedelta objects, you cannot construct a TimeDelta from separate weeks, days, hours, etc. If you want to do that, construct a datetime.timedelta or hightime.timedelta and then use it to construct a 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

DateTime and TimeDelta support the same math operations as datetime.datetime and datetime.timedelta.

For example, you can add or subtract 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 DateTime with a TimeDelta, datetime.timedelta, or 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

min: ClassVar[TimeDelta]: The most negative TimeDelta object, approximately -292 million years.

max: ClassVar[TimeDelta]: The most positive TimeDelta object, approximately 292 million years.

__slots__ = ['_ticks']

classmethod from_ticks(ticks: SupportsIndex) → typing_extensions.Self: Create a TimeDelta from a 128-bit fixed point number expressed as an integer.

classmethod from_tuple(value: nitypes.bintime.TimeValueTuple) → typing_extensions.Self: Create a TimeDelta from 64-bit whole seconds and fractional seconds ints.

property days: int: The number of days in the time delta.

property seconds: int: The number of seconds in the time delta, up to the nearest day.

property microseconds: int: The number of microseconds in the time delta, up to the nearest second.

property femtoseconds: int: The number of femtoseconds in the time delta, up to the nearest microsecond.

property yoctoseconds: 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.

property ticks: int: The total ticks in the time delta as a 128-bit integer.

to_tuple() → nitypes.bintime.TimeValueTuple: The whole seconds and fractional seconds parts of the time delta as 64-bit ints.

total_seconds() → float: The total seconds in the time delta.

Warning

Converting a time value to a floating point number loses precision. Consider using precision_total_seconds instead.

precision_total_seconds() → decimal.Decimal

The precise total seconds in the time delta.

Note: up to 64 significant digits are used in computation.

__neg__() → TimeDelta: Return -self.

__pos__() → TimeDelta: Return +self.

__abs__() → TimeDelta: Return abs(self).

__add__(value: TimeDelta | _OtherTimeDelta, /) → TimeDelta
__add__(value: hightime.datetime, /) → hightime.datetime
__add__(value: datetime.datetime, /) → datetime.datetime: Return self+value.

__radd__

__sub__(value: TimeDelta | _OtherTimeDelta, /) → TimeDelta: Return self-value.

__rsub__(value: TimeDelta | _OtherTimeDelta, /) → TimeDelta
__rsub__(value: hightime.datetime, /) → hightime.datetime
__rsub__(value: datetime.datetime, /) → datetime.datetime: Return value-self.

__mul__(value: int | float | decimal.Decimal, /) → TimeDelta: Return self*value.

__rmul__

__floordiv__(value: TimeDelta, /) → int
__floordiv__(value: int, /) → TimeDelta: Return self//value.

__truediv__(value: TimeDelta, /) → float
__truediv__(value: float, /) → TimeDelta: Return self/value.

__mod__(value: TimeDelta | _OtherTimeDelta, /) → TimeDelta: Return self%value.

__divmod__(value: TimeDelta | _OtherTimeDelta, /) → tuple[int, TimeDelta]: Return (self//value, self%value).

__lt__(value: TimeDelta | _OtherTimeDelta, /) → bool: Return self<value.

__le__(value: TimeDelta | _OtherTimeDelta, /) → bool: Return self<=value.

__eq__(value: object, /) → bool: Return self==value.

__gt__(value: TimeDelta | _OtherTimeDelta, /) → bool: Return self<value.

__ge__(value: TimeDelta | _OtherTimeDelta, /) → bool: Return self>=value.

__bool__() → bool: Return bool(self).

__hash__() → int: Return hash(self).

__reduce__() → tuple[Any, Ellipsis]: Return object state for pickling.

__str__() → str: Return repr(self).

__repr__() → str: Return repr(self).