RecFunctions
============

.. cpp:class:: numpy::RecFunctions

   numpy C++ class.

Example
-------

.. code-block:: cpp

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

   // Use RecFunctions
   RecFunctions obj;
   // ... operations ...

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

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

   * - Signature
     - Return Type
     - Location
     - Example
   * - ``StructuredValue createComparisonValue(const StructuredRecord &record)``
     - StructuredValue
     - NP_RECFUNCTIONS.H:535
     - 

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

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

   * - Signature
     - Return Type
     - Location
     - Example
   * - ``std::string get_fieldstructure(const RecordArray &array)``
     - std::string
     - NP_RECFUNCTIONS.H:412
     - :ref:`View <example-recfunctions-get_fieldstructure-0>`

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

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

   * - Signature
     - Return Type
     - Location
     - Example
   * - ``RecordArray append_fields(const RecordArray &base, const std::vector<std::string>&names, const std::vector<std::pair<DType,std::shared_ptr<void>>>&data, const std::vector<StructuredValue>&fill_values = {}, boolusemask = false, boolasrecarray = true)``
     - RecordArray
     - NP_RECFUNCTIONS.H:13
     - :ref:`View <example-recfunctions-append_fields-1>`
   * - ``RecordArray stack_arrays(const std::vector<RecordArray>&arrays, booldefaults = false, boolusemask = false, boolasrecarray = true, boolautoconvert = false)``
     - RecordArray
     - NP_RECFUNCTIONS.H:217
     - :ref:`View <example-recfunctions-stack_arrays-2>`

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

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

   * - Signature
     - Return Type
     - Location
     - Example
   * - ``size_t calculateLinearIndex(const std::vector<size_t>&indices, const std::vector<size_t>&shape)``
     - size_t
     - NP_RECFUNCTIONS.H:498
     - 
   * - ``RecordArray drop_fields(const RecordArray &base, const std::vector<std::string>&drop_names, boolusemask = false, boolasrecarray = true)``
     - RecordArray
     - NP_RECFUNCTIONS.H:62
     - :ref:`View <example-recfunctions-drop_fields-3>`
   * - ``RecordArray join_by(const std::string &key, const RecordArray &r1, const RecordArray &r2, const std::string &jointype = "inner", const std::string &r1postfix = "1", const std::string &r2postfix = "2", booldefaults = false, boolusemask = false, boolasrecarray = true)``
     - RecordArray
     - NP_RECFUNCTIONS.H:270
     - :ref:`View <example-recfunctions-join_by-4>`
   * - ``RecordArray merge_arrays(const std::vector<RecordArray>&arrays, boolflatten = false, boolusemask = false, boolasrecarray = true)``
     - RecordArray
     - NP_RECFUNCTIONS.H:147
     - :ref:`View <example-recfunctions-merge_arrays-5>`
   * - ``RecordArray rename_fields(const RecordArray &base, const std::unordered_map<std::string,std::string>&namemap)``
     - RecordArray
     - NP_RECFUNCTIONS.H:105
     - :ref:`View <example-recfunctions-rename_fields-6>`
   * - ``RecordArray repack_fields(const RecordArray &array, boolalign = false)``
     - RecordArray
     - NP_RECFUNCTIONS.H:416
     - :ref:`View <example-recfunctions-repack_fields-7>`
   * - ``void setFieldFromData(RecordArray &array, const std::vector<size_t>&indices, const std::string &field_name, const std::pair<DType,std::shared_ptr<void>>&data, size_toffset)``
     - void
     - NP_RECFUNCTIONS.H:508
     - 


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

The following examples are extracted from the test suite.

.. _example-recfunctions-get_fieldstructure-0:

.. dropdown:: get_fieldstructure (np_test_1_all.cpp:21735)
   :class-title: example-dropdown

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

          // std::cout << "Base array:" << std::endl;
          //base.printArray();
      
          std::vector<std::string> names = get_names(base);
          // std::cout << "Field names: ";
          for (const auto& name : names) {
            // std::cout << name << " ";
          }
          // std::cout << std::endl;
      
          // std::cout << "Field structure: " << get_fieldstructure(base) << std::endl;
      
          auto dropped = drop_fields(base, { "score" });
          // std::cout << "After dropping 'score' field:";
          //dropped.printArray();
      
          std::unordered_map<std::string, std::string> rename_map = { {"name", "student_name"} };
          auto renamed = rename_fields(base, rename_map);
          // std::cout << "After renaming 'name' to 'student_name':" << std::endl;
          //renamed.printArray();
      

.. _example-recfunctions-append_fields-1:

.. dropdown:: append_fields (np_test_1_all.cpp:25911)
   :class-title: example-dropdown

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

            auto score_ptr = make_shared_data(score_data);
            auto rank_ptr = make_shared_data(rank_data);
      
            // Append fields
            std::vector<std::string> new_field_names = { "score", "rank" };
            std::vector<std::pair<numpy::DType, std::shared_ptr<void>>> new_field_data = {
                {numpy::DType::FLOAT64, score_ptr},
                {numpy::DType::INT32, rank_ptr}
            };
      
            auto result = numpy::RecFunctions::append_fields(base_arr, new_field_names, new_field_data);
      
            // Verify result has 4 fields
            auto field_names = result.getFieldNames();
            bool passed = (field_names.size() == 4);
      
            if (passed) {
              // Verify original fields preserved
              passed = (result.getFieldValue<numpy::int32>({ 0 }, "id") == 1);
              passed = passed && (result.getFieldValue<numpy::int32>({ 1 }, "id") == 2);
              passed = passed && (result.getFieldValue<numpy::int32>({ 2 }, "name_length") == 6);

.. _example-recfunctions-stack_arrays-2:

.. dropdown:: stack_arrays (np_test_1_all.cpp:21784)
   :class-title: example-dropdown

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

          // std::cout << "Array 1:" << std::endl;
          //arr1.printArray();
      
          // std::cout << "Array 2:" << std::endl;
          //arr2.printArray();
      
          auto merged = merge_arrays({ arr1, arr2 });
          // std::cout << "Merged arrays:";
          //merged.printArray();
      
          auto stacked = stack_arrays({ arr1 });
          // std::cout << "Stacked arrays (single array):";
          //stacked.printArray();
      
          std::cout << " -> tests passed" << std::endl;
        }
      
        void testRecFunctionsJoin() {
          std::cout << "========= testRecFunctionsJoin =======================";
      
          auto dtype = std::make_shared<StructuredDType>(std::vector<std::pair<std::string, DType>>{

.. _example-recfunctions-drop_fields-3:

.. dropdown:: drop_fields (np_test_1_all.cpp:21737)
   :class-title: example-dropdown

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

      
          std::vector<std::string> names = get_names(base);
          // std::cout << "Field names: ";
          for (const auto& name : names) {
            // std::cout << name << " ";
          }
          // std::cout << std::endl;
      
          // std::cout << "Field structure: " << get_fieldstructure(base) << std::endl;
      
          auto dropped = drop_fields(base, { "score" });
          // std::cout << "After dropping 'score' field:";
          //dropped.printArray();
      
          std::unordered_map<std::string, std::string> rename_map = { {"name", "student_name"} };
          auto renamed = rename_fields(base, rename_map);
          // std::cout << "After renaming 'name' to 'student_name':" << std::endl;
          //renamed.printArray();
      
          std::cout << " -> tests passed" << std::endl;
        }

.. _example-recfunctions-join_by-4:

.. dropdown:: join_by (np_test_1_all.cpp:21826)
   :class-title: example-dropdown

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

          right.setFieldValue({ 1 }, "info", std::string("B"));
          right.setFieldValue({ 2 }, "key", static_cast<int32>(4));
          right.setFieldValue({ 2 }, "info", std::string("D"));
      
          // std::cout << "Left array:" << std::endl;
          //left.printArray();
      
          // std::cout << "Right array:" << std::endl;
          //right.printArray();
      
          auto inner_join = join_by("key", left, right, "inner");
          // std::cout << "Inner join on 'key':" << std::endl;
          //inner_join.printArray();
      
          auto outer_join = join_by("key", left, right, "outer");
          // std::cout << "Outer join on 'key':" << std::endl;
          //outer_join.printArray();
      
          std::cout << " -> tests passed" << std::endl;
        }
      

.. _example-recfunctions-merge_arrays-5:

.. dropdown:: merge_arrays (np_test_1_all.cpp:21780)
   :class-title: example-dropdown

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

          arr2.setFieldValue({ 0 }, "name", std::string("Alice"));
          arr2.setFieldValue({ 1 }, "id", static_cast<int32>(4));
          arr2.setFieldValue({ 1 }, "name", std::string("Bob"));
      
          // std::cout << "Array 1:" << std::endl;
          //arr1.printArray();
      
          // std::cout << "Array 2:" << std::endl;
          //arr2.printArray();
      
          auto merged = merge_arrays({ arr1, arr2 });
          // std::cout << "Merged arrays:";
          //merged.printArray();
      
          auto stacked = stack_arrays({ arr1 });
          // std::cout << "Stacked arrays (single array):";
          //stacked.printArray();
      
          std::cout << " -> tests passed" << std::endl;
        }
      

.. _example-recfunctions-rename_fields-6:

.. dropdown:: rename_fields (np_test_1_all.cpp:21742)
   :class-title: example-dropdown

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

          }
          // std::cout << std::endl;
      
          // std::cout << "Field structure: " << get_fieldstructure(base) << std::endl;
      
          auto dropped = drop_fields(base, { "score" });
          // std::cout << "After dropping 'score' field:";
          //dropped.printArray();
      
          std::unordered_map<std::string, std::string> rename_map = { {"name", "student_name"} };
          auto renamed = rename_fields(base, rename_map);
          // std::cout << "After renaming 'name' to 'student_name':" << std::endl;
          //renamed.printArray();
      
          std::cout << " -> tests passed" << std::endl;
        }
      
        void testRecFunctionsMergeStack() {
          std::cout << "========= testRecFunctionsMergeStack =======================";
      
          auto dtype1 = std::make_shared<StructuredDType>(std::vector<std::pair<std::string, DType>>{

.. _example-recfunctions-repack_fields-7:

.. dropdown:: repack_fields (np_test_1_all.cpp:21867)
   :class-title: example-dropdown

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

          // std::cout << "Array with duplicates:" << std::endl;
          //arr.printArray();
      
          auto duplicates = find_duplicates(arr, "id");
          // std::cout << "Duplicate indices based on 'id' field: ";
          for (size_t idx : duplicates) {
            // std::cout << idx << " ";
          }
          // std::cout << std::endl;
      
          auto repacked = repack_fields(arr, false);
          // std::cout << "Repacked array:" << std::endl;
          //repacked.printArray();
      
          std::cout << " -> tests passed" << std::endl;
        }
      
        void testStringParsing() {
          std::cout << "========= testStringParsing =======================";
      
          auto dtype = std::make_shared<StructuredDType>(std::vector<std::pair<std::string, DType>>{