NDFrameBase
===========

.. cpp:class:: numpy::NDFrameBase

   numpy C++ class.

Example
-------

.. code-block:: cpp

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

   // Use NDFrameBase
   NDFrameBase obj;
   // ... operations ...

Array Creation
--------------

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

   * - Signature
     - Return Type
     - Location
     - Example
   * - ``virtual bool empty() const = 0``
     - virtual bool
     - df_ndframe_base.h:73
     - :ref:`View <example-ndframebase-empty-0>`

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

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

   * - Signature
     - Return Type
     - Location
     - Example
   * - ``virtual const Attrs& attrs() const = 0``
     - virtual const Attrs&
     - df_ndframe_base.h:107
     - 
   * - ``virtual Attrs& attrs() = 0``
     - virtual Attrs&
     - df_ndframe_base.h:113
     - 
   * - ``virtual bool get_value_bool(size_t idx) const = 0``
     - virtual bool
     - df_ndframe_base.h:236
     - 
   * - ``virtual std::string get_value_str(size_t idx) const = 0``
     - virtual std::string
     - df_ndframe_base.h:187
     - 

Logical
-------

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

   * - Signature
     - Return Type
     - Location
     - Example
   * - ``virtual bool all(bool skipna = true) const = 0``
     - virtual bool
     - df_ndframe_base.h:270
     - :ref:`View <example-ndframebase-all-1>`
   * - ``virtual bool any(bool skipna = true) const = 0``
     - virtual bool
     - df_ndframe_base.h:277
     - :ref:`View <example-ndframebase-any-2>`

I/O
---

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

   * - Signature
     - Return Type
     - Location
     - Example
   * - ``virtual std::string to_string() const = 0``
     - virtual std::string
     - df_ndframe_base.h:297
     - :ref:`View <example-ndframebase-to_string-3>`
   * - ``virtual std::vector<std::string> to_string_vector() const = 0``
     - virtual std::vector<std::string>
     - df_ndframe_base.h:193
     - 

Type Handling
-------------

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

   * - Signature
     - Return Type
     - Location
     - Example
   * - ``virtual void copy_value_from(size_t src_idx, size_t dst_idx) = 0``
     - virtual void
     - df_ndframe_base.h:259
     - 

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

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

   * - Signature
     - Return Type
     - Location
     - Example
   * - ``virtual bool is_na_at(size_t idx) const = 0``
     - virtual bool
     - df_ndframe_base.h:216
     - 

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

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

   * - Signature
     - Return Type
     - Location
     - Example
   * - ``virtual std::vector<const IndexBase\*> axes() const = 0``
     - virtual std::vector<const IndexBase\*>
     - df_ndframe_base.h:176
     - :ref:`View <example-ndframebase-axes-4>`
   * - ``size_t cache_memory_usage() const override``
     - size_t
     - df_ndframe_base.h:322
     - 
   * - ``void clear_cache() const override = 0``
     - void
     - df_ndframe_base.h:312
     - 
   * - ``virtual std::unique_ptr<NDFrameBase> clone() const = 0``
     - virtual std::unique_ptr<NDFrameBase>
     - df_ndframe_base.h:287
     - :ref:`View <example-ndframebase-clone-5>`
   * - ``virtual size_t count() const = 0``
     - virtual size_t
     - df_ndframe_base.h:209
     - :ref:`View <example-ndframebase-count-6>`
   * - ``virtual std::string dtype_name() const = 0``
     - virtual std::string
     - df_ndframe_base.h:79
     - :ref:`View <example-ndframebase-dtype_name-7>`
   * - ``virtual void fillna_double(double value) = 0``
     - virtual void
     - df_ndframe_base.h:222
     - 
   * - ``virtual const Flags& flags() const = 0``
     - virtual const Flags&
     - df_ndframe_base.h:125
     - :ref:`View <example-ndframebase-flags-8>`
   * - ``bool has_cached_values() const override = 0``
     - bool
     - df_ndframe_base.h:317
     - 
   * - ``virtual bool hasnans() const = 0``
     - virtual bool
     - df_ndframe_base.h:203
     - 
   * - ``virtual const IndexBase& index() const = 0``
     - virtual const IndexBase&
     - df_ndframe_base.h:157
     - :ref:`View <example-ndframebase-index-9>`
   * - ``virtual std::optional<std::string> name() const``
     - virtual std::optional<std::string>
     - df_ndframe_base.h:141
     - :ref:`View <example-ndframebase-name-10>`
   * - ``virtual size_t nbytes() const = 0``
     - virtual size_t
     - df_ndframe_base.h:97
     - :ref:`View <example-ndframebase-nbytes-11>`
   * - ``virtual size_t ndim() const = 0``
     - virtual size_t
     - df_ndframe_base.h:91
     - :ref:`View <example-ndframebase-ndim-12>`
   * - ``virtual void replace_value(double to_replace, double value) = 0``
     - virtual void
     - df_ndframe_base.h:229
     - 
   * - ``virtual std::string repr() const = 0``
     - virtual std::string
     - df_ndframe_base.h:303
     - 
   * - ``virtual void reset_index(bool drop = true) = 0``
     - virtual void
     - df_ndframe_base.h:170
     - 
   * - ``virtual void set_attrs(const Attrs& attrs) = 0``
     - virtual void
     - df_ndframe_base.h:119
     - 
   * - ``virtual void set_flags(const Flags& flags) = 0``
     - virtual void
     - df_ndframe_base.h:131
     - 
   * - ``virtual void set_index(std::unique_ptr<IndexBase> new_index) = 0``
     - virtual void
     - df_ndframe_base.h:164
     - 
   * - ``virtual void set_name(const std::optional<std::string>& /\*name\*/)``
     - virtual void
     - df_ndframe_base.h:147
     - 
   * - ``virtual void set_value_double(size_t idx, double value) = 0``
     - virtual void
     - df_ndframe_base.h:249
     - 
   * - ``virtual void set_value_nan(size_t idx) = 0``
     - virtual void
     - df_ndframe_base.h:242
     - 
   * - ``virtual std::vector<size_t> shape() const = 0``
     - virtual std::vector<size_t>
     - df_ndframe_base.h:85
     - :ref:`View <example-ndframebase-shape-13>`
   * - ``virtual size_t size() const = 0``
     - virtual size_t
     - df_ndframe_base.h:67
     - :ref:`View <example-ndframebase-size-14>`


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

The following examples are extracted from the test suite.

.. _example-ndframebase-empty-0:

.. dropdown:: empty (np_test_1_all.cpp:6316)
   :class-title: example-dropdown

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

      }
      
      void test_data_generator_emptyBenchmarkSorting() {
          std::cout << "========= test_data_generator_empty =======================";
      
          DataGenerator<int> gen(42);
      
          // Test empty data generation
          std::vector<int> data = gen.generate(0, DataPattern::RANDOM);
      
          if (!(data.empty())) {
              std::string description = std::string("test_data_generator_emptyBenchmarkSorting():") + __FILE__ + ":" + std::to_string(__LINE__) + ": !(data.empty())";
              std::cout << std::string("[FAIL] ") + description << std::endl;
              throw std::runtime_error(description);
          }
      
          // std::cout << "Empty data generation test passed" << std::endl;
      
          std::cout << " -> tests passed" << std::endl;
      }
      

.. _example-ndframebase-all-1:

.. dropdown:: all (np_test_4_all.cpp:23928)
   :class-title: example-dropdown

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

                              }
                          }
                      }
      
                      auto result = numpy::einsum<numpy::float64>("ijk->ik", {A});
      
                      if (result.getShape()[0] != 2 || result.getShape()[1] != 2) {
                          throw std::runtime_error("einsum partial sum shape wrong");
                      }
      
                      // Sum over j: 1+2+3 = 6 for all (i,k) positions
                      if (std::abs(result.getElementAt({0, 0}) - 6.0) > 1e-10 ||
                          std::abs(result.getElementAt({1, 1}) - 6.0) > 1e-10) {
                          throw std::runtime_error("einsum partial sum values wrong");
                      }
      
                      // std::cout << "  OK: Partial sum: 'ijk->ik'\n";
                  }
      
                  // Test 5: Size-1 dimension handling
                  {

.. _example-ndframebase-any-2:

.. dropdown:: any (np_test_2_all.cpp:16758)
   :class-title: example-dropdown

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

          // ANY() TESTS - SCALAR RESULT
          // ============================================================================
      
          void np_test_logic_any_scalar_all_false() {
            std::cout << "========= any: all false elements =======================";
      
            // Create array with all false/zero elements
            std::vector<double> data = { 0.0, 0.0, 0.0 };
            numpy::NDArray<double> arr = numpy::createArrayFromVector<double>({ 3 }, data);
      
            bool result = numpy::any(arr);
      
            if (result != false) {
              std::cout << "  [FAIL] : in np_test_logic_any_scalar_all_false() : expected false for all-zero array";
              throw std::runtime_error("np_test_logic_any_scalar_all_false failed: expected false");
            }
      
            std::cout << " -> tests passed" << std::endl;
          }
      
          void np_test_logic_any_scalar_all_true() {

.. _example-ndframebase-to_string-3:

.. dropdown:: to_string (np_test_1_all.cpp:454)
   :class-title: example-dropdown

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

          // Modify through different views
          view1.setElementAt({0, 0}, 100);
          view2.setElementAt({2, 1}, 200);  // This is (1, 2) in original
          view3.setElementAt({0, 0}, 300);  // This is (1, 1) in original
      
          // std::cout << "After modifications through multiple views:" << std::endl;
          //original.printArray();
      
          // Verify all changes are reflected
          if (!(original.getElementAt({0, 0}) == 100)) {
              std::string description = std::string("testAdvancedViewLifecycle():") + __FILE__ + ":" + std::to_string(__LINE__) + ": !(original.getElementAt({0, 0}) == 100)";
              std::cout << std::string("[FAIL] ") + description << std::endl;
              throw std::runtime_error(description);
          }
          if (!(original.getElementAt({1, 2}) == 200)) {
              std::string description = std::string("testAdvancedViewLifecycle():") + __FILE__ + ":" + std::to_string(__LINE__) + ": !(original.getElementAt({1, 2}) == 200)";
              std::cout << std::string("[FAIL] ") + description << std::endl;
              throw std::runtime_error(description);
          }
          if (!(original.getElementAt({1, 1}) == 300)) {
              std::string description = std::string("testAdvancedViewLifecycle():") + __FILE__ + ":" + std::to_string(__LINE__) + ": !(original.getElementAt({1, 1}) == 300)";

.. _example-ndframebase-axes-4:

.. dropdown:: axes (np_test_5_all.cpp:16631)
   :class-title: example-dropdown

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

              return 0;
          } else {
              std::cout << "  [FAIL] reshape() failed" << std::endl;
              return 1;
          }
      }
      
      // Test 15: transpose() - Transpose array (SKIPPED - needs implementation)
      int test_transpose() {
          std::cout << "\n[TEST] ma.transpose() - SKIPPED (needs correct transpose API)" << std::endl;
          return 0;  // Skip for now
      }
      
      // Test 16: swapaxes() - Swap two axes (SKIPPED - needs implementation)
      int test_swapaxes() {
          std::cout << "\n[TEST] ma.swapaxes() - SKIPPED (needs correct swapaxes API)" << std::endl;
          return 0;  // Skip for now
      }
      
      // Test 17: repeat() - Repeat elements
      int test_repeat() {

.. _example-ndframebase-clone-5:

.. dropdown:: clone (np_test_1_all.cpp:24942)
   :class-title: example-dropdown

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

            }
      
            // Test reproducibility
            numpy::random::PCG64DXSM rng2(11111);
            if (rng2.next_uint64() != val) {
              std::cout << "  [FAIL] : in np_test_bitgen_pcg64dxsm() : not reproducible";
              throw std::runtime_error("np_test_bitgen_pcg64dxsm failed");
            }
      
            // Test clone
            auto cloned = rng.clone();
            if (cloned->name() != "PCG64DXSM") {
              std::cout << "  [FAIL] : in np_test_bitgen_pcg64dxsm() : clone name incorrect";
              throw std::runtime_error("np_test_bitgen_pcg64dxsm failed");
            }
      
            std::cout << " -> tests passed" << std::endl;
          }
      
          // ============================================================================
          // PHILOX TESTS

.. _example-ndframebase-count-6:

.. dropdown:: count (np_test_1_all.cpp:3616)
   :class-title: example-dropdown

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

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

.. _example-ndframebase-dtype_name-7:

.. dropdown:: dtype_name (np_test_2_all.cpp:3567)
   :class-title: example-dropdown

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

                std::cout << std::string("[FAIL] ") + description << std::endl;
                throw std::runtime_error(description);
            }
            if (!(flags_info.writeable == true)) {
                std::string description = std::string("testArrayInfo():") + __FILE__ + ":" + std::to_string(__LINE__) + ": !(flags_info.writeable == true)";
                std::cout << std::string("[FAIL] ") + description << std::endl;
                throw std::runtime_error(description);
            }
      
            // Test dtype functions
            if (!(dtype_name(arr) == "float64")) {
                std::string description = std::string("testArrayInfo():") + __FILE__ + ":" + std::to_string(__LINE__) + ": !(dtype_name(arr) == \"float64\")";
                std::cout << std::string("[FAIL] ") + description << std::endl;
                throw std::runtime_error(description);
            }
            if (!(dtype_itemsize(arr) == sizeof(double))) {
                std::string description = std::string("testArrayInfo():") + __FILE__ + ":" + std::to_string(__LINE__) + ": !(dtype_itemsize(arr) == sizeof(double))";
                std::cout << std::string("[FAIL] ") + description << std::endl;
                throw std::runtime_error(description);
            }
      

.. _example-ndframebase-flags-8:

.. dropdown:: flags (np_test_2_all.cpp:3554)
   :class-title: example-dropdown

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

            }
      
            // Test nbytes
            if (!(nbytes(arr) == 24 * sizeof(double))) {
                std::string description = std::string("testArrayInfo():") + __FILE__ + ":" + std::to_string(__LINE__) + ": !(nbytes(arr) == 24 * sizeof(double))";
                std::cout << std::string("[FAIL] ") + description << std::endl;
                throw std::runtime_error(description);
            }
      
            // Test flags
            auto flags_info = flags(arr);
            if (!(flags_info.owndata == true)) {
                std::string description = std::string("testArrayInfo():") + __FILE__ + ":" + std::to_string(__LINE__) + ": !(flags_info.owndata == true)";
                std::cout << std::string("[FAIL] ") + description << std::endl;
                throw std::runtime_error(description);
            }
            if (!(flags_info.writeable == true)) {
                std::string description = std::string("testArrayInfo():") + __FILE__ + ":" + std::to_string(__LINE__) + ": !(flags_info.writeable == true)";
                std::cout << std::string("[FAIL] ") + description << std::endl;
                throw std::runtime_error(description);
            }

.. _example-ndframebase-index-9:

.. dropdown:: index (np_test_5_all.cpp:1283)
   :class-title: example-dropdown

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

      
          // ============================================================================
          // SEARCH OPERATION TESTS
          // ============================================================================
      
          void np_test_string_index() {
            std::cout << "========= index search operation =======================";
      
            std::vector<std::string> strings = { "hello world", "tomorrow" };
            auto arr = numpy::char_::array<32>(strings);
            auto indices = numpy::char_::index(arr, "o");
      
            bool passed = (indices.getSize() == arr.size());
      
            if (!passed) {
              std::cout << "  [FAIL] : in np_test_string_index() : indices size mismatch";
              throw std::runtime_error("np_test_string_index failed");
            }
      
            std::cout << " -> tests passed" << std::endl;
          }

.. _example-ndframebase-name-10:

.. dropdown:: name (np_test_1_all.cpp:24865)
   :class-title: example-dropdown

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

            uint64_t before_restore = rng.next_uint64();
            rng.set_state(state);
            uint64_t after_restore = rng.next_uint64();
      
            if (before_restore != after_restore) {
              std::cout << "  [FAIL] : in np_test_bitgen_mt19937() : state restore failed";
              throw std::runtime_error("np_test_bitgen_mt19937 failed: state");
            }
      
            // Test name
            if (rng.name() != "MT19937") {
              std::cout << "  [FAIL] : in np_test_bitgen_mt19937() : incorrect name";
              throw std::runtime_error("np_test_bitgen_mt19937 failed: name");
            }
      
            std::cout << " -> tests passed" << std::endl;
          }
      
          // ============================================================================
          // PCG64 TESTS
          // ============================================================================

.. _example-ndframebase-nbytes-11:

.. dropdown:: nbytes (np_test_2_all.cpp:3547)
   :class-title: example-dropdown

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

            }
      
            // Test itemsize
            if (!(itemsize(arr) == sizeof(double))) {
                std::string description = std::string("testArrayInfo():") + __FILE__ + ":" + std::to_string(__LINE__) + ": !(itemsize(arr) == sizeof(double))";
                std::cout << std::string("[FAIL] ") + description << std::endl;
                throw std::runtime_error(description);
            }
      
            // Test nbytes
            if (!(nbytes(arr) == 24 * sizeof(double))) {
                std::string description = std::string("testArrayInfo():") + __FILE__ + ":" + std::to_string(__LINE__) + ": !(nbytes(arr) == 24 * sizeof(double))";
                std::cout << std::string("[FAIL] ") + description << std::endl;
                throw std::runtime_error(description);
            }
      
            // Test flags
            auto flags_info = flags(arr);
            if (!(flags_info.owndata == true)) {
                std::string description = std::string("testArrayInfo():") + __FILE__ + ":" + std::to_string(__LINE__) + ": !(flags_info.owndata == true)";
                std::cout << std::string("[FAIL] ") + description << std::endl;

.. _example-ndframebase-ndim-12:

.. dropdown:: ndim (np_test_2_all.cpp:3526)
   :class-title: example-dropdown

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

          void testArrayInfo() {
            std::cout << "Testing array information functions...\n";
      
            // Test basic info functions
            auto arr = createFloat64Array({ 2, 3, 4 });
            for (size_t i = 0; i < arr.getSize(); ++i) {
              arr.setElementAt({ i / 12, (i / 4) % 3, i % 4 }, static_cast<double>(i));
            }
      
            // Test ndim
            if (!(ndim(arr) == 3)) {
                std::string description = std::string("testArrayInfo():") + __FILE__ + ":" + std::to_string(__LINE__) + ": !(ndim(arr) == 3)";
                std::cout << std::string("[FAIL] ") + description << std::endl;
                throw std::runtime_error(description);
            }
      
            // Test size
            if (!(size(arr) == 24)) {
                std::string description = std::string("testArrayInfo():") + __FILE__ + ":" + std::to_string(__LINE__) + ": !(size(arr) == 24)";
                std::cout << std::string("[FAIL] ") + description << std::endl;
                throw std::runtime_error(description);

.. _example-ndframebase-shape-13:

.. dropdown:: shape (np_test_1_all.cpp:3751)
   :class-title: example-dropdown

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

          }
      
          for (size_t j = 0; j < 3; ++j) {
              arr3.setElementAt({0, j}, static_cast<double>((j + 1) * 100));  // [100, 200, 300]
          }
      
          // Broadcast all arrays together
          std::vector<NDArray<double>> arrays = {arr1, arr2, arr3};
          auto broadcasted = broadcast_arrays(arrays);
      
          // All should have shape (2, 3)
          for (const auto& arr : broadcasted) {
              if (!((arr.getShape() == std::vector<size_t>{2, 3}))) {
                  std::string description = std::string("test_broadcast_arrays():") + __FILE__ + ":" + std::to_string(__LINE__) + ": !((arr.getShape() == std::vector<size_t>{2, 3}))";
                  std::cout << std::string("[FAIL] ") + description << std::endl;
                  throw std::runtime_error(description);
              }
          }
      
          // Check values
          if (!(broadcasted[0].getElementAt({0, 1}) == 2.0)) {

.. _example-ndframebase-size-14:

.. dropdown:: size (np_test_1_all.cpp:47)
   :class-title: example-dropdown

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

      
      using namespace numpy;
      using namespace numpy::benchmark;
      using namespace numpy::char_;
      
      // Helper functions for array comparison tests
      namespace {
          const double TOLERANCE = 1e-10;
      
          bool allTrue(const NDArray<bool>& arr) {
              std::vector<size_t> indices(arr.getShape().size(), 0);
              do {
                  if (!arr.getElementAt(indices)) {
                      return false;
                  }
              } while (incrementIndices(indices, arr.getShape()));
              return true;
          }
      
          bool allFalse(const NDArray<bool>& arr) {
              std::vector<size_t> indices(arr.getShape().size(), 0);