DatetimeProperties
==================

.. cpp:class:: pandas::DatetimeProperties

   pandas C++ class.

Example
-------

.. code-block:: cpp

   #include <pandas/pandas.h>
   using namespace pandas;

   // Use DatetimeProperties
   DatetimeProperties obj;
   // ... operations ...

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

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

   * - Signature
     - Return Type
     - Location
     - Example
   * - ``static int64_t get_freq_nanoseconds(const std::string& freq)``
     - static int64_t
     - pd_datetime_accessor.h:720
     - 

Statistics
----------

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

   * - Signature
     - Return Type
     - Location
     - Example
   * - ``std::vector<int64_t> minute() const``
     - std::vector<int64_t>
     - pd_datetime_accessor.h:114
     - :ref:`View <example-datetimeproperties-minute-0>`

Time Series
-----------

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

   * - Signature
     - Return Type
     - Location
     - Example
   * - ``PeriodArray to_period(const std::string& freq = "D") const``
     - PeriodArray
     - pd_datetime_accessor.h:625
     - :ref:`View <example-datetimeproperties-to_period-1>`
   * - ``std::vector<numpy::datetime64> tz_convert(const std::string& tz) const``
     - std::vector<numpy::datetime64>
     - pd_datetime_accessor.h:641
     - :ref:`View <example-datetimeproperties-tz_convert-2>`
   * - ``std::vector<numpy::datetime64> tz_localize(const std::string& tz, const std::string& ambiguous = "raise", const std::string& nonexistent = "raise") const``
     - std::vector<numpy::datetime64>
     - pd_datetime_accessor.h:667
     - :ref:`View <example-datetimeproperties-tz_localize-3>`

I/O
---

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

   * - Signature
     - Return Type
     - Location
     - Example
   * - ``std::vector<numpy::datetime64> to_pydatetime() const``
     - std::vector<numpy::datetime64>
     - pd_datetime_accessor.h:700
     - :ref:`View <example-datetimeproperties-to_pydatetime-4>`

Type Checking
-------------

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

   * - Signature
     - Return Type
     - Location
     - Example
   * - ``std::vector<bool> is_leap_year() const``
     - std::vector<bool>
     - pd_datetime_accessor.h:305
     - :ref:`View <example-datetimeproperties-is_leap_year-5>`
   * - ``std::vector<bool> is_month_end() const``
     - std::vector<bool>
     - pd_datetime_accessor.h:223
     - :ref:`View <example-datetimeproperties-is_month_end-6>`
   * - ``std::vector<bool> is_month_start() const``
     - std::vector<bool>
     - pd_datetime_accessor.h:208
     - :ref:`View <example-datetimeproperties-is_month_start-7>`
   * - ``std::vector<bool> is_quarter_end() const``
     - std::vector<bool>
     - pd_datetime_accessor.h:257
     - :ref:`View <example-datetimeproperties-is_quarter_end-8>`
   * - ``std::vector<bool> is_quarter_start() const``
     - std::vector<bool>
     - pd_datetime_accessor.h:241
     - :ref:`View <example-datetimeproperties-is_quarter_start-9>`
   * - ``std::vector<bool> is_year_end() const``
     - std::vector<bool>
     - pd_datetime_accessor.h:290
     - :ref:`View <example-datetimeproperties-is_year_end-10>`
   * - ``std::vector<bool> is_year_start() const``
     - std::vector<bool>
     - pd_datetime_accessor.h:275
     - :ref:`View <example-datetimeproperties-is_year_start-11>`

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

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

   * - Signature
     - Return Type
     - Location
     - Example
   * - ``std::vector<numpy::datetime64> as_unit(const std::string& unit_str) const``
     - std::vector<numpy::datetime64>
     - pd_datetime_accessor.h:690
     - :ref:`View <example-datetimeproperties-as_unit-12>`
   * - ``std::vector<numpy::datetime64> ceil(const std::string& freq, const std::string& ambiguous = "raise", const std::string& nonexistent = "raise") const``
     - std::vector<numpy::datetime64>
     - pd_datetime_accessor.h:608
     - :ref:`View <example-datetimeproperties-ceil-13>`
   * - ``static numpy::datetime64 ceil_datetime(const numpy::datetime64& dt, const std::string& freq)``
     - static numpy::datetime64
     - pd_datetime_accessor.h:753
     - 
   * - ``std::vector<std::string> date() const``
     - std::vector<std::string>
     - pd_datetime_accessor.h:339
     - :ref:`View <example-datetimeproperties-date-14>`
   * - ``std::vector<int64_t> day() const``
     - std::vector<int64_t>
     - pd_datetime_accessor.h:84
     - :ref:`View <example-datetimeproperties-day-15>`
   * - ``std::vector<std::string> day_name(const std::string& locale = "") const``
     - std::vector<std::string>
     - pd_datetime_accessor.h:430
     - :ref:`View <example-datetimeproperties-day_name-16>`
   * - ``std::vector<int64_t> dayofweek() const``
     - std::vector<int64_t>
     - pd_datetime_accessor.h:144
     - :ref:`View <example-datetimeproperties-dayofweek-17>`
   * - ``std::vector<int64_t> dayofyear() const``
     - std::vector<int64_t>
     - pd_datetime_accessor.h:160
     - :ref:`View <example-datetimeproperties-dayofyear-18>`
   * - ``static int days_in_month(int year, int month)``
     - static int
     - pd_datetime_accessor.h:710
     - :ref:`View <example-datetimeproperties-days_in_month-19>`
   * - ``std::vector<int64_t> days_in_month_prop() const``
     - std::vector<int64_t>
     - pd_datetime_accessor.h:359
     - :ref:`View <example-datetimeproperties-days_in_month_prop-20>`
   * - ``DatetimeArray dta(data, src_tz)``
     - DatetimeArray
     - pd_datetime_accessor.h:654
     - 
   * - ``DatetimeArray dta(data, nullptr)``
     - DatetimeArray
     - pd_datetime_accessor.h:677
     - 
   * - ``std::vector<numpy::datetime64> floor(const std::string& freq, const std::string& ambiguous = "raise", const std::string& nonexistent = "raise") const``
     - std::vector<numpy::datetime64>
     - pd_datetime_accessor.h:591
     - :ref:`View <example-datetimeproperties-floor-21>`
   * - ``static numpy::datetime64 floor_datetime(const numpy::datetime64& dt, const std::string& freq)``
     - static numpy::datetime64
     - pd_datetime_accessor.h:744
     - 
   * - ``std::string freq() const``
     - std::string
     - pd_datetime_accessor.h:410
     - :ref:`View <example-datetimeproperties-freq-22>`
   * - ``bool has_nat() const``
     - bool
     - pd_datetime_accessor.h:37
     - :ref:`View <example-datetimeproperties-has_nat-23>`
   * - ``std::vector<int64_t> hour() const``
     - std::vector<int64_t>
     - pd_datetime_accessor.h:99
     - :ref:`View <example-datetimeproperties-hour-24>`
   * - ``IsoCalendar isocalendar() const``
     - IsoCalendar
     - pd_datetime_accessor.h:496
     - :ref:`View <example-datetimeproperties-isocalendar-25>`
   * - ``DataFrame isocalendar_to_dataframe() const``
     - DataFrame
     - pd_datetime_accessor.h:494
     - 
   * - ``std::vector<int64_t> microsecond() const``
     - std::vector<int64_t>
     - pd_datetime_accessor.h:376
     - :ref:`View <example-datetimeproperties-microsecond-26>`
   * - ``std::vector<int64_t> month() const``
     - std::vector<int64_t>
     - pd_datetime_accessor.h:69
     - :ref:`View <example-datetimeproperties-month-27>`
   * - ``std::vector<std::string> month_name(const std::string& locale = "") const``
     - std::vector<std::string>
     - pd_datetime_accessor.h:448
     - :ref:`View <example-datetimeproperties-month_name-28>`
   * - ``std::vector<int64_t> nanosecond() const``
     - std::vector<int64_t>
     - pd_datetime_accessor.h:393
     - :ref:`View <example-datetimeproperties-nanosecond-29>`
   * - ``std::vector<numpy::datetime64> normalize() const``
     - std::vector<numpy::datetime64>
     - pd_datetime_accessor.h:466
     - :ref:`View <example-datetimeproperties-normalize-30>`
   * - ``const ParentType& parent() const``
     - const ParentType&
     - pd_datetime_accessor.h:35
     - 
   * - ``explicit DatetimeProperties(const ParentType& parent) : parent_(parent)``
     - explicit DatetimeProperties(const ParentType& parent) :
     - pd_datetime_accessor.h:31
     - 
   * - ``std::vector<int64_t> quarter() const``
     - std::vector<int64_t>
     - pd_datetime_accessor.h:175
     - :ref:`View <example-datetimeproperties-quarter-31>`
   * - ``std::vector<numpy::datetime64> round(const std::string& freq, const std::string& ambiguous = "raise", const std::string& nonexistent = "raise") const``
     - std::vector<numpy::datetime64>
     - pd_datetime_accessor.h:574
     - :ref:`View <example-datetimeproperties-round-32>`
   * - ``static numpy::datetime64 round_datetime(const numpy::datetime64& dt, const std::string& freq)``
     - static numpy::datetime64
     - pd_datetime_accessor.h:764
     - 
   * - ``pandas::Series<T> s(std::move(data))``
     - pandas::Series<T>
     - pd_datetime_accessor.h:46
     - :ref:`View <example-datetimeproperties-s-33>`
   * - ``std::vector<int64_t> second() const``
     - std::vector<int64_t>
     - pd_datetime_accessor.h:129
     - :ref:`View <example-datetimeproperties-second-34>`
   * - ``void set_tz_override(const std::string& tz)``
     - void
     - pd_datetime_accessor.h:33
     - 
   * - ``std::vector<std::string> strftime(const std::string& format) const``
     - std::vector<std::string>
     - pd_datetime_accessor.h:322
     - :ref:`View <example-datetimeproperties-strftime-35>`
   * - ``std::vector<std::string> time() const``
     - std::vector<std::string>
     - pd_datetime_accessor.h:343
     - :ref:`View <example-datetimeproperties-time-36>`
   * - ``std::vector<std::string> timetz() const``
     - std::vector<std::string>
     - pd_datetime_accessor.h:422
     - :ref:`View <example-datetimeproperties-timetz-37>`
   * - ``std::string tz() const``
     - std::string
     - pd_datetime_accessor.h:414
     - :ref:`View <example-datetimeproperties-tz-38>`
   * - ``std::string unit() const``
     - std::string
     - pd_datetime_accessor.h:418
     - :ref:`View <example-datetimeproperties-unit-39>`
   * - ``std::vector<int64_t> week() const``
     - std::vector<int64_t>
     - pd_datetime_accessor.h:191
     - :ref:`View <example-datetimeproperties-week-40>`
   * - ``pandas::Series<T> wrap_int_result(std::vector<T>&& data) const``
     - pandas::Series<T>
     - pd_datetime_accessor.h:45
     - :ref:`View <example-datetimeproperties-wrap_int_result-41>`
   * - ``std::vector<int64_t> year() const``
     - std::vector<int64_t>
     - pd_datetime_accessor.h:54
     - :ref:`View <example-datetimeproperties-year-42>`


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

The following examples are extracted from the test suite.

.. _example-datetimeproperties-minute-0:

.. dropdown:: minute (pd_test_1_all.cpp:7505)
   :class-title: example-dropdown

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

          std::cout << "========= minute property =============================";
      
          std::vector<std::optional<numpy::datetime64>> values = {
              make_dt(0),                    // Minute 0
              make_dt(30 * NS_PER_MIN),      // Minute 30
              make_dt(59 * NS_PER_MIN)       // Minute 59
          };
          pandas::DatetimeArray arr(values);
          pandas::DatetimeIndex idx(arr);
      
          auto minutes = idx.minute();
      
          bool passed = (minutes.size() == 3);
          auto m0 = minutes[0];
          auto m1 = minutes[1];
          auto m2 = minutes[2];
          passed = passed && m0.has_value() && *m0 == 0;
          passed = passed && m1.has_value() && *m1 == 30;
          passed = passed && m2.has_value() && *m2 == 59;
      
          if (!passed) {

.. _example-datetimeproperties-to_period-1:

.. dropdown:: to_period (pd_test_2_all.cpp:14554)
   :class-title: example-dropdown

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

      
              std::cout << "====================================== [OK] pd_test_to_parquet test suite ========================" << std::endl;
              return 0;
          }
      
      } // namespace dataframe_tests
      // ------------------- pd_test_to_parquet.cpp (end) -----------------------------
      
      // ------------------- pd_test_to_period.cpp (start) -----------------------------
      // dataframe_tests/pd_test_to_period.cpp
      // Test suite for DataFrame.to_period() method
      
      #include <iostream>
      #include <stdexcept>
      #include <vector>
      #include <string>
      #include <map>
      
      #include "../pandas/pd_dataframe.h"
      
      // CRITICAL: No using namespace directives

.. _example-datetimeproperties-tz_convert-2:

.. dropdown:: tz_convert (pd_test_2_all.cpp:17874)
   :class-title: example-dropdown

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

      
              std::cout << "====================================== [OK] pd_test_transform test suite ========================== " << std::endl;
              return 0;
          }
      
      } // namespace dataframe_tests
      // ------------------- pd_test_transform.cpp (end) -----------------------------
      
      // ------------------- pd_test_tz_convert.cpp (start) -----------------------------
      // dataframe_tests/pd_test_tz_convert.cpp
      // Test for DataFrame.tz_convert() method
      
      #include <iostream>
      #include <stdexcept>
      #include <cmath>
      #include "../pandas/pd_dataframe.h"
      
      namespace dataframe_tests {
          namespace dataframe_tests_tz_convert {
      
              void pd_test_tz_convert_basic() {

.. _example-datetimeproperties-tz_localize-3:

.. dropdown:: tz_localize (pd_test_1_all.cpp:1431)
   :class-title: example-dropdown

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

                  "2023-06-15"
              });
      
              // Initially should be timezone-naive
              if (arr.is_tz_aware()) {
                  std::cout << "  [FAIL] : array should be timezone-naive initially" << std::endl;
                  throw std::runtime_error("pd_test_datetime_array_timezone failed: naive");
              }
      
              // Localize to UTC
              auto localized = arr.tz_localize("UTC");
              if (!localized.is_tz_aware()) {
                  std::cout << "  [FAIL] : localized array should be timezone-aware" << std::endl;
                  throw std::runtime_error("pd_test_datetime_array_timezone failed: localize");
              }
      
              // Verify timezone name in dtype
              auto dt = localized.dtype();
              if (!dt.is_tz_aware()) {
                  std::cout << "  [FAIL] : dtype should be timezone-aware" << std::endl;
                  throw std::runtime_error("pd_test_datetime_array_timezone failed: dtype tz");

.. _example-datetimeproperties-to_pydatetime-4:

.. dropdown:: to_pydatetime (pd_test_timestamp_scalar.cpp:519)
   :class-title: example-dropdown

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

      
            // asm8 alias
            numpy::datetime64 asm8 = ts.asm8();
            if (asm8.isNaT()) { pass = false; fail_msg = "asm8 should not return NaT"; }
      
            // to_numpy
            int64_t value = ts.to_numpy();
            if (value == 0) { pass = false; fail_msg = "to_numpy should return non-zero"; }
      
            // to_pydatetime
            std::tm tm = ts.to_pydatetime();
            if (tm.tm_year != 124) { pass = false; fail_msg = "tm_year should be 124 (2024-1900)"; }
            if (tm.tm_mon != 5) { pass = false; fail_msg = "tm_mon should be 5 (June)"; }
      
            // timestamp
            double posix = ts.timestamp();
            if (posix <= 0) { pass = false; fail_msg = "POSIX timestamp should be positive"; }
      
            // timetuple
            auto [y, mo, d, h, mi, s] = ts.timetuple();
            if (y != 2024 || mo != 6) { pass = false; fail_msg = "timetuple values incorrect"; }

.. _example-datetimeproperties-is_leap_year-5:

.. dropdown:: is_leap_year (pd_test_1_all.cpp:1280)
   :class-title: example-dropdown

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

              }
      
              // is_month_end
              auto me = arr.is_month_end();
              if (!me[1].has_value() || !me[1].value()) {
                  std::cout << "  [FAIL] : 2023-03-31 should be month end" << std::endl;
                  throw std::runtime_error("pd_test_datetime_array_boolean_props failed: month end");
              }
      
              // is_leap_year
              auto ly = arr.is_leap_year();
              if (!ly[2].has_value() || !ly[2].value()) {
                  std::cout << "  [FAIL] : 2024 should be leap year" << std::endl;
                  throw std::runtime_error("pd_test_datetime_array_boolean_props failed: leap year");
              }
              if (!ly[0].has_value() || ly[0].value()) {
                  std::cout << "  [FAIL] : 2023 should not be leap year" << std::endl;
                  throw std::runtime_error("pd_test_datetime_array_boolean_props failed: not leap year");
              }
      
              std::cout << " -> tests passed" << std::endl;

.. _example-datetimeproperties-is_month_end-6:

.. dropdown:: is_month_end (pd_test_1_all.cpp:1273)
   :class-title: example-dropdown

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

              }
      
              // is_month_start
              auto ms = arr.is_month_start();
              if (!ms[0].has_value() || !ms[0].value()) {
                  std::cout << "  [FAIL] : 2023-01-01 should be month start" << std::endl;
                  throw std::runtime_error("pd_test_datetime_array_boolean_props failed: month start");
              }
      
              // is_month_end
              auto me = arr.is_month_end();
              if (!me[1].has_value() || !me[1].value()) {
                  std::cout << "  [FAIL] : 2023-03-31 should be month end" << std::endl;
                  throw std::runtime_error("pd_test_datetime_array_boolean_props failed: month end");
              }
      
              // is_leap_year
              auto ly = arr.is_leap_year();
              if (!ly[2].has_value() || !ly[2].value()) {
                  std::cout << "  [FAIL] : 2024 should be leap year" << std::endl;
                  throw std::runtime_error("pd_test_datetime_array_boolean_props failed: leap year");

.. _example-datetimeproperties-is_month_start-7:

.. dropdown:: is_month_start (pd_test_1_all.cpp:1266)
   :class-title: example-dropdown

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

              if (!ys[0].has_value() || !ys[0].value()) {
                  std::cout << "  [FAIL] : 2023-01-01 should be year start" << std::endl;
                  throw std::runtime_error("pd_test_datetime_array_boolean_props failed: year start");
              }
              if (!ys[1].has_value() || ys[1].value()) {
                  std::cout << "  [FAIL] : 2023-03-31 should not be year start" << std::endl;
                  throw std::runtime_error("pd_test_datetime_array_boolean_props failed: not year start");
              }
      
              // is_month_start
              auto ms = arr.is_month_start();
              if (!ms[0].has_value() || !ms[0].value()) {
                  std::cout << "  [FAIL] : 2023-01-01 should be month start" << std::endl;
                  throw std::runtime_error("pd_test_datetime_array_boolean_props failed: month start");
              }
      
              // is_month_end
              auto me = arr.is_month_end();
              if (!me[1].has_value() || !me[1].value()) {
                  std::cout << "  [FAIL] : 2023-03-31 should be month end" << std::endl;
                  throw std::runtime_error("pd_test_datetime_array_boolean_props failed: month end");

.. _example-datetimeproperties-is_quarter_end-8:

.. dropdown:: is_quarter_end (pd_test_3_all.cpp:25056)
   :class-title: example-dropdown

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

          };
          pandas::Series<numpy::datetime64> s(dates);
          pandas::DatetimeProperties<pandas::Series<numpy::datetime64>> dt(s);
          if (dt.has_nat()) throw std::runtime_error("has_nat should be false for clean series");
          auto ms = dt.is_month_start();
          if (ms[0] != true || ms[1] != false) throw std::runtime_error("is_month_start failed");
          auto me = dt.is_month_end();
          if (me[1] != true || me[0] != false) throw std::runtime_error("is_month_end failed");
          auto qs = dt.is_quarter_start();
          if (qs[0] != true || qs[1] != false) throw std::runtime_error("is_quarter_start failed");
          auto qe = dt.is_quarter_end();
          if (qe[2] != true || qe[0] != false) throw std::runtime_error("is_quarter_end failed");
          auto ys = dt.is_year_start();
          if (ys[0] != true || ys[1] != false) throw std::runtime_error("is_year_start failed");
          auto ye = dt.is_year_end();
          if (ye[3] != true || ye[0] != false) throw std::runtime_error("is_year_end failed");
          std::cout << " -> tests passed" << std::endl;
      }
      
      void pd_test_dt_bool_na_with_nat() {
          std::cout << "========= pd_test_dt_bool_na: series with NaT ==========";

.. _example-datetimeproperties-is_quarter_start-9:

.. dropdown:: is_quarter_start (pd_test_3_all.cpp:25054)
   :class-title: example-dropdown

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

              numpy::datetime64("2024-03-31"),
              numpy::datetime64("2024-12-31")
          };
          pandas::Series<numpy::datetime64> s(dates);
          pandas::DatetimeProperties<pandas::Series<numpy::datetime64>> dt(s);
          if (dt.has_nat()) throw std::runtime_error("has_nat should be false for clean series");
          auto ms = dt.is_month_start();
          if (ms[0] != true || ms[1] != false) throw std::runtime_error("is_month_start failed");
          auto me = dt.is_month_end();
          if (me[1] != true || me[0] != false) throw std::runtime_error("is_month_end failed");
          auto qs = dt.is_quarter_start();
          if (qs[0] != true || qs[1] != false) throw std::runtime_error("is_quarter_start failed");
          auto qe = dt.is_quarter_end();
          if (qe[2] != true || qe[0] != false) throw std::runtime_error("is_quarter_end failed");
          auto ys = dt.is_year_start();
          if (ys[0] != true || ys[1] != false) throw std::runtime_error("is_year_start failed");
          auto ye = dt.is_year_end();
          if (ye[3] != true || ye[0] != false) throw std::runtime_error("is_year_end failed");
          std::cout << " -> tests passed" << std::endl;
      }
      

.. _example-datetimeproperties-is_year_end-10:

.. dropdown:: is_year_end (pd_test_3_all.cpp:25060)
   :class-title: example-dropdown

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

          auto ms = dt.is_month_start();
          if (ms[0] != true || ms[1] != false) throw std::runtime_error("is_month_start failed");
          auto me = dt.is_month_end();
          if (me[1] != true || me[0] != false) throw std::runtime_error("is_month_end failed");
          auto qs = dt.is_quarter_start();
          if (qs[0] != true || qs[1] != false) throw std::runtime_error("is_quarter_start failed");
          auto qe = dt.is_quarter_end();
          if (qe[2] != true || qe[0] != false) throw std::runtime_error("is_quarter_end failed");
          auto ys = dt.is_year_start();
          if (ys[0] != true || ys[1] != false) throw std::runtime_error("is_year_start failed");
          auto ye = dt.is_year_end();
          if (ye[3] != true || ye[0] != false) throw std::runtime_error("is_year_end failed");
          std::cout << " -> tests passed" << std::endl;
      }
      
      void pd_test_dt_bool_na_with_nat() {
          std::cout << "========= pd_test_dt_bool_na: series with NaT ==========";
          std::vector<numpy::datetime64> dates = {
              numpy::datetime64("2024-01-01"),
              numpy::datetime64(),  // NaT
              numpy::datetime64("2024-12-31")

.. _example-datetimeproperties-is_year_start-11:

.. dropdown:: is_year_start (pd_test_1_all.cpp:1255)
   :class-title: example-dropdown

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

              std::cout << "========= DatetimeArray: boolean properties ======================= ";
      
              pandas::DatetimeArray arr(std::vector<std::string>{
                  "2023-01-01",   // year start, month start
                  "2023-03-31",   // quarter end, month end
                  "2024-02-29",   // leap year (2024 is leap year)
                  "2023-12-31"    // year end, month end
              });
      
              // is_year_start
              auto ys = arr.is_year_start();
              if (!ys[0].has_value() || !ys[0].value()) {
                  std::cout << "  [FAIL] : 2023-01-01 should be year start" << std::endl;
                  throw std::runtime_error("pd_test_datetime_array_boolean_props failed: year start");
              }
              if (!ys[1].has_value() || ys[1].value()) {
                  std::cout << "  [FAIL] : 2023-03-31 should not be year start" << std::endl;
                  throw std::runtime_error("pd_test_datetime_array_boolean_props failed: not year start");
              }
      
              // is_month_start

.. _example-datetimeproperties-as_unit-12:

.. dropdown:: as_unit (pd_test_1_all.cpp:9361)
   :class-title: example-dropdown

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

          data.setElementAt({1}, numpy::datetime64(2000000000LL, numpy::DateTimeUnit::Nanosecond));  // 2 seconds in ns
      
          numpy::NDArray<numpy::bool_> mask(std::vector<size_t>{2});
          mask.setElementAt({0}, numpy::bool_(false));
          mask.setElementAt({1}, numpy::bool_(false));
      
          pandas::DatetimeArray arr(data, mask);
          pandas::DatetimeTDMixin idx(arr, "test");
      
          // Convert to microseconds
          pandas::DatetimeTDMixin us_idx = idx.as_unit("us");
      
          // Convert to same unit (should return identical)
          pandas::DatetimeTDMixin same_idx = idx.as_unit("ns");
      
          bool passed = (us_idx.size() == 2 && same_idx.size() == 2 &&
                         us_idx.name().has_value() && *us_idx.name() == "test");
          if (!passed) {
              std::cout << "  [FAIL] : in pd_test_datetime_as_unit() : as_unit check failed" << std::endl;
              throw std::runtime_error("pd_test_datetime_as_unit failed");
          }

.. _example-datetimeproperties-ceil-13:

.. dropdown:: ceil (pd_test_1_all.cpp:4949)
   :class-title: example-dropdown

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

                      throw std::runtime_error("pd_test_arithmetic_series_round failed: round failed");
                  }
      
                  auto f = a.floor();
                  passed = std::abs(f[0] - 1.0) < 0.001 && std::abs(f[2] - 3.0) < 0.001 && std::abs(f[3] - (-2.0)) < 0.001;
                  if (!passed) {
                      std::cout << "  [FAIL] : in pd_test_arithmetic_series_round() : floor failed" << std::endl;
                      throw std::runtime_error("pd_test_arithmetic_series_round failed: floor failed");
                  }
      
                  auto c = a.ceil();
                  passed = std::abs(c[0] - 2.0) < 0.001 && std::abs(c[2] - 4.0) < 0.001 && std::abs(c[3] - (-1.0)) < 0.001;
                  if (!passed) {
                      std::cout << "  [FAIL] : in pd_test_arithmetic_series_round() : ceil failed" << std::endl;
                      throw std::runtime_error("pd_test_arithmetic_series_round failed: ceil failed");
                  }
      
                  // Round with decimals
                  pandas::Series<double> b({1.234, 2.567, 3.891});
                  auto r2 = b.round(2);
                  passed = std::abs(r2[0] - 1.23) < 0.001 && std::abs(r2[1] - 2.57) < 0.001;

.. _example-datetimeproperties-date-14:

.. dropdown:: date (pd_test_2_all.cpp:21549)
   :class-title: example-dropdown

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

          std::cout << "  -- test_pivot_grouper_mixed_plain --" << std::endl;
      
          // Mix plain column and grouper
          auto df = make_df(
              {"date", "region", "product", "sales"},
              {{"2023-01-15", "2023-01-20", "2023-02-10", "2023-02-25"},
               {"East", "West", "East", "West"},
               {"A", "B", "A", "B"},
               {"100", "200", "150", "250"}});
      
          // index: region (plain) + date (grouper with freq)
          std::vector<std::pair<std::string, std::string>> idx_groupers = {
              {"region", ""},    // plain column (empty freq)
              {"date", "ME"}     // grouper with monthly freq
          };
          std::vector<std::pair<std::string, std::string>> col_groupers = {};
      
          auto result = pandas::detail::pivot_table_with_grouper(
              df, {"sales"}, idx_groupers, col_groupers, "sum");
      
          check(result.nrows() > 0, "has_rows");

.. _example-datetimeproperties-day-15:

.. dropdown:: day (pd_test_1_all.cpp:1193)
   :class-title: example-dropdown

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

                  std::cout << "  [FAIL] : month[0] should be 3" << std::endl;
                  throw std::runtime_error("pd_test_datetime_array_component_month_day failed: month[0]");
              }
              auto m1 = months[1];
              if (!m1.has_value() || m1.value() != 12) {
                  std::cout << "  [FAIL] : month[1] should be 12" << std::endl;
                  throw std::runtime_error("pd_test_datetime_array_component_month_day failed: month[1]");
              }
      
              // Day
              auto days = arr.day();
              auto d0 = days[0];
              if (!d0.has_value() || d0.value() != 15) {
                  std::cout << "  [FAIL] : day[0] should be 15" << std::endl;
                  throw std::runtime_error("pd_test_datetime_array_component_month_day failed: day[0]");
              }
              auto d1 = days[1];
              if (!d1.has_value() || d1.value() != 25) {
                  std::cout << "  [FAIL] : day[1] should be 25" << std::endl;
                  throw std::runtime_error("pd_test_datetime_array_component_month_day failed: day[1]");
              }

.. _example-datetimeproperties-day_name-16:

.. dropdown:: day_name (pd_test_1_all.cpp:8474)
   :class-title: example-dropdown

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

      
      void pd_test_datetime_mixin_day_name() {
          std::cout << "========= day_name ====================================";
      
          std::vector<std::optional<numpy::datetime64>> values = {
              numpy::datetime64(0LL, numpy::DateTimeUnit::Nanosecond)  // 1970-01-01 = Thursday
          };
          pandas::DatetimeArray arr(values);
          pandas::DatetimeMixinIndex idx(arr);
      
          std::vector<std::string> names = idx.day_name();
      
          bool passed = (names.size() == 1 && names[0] == "Thursday");
          if (!passed) {
              std::cout << "  [FAIL] : in pd_test_datetime_mixin_day_name() got: " << names[0] << std::endl;
              throw std::runtime_error("pd_test_datetime_mixin_day_name failed");
          }
      
          std::cout << " -> tests passed" << std::endl;
      }
      

.. _example-datetimeproperties-dayofweek-17:

.. dropdown:: dayofweek (pd_test_1_all.cpp:7565)
   :class-title: example-dropdown

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

          // 1970-01-01 was a Thursday (day 3)
          std::vector<std::optional<numpy::datetime64>> values = {
              make_dt(0),                // Thursday (3)
              make_dt(NS_PER_DAY),       // Friday (4)
              make_dt(2 * NS_PER_DAY),   // Saturday (5)
              make_dt(3 * NS_PER_DAY)    // Sunday (6)
          };
          pandas::DatetimeArray arr(values);
          pandas::DatetimeIndex idx(arr);
      
          auto dow = idx.dayofweek();
      
          bool passed = (dow.size() == 4);
          if (!passed) {
              std::cout << "  [FAIL] : in pd_test_datetime_index_dayofweek()" << std::endl;
              throw std::runtime_error("pd_test_datetime_index_dayofweek failed");
          }
      
          std::cout << " -> tests passed" << std::endl;
      }
      

.. _example-datetimeproperties-dayofyear-18:

.. dropdown:: dayofyear (pd_test_3_all.cpp:18582)
   :class-title: example-dropdown

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

          auto seconds = s.dt().second();
          if (seconds[0] != 45 || seconds[1] != 30 || seconds[2] != 59) {
              std::cout << "  [FAIL] : second() failed" << std::endl;
              throw std::runtime_error("pd_test_dt_time_components: second() failed");
          }
      
          std::cout << " -> tests passed" << std::endl;
      }
      
      // ============================================================================
      // Test dt().dayofweek(), dt().dayofyear(), dt().quarter()
      // ============================================================================
      
      void pd_test_dt_derived_properties() {
          std::cout << "========= Series.dt().dayofweek/dayofyear/quarter() ======";
      
          // 2020-01-01 is a Wednesday (dayofweek=2), dayofyear=1, Q1
          // 2020-07-04 is a Saturday (dayofweek=5), dayofyear=186, Q3
          pandas::Series<std::string> s({"2020-01-01", "2020-07-04"});
      
          auto dow = s.dt().dayofweek();

.. _example-datetimeproperties-days_in_month-19:

.. dropdown:: days_in_month (pd_test_1_all.cpp:2766)
   :class-title: example-dropdown

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

                  std::cout << "  [FAIL] : day[0] should be 15" << std::endl;
                  throw std::runtime_error("pd_test_period_array_day_components failed: day[0]");
              }
              auto d1 = days[1];
              if (!d1.has_value() || d1.value() != 25) {
                  std::cout << "  [FAIL] : day[1] should be 25" << std::endl;
                  throw std::runtime_error("pd_test_period_array_day_components failed: day[1]");
              }
      
              // Days in month
              auto dim = arr.days_in_month();
              auto dim0 = dim[0];
              if (!dim0.has_value() || dim0.value() != 31) {
                  std::cout << "  [FAIL] : days_in_month[0] should be 31 (March)" << std::endl;
                  throw std::runtime_error("pd_test_period_array_day_components failed: days_in_month[0]");
              }
              auto dim1 = dim[1];
              if (!dim1.has_value() || dim1.value() != 31) {
                  std::cout << "  [FAIL] : days_in_month[1] should be 31 (December)" << std::endl;
                  throw std::runtime_error("pd_test_period_array_day_components failed: days_in_month[1]");
              }

.. _example-datetimeproperties-days_in_month_prop-20:

.. dropdown:: days_in_month_prop (pd_test_3_all.cpp:22045)
   :class-title: example-dropdown

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

      void test_dt_days_in_month() {
          std::cout << "========= dt.days_in_month ======================";
      
          std::vector<numpy::datetime64> dates = {
              numpy::datetime64("2023-01-15"),  // Jan = 31
              numpy::datetime64("2023-02-15"),  // Feb 2023 = 28
              numpy::datetime64("2024-02-15")   // Feb 2024 (leap) = 29
          };
          pandas::Series<numpy::datetime64> s(dates);
      
          auto result = s.dt().days_in_month_prop();
          if (result[0] != 31 || result[1] != 28 || result[2] != 29) {
              throw std::runtime_error("dt.days_in_month: wrong values");
          }
      
          // Also test alias
          auto alias = s.dt().daysinmonth();
          if (alias[0] != 31) {
              throw std::runtime_error("dt.daysinmonth: wrong values");
          }
      

.. _example-datetimeproperties-floor-21:

.. dropdown:: floor (pd_test_1_all.cpp:4942)
   :class-title: example-dropdown

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

      
                  pandas::Series<double> a({1.4, 2.5, 3.6, -1.4, -2.5});
      
                  auto r = a.round();
                  bool passed = std::abs(r[0] - 1.0) < 0.001 && std::abs(r[2] - 4.0) < 0.001;
                  if (!passed) {
                      std::cout << "  [FAIL] : in pd_test_arithmetic_series_round() : round failed" << std::endl;
                      throw std::runtime_error("pd_test_arithmetic_series_round failed: round failed");
                  }
      
                  auto f = a.floor();
                  passed = std::abs(f[0] - 1.0) < 0.001 && std::abs(f[2] - 3.0) < 0.001 && std::abs(f[3] - (-2.0)) < 0.001;
                  if (!passed) {
                      std::cout << "  [FAIL] : in pd_test_arithmetic_series_round() : floor failed" << std::endl;
                      throw std::runtime_error("pd_test_arithmetic_series_round failed: floor failed");
                  }
      
                  auto c = a.ceil();
                  passed = std::abs(c[0] - 2.0) < 0.001 && std::abs(c[2] - 4.0) < 0.001 && std::abs(c[3] - (-1.0)) < 0.001;
                  if (!passed) {
                      std::cout << "  [FAIL] : in pd_test_arithmetic_series_round() : ceil failed" << std::endl;

.. _example-datetimeproperties-freq-22:

.. dropdown:: freq (pd_test_1_all.cpp:8233)
   :class-title: example-dropdown

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

          std::cout << "========= freq property ===============================";
      
          std::vector<std::optional<numpy::datetime64>> values = {
              numpy::datetime64(0LL, numpy::DateTimeUnit::Nanosecond),
              numpy::datetime64(86400000000000LL, numpy::DateTimeUnit::Nanosecond)  // 1 day
          };
          pandas::DatetimeArray arr(values);
          pandas::DatetimeMixinIndex idx(arr);
      
          // Default freq is nullopt or inferred
          auto f = idx.freq();
          std::string fs = idx.freqstr();
      
          bool passed = true;  // freq may or may not be set
          if (!passed) {
              std::cout << "  [FAIL] : in pd_test_datetime_mixin_freq()" << std::endl;
              throw std::runtime_error("pd_test_datetime_mixin_freq failed");
          }
      
          std::cout << " -> tests passed" << std::endl;
      }

.. _example-datetimeproperties-has_nat-23:

.. dropdown:: has_nat (pd_test_3_all.cpp:25049)
   :class-title: example-dropdown

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

      void pd_test_dt_bool_na_clean() {
          std::cout << "========= pd_test_dt_bool_na: clean series =============";
          std::vector<numpy::datetime64> dates = {
              numpy::datetime64("2024-01-01"),
              numpy::datetime64("2024-01-31"),
              numpy::datetime64("2024-03-31"),
              numpy::datetime64("2024-12-31")
          };
          pandas::Series<numpy::datetime64> s(dates);
          pandas::DatetimeProperties<pandas::Series<numpy::datetime64>> dt(s);
          if (dt.has_nat()) throw std::runtime_error("has_nat should be false for clean series");
          auto ms = dt.is_month_start();
          if (ms[0] != true || ms[1] != false) throw std::runtime_error("is_month_start failed");
          auto me = dt.is_month_end();
          if (me[1] != true || me[0] != false) throw std::runtime_error("is_month_end failed");
          auto qs = dt.is_quarter_start();
          if (qs[0] != true || qs[1] != false) throw std::runtime_error("is_quarter_start failed");
          auto qe = dt.is_quarter_end();
          if (qe[2] != true || qe[0] != false) throw std::runtime_error("is_quarter_end failed");
          auto ys = dt.is_year_start();
          if (ys[0] != true || ys[1] != false) throw std::runtime_error("is_year_start failed");

.. _example-datetimeproperties-hour-24:

.. dropdown:: hour (pd_test_1_all.cpp:7476)
   :class-title: example-dropdown

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

          std::cout << "========= hour property ===============================";
      
          std::vector<std::optional<numpy::datetime64>> values = {
              make_dt(0),                    // Hour 0
              make_dt(6 * NS_PER_HOUR),      // Hour 6
              make_dt(23 * NS_PER_HOUR)      // Hour 23
          };
          pandas::DatetimeArray arr(values);
          pandas::DatetimeIndex idx(arr);
      
          auto hours = idx.hour();
      
          bool passed = (hours.size() == 3);
          auto h0 = hours[0];
          auto h1 = hours[1];
          auto h2 = hours[2];
          passed = passed && h0.has_value() && *h0 == 0;
          passed = passed && h1.has_value() && *h1 == 6;
          passed = passed && h2.has_value() && *h2 == 23;
      
          if (!passed) {

.. _example-datetimeproperties-isocalendar-25:

.. dropdown:: isocalendar (pd_test_3_all.cpp:22134)
   :class-title: example-dropdown

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

      }
      
      void test_dt_isocalendar() {
          std::cout << "========= dt.isocalendar =========================";
      
          std::vector<numpy::datetime64> dates = {
              numpy::datetime64("2023-01-15")
          };
          pandas::Series<numpy::datetime64> s(dates);
      
          auto iso = s.dt().isocalendar();
          if (iso.year.size() != 1 || iso.week.size() != 1 || iso.day.size() != 1) {
              throw std::runtime_error("dt.isocalendar: wrong size");
          }
          if (iso.year[0] != 2023) {
              throw std::runtime_error("dt.isocalendar: wrong year");
          }
      
          std::cout << " -> tests passed" << std::endl;
      }
      

.. _example-datetimeproperties-microsecond-26:

.. dropdown:: microsecond (pd_test_timestamp_scalar.cpp:45)
   :class-title: example-dropdown

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

            // Component constructor
            pandas::Timestamp ts1(2024, 6, 15, 14, 30, 45);
            if (ts1.year() != 2024 || ts1.month() != 6 || ts1.day() != 15 ||
                ts1.hour() != 14 || ts1.minute() != 30 || ts1.second() != 45) {
              pass = false;
              fail_msg = "Component constructor values incorrect";
            }
      
            // With microseconds and nanoseconds
            pandas::Timestamp ts2(2024, 1, 1, 12, 0, 0, 123456, 789);
            if (ts2.microsecond() != 123456 || ts2.nanosecond() != 789) {
              pass = false;
              fail_msg = "Microsecond/nanosecond values incorrect";
            }
      
            // String constructor - ISO format
            pandas::Timestamp ts3("2024-06-15T14:30:45");
            if (ts3.year() != 2024 || ts3.month() != 6 || ts3.day() != 15) {
              pass = false;
              fail_msg = "String constructor parse failed";
            }

.. _example-datetimeproperties-month-27:

.. dropdown:: month (pd_test_1_all.cpp:1180)
   :class-title: example-dropdown

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

          void pd_test_datetime_array_component_month_day() {
              std::cout << "========= DatetimeArray: month/day components ======================= ";
      
              pandas::DatetimeArray arr(std::vector<std::string>{
                  "2023-03-15",
                  "2023-12-25",
                  "NaT"
              });
      
              // Month
              auto months = arr.month();
              auto m0 = months[0];
              if (!m0.has_value() || m0.value() != 3) {
                  std::cout << "  [FAIL] : month[0] should be 3" << std::endl;
                  throw std::runtime_error("pd_test_datetime_array_component_month_day failed: month[0]");
              }
              auto m1 = months[1];
              if (!m1.has_value() || m1.value() != 12) {
                  std::cout << "  [FAIL] : month[1] should be 12" << std::endl;
                  throw std::runtime_error("pd_test_datetime_array_component_month_day failed: month[1]");
              }

.. _example-datetimeproperties-month_name-28:

.. dropdown:: month_name (pd_test_1_all.cpp:8454)
   :class-title: example-dropdown

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

      
      void pd_test_datetime_mixin_month_name() {
          std::cout << "========= month_name ==================================";
      
          std::vector<std::optional<numpy::datetime64>> values = {
              numpy::datetime64(0LL, numpy::DateTimeUnit::Nanosecond)  // 1970-01-01 = January
          };
          pandas::DatetimeArray arr(values);
          pandas::DatetimeMixinIndex idx(arr);
      
          std::vector<std::string> names = idx.month_name();
      
          bool passed = (names.size() == 1 && names[0] == "January");
          if (!passed) {
              std::cout << "  [FAIL] : in pd_test_datetime_mixin_month_name() got: " << names[0] << std::endl;
              throw std::runtime_error("pd_test_datetime_mixin_month_name failed");
          }
      
          std::cout << " -> tests passed" << std::endl;
      }
      

.. _example-datetimeproperties-nanosecond-29:

.. dropdown:: nanosecond (pd_test_timestamp_scalar.cpp:45)
   :class-title: example-dropdown

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

            // Component constructor
            pandas::Timestamp ts1(2024, 6, 15, 14, 30, 45);
            if (ts1.year() != 2024 || ts1.month() != 6 || ts1.day() != 15 ||
                ts1.hour() != 14 || ts1.minute() != 30 || ts1.second() != 45) {
              pass = false;
              fail_msg = "Component constructor values incorrect";
            }
      
            // With microseconds and nanoseconds
            pandas::Timestamp ts2(2024, 1, 1, 12, 0, 0, 123456, 789);
            if (ts2.microsecond() != 123456 || ts2.nanosecond() != 789) {
              pass = false;
              fail_msg = "Microsecond/nanosecond values incorrect";
            }
      
            // String constructor - ISO format
            pandas::Timestamp ts3("2024-06-15T14:30:45");
            if (ts3.year() != 2024 || ts3.month() != 6 || ts3.day() != 15) {
              pass = false;
              fail_msg = "String constructor parse failed";
            }

.. _example-datetimeproperties-normalize-30:

.. dropdown:: normalize (pd_test_1_all.cpp:8723)
   :class-title: example-dropdown

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

      void pd_test_datetime_mixin_normalize() {
          std::cout << "========= normalize ===================================";
      
          // Create datetime with time component
          std::vector<std::optional<numpy::datetime64>> values = {
              numpy::datetime64(86400000000000LL + 3600000000000LL, numpy::DateTimeUnit::Nanosecond)  // 1 day + 1 hour
          };
          pandas::DatetimeArray arr(values);
          pandas::DatetimeMixinIndex idx(arr);
      
          pandas::DatetimeMixinIndex normalized = idx.normalize();
      
          bool passed = (normalized.size() == 1);
          if (!passed) {
              std::cout << "  [FAIL] : in pd_test_datetime_mixin_normalize()" << std::endl;
              throw std::runtime_error("pd_test_datetime_mixin_normalize failed");
          }
      
          std::cout << " -> tests passed" << std::endl;
      }
      

.. _example-datetimeproperties-quarter-31:

.. dropdown:: quarter (pd_test_1_all.cpp:1218)
   :class-title: example-dropdown

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

          void pd_test_datetime_array_quarter() {
              std::cout << "========= DatetimeArray: quarter ======================= ";
      
              pandas::DatetimeArray arr(std::vector<std::string>{
                  "2023-01-15",  // Q1
                  "2023-05-20",  // Q2
                  "2023-09-10",  // Q3
                  "2023-11-25"   // Q4
              });
      
              auto quarters = arr.quarter();
      
              auto q0 = quarters[0];
              if (!q0.has_value() || q0.value() != 1) {
                  std::cout << "  [FAIL] : quarter[0] should be 1" << std::endl;
                  throw std::runtime_error("pd_test_datetime_array_quarter failed: quarter[0]");
              }
              auto q1 = quarters[1];
              if (!q1.has_value() || q1.value() != 2) {
                  std::cout << "  [FAIL] : quarter[1] should be 2" << std::endl;
                  throw std::runtime_error("pd_test_datetime_array_quarter failed: quarter[1]");

.. _example-datetimeproperties-round-32:

.. dropdown:: round (pd_test_1_all.cpp:1688)
   :class-title: example-dropdown

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

      
          void pd_test_floating_array_rounding() {
              std::cout << "========= FloatingArray: rounding ======================= ";
      
              pandas::FloatingArray<double> arr({
                  std::optional<double>(1.234),
                  std::optional<double>(2.567),
                  std::nullopt
              });
      
              auto rounded = arr.round(2);
              if (std::abs(rounded[0].value() - 1.23) > 0.001 ||
                  std::abs(rounded[1].value() - 2.57) > 0.001) {
                  std::cout << "  [FAIL] : in pd_test_floating_array_rounding() : round(2)" << std::endl;
                  throw std::runtime_error("pd_test_floating_array_rounding failed: round(2)");
              }
      
              if (!rounded.is_na(2)) {
                  std::cout << "  [FAIL] : in pd_test_floating_array_rounding() : round should preserve NA" << std::endl;
                  throw std::runtime_error("pd_test_floating_array_rounding failed: NA preservation");
              }

.. _example-datetimeproperties-s-33:

.. dropdown:: s (pd_test_1_all.cpp:4524)
   :class-title: example-dropdown

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

      #include <vector>
      #include "../pandas/pd_dataframe.h"
      #include "../pandas/pd_series.h"
      
      namespace dataframe_tests {
          namespace dataframe_tests_aggregation {
      
              void pd_test_aggregation_series_sem() {
                  std::cout << "========= Series sem ============================";
      
                  pandas::Series<double> s({1.0, 2.0, 3.0, 4.0, 5.0});
                  auto sem_val = s.sem();
                  // std(ddof=1) = sqrt(2.5), sem = sqrt(2.5)/sqrt(5) ≈ 0.707
                  bool passed = sem_val.has_value() && std::abs(*sem_val - 0.707) < 0.01;
                  if (!passed) {
                      std::cout << "  [FAIL] : in pd_test_aggregation_series_sem() : sem value incorrect" << std::endl;
                      throw std::runtime_error("pd_test_aggregation_series_sem failed: sem value incorrect");
                  }
      
                  std::cout << " -> tests passed" << std::endl;
              }

.. _example-datetimeproperties-second-34:

.. dropdown:: second (pd_test_1_all.cpp:7534)
   :class-title: example-dropdown

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

          std::cout << "========= second property =============================";
      
          std::vector<std::optional<numpy::datetime64>> values = {
              make_dt(0),                    // Second 0
              make_dt(30 * NS_PER_SEC),      // Second 30
              make_dt(59 * NS_PER_SEC)       // Second 59
          };
          pandas::DatetimeArray arr(values);
          pandas::DatetimeIndex idx(arr);
      
          auto seconds = idx.second();
      
          bool passed = (seconds.size() == 3);
          auto s0 = seconds[0];
          auto s1 = seconds[1];
          auto s2 = seconds[2];
          passed = passed && s0.has_value() && *s0 == 0;
          passed = passed && s1.has_value() && *s1 == 30;
          passed = passed && s2.has_value() && *s2 == 59;
      
          if (!passed) {

.. _example-datetimeproperties-strftime-35:

.. dropdown:: strftime (pd_test_1_all.cpp:8434)
   :class-title: example-dropdown

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

      void pd_test_datetime_mixin_strftime() {
          std::cout << "========= strftime ====================================";
      
          std::vector<std::optional<numpy::datetime64>> values = {
              numpy::datetime64(0LL, numpy::DateTimeUnit::Nanosecond),  // 1970-01-01
              numpy::datetime64(86400000000000LL, numpy::DateTimeUnit::Nanosecond)  // 1970-01-02
          };
          pandas::DatetimeArray arr(values);
          pandas::DatetimeMixinIndex idx(arr);
      
          std::vector<std::string> formatted = idx.strftime("%Y-%m-%d");
      
          bool passed = (formatted.size() == 2 && !formatted[0].empty() && !formatted[1].empty());
          if (!passed) {
              std::cout << "  [FAIL] : in pd_test_datetime_mixin_strftime()" << std::endl;
              throw std::runtime_error("pd_test_datetime_mixin_strftime failed");
          }
      
          std::cout << " -> tests passed" << std::endl;
      }
      

.. _example-datetimeproperties-time-36:

.. dropdown:: time (pd_test_timestamp_scalar.cpp:535)
   :class-title: example-dropdown

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

            if (posix <= 0) { pass = false; fail_msg = "POSIX timestamp should be positive"; }
      
            // timetuple
            auto [y, mo, d, h, mi, s] = ts.timetuple();
            if (y != 2024 || mo != 6) { pass = false; fail_msg = "timetuple values incorrect"; }
      
            // date/time tuples
            auto [dy, dm, dd] = ts.date();
            if (dy != 2024) { pass = false; fail_msg = "date tuple year"; }
      
            auto [th, tmi, ts2, tus] = ts.time();
            if (th != 12) { pass = false; fail_msg = "time tuple hour"; }
      
            // Julian date
            double jd = ts.to_julian_date();
            if (jd < 2400000) { pass = false; fail_msg = "Julian date should be reasonable"; }
      
            // Ordinal
            int ord = ts.toordinal();
            if (ord <= 0) { pass = false; fail_msg = "Ordinal should be positive"; }
      

.. _example-datetimeproperties-timetz-37:

.. dropdown:: timetz (pd_test_timestamp_scalar.cpp:1042)
   :class-title: example-dropdown

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

            // Test 3: utctimetuple() - returns (year, month, day, hour, minute, second) in UTC
            pandas::Timestamp ts_utc(2024, 6, 15, 14, 30, 45, 0, 0, "UTC");
            auto utc_tuple = ts_utc.utctimetuple();
            if (pass && std::get<0>(utc_tuple) != 2024) { pass = false; fail_msg = "utctimetuple year mismatch"; }
            if (pass && std::get<1>(utc_tuple) != 6) { pass = false; fail_msg = "utctimetuple month mismatch"; }
            if (pass && std::get<2>(utc_tuple) != 15) { pass = false; fail_msg = "utctimetuple day mismatch"; }
            if (pass && std::get<3>(utc_tuple) != 14) { pass = false; fail_msg = "utctimetuple hour mismatch"; }
            if (pass && std::get<4>(utc_tuple) != 30) { pass = false; fail_msg = "utctimetuple minute mismatch"; }
            if (pass && std::get<5>(utc_tuple) != 45) { pass = false; fail_msg = "utctimetuple second mismatch"; }
      
            // Test 4: timetz() - returns (hour, minute, second, microsecond, tz_offset_seconds)
            pandas::Timestamp ts_tz(2024, 6, 15, 14, 30, 45, 123456, 0, "UTC");
            auto time_tuple = ts_tz.timetz();
            if (pass && std::get<0>(time_tuple) != 14) { pass = false; fail_msg = "timetz hour mismatch"; }
            if (pass && std::get<1>(time_tuple) != 30) { pass = false; fail_msg = "timetz minute mismatch"; }
            if (pass && std::get<2>(time_tuple) != 45) { pass = false; fail_msg = "timetz second mismatch"; }
            if (pass && std::get<3>(time_tuple) != 123456) { pass = false; fail_msg = "timetz microsecond mismatch"; }
            // UTC offset should be 0 for UTC timezone
            if (pass && std::get<4>(time_tuple) != 0) { pass = false; fail_msg = "timetz UTC offset should be 0, got " + std::to_string(std::get<4>(time_tuple)); }
      
            if (!pass) {

.. _example-datetimeproperties-tz-38:

.. dropdown:: tz (pd_test_2_all.cpp:17914)
   :class-title: example-dropdown

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

                  pandas::DataFrame df(data);
                  df.set_index(std::make_unique<pandas::DatetimeIndex>(tz_aware_idx));
      
                  // Verify the index is timezone-aware
                  const pandas::DatetimeIndex* original_idx = dynamic_cast<const pandas::DatetimeIndex*>(&df.index());
                  if (!original_idx) {
                      std::cout << "  [FAIL] : in pd_test_tz_convert_basic() : index is not DatetimeIndex" << std::endl;
                      throw std::runtime_error("pd_test_tz_convert_basic failed: index is not DatetimeIndex");
                  }
      
                  std::string original_tz = original_idx->tz();
                  if (original_tz.empty()) {
                      std::cout << "  [FAIL] : in pd_test_tz_convert_basic() : original index is not timezone-aware" << std::endl;
                      throw std::runtime_error("pd_test_tz_convert_basic failed: original index is not timezone-aware");
                  }
      
                  // Convert to Asia/Shanghai timezone
                  pandas::DataFrame df_shanghai = df.tz_convert("Asia/Shanghai");
      
                  // Verify result has a DatetimeIndex
                  const pandas::DatetimeIndex* converted_idx = dynamic_cast<const pandas::DatetimeIndex*>(&df_shanghai.index());

.. _example-datetimeproperties-unit-39:

.. dropdown:: unit (pd_test_1_all.cpp:9284)
   :class-title: example-dropdown

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

          data.setElementAt({0}, numpy::datetime64(1000LL, numpy::DateTimeUnit::Nanosecond));
          data.setElementAt({1}, numpy::datetime64(2000LL, numpy::DateTimeUnit::Nanosecond));
      
          numpy::NDArray<numpy::bool_> mask(std::vector<size_t>{2});
          mask.setElementAt({0}, numpy::bool_(false));
          mask.setElementAt({1}, numpy::bool_(false));
      
          pandas::DatetimeArray arr(data, mask);
          pandas::DatetimeTDMixin idx(arr);
      
          std::string unit = idx.unit();
      
          bool passed = (unit == "ns");  // nanosecond
          if (!passed) {
              std::cout << "  [FAIL] : in pd_test_datetime_unit_property() : unit property check failed, got '" << unit << "'" << std::endl;
              throw std::runtime_error("pd_test_datetime_unit_property failed");
          }
      
          std::cout << " -> tests passed" << std::endl;
      }
      

.. _example-datetimeproperties-week-40:

.. dropdown:: week (pd_test_timestamp_scalar.cpp:406)
   :class-title: example-dropdown

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

            // 2024-06-15 is a Saturday
            pandas::Timestamp ts(2024, 6, 15);
      
            if (ts.dayofweek() != 5) { pass = false; fail_msg = "2024-06-15 should be Saturday (5)"; }
            if (ts.day_of_week() != 5) { pass = false; fail_msg = "day_of_week alias"; }
            if (ts.dayofyear() != 167) { pass = false; fail_msg = "2024-06-15 should be day 167"; }
            if (ts.day_of_year() != 167) { pass = false; fail_msg = "day_of_year alias"; }
            if (ts.quarter() != 2) { pass = false; fail_msg = "June is Q2"; }
            if (ts.days_in_month() != 30) { pass = false; fail_msg = "June has 30 days"; }
      
            int week = ts.week();
            if (week < 1 || week > 53) { pass = false; fail_msg = "week should be 1-53"; }
      
            if (!pass) {
              std::cout << "  [FAIL] : in np_test_timestamp_derived() : " << fail_msg;
              throw std::runtime_error("np_test_timestamp_derived failed: " + fail_msg);
            }
      
            std::cout << " -> tests passed" << std::endl;
          }
      

.. _example-datetimeproperties-wrap_int_result-41:

.. dropdown:: wrap_int_result (pd_test_3_all.cpp:25102)
   :class-title: example-dropdown

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

      
      void pd_test_dt_bool_na_name_preserve() {
          std::cout << "========= pd_test_dt_bool_na: name preservation ========";
          std::vector<numpy::datetime64> dates = {
              numpy::datetime64("2024-01-01"),
              numpy::datetime64("2024-06-15")
          };
          pandas::Series<numpy::datetime64> s(dates);
          s.set_name("test_dates");
          pandas::DatetimeProperties<pandas::Series<numpy::datetime64>> dt(s);
          auto year_series = dt.wrap_int_result(dt.year());
          if (!year_series.name().has_value() || year_series.name().value() != "test_dates")
              throw std::runtime_error("name not preserved through wrap_int_result");
          std::cout << " -> tests passed" << std::endl;
      }
      
      int pd_test_dt_bool_na_main() {
          std::cout << "====================================== running pd_test_dt_bool_na ==================================== " << std::endl;
          try {
              pd_test_dt_bool_na_clean();
              pd_test_dt_bool_na_with_nat();

.. _example-datetimeproperties-year-42:

.. dropdown:: year (pd_test_1_all.cpp:1147)
   :class-title: example-dropdown

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

      
          void pd_test_datetime_array_component_year() {
              std::cout << "========= DatetimeArray: year component ======================= ";
      
              pandas::DatetimeArray arr(std::vector<std::string>{
                  "2020-01-15",
                  "NaT",
                  "2025-06-20"
              });
      
              auto years = arr.year();
      
              auto y0 = years[0];
              if (!y0.has_value() || y0.value() != 2020) {
                  std::cout << "  [FAIL] : year[0] should be 2020" << std::endl;
                  throw std::runtime_error("pd_test_datetime_array_component_year failed: year[0]");
              }
      
              auto y1 = years[1];
              if (y1.has_value()) {
                  std::cout << "  [FAIL] : year[1] should be NA (NaT)" << std::endl;