StructuredDType
===============

.. cpp:class:: numpy::StructuredDType

   numpy C++ class.

Example
-------

.. code-block:: cpp

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

   // Use StructuredDType
   StructuredDType obj;
   // ... operations ...

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

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

   * - Signature
     - Location
     - Example
   * - ``StructuredDType(const std::vector<std::pair<std::string,DType>>&field_specs, boolpacked = false)``
     - NP_STRUCTURED_DTYPE.H:104
     - 
   * - ``StructuredDType(const std::vector<FieldDescriptor>&fields, boolpacked = false)``
     - NP_STRUCTURED_DTYPE.H:117
     - 

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

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

   * - Signature
     - Return Type
     - Location
     - Example
   * - ``size_t getAlignment()``
     - size_t
     - NP_STRUCTURED_DTYPE.H:148
     - 
   * - ``const FieldDescriptor & getField(const std::string &name)``
     - const FieldDescriptor &
     - NP_STRUCTURED_DTYPE.H:127
     - :ref:`View <example-structureddtype-getfield-0>`
   * - ``const FieldDescriptor & getField(size_tindex)``
     - const FieldDescriptor &
     - NP_STRUCTURED_DTYPE.H:135
     - :ref:`View <example-structureddtype-getfield-1>`
   * - ``size_t getFieldAlignment(DTypedtype)``
     - size_t
     - NP_STRUCTURED_DTYPE.H:90
     - 
   * - ``size_t getFieldCount()``
     - size_t
     - NP_STRUCTURED_DTYPE.H:146
     - :ref:`View <example-structureddtype-getfieldcount-2>`
   * - ``size_t getFieldIndex(const std::string &name)``
     - size_t
     - NP_STRUCTURED_DTYPE.H:160
     - 
   * - ``const std::vector<FieldDescriptor>& getFields()``
     - const std::vector<FieldDescriptor>&
     - NP_STRUCTURED_DTYPE.H:125
     - 
   * - ``size_t getTotalSize()``
     - size_t
     - NP_STRUCTURED_DTYPE.H:147
     - 

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

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

   * - Signature
     - Return Type
     - Location
     - Example
   * - ``void calculateLayout()``
     - void
     - NP_STRUCTURED_DTYPE.H:65
     - 
   * - ``std::string dtypeToString(DTypedtype)``
     - std::string
     - NP_STRUCTURED_DTYPE.H:190
     - 
   * - ``bool hasField(const std::string &name)``
     - bool
     - NP_STRUCTURED_DTYPE.H:142
     - :ref:`View <example-structureddtype-hasfield-3>`
   * - ``bool isPacked()``
     - bool
     - NP_STRUCTURED_DTYPE.H:149
     - 
   * - ``std::string toString()``
     - std::string
     - NP_STRUCTURED_DTYPE.H:168
     - :ref:`View <example-structureddtype-tostring-4>`


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

The following examples are extracted from the test suite.

.. _example-structureddtype-getfield-0:

.. dropdown:: getField (np_test_2_all.cpp:18700)
   :class-title: example-dropdown

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

      
          void np_test_io_extensions_recfromcsv_dtype_detection() {
            std::cout << "========= recfromcsv: automatic dtype detection =======================";
      
            create_csv_file("test_dtypes.csv");
      
            auto data = numpy::io::recfromcsv(csv_test_dir + "test_dtypes.csv");
            auto dtype = data.getDType();
      
            // Verify string field detected
            auto name_dtype = dtype.getField("name").dtype;
            if (name_dtype != numpy::DType::STR32 && name_dtype != numpy::DType::STR16 &&
              name_dtype != numpy::DType::STR8 && name_dtype != numpy::DType::STR64) {
              std::cout << "  [FAIL] : Expected STRING type for name field" << std::endl;
              throw std::runtime_error("np_test_io_extensions_recfromcsv_dtype_detection failed: wrong name dtype");
            }
      
            // Verify integer field detected
            auto age_dtype = dtype.getField("age").dtype;
            if (age_dtype != numpy::DType::INT64 && age_dtype != numpy::DType::INT32) {
              std::cout << "  [FAIL] : Expected INT type for age field";

.. _example-structureddtype-getfield-1:

.. dropdown:: getField (np_test_2_all.cpp:18700)
   :class-title: example-dropdown

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

      
          void np_test_io_extensions_recfromcsv_dtype_detection() {
            std::cout << "========= recfromcsv: automatic dtype detection =======================";
      
            create_csv_file("test_dtypes.csv");
      
            auto data = numpy::io::recfromcsv(csv_test_dir + "test_dtypes.csv");
            auto dtype = data.getDType();
      
            // Verify string field detected
            auto name_dtype = dtype.getField("name").dtype;
            if (name_dtype != numpy::DType::STR32 && name_dtype != numpy::DType::STR16 &&
              name_dtype != numpy::DType::STR8 && name_dtype != numpy::DType::STR64) {
              std::cout << "  [FAIL] : Expected STRING type for name field" << std::endl;
              throw std::runtime_error("np_test_io_extensions_recfromcsv_dtype_detection failed: wrong name dtype");
            }
      
            // Verify integer field detected
            auto age_dtype = dtype.getField("age").dtype;
            if (age_dtype != numpy::DType::INT64 && age_dtype != numpy::DType::INT32) {
              std::cout << "  [FAIL] : Expected INT type for age field";

.. _example-structureddtype-getfieldcount-2:

.. dropdown:: getFieldCount (np_test_2_all.cpp:18627)
   :class-title: example-dropdown

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

      
            // Verify shape
            if (data.getShape()[0] != 3) {
              std::cout << "  [FAIL] : in np_test_io_extensions_recfromcsv_basic() : Expected 3 rows, got "
                << data.getShape()[0] << std::endl;
              throw std::runtime_error("np_test_io_extensions_recfromcsv_basic failed: wrong row count");
            }
      
            // Verify field count
            auto dtype = data.getDType();
            if (dtype.getFieldCount() != 5) {
              std::cout << "  [FAIL] : in np_test_io_extensions_recfromcsv_basic() : Expected 5 fields, got "
                << dtype.getFieldCount() << std::endl;
              throw std::runtime_error("np_test_io_extensions_recfromcsv_basic failed: wrong field count");
            }
      
            // Verify field names
            if (!dtype.hasField("name") || !dtype.hasField("age") || !dtype.hasField("salary")) {
              std::cout << "  [FAIL] : in np_test_io_extensions_recfromcsv_basic() : Missing expected fields";
              throw std::runtime_error("np_test_io_extensions_recfromcsv_basic failed: missing fields");
            }

.. _example-structureddtype-hasfield-3:

.. dropdown:: hasField (np_test_2_all.cpp:18634)
   :class-title: example-dropdown

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

      
            // Verify field count
            auto dtype = data.getDType();
            if (dtype.getFieldCount() != 5) {
              std::cout << "  [FAIL] : in np_test_io_extensions_recfromcsv_basic() : Expected 5 fields, got "
                << dtype.getFieldCount() << std::endl;
              throw std::runtime_error("np_test_io_extensions_recfromcsv_basic failed: wrong field count");
            }
      
            // Verify field names
            if (!dtype.hasField("name") || !dtype.hasField("age") || !dtype.hasField("salary")) {
              std::cout << "  [FAIL] : in np_test_io_extensions_recfromcsv_basic() : Missing expected fields";
              throw std::runtime_error("np_test_io_extensions_recfromcsv_basic failed: missing fields");
            }
      
            // Verify data values
            auto name = data.getFieldValue<numpy::str32>({ 0 }, "name");
            if (std::string(name) != "Alice") {
              std::cout << "  [FAIL] : Expected 'Alice', got '" << std::string(name) << "'";
              throw std::runtime_error("np_test_io_extensions_recfromcsv_basic failed: wrong name");
            }

.. _example-structureddtype-tostring-4:

.. 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");