timedelta64
===========

.. cpp:class:: numpy::timedelta64

   numpy C++ class.

Example
-------

.. code-block:: cpp

   #include <numpy/np_ndarray.h>
   using namespace numpy;

   // Use timedelta64
   timedelta64 obj;
   // ... operations ...

Constructors
------------

.. list-table::
   :widths: 55 25 20
   :header-rows: 1

   * - Signature
     - Location
     - Example
   * - ``timedelta64(int64_tvalue, DateTimeUnitunit)``
     - NP_TIMEDELTA64.H:25
     - :ref:`View <example-timedelta64-timedelta64-0>`
   * - ``timedelta64(const std::string &delta_string)``
     - NP_TIMEDELTA64.H:26
     - :ref:`View <example-timedelta64-timedelta64-1>`

Operators
---------

.. list-table::
   :widths: 40 25 15 20
   :header-rows: 1

   * - Signature
     - Return Type
     - Location
     - Example
   * - ``timedelta64 operator+(const timedelta64 &other)``
     - timedelta64
     - NP_TIMEDELTA64.H:31
     - 
   * - ``timedelta64 operator-(const timedelta64 &other)``
     - timedelta64
     - NP_TIMEDELTA64.H:32
     - 
   * - ``timedelta64 operator\*(int64_tscalar)``
     - timedelta64
     - NP_TIMEDELTA64.H:33
     - 
   * - ``timedelta64 operator/(int64_tscalar)``
     - timedelta64
     - NP_TIMEDELTA64.H:34
     - 
   * - ``timedelta64 operator-()``
     - timedelta64
     - NP_TIMEDELTA64.H:36
     - 
   * - ``bool operator==(const timedelta64 &other)``
     - bool
     - NP_TIMEDELTA64.H:38
     - 
   * - ``bool operator!=(const timedelta64 &other)``
     - bool
     - NP_TIMEDELTA64.H:39
     - 
   * - ``bool operator<(const timedelta64 &other)``
     - bool
     - NP_TIMEDELTA64.H:40
     - 
   * - ``bool operator<=(const timedelta64 &other)``
     - bool
     - NP_TIMEDELTA64.H:41
     - 
   * - ``bool operator>(const timedelta64 &other)``
     - bool
     - NP_TIMEDELTA64.H:42
     - 
   * - ``bool operator>=(const timedelta64 &other)``
     - bool
     - NP_TIMEDELTA64.H:43
     - 

Indexing / Selection
--------------------

.. list-table::
   :widths: 40 20 15 25
   :header-rows: 1

   * - Signature
     - Return Type
     - Location
     - Example
   * - ``DateTimeUnit getUnit()``
     - DateTimeUnit
     - NP_TIMEDELTA64.H:29
     - :ref:`View <example-timedelta64-getunit-2>`
   * - ``int64_t getValue()``
     - int64_t
     - NP_TIMEDELTA64.H:28
     - :ref:`View <example-timedelta64-getvalue-3>`

Math Operations
---------------

.. list-table::
   :widths: 40 20 15 25
   :header-rows: 1

   * - Signature
     - Return Type
     - Location
     - Example
   * - ``timedelta64 abs()``
     - timedelta64
     - NP_TIMEDELTA64.H:52
     - :ref:`View <example-timedelta64-abs-4>`

Other Methods
-------------

.. list-table::
   :widths: 40 20 15 25
   :header-rows: 1

   * - Signature
     - Return Type
     - Location
     - Example
   * - ``timedelta64 NaT(DateTimeUnitunit = DateTimeUnit::Second)``
     - timedelta64
     - NP_TIMEDELTA64.H:55
     - :ref:`View <example-timedelta64-nat-5>`
   * - ``timedelta64 convertTo(DateTimeUnitnew_unit)``
     - timedelta64
     - NP_TIMEDELTA64.H:57
     - :ref:`View <example-timedelta64-convertto-6>`
   * - ``timedelta64 fromSeconds(int64_tseconds, DateTimeUnitunit)``
     - timedelta64
     - NP_TIMEDELTA64.H:22
     - :ref:`View <example-timedelta64-fromseconds-7>`
   * - ``bool isNaT()``
     - bool
     - NP_TIMEDELTA64.H:54
     - :ref:`View <example-timedelta64-isnat-8>`
   * - ``int64_t parseDeltaString(const std::string &delta_string, DateTimeUnit &unit)``
     - int64_t
     - NP_TIMEDELTA64.H:60
     - 
   * - ``int64_t toDays()``
     - int64_t
     - NP_TIMEDELTA64.H:47
     - :ref:`View <example-timedelta64-todays-9>`
   * - ``int64_t toHours()``
     - int64_t
     - NP_TIMEDELTA64.H:48
     - :ref:`View <example-timedelta64-tohours-10>`
   * - ``int64_t toMinutes()``
     - int64_t
     - NP_TIMEDELTA64.H:49
     - :ref:`View <example-timedelta64-tominutes-11>`
   * - ``int64_t toSeconds()``
     - int64_t
     - NP_TIMEDELTA64.H:21
     - :ref:`View <example-timedelta64-toseconds-12>`
   * - ``double toSecondsDouble()``
     - double
     - NP_TIMEDELTA64.H:50
     - 
   * - ``std::string toString()``
     - std::string
     - NP_TIMEDELTA64.H:45
     - :ref:`View <example-timedelta64-tostring-13>`


Code Examples
-------------

The following examples are extracted from the test suite.

.. _example-timedelta64-timedelta64-0:

.. dropdown:: timedelta64 (np_test_1_all.cpp:7030)
   :class-title: example-dropdown

   .. code-block:: cpp
      :linenos:
      :lineno-start: 7020
      :emphasize-lines: 11

          datetime64 nat_dt = datetime64::NaT();
          timedelta64 nat_td = timedelta64::NaT();
      
          // std::cout << "NaT datetime: " << nat_dt.toString() << std::endl;
          // std::cout << "NaT timedelta: " << nat_td.toString() << std::endl;
      
          datetime64 valid_date("2024-01-01");
      
          // NaT arithmetic
          datetime64 result1 = valid_date + nat_td;
          datetime64 result2 = nat_dt + timedelta64(1, DateTimeUnit::Day);
          timedelta64 result3 = valid_date - nat_dt;
      
          // std::cout << "Valid date + NaT timedelta = " << result1.toString() << std::endl;
          // std::cout << "NaT datetime + valid timedelta = " << result2.toString() << std::endl;
          // std::cout << "Valid date - NaT datetime = " << result3.toString() << std::endl;
      
          // NaT comparisons
          // std::cout << "NaT == NaT: " << (nat_dt == datetime64::NaT()) << std::endl;
          // std::cout << "Valid date == NaT: " << (valid_date == nat_dt) << std::endl;
          // std::cout << "NaT < Valid date: " << (nat_dt < valid_date) << std::endl;

.. _example-timedelta64-timedelta64-1:

.. dropdown:: timedelta64 (np_test_1_all.cpp:7030)
   :class-title: example-dropdown

   .. code-block:: cpp
      :linenos:
      :lineno-start: 7020
      :emphasize-lines: 11

          datetime64 nat_dt = datetime64::NaT();
          timedelta64 nat_td = timedelta64::NaT();
      
          // std::cout << "NaT datetime: " << nat_dt.toString() << std::endl;
          // std::cout << "NaT timedelta: " << nat_td.toString() << std::endl;
      
          datetime64 valid_date("2024-01-01");
      
          // NaT arithmetic
          datetime64 result1 = valid_date + nat_td;
          datetime64 result2 = nat_dt + timedelta64(1, DateTimeUnit::Day);
          timedelta64 result3 = valid_date - nat_dt;
      
          // std::cout << "Valid date + NaT timedelta = " << result1.toString() << std::endl;
          // std::cout << "NaT datetime + valid timedelta = " << result2.toString() << std::endl;
          // std::cout << "Valid date - NaT datetime = " << result3.toString() << std::endl;
      
          // NaT comparisons
          // std::cout << "NaT == NaT: " << (nat_dt == datetime64::NaT()) << std::endl;
          // std::cout << "Valid date == NaT: " << (valid_date == nat_dt) << std::endl;
          // std::cout << "NaT < Valid date: " << (nat_dt < valid_date) << std::endl;

.. _example-timedelta64-getunit-2:

.. dropdown:: getUnit (np_test_1_all.cpp:28800)
   :class-title: example-dropdown

   .. code-block:: cpp
      :linenos:
      :lineno-start: 28790
      :emphasize-lines: 11

            std::cout << " -> tests passed" << std::endl;
          }
      
          void np_test_datetime64_accessors() {
            std::cout << "========= datetime64 accessors: getValue/getUnit =======================";
      
            auto dt = numpy::datetime64("2024-01-15");
      
            // Test getValue and getUnit
            int64_t value = dt.getValue();
            numpy::DateTimeUnit unit = dt.getUnit();
      
            bool passed = (value != 0);
      
            if (!passed) {
              std::cout << "  [FAIL] : in np_test_datetime64_accessors() : Accessor methods failed";
              throw std::runtime_error("np_test_datetime64_accessors failed");
            }
      
            std::cout << " -> tests passed" << std::endl;
          }

.. _example-timedelta64-getvalue-3:

.. dropdown:: getValue (np_test_1_all.cpp:28799)
   :class-title: example-dropdown

   .. code-block:: cpp
      :linenos:
      :lineno-start: 28789
      :emphasize-lines: 11

      
            std::cout << " -> tests passed" << std::endl;
          }
      
          void np_test_datetime64_accessors() {
            std::cout << "========= datetime64 accessors: getValue/getUnit =======================";
      
            auto dt = numpy::datetime64("2024-01-15");
      
            // Test getValue and getUnit
            int64_t value = dt.getValue();
            numpy::DateTimeUnit unit = dt.getUnit();
      
            bool passed = (value != 0);
      
            if (!passed) {
              std::cout << "  [FAIL] : in np_test_datetime64_accessors() : Accessor methods failed";
              throw std::runtime_error("np_test_datetime64_accessors failed");
            }
      
            std::cout << " -> tests passed" << std::endl;

.. _example-timedelta64-abs-4:

.. dropdown:: abs (np_test_1_all.cpp:101)
   :class-title: example-dropdown

   .. code-block:: cpp
      :linenos:
      :lineno-start: 91
      :emphasize-lines: 11

              if (arr.getShape().size() == 1 && arr.getShape()[0] <= 10) {
                  for (size_t i = 0; i < arr.getShape()[0]; ++i) {
                      // std::cout << static_cast<int64_t>(arr.getElementAt({i})) << " ";
                  }
              }
              // std::cout << std::endl;
          }
      
          // Helper function for core array extensions tests
          bool isApproxEqualExt(double a, double b, double tolerance = 1e-10) {
              return std::abs(a - b) < tolerance;
          }
      }
      
      void f_nothing() {
          // This function does nothing and tests nothing
          // It's a placeholder test function
      }
      
      // ------ merging np_test_advanced_indexing.cpp -- number of functions merged=16 --------------------------------
      

.. _example-timedelta64-nat-5:

.. dropdown:: NaT (np_test_1_all.cpp:7020)
   :class-title: example-dropdown

   .. code-block:: cpp
      :linenos:
      :lineno-start: 7010
      :emphasize-lines: 11

              // std::cout << april_2024.getElementAt({i}).toString() << " ";
          }
          // std::cout << std::endl;
      
              std::cout << " -> tests passed" << std::endl;
      }
      
      void testNaTHandlingDateTime() {
          std::cout << "========= testNaTHandlingDateTime =======================";
      
          datetime64 nat_dt = datetime64::NaT();
          timedelta64 nat_td = timedelta64::NaT();
      
          // std::cout << "NaT datetime: " << nat_dt.toString() << std::endl;
          // std::cout << "NaT timedelta: " << nat_td.toString() << std::endl;
      
          datetime64 valid_date("2024-01-01");
      
          // NaT arithmetic
          datetime64 result1 = valid_date + nat_td;
          datetime64 result2 = nat_dt + timedelta64(1, DateTimeUnit::Day);

.. _example-timedelta64-convertto-6:

.. dropdown:: convertTo (np_test_1_all.cpp:7051)
   :class-title: example-dropdown

   .. code-block:: cpp
      :linenos:
      :lineno-start: 7041
      :emphasize-lines: 11

      
              std::cout << " -> tests passed" << std::endl;
      }
      
      void testConversionsDateTime() {
          std::cout << "========= testConversionsDateTime =======================";
      
          datetime64 dt_seconds("2024-01-01T12:30:45");
          // std::cout << "Original (seconds): " << dt_seconds.toString() << std::endl;
      
          datetime64 dt_days = dt_seconds.convertTo(DateTimeUnit::Day);
          // std::cout << "Converted to days: " << dt_days.toString() << std::endl;
      
          datetime64 dt_hours = dt_seconds.convertTo(DateTimeUnit::Hour);
          // std::cout << "Converted to hours: " << dt_hours.toString() << std::endl;
      
          timedelta64 td_hours(24, DateTimeUnit::Hour);
          // std::cout << "24 hours: " << td_hours.toString() << std::endl;
      
          timedelta64 td_days = td_hours.convertTo(DateTimeUnit::Day);
          // std::cout << "Converted to days: " << td_days.toString() << std::endl;

.. _example-timedelta64-fromseconds-7:

.. dropdown:: fromSeconds (np_test_1_all.cpp:28819)
   :class-title: example-dropdown

   .. code-block:: cpp
      :linenos:
      :lineno-start: 28809
      :emphasize-lines: 11

            std::cout << " -> tests passed" << std::endl;
          }
      
          // ============================================================================
          // TIMEDELTA64 METHODS TESTS
          // ============================================================================
      
          void np_test_timedelta64_conversions() {
            std::cout << "========= timedelta64 conversions: fromSeconds/toSeconds/toDays =======================";
      
            // Test fromSeconds (needs two parameters: seconds and unit)
            int64_t seconds = 86400; // 1 day
            auto td = numpy::timedelta64::fromSeconds(seconds, numpy::DateTimeUnit::Second);
      
            // Test toSeconds
            int64_t converted_seconds = td.toSeconds();
      
            // Test toDays (returns int64_t)
            int64_t days = td.toDays();
      
            bool passed = (converted_seconds == seconds && days == 1);

.. _example-timedelta64-isnat-8:

.. dropdown:: isNaT (np_test_1_all.cpp:6821)
   :class-title: example-dropdown

   .. code-block:: cpp
      :linenos:
      :lineno-start: 6811
      :emphasize-lines: 11

      
          std::cout << " -> tests passed" << std::endl;
      }
      
      // DateTime Functions (merged from np_test_datetime.cpp)
      void testDatetime64CreationDateTime() {
          std::cout << "========= testDatetime64CreationDateTime =======================";
      
          // Test default constructor
          datetime64 default_dt;
          if (!(default_dt.isNaT())) {
              std::string description = std::string("testDatetime64CreationDateTime():") + __FILE__ + ":" + std::to_string(__LINE__) + ": !(default_dt.isNaT())";
              std::cout << std::string("[FAIL] ") + description << std::endl;
              throw std::runtime_error(description);
          }
          // std::cout << "Default datetime64 is NaT: " << default_dt.toString() << std::endl;
      
          // Test value constructor
          datetime64 epoch_day(0, DateTimeUnit::Day);
          // std::cout << "Epoch day: " << epoch_day.toString() << std::endl;
      

.. _example-timedelta64-todays-9:

.. dropdown:: toDays (np_test_1_all.cpp:28826)
   :class-title: example-dropdown

   .. code-block:: cpp
      :linenos:
      :lineno-start: 28816
      :emphasize-lines: 11

          void np_test_timedelta64_conversions() {
            std::cout << "========= timedelta64 conversions: fromSeconds/toSeconds/toDays =======================";
      
            // Test fromSeconds (needs two parameters: seconds and unit)
            int64_t seconds = 86400; // 1 day
            auto td = numpy::timedelta64::fromSeconds(seconds, numpy::DateTimeUnit::Second);
      
            // Test toSeconds
            int64_t converted_seconds = td.toSeconds();
      
            // Test toDays (returns int64_t)
            int64_t days = td.toDays();
      
            bool passed = (converted_seconds == seconds && days == 1);
      
            if (!passed) {
              std::cout << "  [FAIL] : in np_test_timedelta64_conversions() : Conversion failed - seconds: "
                << converted_seconds << ", days: " << days << std::endl;
              throw std::runtime_error("np_test_timedelta64_conversions failed");
            }
      

.. _example-timedelta64-tohours-10:

.. dropdown:: toHours (np_test_1_all.cpp:6863)
   :class-title: example-dropdown

   .. code-block:: cpp
      :linenos:
      :lineno-start: 6853
      :emphasize-lines: 11

          timedelta64 one_day(1, DateTimeUnit::Day);
          // std::cout << "One day: " << one_day.toString() << std::endl;
      
          timedelta64 five_hours(5, DateTimeUnit::Hour);
          // std::cout << "Five hours: " << five_hours.toString() << std::endl;
      
          timedelta64 from_string("30 minutes");
          // std::cout << "From string '30 minutes': " << from_string.toString() << std::endl;
      
          // Test conversions
          // std::cout << "One day in hours: " << one_day.toHours() << std::endl;
          // std::cout << "Five hours in minutes: " << five_hours.toMinutes() << std::endl;
      
              std::cout << " -> tests passed" << std::endl;
      }
      
      void testDatetimeArithmeticDateTime() {
          std::cout << "========= testDatetimeArithmeticDateTime =======================";
      
          datetime64 start_date("2024-01-01");
          timedelta64 one_week(7, DateTimeUnit::Day);

.. _example-timedelta64-tominutes-11:

.. dropdown:: toMinutes (np_test_1_all.cpp:6864)
   :class-title: example-dropdown

   .. code-block:: cpp
      :linenos:
      :lineno-start: 6854
      :emphasize-lines: 11

          // std::cout << "One day: " << one_day.toString() << std::endl;
      
          timedelta64 five_hours(5, DateTimeUnit::Hour);
          // std::cout << "Five hours: " << five_hours.toString() << std::endl;
      
          timedelta64 from_string("30 minutes");
          // std::cout << "From string '30 minutes': " << from_string.toString() << std::endl;
      
          // Test conversions
          // std::cout << "One day in hours: " << one_day.toHours() << std::endl;
          // std::cout << "Five hours in minutes: " << five_hours.toMinutes() << std::endl;
      
              std::cout << " -> tests passed" << std::endl;
      }
      
      void testDatetimeArithmeticDateTime() {
          std::cout << "========= testDatetimeArithmeticDateTime =======================";
      
          datetime64 start_date("2024-01-01");
          timedelta64 one_week(7, DateTimeUnit::Day);
          timedelta64 three_days(3, DateTimeUnit::Day);

.. _example-timedelta64-toseconds-12:

.. dropdown:: toSeconds (np_test_1_all.cpp:28824)
   :class-title: example-dropdown

   .. code-block:: cpp
      :linenos:
      :lineno-start: 28814
      :emphasize-lines: 11

          // ============================================================================
      
          void np_test_timedelta64_conversions() {
            std::cout << "========= timedelta64 conversions: fromSeconds/toSeconds/toDays =======================";
      
            // Test fromSeconds (needs two parameters: seconds and unit)
            int64_t seconds = 86400; // 1 day
            auto td = numpy::timedelta64::fromSeconds(seconds, numpy::DateTimeUnit::Second);
      
            // Test toSeconds
            int64_t converted_seconds = td.toSeconds();
      
            // Test toDays (returns int64_t)
            int64_t days = td.toDays();
      
            bool passed = (converted_seconds == seconds && days == 1);
      
            if (!passed) {
              std::cout << "  [FAIL] : in np_test_timedelta64_conversions() : Conversion failed - seconds: "
                << converted_seconds << ", days: " << days << std::endl;
              throw std::runtime_error("np_test_timedelta64_conversions failed");

.. _example-timedelta64-tostring-13:

.. dropdown:: toString (np_test_1_all.cpp:6826)
   :class-title: example-dropdown

   .. code-block:: cpp
      :linenos:
      :lineno-start: 6816
      :emphasize-lines: 11

      void testDatetime64CreationDateTime() {
          std::cout << "========= testDatetime64CreationDateTime =======================";
      
          // Test default constructor
          datetime64 default_dt;
          if (!(default_dt.isNaT())) {
              std::string description = std::string("testDatetime64CreationDateTime():") + __FILE__ + ":" + std::to_string(__LINE__) + ": !(default_dt.isNaT())";
              std::cout << std::string("[FAIL] ") + description << std::endl;
              throw std::runtime_error(description);
          }
          // std::cout << "Default datetime64 is NaT: " << default_dt.toString() << std::endl;
      
          // Test value constructor
          datetime64 epoch_day(0, DateTimeUnit::Day);
          // std::cout << "Epoch day: " << epoch_day.toString() << std::endl;
      
          // Test string constructor
          datetime64 date_from_string("2024-01-15");
          // std::cout << "Date from string '2024-01-15': " << date_from_string.toString() << std::endl;
      
          datetime64 datetime_from_string("2024-01-15T10:30:45");