RecordArray
===========

.. cpp:class:: numpy::RecordArray

   numpy C++ class.

Example
-------

.. code-block:: cpp

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

   // Use RecordArray
   RecordArray obj;
   // ... operations ...

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

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

   * - Signature
     - Location
     - Example
   * - ``RecordArray(std::shared_ptr<StructuredDType>dtype, const std::vector<size_t>&shape)``
     - NP_RECARRAY.H:83
     - :ref:`View <example-recordarray-recordarray-0>`

Operators
---------

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

   * - Signature
     - Return Type
     - Location
     - Example
   * - ``RecordProxy operator[](const std::vector<size_t>&indices)``
     - RecordProxy
     - NP_RECARRAY.H:88
     - 
   * - ``const RecordProxy operator[](const std::vector<size_t>&indices)``
     - const RecordProxy
     - NP_RECARRAY.H:92
     - 
   * - ``RecordProxy operator[](size_tindex)``
     - RecordProxy
     - NP_RECARRAY.H:96
     - 
   * - ``const RecordProxy operator[](size_tindex)``
     - const RecordProxy
     - NP_RECARRAY.H:103
     - 

Sorting
-------

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

   * - Signature
     - Return Type
     - Location
     - Example
   * - ``void sortByField(const std::string &field_name, boolascending = true)``
     - void
     - NP_RECARRAY.H:294
     - :ref:`View <example-recordarray-sortbyfield-1>`

Joining / Splitting
-------------------

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

   * - Signature
     - Return Type
     - Location
     - Example
   * - ``RecordArray concatenate(const RecordArray &other, size_taxis = 0)``
     - RecordArray
     - NP_RECARRAY.H:232
     - :ref:`View <example-recordarray-concatenate-2>`

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

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

   * - Signature
     - Return Type
     - Location
     - Example
   * - ``RecordArray copy()``
     - RecordArray
     - NP_RECARRAY.H:175
     - :ref:`View <example-recordarray-copy-3>`

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

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

   * - Signature
     - Return Type
     - Location
     - Example
   * - ``void printArray(std::ostream &os = std::cout)``
     - void
     - NP_RECARRAY.H:353
     - :ref:`View <example-recordarray-printarray-4>`
   * - ``void setFieldFromTypedArray(const std::string &field_name, const NDArray<int32>&values)``
     - void
     - NP_RECARRAY.H:119
     - 
   * - ``void setFieldFromTypedArray(const std::string &field_name, const NDArray<float64>&values)``
     - void
     - NP_RECARRAY.H:147
     - 
   * - ``void setupFieldAccessors()``
     - void
     - NP_RECARRAY.H:74
     - 
   * - ``std::string shapeToString(const std::vector<size_t>&shape)``
     - std::string
     - NP_RECARRAY.H:358
     - 
   * - ``RecordArray slice(const std::vector<std::pair<size_t,size_t>>&ranges)``
     - RecordArray
     - NP_RECARRAY.H:198
     - :ref:`View <example-recordarray-slice-5>`
   * - ``std::string toString()``
     - std::string
     - NP_RECARRAY.H:340
     - :ref:`View <example-recordarray-tostring-6>`


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

The following examples are extracted from the test suite.

.. _example-recordarray-recordarray-0:

.. dropdown:: RecordArray (np_test_5_all.cpp:8512)
   :class-title: example-dropdown

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

      
          std::cout << " -> tests passed" << std::endl;
        }
      
        // ===========================
        // RecordArray Tests
        // ===========================
      
      #endif  // End of StructuredArray tests
      
      #if 0  // TODO: Fix RecordArray (depends on StructuredArray)
        void np_test_toString_recarray_basic() {
          std::cout << "========= RecordArray::toString() basic =======================";
      
          std::vector<numpy::StructuredField> fields = {
              {"id", numpy::DType::INT64, 0, 8},
              {"value", numpy::DType::FLOAT32, 8, 4}
          };
      
          auto dtype = std::make_shared<numpy::StructuredDType>(fields);
          numpy::RecordArray arr(dtype, std::vector<size_t>{3});

.. _example-recordarray-sortbyfield-1:

.. dropdown:: sortByField (np_test_1_all.cpp:21704)
   :class-title: example-dropdown

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

          //x_field.printArray();
      
          auto y_field = arr.getFieldAsTypedArray<float64>("y");
          // std::cout << "Y field as array: ";
          //y_field.printArray();
      
          auto copy = arr.copy();
          // std::cout << "Copied array:" << std::endl;
          //copy.printArray();
      
          arr.sortByField("x", false);
          // std::cout << "Array sorted by x (descending):" << std::endl;
          //arr.printArray();
      
          std::cout << " -> tests passed" << std::endl;
        }
      
        void testRecFunctionsBasic() {
          std::cout << "========= testRecFunctionsBasic =======================";
      
          auto dtype = std::make_shared<StructuredDType>(std::vector<std::pair<std::string, DType>>{

.. _example-recordarray-concatenate-2:

.. dropdown:: concatenate (np_test_1_all.cpp:5432)
   :class-title: example-dropdown

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

          auto arr2 = NDArray<int32>::createRange(3, 6, 1);  // [3, 4, 5]
          auto arr3 = NDArray<int32>::createRange(6, 9, 1);  // [6, 7, 8]
      
          // std::cout << "Array 1:" << std::endl;
          //arr1.printArray();
          // std::cout << "Array 2:" << std::endl;
          //arr2.printArray();
          // std::cout << "Array 3:" << std::endl;
          //arr3.printArray();
      
          auto result = concatenate<int32>({arr1, arr2, arr3}, 0);
          // std::cout << "Concatenated (axis=0):";
          //result.printArray();
      
          // Verify shape and content
          if (!(result.getShape()[0] == 9)) {
              std::string description = std::string("testConcatenateArrayUtils():") + __FILE__ + ":" + std::to_string(__LINE__) + ": !(result.getShape()[0] == 9)";
              std::cout << std::string("[FAIL] ") + description << std::endl;
              throw std::runtime_error(description);
          }
          for (int i = 0; i < 9; ++i) {

.. _example-recordarray-copy-3:

.. dropdown:: copy (np_test_1_all.cpp:9812)
   :class-title: example-dropdown

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

          //original.printArray();
      
          // The modification should be at position (1,1) in original
          if (!(original.getElementAt({1, 1}) == 9999)) {
              std::string description = std::string("testSliceCopyVsViewMemoryOwnership():") + __FILE__ + ":" + std::to_string(__LINE__) + ": !(original.getElementAt({1, 1}) == 9999)";
              std::cout << std::string("[FAIL] ") + description << std::endl;
              throw std::runtime_error(description);
          }
          // std::cout << "[OK] Slice view shares memory with original";
      
          // Test slice copy (should be independent)
          auto slice_copy = original.sliceArray({{2, 4}, {2, 4}});
          // std::cout << "Slice copy [2:4, 2:4]:";
          //slice_copy.printArray();
      
          slice_copy.setElementAt({0, 0}, 7777);
      
          // std::cout << "After modifying slice copy at (0,0):" << std::endl;
          // std::cout << "Original array:" << std::endl;
          //original.printArray();
          // std::cout << "Slice copy:" << std::endl;

.. _example-recordarray-printarray-4:

.. dropdown:: printArray (np_test_1_all.cpp:67)
   :class-title: example-dropdown

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

              std::vector<size_t> indices(arr.getShape().size(), 0);
              do {
                  if (arr.getElementAt(indices)) {
                      return false;
                  }
              } while (incrementIndices(indices, arr.getShape()));
              return true;
          }
      
          template<typename T>
          void printArray(const NDArray<T>& arr, const std::string& name) {
              std::cout << name << ": ";
              if (arr.getShape().size() == 1) {
                  for (size_t i = 0; i < arr.getShape()[0]; ++i) {
                      // std::cout << arr.getElementAt({i}) << " ";
                  }
              }
              // std::cout << std::endl;
          }
      
          // Helper functions for bitwise operations tests

.. _example-recordarray-slice-5:

.. dropdown:: slice (np_test_1_all.cpp:13009)
   :class-title: example-dropdown

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

          // Test substr valid start but excessive length
          auto result3 = str1.substr(2, 10);  // start=2, len=10 on string of length 5
          if (!(result3.to_string() == "llo")) {
              std::string description = std::string("test_variable_string_out_of_bounds():") + __FILE__ + ":" + std::to_string(__LINE__) + ": !(result3.to_string() == \"llo\")";
              std::cout << std::string("[FAIL] ") + description << std::endl;
              throw std::runtime_error(description);
          }
          // std::cout << "[OK] vstring_ substr(2, 10) on 'hello' returns 'llo'\n";
      
          // Test slice method with out-of-bounds
          auto result4 = str1.slice(10, 15);  // slice[10:15] on string of length 5
          if (!(result4.to_string() == "")) {
              std::string description = std::string("test_variable_string_out_of_bounds():") + __FILE__ + ":" + std::to_string(__LINE__) + ": !(result4.to_string() == \"\")";
              std::cout << std::string("[FAIL] ") + description << std::endl;
              throw std::runtime_error(description);
          }
          // std::cout << "[OK] vstring_ slice(10, 15) on 'hello' returns empty string\n";
      
          // Test slice with negative indices
          auto result5 = str1.slice(-2, -1);  // slice[-2:-1] should be "l"
          if (!(result5.to_string() == "l")) {

.. _example-recordarray-tostring-6:

.. dropdown:: toString (np_test_1_all.cpp:6826)
   :class-title: example-dropdown

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

      void testDatetime64CreationDateTime() {
          std::cout << "========= testDatetime64CreationDateTime =======================";
      
          // Test default constructor
          datetime64 default_dt;
          if (!(default_dt.isNaT())) {
              std::string description = std::string("testDatetime64CreationDateTime():") + __FILE__ + ":" + std::to_string(__LINE__) + ": !(default_dt.isNaT())";
              std::cout << std::string("[FAIL] ") + description << std::endl;
              throw std::runtime_error(description);
          }
          // std::cout << "Default datetime64 is NaT: " << default_dt.toString() << std::endl;
      
          // Test value constructor
          datetime64 epoch_day(0, DateTimeUnit::Day);
          // std::cout << "Epoch day: " << epoch_day.toString() << std::endl;
      
          // Test string constructor
          datetime64 date_from_string("2024-01-15");
          // std::cout << "Date from string '2024-01-15': " << date_from_string.toString() << std::endl;
      
          datetime64 datetime_from_string("2024-01-15T10:30:45");