Period
======

.. cpp:class:: pandas::Period

   Scalar type representing a single value.

Example
-------

.. code-block:: cpp

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

   // Use Period
   Period obj;
   // ... operations ...

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

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

   * - Signature
     - Location
     - Example
   * - ``Period(int64_t ordinal, const std::string& freq)``
     - pd_period.h:74
     - 
   * - ``Period(const std::string& value, const std::string& freq)``
     - pd_period.h:92
     - 

Statistics
----------

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

   * - Signature
     - Return Type
     - Location
     - Example
   * - ``int minute() const``
     - int
     - pd_period.h:227
     - :ref:`View <example-period-minute-0>`

Arithmetic
----------

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

   * - Signature
     - Return Type
     - Location
     - Example
   * - ``Period add_ordinals(int64_t n) const``
     - Period
     - pd_period.h:480
     - 

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

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

   * - Signature
     - Return Type
     - Location
     - Example
   * - ``Period asfreq(const std::string& freq, const std::string& how = "E") const``
     - Period
     - pd_period.h:317
     - :ref:`View <example-period-asfreq-1>`
   * - ``pandas::Timestamp to_timestamp(const std::string& freq = "", const std::string& how = "start") const``
     - pandas::Timestamp
     - pd_period.h:381
     - :ref:`View <example-period-to_timestamp-2>`

Iteration
---------

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

   * - Signature
     - Return Type
     - Location
     - Example
   * - ``pandas::Timestamp end_time() const``
     - pandas::Timestamp
     - pd_period.h:407
     - :ref:`View <example-period-end_time-3>`

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

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

   * - Signature
     - Return Type
     - Location
     - Example
   * - ``bool is_leap_year() const``
     - bool
     - pd_period.h:302
     - :ref:`View <example-period-is_leap_year-4>`

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

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

   * - Signature
     - Return Type
     - Location
     - Example
   * - ``static Period NaT(const std::string& freq = "D")``
     - static Period
     - pd_period.h:160
     - :ref:`View <example-period-nat-5>`
   * - ``int day() const``
     - int
     - pd_period.h:211
     - :ref:`View <example-period-day-6>`
   * - ``int day_of_week() const { return dayofweek()``
     - int
     - pd_period.h:256
     - :ref:`View <example-period-day_of_week-7>`
   * - ``int day_of_year() const { return dayofyear()``
     - int
     - pd_period.h:266
     - :ref:`View <example-period-day_of_year-8>`
   * - ``int dayofweek() const``
     - int
     - pd_period.h:251
     - :ref:`View <example-period-dayofweek-9>`
   * - ``int dayofyear() const``
     - int
     - pd_period.h:261
     - :ref:`View <example-period-dayofyear-10>`
   * - ``int days_in_month() const``
     - int
     - pd_period.h:290
     - :ref:`View <example-period-days_in_month-11>`
   * - ``days_since_epoch_to_date(days, y, m, d)``
     - 
     - pd_period.h:352
     - 
   * - ``PeriodFrequency freq() const``
     - PeriodFrequency
     - pd_period.h:181
     - :ref:`View <example-period-freq-12>`
   * - ``int64_t freq_multiplier() const``
     - int64_t
     - pd_period.h:489
     - 
   * - ``static int64_t freq_to_nanos(PeriodFrequency freq)``
     - static int64_t
     - pd_period.h:466
     - 
   * - ``std::string freqstr() const``
     - std::string
     - pd_period.h:176
     - :ref:`View <example-period-freqstr-13>`
   * - ``int hour() const``
     - int
     - pd_period.h:219
     - :ref:`View <example-period-hour-14>`
   * - ``bool isNaT() const``
     - bool
     - pd_period.h:186
     - :ref:`View <example-period-isnat-15>`
   * - ``int month() const``
     - int
     - pd_period.h:203
     - :ref:`View <example-period-month-16>`
   * - ``static Period now(const std::string& freq = "D", const std::string& tz = "")``
     - static Period
     - pd_period.h:129
     - :ref:`View <example-period-now-17>`
   * - ``int64_t ordinal() const``
     - int64_t
     - pd_period.h:171
     - :ref:`View <example-period-ordinal-18>`
   * - ``int quarter() const``
     - int
     - pd_period.h:243
     - :ref:`View <example-period-quarter-19>`
   * - ``int qyear() const``
     - int
     - pd_period.h:281
     - :ref:`View <example-period-qyear-20>`
   * - ``std::string repr() const``
     - std::string
     - pd_period.h:450
     - :ref:`View <example-period-repr-21>`
   * - ``int second() const``
     - int
     - pd_period.h:235
     - :ref:`View <example-period-second-22>`
   * - ``pandas::Timestamp start_time() const``
     - pandas::Timestamp
     - pd_period.h:400
     - :ref:`View <example-period-start_time-23>`
   * - ``std::string strftime(const std::string& date_format) const``
     - std::string
     - pd_period.h:428
     - :ref:`View <example-period-strftime-24>`
   * - ``std::string toString() const``
     - std::string
     - pd_period.h:418
     - :ref:`View <example-period-tostring-25>`
   * - ``int week() const``
     - int
     - pd_period.h:271
     - :ref:`View <example-period-week-26>`
   * - ``int weekofyear() const { return week()``
     - int
     - pd_period.h:276
     - 
   * - ``int year() const``
     - int
     - pd_period.h:195
     - :ref:`View <example-period-year-27>`


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

The following examples are extracted from the test suite.

.. _example-period-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-period-asfreq-1:

.. dropdown:: asfreq (pd_test_1_all.cpp:2869)
   :class-title: example-dropdown

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

              std::cout << "========= PeriodArray: asfreq ======================= ";
      
              // Monthly to quarterly
              pandas::PeriodArray arr_m(std::vector<std::string>{
                  "2024-01",
                  "2024-04",
                  "2024-07",
                  "NaT"
              }, "M");
      
              auto arr_q = arr_m.asfreq("Q");
              if (arr_q.size() != 4) {
                  std::cout << "  [FAIL] : asfreq size should be 4" << std::endl;
                  throw std::runtime_error("pd_test_period_array_asfreq failed: size");
              }
              if (arr_q.freqstr() != "Q") {
                  std::cout << "  [FAIL] : asfreq freqstr should be 'Q'" << std::endl;
                  throw std::runtime_error("pd_test_period_array_asfreq failed: freqstr");
              }
      
              // Check NaT is preserved

.. _example-period-to_timestamp-2:

.. dropdown:: to_timestamp (pd_test_1_all.cpp:2830)
   :class-title: example-dropdown

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

          void pd_test_period_array_to_timestamp() {
              std::cout << "========= PeriodArray: to_timestamp ======================= ";
      
              pandas::PeriodArray arr(std::vector<std::string>{
                  "2024-01",
                  "2024-06",
                  "NaT"
              }, "M");
      
              // to_timestamp with start
              auto ts_start = arr.to_timestamp("start");
              if (ts_start.size() != 3) {
                  std::cout << "  [FAIL] : to_timestamp size should be 3" << std::endl;
                  throw std::runtime_error("pd_test_period_array_to_timestamp failed: size");
              }
      
              auto ts0 = ts_start[0];
              if (!ts0.has_value()) {
                  std::cout << "  [FAIL] : ts_start[0] should have value" << std::endl;
                  throw std::runtime_error("pd_test_period_array_to_timestamp failed: ts_start[0]");
              }

.. _example-period-end_time-3:

.. dropdown:: end_time (pd_test_1_all.cpp:17146)
   :class-title: example-dropdown

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

      
          std::cout << " -> tests passed" << std::endl;
      }
      
      void pd_test_period_index_end_time() {
          std::cout << "========= end_time property ===========================";
      
          std::vector<int64_t> ordinals = {0};  // 1970-01-01 daily period
          pandas::PeriodIndex idx = pandas::PeriodIndex::from_ordinals(ordinals, "D");
      
          pandas::DatetimeArray end_times = idx.end_time();
      
          bool passed = (end_times.size() == 1 && !end_times.is_na(0));
          if (!passed) {
              std::cout << "  [FAIL] : in pd_test_period_index_end_time()" << std::endl;
              throw std::runtime_error("pd_test_period_index_end_time failed");
          }
      
          std::cout << " -> tests passed" << std::endl;
      }
      

.. _example-period-is_leap_year-4:

.. 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-period-nat-5:

.. dropdown:: NaT (pd_test_1_all.cpp:1305)
   :class-title: example-dropdown

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

      
              pandas::DatetimeArray arr(std::vector<std::string>{
                  "2023-06-15",
                  "NaT",
                  "2023-01-01",
                  "2023-12-31"
              });
      
              // argsort ascending
              auto indices = arr.argsort(true, "last");
              // Expected order: 2023-01-01(2), 2023-06-15(0), 2023-12-31(3), NaT(1)
              if (indices.getElementAt({0}) != 2) {
                  std::cout << "  [FAIL] : argsort: first should be index 2 (2023-01-01)" << std::endl;
                  throw std::runtime_error("pd_test_datetime_array_sorting failed: argsort first");
              }
              if (indices.getElementAt({3}) != 1) {
                  std::cout << "  [FAIL] : argsort: last should be index 1 (NaT)" << std::endl;
                  throw std::runtime_error("pd_test_datetime_array_sorting failed: NaT position");
              }
      
              // argmin

.. _example-period-day-6:

.. 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-period-day_of_week-7:

.. dropdown:: day_of_week (pd_test_3_all.cpp:22018)
   :class-title: example-dropdown

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

      void test_dt_aliases() {
          std::cout << "========= dt accessor aliases ====================";
      
          std::vector<numpy::datetime64> dates = {
              numpy::datetime64("2023-01-15"),
              numpy::datetime64("2023-06-20")
          };
          pandas::Series<numpy::datetime64> s(dates);
      
          auto dow1 = s.dt().dayofweek();
          auto dow2 = s.dt().day_of_week();
          auto dow3 = s.dt().weekday();
      
          if (dow1[0] != dow2[0] || dow1[0] != dow3[0]) {
              throw std::runtime_error("dt aliases: dayofweek/day_of_week/weekday mismatch");
          }
      
          auto doy1 = s.dt().dayofyear();
          auto doy2 = s.dt().day_of_year();
      
          if (doy1[0] != doy2[0]) {

.. _example-period-day_of_year-8:

.. dropdown:: day_of_year (pd_test_3_all.cpp:22026)
   :class-title: example-dropdown

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

      
          auto dow1 = s.dt().dayofweek();
          auto dow2 = s.dt().day_of_week();
          auto dow3 = s.dt().weekday();
      
          if (dow1[0] != dow2[0] || dow1[0] != dow3[0]) {
              throw std::runtime_error("dt aliases: dayofweek/day_of_week/weekday mismatch");
          }
      
          auto doy1 = s.dt().dayofyear();
          auto doy2 = s.dt().day_of_year();
      
          if (doy1[0] != doy2[0]) {
              throw std::runtime_error("dt aliases: dayofyear/day_of_year mismatch");
          }
      
          std::cout << " -> tests passed" << std::endl;
      }
      
      void test_dt_days_in_month() {
          std::cout << "========= dt.days_in_month ======================";

.. _example-period-dayofweek-9:

.. 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-period-dayofyear-10:

.. 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-period-days_in_month-11:

.. 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-period-freq-12:

.. 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-period-freqstr-13:

.. dropdown:: freqstr (pd_test_1_all.cpp:2671)
   :class-title: example-dropdown

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

              }
      
              pandas::PeriodDtype dtype_y("Y");
              if (dtype_y.name() != "period[Y]") {
                  std::cout << "  [FAIL] : dtype_y.name() should be 'period[Y]'" << std::endl;
                  throw std::runtime_error("pd_test_period_array_freq_validation failed: dtype name Y");
              }
      
              // Test frequency string
              pandas::PeriodArray arr(std::vector<std::string>{"2024-01-15"}, "D");
              if (arr.freqstr() != "D") {
                  std::cout << "  [FAIL] : arr.freqstr() should be 'D'" << std::endl;
                  throw std::runtime_error("pd_test_period_array_freq_validation failed: freqstr");
              }
      
              std::cout << " -> tests passed" << std::endl;
          }
      
          void pd_test_period_array_year_month_quarter() {
              std::cout << "========= PeriodArray: year/month/quarter components ======================= ";
      

.. _example-period-hour-14:

.. 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-period-isnat-15:

.. dropdown:: isNaT (pd_test_3_all.cpp:1523)
   :class-title: example-dropdown

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

          }
      
          // Case B: pandas::Timedelta == pandas::Timedelta
          {
              static_assert(std::is_same_v<pandas::Timedelta, pandas::Timedelta>,
                            "pandas::Timedelta must alias pandas::Timedelta");
          }
      
          // Case C: pandas::NaT is a NaT-valued Timestamp
          {
              if (!pandas::NaT.isNaT()) {
                  throw std::runtime_error("pandas::NaT is not a NaT value");
              }
              pandas::Timestamp default_ts;
              if (default_ts.isNaT() != pandas::NaT.isNaT()) {
                  throw std::runtime_error(
                      "pandas::NaT and default Timestamp NaT-state mismatch");
              }
          }
      
          // Case D: round-trip - reproduces the failing test pattern

.. _example-period-month-16:

.. 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-period-now-17:

.. dropdown:: now (pd_test_3_all.cpp:20077)
   :class-title: example-dropdown

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

          bool passed = months_default[0] == "June" && days_default[0] == "Monday";
          if (!passed) {
              std::cout << "  [FAIL] : in pd_test_name_locale_params()" << std::endl;
              throw std::runtime_error("pd_test_name_locale_params failed");
          }
      
          std::cout << " -> tests passed" << std::endl;
      }
      
      // ============================================================================
      // Test Period.now() with tz parameter
      // ============================================================================
      
      void pd_test_period_now_tz() {
          std::cout << "========= Period.now(tz) ================================";
      
          // Test now() with default (local time)
          auto p_local = pandas::Period::now("D");
      
          // Test now() with UTC timezone
          auto p_utc = pandas::Period::now("D", "UTC");

.. _example-period-ordinal-18:

.. dropdown:: ordinal (pd_test_5_all.cpp:41796)
   :class-title: example-dropdown

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

          std::cout << "----- case_11_period_nat_sentinel_api_self_check -----\n";
          pandas::Period nat1 = pandas::Period::NaT("D");
          pandas::Period nat2;  // default ctor = NaT
          pandas::Period real(123, std::string("D"));
      
          pandas_tests::check(nat1.isNaT(), "case11.NaT_factory_isNaT", local_fail);
          pandas_tests::check(nat2.isNaT(),
                              "case11.default_ctor_isNaT", local_fail);
          pandas_tests::check(!real.isNaT(),
                              "case11.real_period_is_NOT_NaT", local_fail);
          pandas_tests::check(nat1.ordinal() == pandas::PERIOD_NAT,
                              "case11.NaT_ordinal_equals_PERIOD_NAT_sentinel", local_fail);
          pandas_tests::check(real.ordinal() == 123,
                              "case11.real_period_ordinal_value", local_fail);
      
          std::cout << "  NaT.ordinal=" << nat1.ordinal()
                    << " PERIOD_NAT=" << pandas::PERIOD_NAT
                    << " real.ordinal=" << real.ordinal() << "\n";
      }
      
      void case_12_period_oracle_parity_subset(int& local_fail) {

.. _example-period-quarter-19:

.. 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-period-qyear-20:

.. dropdown:: qyear (pd_test_1_all.cpp:17092)
   :class-title: example-dropdown

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

      // ============================================================================
      
      void pd_test_period_index_qyear() {
          std::cout << "========= qyear property ==============================";
      
          // Monthly periods in Q1 2020
          std::vector<int> years = {2020, 2020, 2020};
          std::vector<int> months = {1, 2, 3};
          pandas::PeriodIndex idx = pandas::PeriodIndex::from_fields(years, months, {}, {}, {}, {}, "M");
      
          pandas::IntegerArray<numpy::int32> qyears = idx.qyear();
      
          bool passed = (qyears.size() == 3 &&
                         qyears[0].has_value() && *qyears[0] == 2020 &&
                         qyears[1].has_value() && *qyears[1] == 2020 &&
                         qyears[2].has_value() && *qyears[2] == 2020);
          if (!passed) {
              std::cout << "  [FAIL] : in pd_test_period_index_qyear()" << std::endl;
              throw std::runtime_error("pd_test_period_index_qyear failed");
          }
      

.. _example-period-repr-21:

.. dropdown:: repr (pd_test_1_all.cpp:10906)
   :class-title: example-dropdown

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

          std::cout << " -> tests passed" << std::endl;
      }
      
      void pd_test_extension_index_repr() {
          std::cout << "========= repr =========================";
      
          pandas::CategoricalArray arr({"a", "b", "c"});
          // Use ExtensionIndex<CategoricalArray> directly to test base class repr
          pandas::ExtensionIndex<pandas::CategoricalArray> idx(arr, "test");
      
          std::string repr_str = idx.repr();
      
          bool passed = (!repr_str.empty() && repr_str.find("ExtensionIndex") != std::string::npos);
          if (!passed) {
              std::cout << "  [FAIL] : in pd_test_extension_index_repr() : repr check failed" << std::endl;
              throw std::runtime_error("pd_test_extension_index_repr failed");
          }
      
          std::cout << " -> tests passed" << std::endl;
      }
      

.. _example-period-second-22:

.. 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-period-start_time-23:

.. dropdown:: start_time (pd_test_1_all.cpp:2848)
   :class-title: example-dropdown

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

                  std::cout << "  [FAIL] : ts_start[0] should have value" << std::endl;
                  throw std::runtime_error("pd_test_period_array_to_timestamp failed: ts_start[0]");
              }
      
              auto ts2 = ts_start[2];
              if (ts2.has_value()) {
                  std::cout << "  [FAIL] : ts_start[2] should be NaT" << std::endl;
                  throw std::runtime_error("pd_test_period_array_to_timestamp failed: ts_start[2]");
              }
      
              // start_time() alias
              auto start_times = arr.start_time();
              if (start_times.size() != 3) {
                  std::cout << "  [FAIL] : start_time size should be 3" << std::endl;
                  throw std::runtime_error("pd_test_period_array_to_timestamp failed: start_time size");
              }
      
              std::cout << " -> tests passed" << std::endl;
          }
      
          void pd_test_period_array_asfreq() {

.. _example-period-strftime-24:

.. 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-period-tostring-25:

.. dropdown:: toString (pd_test_1_all.cpp:9539)
   :class-title: example-dropdown

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

      
      void pd_test_timedelta_rounding_params() {
          std::cout << "========= Timedelta rounding with DST params =====";
      
          // Create a Timedelta: 1h 30m 45s
          // Constructor is: (days, hours, minutes, seconds, ...)
          pandas::Timedelta td(0, 1, 30, 45);  // 0 days, 1h, 30m, 45s
      
          // Test floor with ambiguous/nonexistent params
          pandas::Timedelta floored = td.floor("h", "raise", "raise");
          std::cout << std::endl << "  floor('h'): " << floored.toString();
      
          // Test ceil with ambiguous/nonexistent params
          pandas::Timedelta ceiled = td.ceil("h", "raise", "raise");
          std::cout << std::endl << "  ceil('h'): " << ceiled.toString();
      
          // Test round with ambiguous/nonexistent params
          pandas::Timedelta rounded = td.round("h", "raise", "raise");
          std::cout << std::endl << "  round('h'): " << rounded.toString();
      
          // Verify results:

.. _example-period-week-26:

.. 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-period-year-27:

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