Timedelta ========= .. currentmodule:: pandasCore .. class:: Timedelta Represents a duration, the difference between two dates or times. Example ------- .. code-block:: python import pandasCore as pd # Create Timedelta obj = pd.Timedelta(...) Attributes ---------- .. list-table:: :widths: 25 60 15 :header-rows: 1 * - Attribute - Description - Example * - :attr:`~Timedelta.components` - Return a tuple of components. - :ref:`View ` * - :attr:`~Timedelta.days` - Return the days component - :ref:`View ` * - :attr:`~Timedelta.delta` - Return the internal value in nanoseconds (alias for value) - * - :attr:`~Timedelta.hours` - Return the hours component (0-23) - :ref:`View ` * - :attr:`~Timedelta.microseconds` - Return the microseconds component (0-999) - * - :attr:`~Timedelta.milliseconds` - Return the milliseconds component (0-999) - * - :attr:`~Timedelta.minutes` - Return the minutes component (0-59) - :ref:`View ` * - :attr:`~Timedelta.nanoseconds` - Return the nanoseconds component (0-999) - * - :attr:`~Timedelta.seconds` - Return the seconds component (0-59) - :ref:`View ` * - :attr:`~Timedelta.total_days` - Total days in the duration - * - :attr:`~Timedelta.total_hours` - Total hours in the duration - * - :attr:`~Timedelta.total_minutes` - Total minutes in the duration - * - :attr:`~Timedelta.total_nanoseconds` - Total nanoseconds in the duration - * - :attr:`~Timedelta.value` - Return the internal value in nanoseconds - :ref:`View ` Construction ------------ .. list-table:: :widths: 25 60 15 :header-rows: 1 * - Method - Description - Example * - :meth:`~Timedelta.__init__` ``(value: object = None, unit: object = None, **kwargs)`` - Create a Timedelta. - :ref:`View ` Arithmetic ---------- .. list-table:: :widths: 25 60 15 :header-rows: 1 * - Method - Description - Example * - :meth:`~Timedelta.__abs__` ``()`` - - * - :meth:`~Timedelta.__add__` ``(arg0: pandasCore.Timedelta)`` - - * - :meth:`~Timedelta.__floordiv__` ``(*args, **kwargs) | (arg0: typing.SupportsInt) | (arg0: pandasCore.Timedelta)`` - - * - :meth:`~Timedelta.__mod__` ``(arg0: pandasCore.Timedelta)`` - - * - :meth:`~Timedelta.__mul__` ``(*args, **kwargs) | (arg0: typing.SupportsInt) | (arg0: typing.SupportsFloat)`` - - * - :meth:`~Timedelta.__neg__` ``()`` - - * - :meth:`~Timedelta.__pos__` ``()`` - - * - :meth:`~Timedelta.__sub__` ``(arg0: pandasCore.Timedelta)`` - - * - :meth:`~Timedelta.__truediv__` ``(*args, **kwargs) | (arg0: typing.SupportsInt) | (arg0: typing.SupportsFloat) | (arg0: pandasCore.Timedelta)`` - - Comparison ---------- .. list-table:: :widths: 25 60 15 :header-rows: 1 * - Method - Description - Example * - :meth:`~Timedelta.__eq__` ``(arg0: pandasCore.Timedelta)`` - - * - :meth:`~Timedelta.__ge__` ``(arg0: pandasCore.Timedelta)`` - - * - :meth:`~Timedelta.__gt__` ``(arg0: pandasCore.Timedelta)`` - - * - :meth:`~Timedelta.__le__` ``(arg0: pandasCore.Timedelta)`` - - * - :meth:`~Timedelta.__lt__` ``(arg0: pandasCore.Timedelta)`` - - * - :meth:`~Timedelta.__ne__` ``(arg0: pandasCore.Timedelta)`` - - I/O --- .. list-table:: :widths: 25 60 15 :header-rows: 1 * - Method - Description - Example * - :meth:`~Timedelta.to_numpy` ``(dtype: object = None, copy: bool = False)`` - Return the value as nanoseconds (for numpy compatibility) - * - :meth:`~Timedelta.to_pytimedelta` ``()`` - Convert to Python datetime.timedelta object. - :ref:`View ` * - :meth:`~Timedelta.to_timedelta64` ``()`` - Convert to numpy timedelta64. - Conversion ---------- .. list-table:: :widths: 25 60 15 :header-rows: 1 * - Method - Description - Example * - :meth:`~Timedelta.view` ``(dtype: object)`` - View the Timedelta as a different dtype. - Datetime Methods ---------------- .. list-table:: :widths: 25 60 15 :header-rows: 1 * - Method - Description - Example * - :meth:`~Timedelta.ceil` ``(freq: str)`` - Round up the Timedelta to the specified resolution. - :ref:`View ` * - :meth:`~Timedelta.floor` ``(freq: str)`` - Round down the Timedelta to the specified resolution. - :ref:`View ` * - :meth:`~Timedelta.round` ``(freq: str)`` - Round the Timedelta to the specified resolution. - :ref:`View ` Other Methods ------------- .. list-table:: :widths: 25 60 15 :header-rows: 1 * - Method - Description - Example * - :meth:`~Timedelta.__hash__` ``()`` - - * - :meth:`~Timedelta.__repr__` ``()`` - - * - :meth:`~Timedelta.__str__` ``()`` - - * - :meth:`~Timedelta.as_unit` ``(unit: str, round_ok: bool = True)`` - Convert Timedelta to target unit resolution. - * - :meth:`~Timedelta.components_str` ``()`` - Return a string representation of components - * - :meth:`~Timedelta.isnat` ``()`` - Return True if the Timedelta is NaT (Not-a-Timedelta) - * - :meth:`~Timedelta.isoformat` ``()`` - Return ISO 8601 duration format string. - :ref:`View ` * - :meth:`~Timedelta.total_seconds` ``()`` - Total seconds in the duration. - :ref:`View ` Code Examples ------------- The following examples are extracted from the test suite. .. _example-timedelta-components-0: .. dropdown:: components (test_timedelta.py:534) :class-title: example-dropdown .. code-block:: python :linenos: :lineno-start: 524 :emphasize-lines: 11 f_print_error(f"Exception: {e}") return False def test_components(): """Test Timedelta components property""" f_print_header("Test: Timedelta components") try: td = pandasCore.Timedelta("1 days 02:30:45") components = td.components if components is not None and len(components) == 7: f_print_success(f"components: {components}") # (days, hours, minutes, seconds, milliseconds, microseconds, nanoseconds) if components[0] == 1 and components[1] == 2 and components[2] == 30 and components[3] == 45: f_print_success("Components values are correct") else: f_print_error(f"Components values wrong: {components}") return False else: .. _example-timedelta-days-1: .. dropdown:: days (test_timedelta.py:88) :class-title: example-dropdown .. code-block:: python :linenos: :lineno-start: 78 :emphasize-lines: 11 def test_construction_from_string(): """Test Timedelta construction from string""" f_print_header("Test: Timedelta Construction from String") try: # Create Timedelta from string td = pandasCore.Timedelta("1 days 02:30:00") f_print_success("Created Timedelta from string '1 days 02:30:00'") # Check days component if td.days == 1: f_print_success(f"days is correct: {td.days}") else: f_print_error(f"days is wrong: {td.days}, expected 1") return False # Check hours component if td.hours == 2: f_print_success(f"hours is correct: {td.hours}") else: f_print_error(f"hours is wrong: {td.hours}, expected 2") .. _example-timedelta-hours-2: .. dropdown:: hours (test_timedelta.py:95) :class-title: example-dropdown .. code-block:: python :linenos: :lineno-start: 85 :emphasize-lines: 11 f_print_success("Created Timedelta from string '1 days 02:30:00'") # Check days component if td.days == 1: f_print_success(f"days is correct: {td.days}") else: f_print_error(f"days is wrong: {td.days}, expected 1") return False # Check hours component if td.hours == 2: f_print_success(f"hours is correct: {td.hours}") else: f_print_error(f"hours is wrong: {td.hours}, expected 2") return False # Check minutes component if td.minutes == 30: f_print_success(f"minutes is correct: {td.minutes}") else: f_print_error(f"minutes is wrong: {td.minutes}, expected 30") .. _example-timedelta-minutes-3: .. dropdown:: minutes (test_timedelta.py:102) :class-title: example-dropdown .. code-block:: python :linenos: :lineno-start: 92 :emphasize-lines: 11 return False # Check hours component if td.hours == 2: f_print_success(f"hours is correct: {td.hours}") else: f_print_error(f"hours is wrong: {td.hours}, expected 2") return False # Check minutes component if td.minutes == 30: f_print_success(f"minutes is correct: {td.minutes}") else: f_print_error(f"minutes is wrong: {td.minutes}, expected 30") return False # Check repr repr_str = repr(td) f_print_info(f"repr: {repr_str}") # Test short format .. _example-timedelta-seconds-4: .. dropdown:: seconds (test_timedelta.py:201) :class-title: example-dropdown .. code-block:: python :linenos: :lineno-start: 191 :emphasize-lines: 11 return False # Check minutes if td.minutes == 30: f_print_success(f"minutes: {td.minutes}") else: f_print_error(f"minutes wrong: {td.minutes}, expected 30") return False # Check seconds if td.seconds == 45: f_print_success(f"seconds: {td.seconds}") else: f_print_error(f"seconds wrong: {td.seconds}, expected 45") return False return True except Exception as e: f_print_error(f"Exception: {e}") return False .. _example-timedelta-value-5: .. dropdown:: value (test_timedelta.py:37) :class-title: example-dropdown .. code-block:: python :linenos: :lineno-start: 27 :emphasize-lines: 11 def test_construction_default(): """Test default Timedelta construction (zero duration)""" f_print_header("Test: Timedelta Default Construction") try: # Create default Timedelta (zero duration) td = pandasCore.Timedelta() f_print_success("Created default Timedelta") # Check value is 0 if td.value == 0: f_print_success(f"value is correct: {td.value}") else: f_print_error(f"value is wrong: {td.value}, expected 0") return False # Check repr repr_str = repr(td) f_print_info(f"repr: {repr_str}") return True .. _example-timedelta-dunder-initdunder--6: .. dropdown:: __init__ (test_timedelta.py:33) :class-title: example-dropdown .. code-block:: python :linenos: :lineno-start: 23 :emphasize-lines: 11 import pandasCore import pandas as pd def test_construction_default(): """Test default Timedelta construction (zero duration)""" f_print_header("Test: Timedelta Default Construction") try: # Create default Timedelta (zero duration) td = pandasCore.Timedelta() f_print_success("Created default Timedelta") # Check value is 0 if td.value == 0: f_print_success(f"value is correct: {td.value}") else: f_print_error(f"value is wrong: {td.value}, expected 0") return False # Check repr .. _example-timedelta-to_pytimedelta-7: .. dropdown:: to_pytimedelta (test_timedelta.py:495) :class-title: example-dropdown .. code-block:: python :linenos: :lineno-start: 485 :emphasize-lines: 11 f_print_error(f"Exception: {e}") return False def test_to_pytimedelta(): """Test Timedelta to_pytimedelta conversion""" f_print_header("Test: Timedelta to_pytimedelta") try: td = pandasCore.Timedelta("1 days 02:30:45") py_td = td.to_pytimedelta() # Check if it's a Python timedelta import datetime if isinstance(py_td, datetime.timedelta): f_print_success(f"to_pytimedelta returned: {py_td}") else: f_print_error(f"to_pytimedelta should return datetime.timedelta, got: {type(py_td)}") return False # Check days .. _example-timedelta-ceil-8: .. dropdown:: ceil (test_timedelta.py:285) :class-title: example-dropdown .. code-block:: python :linenos: :lineno-start: 275 :emphasize-lines: 11 # Floor to hour td_floor = td.floor("h") if td_floor.hours == 12 and td_floor.minutes == 0: f_print_success(f"floor('h'): {td_floor}") else: f_print_error(f"floor('h') wrong: hours={td_floor.hours}, minutes={td_floor.minutes}") return False # Ceil to hour td_ceil = td.ceil("h") if td_ceil.hours == 13 and td_ceil.minutes == 0: f_print_success(f"ceil('h'): {td_ceil}") else: f_print_error(f"ceil('h') wrong: hours={td_ceil.hours}, minutes={td_ceil.minutes}") return False # Round to hour (30:30 should round up to 13) td_round = td.round("h") if td_round.hours == 13: f_print_success(f"round('h'): {td_round}") .. _example-timedelta-floor-9: .. dropdown:: floor (test_timedelta.py:277) :class-title: example-dropdown .. code-block:: python :linenos: :lineno-start: 267 :emphasize-lines: 11 def test_rounding_methods(): """Test Timedelta rounding methods""" f_print_header("Test: Timedelta Rounding Methods") try: # Create Timedelta: 1 day, 12 hours, 30 minutes, 30 seconds td = pandasCore.Timedelta("1 days 12:30:30") # Floor to hour td_floor = td.floor("h") if td_floor.hours == 12 and td_floor.minutes == 0: f_print_success(f"floor('h'): {td_floor}") else: f_print_error(f"floor('h') wrong: hours={td_floor.hours}, minutes={td_floor.minutes}") return False # Ceil to hour td_ceil = td.ceil("h") if td_ceil.hours == 13 and td_ceil.minutes == 0: f_print_success(f"ceil('h'): {td_ceil}") .. _example-timedelta-round-10: .. dropdown:: round (test_timedelta.py:293) :class-title: example-dropdown .. code-block:: python :linenos: :lineno-start: 283 :emphasize-lines: 11 # Ceil to hour td_ceil = td.ceil("h") if td_ceil.hours == 13 and td_ceil.minutes == 0: f_print_success(f"ceil('h'): {td_ceil}") else: f_print_error(f"ceil('h') wrong: hours={td_ceil.hours}, minutes={td_ceil.minutes}") return False # Round to hour (30:30 should round up to 13) td_round = td.round("h") if td_round.hours == 13: f_print_success(f"round('h'): {td_round}") else: f_print_error(f"round('h') wrong: hours={td_round.hours}") return False return True except Exception as e: f_print_error(f"Exception: {e}") .. _example-timedelta-isoformat-11: .. dropdown:: isoformat (test_timedelta.py:252) :class-title: example-dropdown .. code-block:: python :linenos: :lineno-start: 242 :emphasize-lines: 11 f_print_error(f"Exception: {e}") return False def test_isoformat(): """Test Timedelta isoformat method""" f_print_header("Test: Timedelta isoformat") try: td = pandasCore.Timedelta("1 days 02:30:00") iso_str = td.isoformat() # Should contain P (period) and D (days) if "P" in iso_str and "D" in iso_str: f_print_success(f"isoformat: {iso_str}") else: f_print_error(f"isoformat wrong: {iso_str}") return False return True .. _example-timedelta-total_seconds-12: .. dropdown:: total_seconds (test_timedelta.py:64) :class-title: example-dropdown .. code-block:: python :linenos: :lineno-start: 54 :emphasize-lines: 11 def test_construction_from_nanoseconds(): """Test Timedelta construction from nanoseconds""" f_print_header("Test: Timedelta Construction from Nanoseconds") try: # Create Timedelta from nanoseconds (1 second = 1e9 nanoseconds) td = pandasCore.Timedelta(1000000000) f_print_success("Created Timedelta from nanoseconds") # Check total_seconds total_sec = td.total_seconds() if abs(total_sec - 1.0) < 0.0001: f_print_success(f"total_seconds is correct: {total_sec}") else: f_print_error(f"total_seconds is wrong: {total_sec}, expected 1.0") return False return True except Exception as e: f_print_error(f"Exception: {e}")