NestedArray
===========

.. cpp:class:: numpy::NestedArray

   numpy C++ class.

Example
-------

.. code-block:: cpp

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

   // Use NestedArray
   NestedArray obj;
   // ... operations ...

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

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

   * - Signature
     - Return Type
     - Location
     - Example
   * - ``std::vector<NDArray<U>\*> extractNDArraysOfType(const NDArray<object\_>&arr, boolflatten = false)``
     - std::vector<NDArray<U>\*>
     - NP_NESTED_ARRAY.H:154
     - 
   * - ``std::vector<std::pair<std::vector<size_t>,U\*>> extractWithIndices(const NDArray<object\_>&arr)``
     - std::vector<std::pair<std::vector<size_t>,U\*>>
     - NP_NESTED_ARRAY.H:196
     - 
   * - ``size_t getNestedDepth(const NDArray<object\_>&arr)``
     - size_t
     - NP_NESTED_ARRAY.H:166
     - :ref:`View <example-nestedarray-getnesteddepth-0>`
   * - ``size_t getNestedDepthRecursive(const object\_ &obj)``
     - size_t
     - NP_NESTED_ARRAY.H:206
     - 

Shape Manipulation
------------------

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

   * - Signature
     - Return Type
     - Location
     - Example
   * - ``void flattenNestedRecursive(const NDArray<object\_>&arr, std::vector<object\_>&result)``
     - void
     - NP_NESTED_ARRAY.H:209
     - 

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

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

   * - Signature
     - Return Type
     - Location
     - Example
   * - ``bool incrementIndicesHelper(std::vector<size_t>&indices, const std::vector<size_t>&shape)``
     - bool
     - NP_NESTED_ARRAY.H:203
     - 
   * - ``bool isHomogeneousArrays(const NDArray<object\_>&arr)``
     - bool
     - NP_NESTED_ARRAY.H:159
     - :ref:`View <example-nestedarray-ishomogeneousarrays-1>`
   * - ``bool isRectangular(const NDArray<object\_>&arr)``
     - bool
     - NP_NESTED_ARRAY.H:182
     - :ref:`View <example-nestedarray-isrectangular-2>`
   * - ``std::string printNestedArray(const NDArray<object\_>&arr, intmax_depth = 10)``
     - std::string
     - NP_NESTED_ARRAY.H:186
     - :ref:`View <example-nestedarray-printnestedarray-3>`
   * - ``void printNestedArrayRecursive(const NDArray<object\_>&arr, std::ostringstream &oss, intcurrent_depth, intmax_depth, const std::string &indent)``
     - void
     - NP_NESTED_ARRAY.H:212
     - 
   * - ``void printNestedStructure(const NDArray<object\_>&arr, intmax_depth = 5)``
     - void
     - NP_NESTED_ARRAY.H:157
     - 
   * - ``void printNestedStructureRecursive(const NDArray<object\_>&arr, intcurrent_depth, intmax_depth, const std::string &indent = "")``
     - void
     - NP_NESTED_ARRAY.H:200
     - 
   * - ``bool validateNestedStructure(const NDArray<object\_>&arr)``
     - bool
     - NP_NESTED_ARRAY.H:172
     - :ref:`View <example-nestedarray-validatenestedstructure-4>`


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

The following examples are extracted from the test suite.

.. _example-nestedarray-getnesteddepth-0:

.. dropdown:: getNestedDepth (np_test_3_all.cpp:21171)
   :class-title: example-dropdown

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

          // Level 2: object arrays containing int arrays
          numpy::NDArray<numpy::object_> mid({2});
          mid.setElementAt({0}, numpy::object_(inner1));
          mid.setElementAt({1}, numpy::object_(inner2));
      
          // Level 3: object array containing object arrays
          numpy::NDArray<numpy::object_> outer({1});
          outer.setElementAt({0}, numpy::object_(mid));
      
          // Test getNestedDepth
          size_t depth = numpy::NestedArray<int>::getNestedDepth(outer);
          CHECK(depth >= 2, "np_test_nested_deep", "depth < 2");
      
          std::cout << " -> tests passed" << std::endl;
      }
      
      // Test 4: Jagged arrays
      void np_test_nested_jagged() {
          std::cout << "========= Jagged arrays ====" ;
      
          // Create jagged array using convenience function

.. _example-nestedarray-ishomogeneousarrays-1:

.. dropdown:: isHomogeneousArrays (np_test_1_all.cpp:1824)
   :class-title: example-dropdown

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

              }
          }
      
          // Test homogeneous array detection
          std::vector<NDArray<double>> double_arrays;
          for (int i = 0; i < 3; ++i) {
              double_arrays.push_back(NDArray<double>({2}, i * 1.5));
          }
      
          NDArray<object_> homogeneous = createObjectArrayFromNDArrays(double_arrays);
          if (!(NestedArray<double>::isHomogeneousArrays(homogeneous))) {
              std::string description = std::string("testObjectArrayOperations():") + __FILE__ + ":" + std::to_string(__LINE__) + ": !(NestedArray<double>::isHomogeneousArrays(homogeneous))";
              std::cout << std::string("[FAIL] ") + description << std::endl;
              throw std::runtime_error(description);
          }
      
          // Test heterogeneous detection
          NDArray<object_> heterogeneous = createMixedObjectArray({
              object_(NDArray<int>({2}, 1)),
              object_(42)
          });

.. _example-nestedarray-isrectangular-2:

.. dropdown:: isRectangular (np_test_3_all.cpp:21198)
   :class-title: example-dropdown

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

          CHECK(jagged.getSize() == 3, "np_test_nested_jagged", "jagged.size != 3");
      
          // Test getRowLengths
          std::vector<size_t> lengths = numpy::NestedArray<int>::getRowLengths(jagged);
          CHECK(lengths.size() == 3, "np_test_nested_jagged", "lengths.size != 3");
          CHECK(lengths[0] == 3, "np_test_nested_jagged", "lengths[0] != 3");
          CHECK(lengths[1] == 2, "np_test_nested_jagged", "lengths[1] != 2");
          CHECK(lengths[2] == 4, "np_test_nested_jagged", "lengths[2] != 4");
      
          // Test isRectangular
          bool is_rect = numpy::NestedArray<int>::isRectangular(jagged);
          CHECK(!is_rect, "np_test_nested_jagged", "jagged should not be rectangular");
      
          // Create rectangular array
          numpy::NDArray<numpy::object_> rect = numpy::make_jagged_array({
              {1, 2, 3},
              {4, 5, 6},
              {7, 8, 9}
          });
          bool is_rect2 = numpy::NestedArray<int>::isRectangular(rect);
          CHECK(is_rect2, "np_test_nested_jagged", "rect should be rectangular");

.. _example-nestedarray-printnestedarray-3:

.. dropdown:: printNestedArray (np_test_3_all.cpp:21364)
   :class-title: example-dropdown

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

          // Create nested structure
          numpy::NDArray<numpy::object_> inner({2});
          inner.setElementAt({0}, numpy::object_(1));
          inner.setElementAt({1}, numpy::object_(2));
      
          numpy::NDArray<numpy::object_> outer({2});
          outer.setElementAt({0}, numpy::object_(inner));
          outer.setElementAt({1}, numpy::object_(std::string("hello")));
      
          // Get print output
          std::string output = numpy::NestedArray<int>::printNestedArray(outer);
      
          // Check output contains expected elements
          CHECK(output.find("Nested Array Structure") != std::string::npos, "np_test_nested_print", "missing header");
          CHECK(output.find("shape=") != std::string::npos, "np_test_nested_print", "missing shape");
      
          std::cout << " -> tests passed" << std::endl;
      }
      
      #undef CHECK
      

.. _example-nestedarray-validatenestedstructure-4:

.. dropdown:: validateNestedStructure (np_test_3_all.cpp:21285)
   :class-title: example-dropdown

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

          inner1.setElementAt({1}, numpy::object_(2));
      
          numpy::NDArray<numpy::object_> inner2({2});
          inner2.setElementAt({0}, numpy::object_(3));
          inner2.setElementAt({1}, numpy::object_(4));
      
          numpy::NDArray<numpy::object_> outer({2});
          outer.setElementAt({0}, numpy::object_(inner1));
          outer.setElementAt({1}, numpy::object_(inner2));
      
          bool valid = numpy::NestedArray<int>::validateNestedStructure(outer);
          CHECK(valid, "np_test_nested_validate", "homogeneous should be valid");
      
          // Create heterogeneous structure (different inner shapes)
          numpy::NDArray<numpy::object_> inner3({3});  // Different size!
          inner3.setElementAt({0}, numpy::object_(1));
          inner3.setElementAt({1}, numpy::object_(2));
          inner3.setElementAt({2}, numpy::object_(3));
      
          numpy::NDArray<numpy::object_> hetero({2});
          hetero.setElementAt({0}, numpy::object_(inner1));  // size 2