datetime64
==========

.. cpp:class:: numpy::datetime64

   numpy C++ class.

Example
-------

.. code-block:: cpp

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

   // Use datetime64
   datetime64 obj;
   // ... operations ...

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

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

   * - Signature
     - Location
     - Example
   * - ``datetime64(int64_tvalue, DateTimeUnitunit)``
     - NP_DATETIME64.H:42
     - :ref:`View <example-datetime64-datetime64-0>`
   * - ``datetime64(const std::string &iso_string)``
     - NP_DATETIME64.H:43
     - :ref:`View <example-datetime64-datetime64-1>`

Operators
---------

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

   * - Signature
     - Return Type
     - Location
     - Example
   * - ``timedelta64 operator-(const datetime64 &other)``
     - timedelta64
     - NP_DATETIME64.H:48
     - 
   * - ``datetime64 operator+(const timedelta64 &delta)``
     - datetime64
     - NP_DATETIME64.H:49
     - 
   * - ``datetime64 operator-(const timedelta64 &delta)``
     - datetime64
     - NP_DATETIME64.H:50
     - 
   * - ``bool operator==(const datetime64 &other)``
     - bool
     - NP_DATETIME64.H:52
     - 
   * - ``bool operator!=(const datetime64 &other)``
     - bool
     - NP_DATETIME64.H:53
     - 
   * - ``bool operator<(const datetime64 &other)``
     - bool
     - NP_DATETIME64.H:54
     - 
   * - ``bool operator<=(const datetime64 &other)``
     - bool
     - NP_DATETIME64.H:55
     - 
   * - ``bool operator>(const datetime64 &other)``
     - bool
     - NP_DATETIME64.H:56
     - 
   * - ``bool operator>=(const datetime64 &other)``
     - bool
     - NP_DATETIME64.H:57
     - 

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

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

   * - Signature
     - Return Type
     - Location
     - Example
   * - ``DateTimeUnit getUnit()``
     - DateTimeUnit
     - NP_DATETIME64.H:46
     - :ref:`View <example-datetime64-getunit-2>`
   * - ``int64_t getValue()``
     - int64_t
     - NP_DATETIME64.H:45
     - :ref:`View <example-datetime64-getvalue-3>`

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

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

   * - Signature
     - Return Type
     - Location
     - Example
   * - ``datetime64 NaT(DateTimeUnitunit = DateTimeUnit::Second)``
     - datetime64
     - NP_DATETIME64.H:66
     - :ref:`View <example-datetime64-nat-4>`
   * - ``datetime64 convertTo(DateTimeUnitnew_unit)``
     - datetime64
     - NP_DATETIME64.H:68
     - :ref:`View <example-datetime64-convertto-5>`
   * - ``int daysInMonth(intyear, intmonth)``
     - int
     - NP_DATETIME64.H:72
     - :ref:`View <example-datetime64-daysinmonth-6>`
   * - ``datetime64 fromEpochSeconds(int64_tseconds, DateTimeUnitunit)``
     - datetime64
     - NP_DATETIME64.H:39
     - :ref:`View <example-datetime64-fromepochseconds-7>`
   * - ``bool isLeapYear(intyear)``
     - bool
     - NP_DATETIME64.H:71
     - :ref:`View <example-datetime64-isleapyear-8>`
   * - ``bool isNaT()``
     - bool
     - NP_DATETIME64.H:65
     - :ref:`View <example-datetime64-isnat-9>`
   * - ``datetime64 now(DateTimeUnitunit = DateTimeUnit::Second)``
     - datetime64
     - NP_DATETIME64.H:62
     - :ref:`View <example-datetime64-now-10>`
   * - ``int64_t parseISO8601(const std::string &iso_string, DateTimeUnit &unit)``
     - int64_t
     - NP_DATETIME64.H:70
     - 
   * - ``int64_t toEpochSeconds()``
     - int64_t
     - NP_DATETIME64.H:38
     - :ref:`View <example-datetime64-toepochseconds-11>`
   * - ``std::string toString()``
     - std::string
     - NP_DATETIME64.H:59
     - :ref:`View <example-datetime64-tostring-12>`
   * - ``std::tm toTm()``
     - std::tm
     - NP_DATETIME64.H:60
     - 
   * - ``datetime64 today()``
     - datetime64
     - NP_DATETIME64.H:63
     - :ref:`View <example-datetime64-today-13>`


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

The following examples are extracted from the test suite.

.. _example-datetime64-datetime64-0:

.. dropdown:: datetime64 (np_test_1_all.cpp:6990)
   :class-title: example-dropdown

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

      }
      
      void testBusinessDateRangeDateTime() {
          std::cout << "========= testBusinessDateRangeDateTime =======================";
      
          datetime64 start("2024-03-11");  // Monday
          datetime64 end("2024-03-22");    // Friday (2 weeks later)
      
          // Create holidays set
          std::set<datetime64> holidays;
          holidays.insert(datetime64("2024-03-15"));  // Friday holiday
      
          auto business_dates = createBusinessDateRange(start, end, holidays);
          // std::cout << "Business dates from " << start.toString()
                    // << " to " << end.toString() << " (excluding 2024-03-15):" << std::endl;
          //business_dates.printArray();
      
              std::cout << " -> tests passed" << std::endl;
      }
      
      void testMonthRangeDateTime() {

.. _example-datetime64-datetime64-1:

.. dropdown:: datetime64 (np_test_1_all.cpp:6990)
   :class-title: example-dropdown

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

      }
      
      void testBusinessDateRangeDateTime() {
          std::cout << "========= testBusinessDateRangeDateTime =======================";
      
          datetime64 start("2024-03-11");  // Monday
          datetime64 end("2024-03-22");    // Friday (2 weeks later)
      
          // Create holidays set
          std::set<datetime64> holidays;
          holidays.insert(datetime64("2024-03-15"));  // Friday holiday
      
          auto business_dates = createBusinessDateRange(start, end, holidays);
          // std::cout << "Business dates from " << start.toString()
                    // << " to " << end.toString() << " (excluding 2024-03-15):" << std::endl;
          //business_dates.printArray();
      
              std::cout << " -> tests passed" << std::endl;
      }
      
      void testMonthRangeDateTime() {

.. _example-datetime64-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-datetime64-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-datetime64-nat-4:

.. 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-datetime64-convertto-5:

.. 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-datetime64-daysinmonth-6:

.. dropdown:: daysInMonth (np_test_1_all.cpp:6977)
   :class-title: example-dropdown

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

          // std::cout << "Business days from " << start_bday.toString()
                    // << " to " << end_bday.toString() << ": " << business_days << std::endl;
      
          datetime64 offset_date = datetime_utils::businessDayOffset(start_bday, 3);
          // std::cout << "3 business days after " << start_bday.toString()
                    // << ": " << offset_date.toString() << std::endl;
      
          // Test leap year
          // std::cout << "2024 is leap year: " << datetime_utils::isLeapYear(2024) << std::endl;
          // std::cout << "2023 is leap year: " << datetime_utils::isLeapYear(2023) << std::endl;
          // std::cout << "Days in February 2024: " << datetime_utils::daysInMonth(2024, 2) << std::endl;
      
              std::cout << " -> tests passed" << std::endl;
      }
      
      void testBusinessDateRangeDateTime() {
          std::cout << "========= testBusinessDateRangeDateTime =======================";
      
          datetime64 start("2024-03-11");  // Monday
          datetime64 end("2024-03-22");    // Friday (2 weeks later)
      

.. _example-datetime64-fromepochseconds-7:

.. dropdown:: fromEpochSeconds (np_test_1_all.cpp:28776)
   :class-title: example-dropdown

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

            std::cout << " -> tests passed" << std::endl;
          }
      
          // ============================================================================
          // DATETIME64 METHODS TESTS
          // ============================================================================
      
          void np_test_datetime64_epoch_conversion() {
            std::cout << "========= datetime64 epoch conversion: fromEpochSeconds/toEpochSeconds =======================";
      
            // Test fromEpochSeconds (needs two parameters: seconds and unit)
            int64_t epoch_seconds = 1704067200; // Jan 1, 2024 00:00:00 UTC
            auto dt = numpy::datetime64::fromEpochSeconds(epoch_seconds, numpy::DateTimeUnit::Second);
      
            // Test toEpochSeconds
            int64_t converted = dt.toEpochSeconds();
      
            bool passed = (converted == epoch_seconds);
      
            if (!passed) {
              std::cout << "  [FAIL] : in np_test_datetime64_epoch_conversion() : Epoch conversion failed";

.. _example-datetime64-isleapyear-8:

.. dropdown:: isLeapYear (np_test_1_all.cpp:6975)
   :class-title: example-dropdown

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

      
          int64_t business_days = datetime_utils::businessDayCount(start_bday, end_bday);
          // std::cout << "Business days from " << start_bday.toString()
                    // << " to " << end_bday.toString() << ": " << business_days << std::endl;
      
          datetime64 offset_date = datetime_utils::businessDayOffset(start_bday, 3);
          // std::cout << "3 business days after " << start_bday.toString()
                    // << ": " << offset_date.toString() << std::endl;
      
          // Test leap year
          // std::cout << "2024 is leap year: " << datetime_utils::isLeapYear(2024) << std::endl;
          // std::cout << "2023 is leap year: " << datetime_utils::isLeapYear(2023) << std::endl;
          // std::cout << "Days in February 2024: " << datetime_utils::daysInMonth(2024, 2) << std::endl;
      
              std::cout << " -> tests passed" << std::endl;
      }
      
      void testBusinessDateRangeDateTime() {
          std::cout << "========= testBusinessDateRangeDateTime =======================";
      
          datetime64 start("2024-03-11");  // Monday

.. _example-datetime64-isnat-9:

.. 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-datetime64-now-10:

.. dropdown:: now (np_test_1_all.cpp:3611)
   :class-title: example-dropdown

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

      
      void test_broadcasting_performance() {
          std::cout << "========= test_broadcasting_performance =======================";
          // std::cout << "Testing broadcasting performance..." << std::endl;
      
          // Create larger arrays for performance testing
          auto large_arr = NDArray<double>::createOnes({100, 100});
          auto broadcast_arr = NDArray<double>::createOnes({1, 100});
      
          // Time the operation (basic timing)
          auto start = std::chrono::high_resolution_clock::now();
          auto result = large_arr.addArrays(broadcast_arr);
          auto end = std::chrono::high_resolution_clock::now();
      
          auto duration = std::chrono::duration_cast<std::chrono::microseconds>(end - start);
          // std::cout << "Large array broadcasting took " << duration.count() << " microseconds" << std::endl;
      
          // Verify result shape
          if (!((result.getShape() == std::vector<size_t>{100, 100}))) {
              std::string description = std::string("test_broadcasting_performance():") + __FILE__ + ":" + std::to_string(__LINE__) + ": !((result.getShape() == std::vector<size_t>{100, 100}))";
              std::cout << std::string("[FAIL] ") + description << std::endl;

.. _example-datetime64-toepochseconds-11:

.. dropdown:: toEpochSeconds (np_test_1_all.cpp:28781)
   :class-title: example-dropdown

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

          // ============================================================================
      
          void np_test_datetime64_epoch_conversion() {
            std::cout << "========= datetime64 epoch conversion: fromEpochSeconds/toEpochSeconds =======================";
      
            // Test fromEpochSeconds (needs two parameters: seconds and unit)
            int64_t epoch_seconds = 1704067200; // Jan 1, 2024 00:00:00 UTC
            auto dt = numpy::datetime64::fromEpochSeconds(epoch_seconds, numpy::DateTimeUnit::Second);
      
            // Test toEpochSeconds
            int64_t converted = dt.toEpochSeconds();
      
            bool passed = (converted == epoch_seconds);
      
            if (!passed) {
              std::cout << "  [FAIL] : in np_test_datetime64_epoch_conversion() : Epoch conversion failed";
              throw std::runtime_error("np_test_datetime64_epoch_conversion failed");
            }
      
            std::cout << " -> tests passed" << std::endl;
          }

.. _example-datetime64-tostring-12:

.. 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");

.. _example-datetime64-today-13:

.. dropdown:: today (np_test_1_all.cpp:6840)
   :class-title: example-dropdown

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

          // 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");
          // std::cout << "DateTime from string '2024-01-15T10:30:45': " << datetime_from_string.toString() << std::endl;
      
          // Test static methods
          datetime64 today = datetime64::today();
          // std::cout << "Today: " << today.toString() << std::endl;
      
          datetime64 now = datetime64::now();
          // std::cout << "Now: " << now.toString() << std::endl;
      
              std::cout << " -> tests passed" << std::endl;
      }
      
      void testTimedelta64CreationDateTime() {
          std::cout << "========= testTimedelta64CreationDateTime =======================";