MixedTzDatetimeArray
====================

.. cpp:class:: pandas::MixedTzDatetimeArray

   pandas C++ class.

Example
-------

.. code-block:: cpp

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

   // Use MixedTzDatetimeArray
   MixedTzDatetimeArray obj;
   // ... operations ...

Construction
------------

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

   * - Signature
     - Return Type
     - Location
     - Example
   * - ``static MixedTzDatetimeArray from_timestamps( const std::vector<std::optional<Timestamp>>& vec)``
     - static MixedTzDatetimeArray
     - pd_mixed_tz_datetime_array.h:82
     - :ref:`View <example-mixedtzdatetimearray-from_timestamps-0>`

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

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

   * - Signature
     - Return Type
     - Location
     - Example
   * - ``const numpy::NDArray<numpy::bool_>& mask() const``
     - const numpy::NDArray<numpy::bool_>&
     - pd_mixed_tz_datetime_array.h:153
     - :ref:`View <example-mixedtzdatetimearray-mask-1>`

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

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

   * - Signature
     - Return Type
     - Location
     - Example
   * - ``bool is_na(size_t i) const``
     - bool
     - pd_mixed_tz_datetime_array.h:115
     - :ref:`View <example-mixedtzdatetimearray-is_na-2>`

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

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

   * - Signature
     - Return Type
     - Location
     - Example
   * - ``const numpy::NDArray<int64_t>& data() const``
     - const numpy::NDArray<int64_t>&
     - pd_mixed_tz_datetime_array.h:152
     - :ref:`View <example-mixedtzdatetimearray-data-3>`
   * - ``std::string dtype() const``
     - std::string
     - pd_mixed_tz_datetime_array.h:143
     - :ref:`View <example-mixedtzdatetimearray-dtype-4>`
   * - ``const std::vector<std::string>& element_tz() const``
     - const std::vector<std::string>&
     - pd_mixed_tz_datetime_array.h:130
     - 
   * - ``const std::string& element_tz_at(size_t i) const``
     - const std::string&
     - pd_mixed_tz_datetime_array.h:124
     - :ref:`View <example-mixedtzdatetimearray-element_tz_at-5>`
   * - ``int64_t ns_at(size_t i) const``
     - int64_t
     - pd_mixed_tz_datetime_array.h:119
     - 
   * - ``size_t size() const { return data_.getSize()``
     - size_t
     - pd_mixed_tz_datetime_array.h:113
     - :ref:`View <example-mixedtzdatetimearray-size-6>`
   * - ``numpy::DateTimeUnit unit() const``
     - numpy::DateTimeUnit
     - pd_mixed_tz_datetime_array.h:146
     - :ref:`View <example-mixedtzdatetimearray-unit-7>`

Internal Methods
----------------

*1 internal methods (prefixed with underscore)*


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

The following examples are extracted from the test suite.

.. _example-mixedtzdatetimearray-from_timestamps-0:

.. dropdown:: from_timestamps (pd_test_extension_array.cpp:9)
   :class-title: example-dropdown

   .. code-block:: cpp
      :linenos:
      :lineno-start: 1
      :emphasize-lines: 9

      // pd_test_extension_array.cpp — L3 step L3.15 + Fix A storage-flip extensions
      //
      // Storage invariants and round-trip integrity for pandas::DatetimeArray and
      // pandas::TimedeltaArray after the Fix A storage flip
      // (do/plan_L3_fix_a_storage_flip.md, applied 2026-05-04).
      //
      // Verifies:
      //   - sizeof(int64_t) == 8 (storage element size invariant)
      //   - DatetimeArray::from_timestamps() round-trips a vector<optional<Timestamp>>
      //   - NaT slots are preserved through the round-trip (mask stays consistent)
      //   - tz-aware uniform-tz construction produces a non-null tz_ field
      //   - Boxing reconstruction via getElementAt() recovers the input ns values
      //   - Fix A storage shape: data() returns NDArray<int64_t> (8 B/elem, ns count)
      //   - NaT sentinel: INT64_MIN round-trips through the boxing layer
      //   - All 4 linear units (s/ms/us/ns) round-trip through ns-canonical storage
      //   - Tz-aware boxing reconstruction (UTC, US/Eastern, +05:30) preserves tz
      
      #include "../pandas/pd_datetime_array.h"
      #include "../pandas/pd_timedelta_array.h"

.. _example-mixedtzdatetimearray-mask-1:

.. dropdown:: mask (pd_test_1_all.cpp:9119)
   :class-title: example-dropdown

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

      
      void pd_test_datetime_mixin_array_constructor() {
          std::cout << "========= DatetimeTDMixin array constructor =========================";
      
          // Create DatetimeArray with some values
          numpy::NDArray<numpy::datetime64> data(std::vector<size_t>{3});
          data.setElementAt({0}, numpy::datetime64(1000000000000000000LL, numpy::DateTimeUnit::Nanosecond));  // ~2001
          data.setElementAt({1}, numpy::datetime64(1500000000000000000LL, numpy::DateTimeUnit::Nanosecond));  // ~2017
          data.setElementAt({2}, numpy::datetime64(1600000000000000000LL, numpy::DateTimeUnit::Nanosecond));  // ~2020
      
          numpy::NDArray<numpy::bool_> mask(std::vector<size_t>{3});
          mask.setElementAt({0}, numpy::bool_(false));
          mask.setElementAt({1}, numpy::bool_(false));
          mask.setElementAt({2}, numpy::bool_(false));
      
          pandas::DatetimeArray arr(data, mask);
          pandas::DatetimeTDMixin idx(arr, "timestamps");
      
          bool passed = (idx.size() == 3 && !idx.empty() &&
                         idx.name().has_value() && *idx.name() == "timestamps" &&
                         idx.inferred_type() == "datetime");

.. _example-mixedtzdatetimearray-is_na-2:

.. dropdown:: is_na (pd_test_1_all.cpp:51)
   :class-title: example-dropdown

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

      
          void pd_test_boolean_array_na_handling() {
              std::cout << "========= BooleanArray: NA handling ======================= ";
      
              pandas::BooleanArray arr({
                  std::optional<bool>(true),
                  std::nullopt,  // NA at index 1
                  std::optional<bool>(false)
              });
      
              if (!arr.is_na(1)) {
                  std::cout << "  [FAIL] : in pd_test_boolean_array_na_handling() : is_na(1) should be true" << std::endl;
                  throw std::runtime_error("pd_test_boolean_array_na_handling failed: is_na(1) should be true");
              }
      
              if (arr.is_na(0)) {
                  std::cout << "  [FAIL] : in pd_test_boolean_array_na_handling() : is_na(0) should be false" << std::endl;
                  throw std::runtime_error("pd_test_boolean_array_na_handling failed: is_na(0) should be false");
              }
      
              if (!arr.has_na()) {

.. _example-mixedtzdatetimearray-data-3:

.. dropdown:: data (pd_test_1_all.cpp:9114)
   :class-title: example-dropdown

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

              throw std::runtime_error("pd_test_datetime_mixin_default_constructor failed");
          }
      
          std::cout << " -> tests passed" << std::endl;
      }
      
      void pd_test_datetime_mixin_array_constructor() {
          std::cout << "========= DatetimeTDMixin array constructor =========================";
      
          // Create DatetimeArray with some values
          numpy::NDArray<numpy::datetime64> data(std::vector<size_t>{3});
          data.setElementAt({0}, numpy::datetime64(1000000000000000000LL, numpy::DateTimeUnit::Nanosecond));  // ~2001
          data.setElementAt({1}, numpy::datetime64(1500000000000000000LL, numpy::DateTimeUnit::Nanosecond));  // ~2017
          data.setElementAt({2}, numpy::datetime64(1600000000000000000LL, numpy::DateTimeUnit::Nanosecond));  // ~2020
      
          numpy::NDArray<numpy::bool_> mask(std::vector<size_t>{3});
          mask.setElementAt({0}, numpy::bool_(false));
          mask.setElementAt({1}, numpy::bool_(false));
          mask.setElementAt({2}, numpy::bool_(false));
      
          pandas::DatetimeArray arr(data, mask);

.. _example-mixedtzdatetimearray-dtype-4:

.. dropdown:: dtype (pd_test_1_all.cpp:295)
   :class-title: example-dropdown

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

                  throw std::runtime_error("pd_test_boolean_array_reductions failed: mean");
              }
      
              std::cout << " -> tests passed" << std::endl;
          }
      
          void pd_test_boolean_array_dtype() {
              std::cout << "========= BooleanArray: dtype ======================= ";
      
              pandas::BooleanArray arr;
              if (arr.dtype().name() != "boolean") {
                  std::cout << "  [FAIL] : in pd_test_boolean_array_dtype() : dtype name should be 'boolean'" << std::endl;
                  throw std::runtime_error("pd_test_boolean_array_dtype failed: dtype name");
              }
      
              if (arr.dtype().kind() != "b") {
                  std::cout << "  [FAIL] : in pd_test_boolean_array_dtype() : dtype kind should be 'b'" << std::endl;
                  throw std::runtime_error("pd_test_boolean_array_dtype failed: dtype kind");
              }
      
              std::cout << " -> tests passed" << std::endl;

.. _example-mixedtzdatetimearray-element_tz_at-5:

.. dropdown:: element_tz_at (pd_test_mixed_tz_array.cpp:40)
   :class-title: example-dropdown

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

      static int test_round_trip_mixed_tz() {
          int errors_before = g_errors;
          std::vector<std::optional<pandas::Timestamp>> v = {
              pandas::Timestamp(1577836800000000000LL, "UTC"),
              std::nullopt,
              pandas::Timestamp(1609459200000000000LL, "US/Eastern"),
          };
          auto arr = pandas::MixedTzDatetimeArray::from_timestamps(v);
          check(arr.size() == 3, "size == 3");
          check(arr.is_na(1), "NaT slot at index 1");
          check(arr.element_tz_at(0) == "UTC", "element_tz_at(0) == 'UTC'");
          check(arr.element_tz_at(2) == "US/Eastern", "element_tz_at(2) == 'US/Eastern'");
      
          auto ts0 = arr._box_func(0);
          check(!ts0.isNaT(), "_box_func(0) is not NaT");
          check(ts0.value() == 1577836800000000000LL, "_box_func(0) ns matches");
      
          auto ts1 = arr._box_func(1);
          check(ts1.isNaT(), "_box_func(1) is NaT");
          return g_errors - errors_before;
      }

.. _example-mixedtzdatetimearray-size-6:

.. dropdown:: size (pd_test_1_all.cpp:22)
   :class-title: example-dropdown

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

      #include "../pandas/pd_boolean_array.h"
      
      namespace dataframe_tests {
      
      namespace dataframe_tests_boolean_array {
          void pd_test_boolean_array_constructors() {
              std::cout << "========= BooleanArray: constructors ======================= ";
      
              // Default constructor
              pandas::BooleanArray arr1;
              if (arr1.size() != 0) {
                  std::cout << "  [FAIL] : in pd_test_boolean_array_constructors() : default constructor size != 0" << std::endl;
                  throw std::runtime_error("pd_test_boolean_array_constructors failed: default constructor size != 0");
              }
      
              // Initializer list constructor
              pandas::BooleanArray arr2({
                  std::optional<bool>(true),
                  std::optional<bool>(false),
                  std::nullopt,
                  std::optional<bool>(true)

.. _example-mixedtzdatetimearray-unit-7:

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