str_
====

.. cpp:class:: numpy::str_

   numpy C++ class.

Example
-------

.. code-block:: cpp

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

   // Use str_
   str_ obj;
   // ... operations ...

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

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

   * - Signature
     - Location
     - Example
   * - ``str\_(const std::string &s)``
     - NP_STRING_TYPES.H:22
     - 
   * - ``str\_(const char \*s)``
     - NP_STRING_TYPES.H:27
     - 
   * - ``str\_(const str\_ &other)``
     - NP_STRING_TYPES.H:36
     - 

Operators
---------

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

   * - Signature
     - Return Type
     - Location
     - Example
   * - ``str\_ & operator=(const str\_ &other)``
     - str\_ &
     - NP_STRING_TYPES.H:41
     - 
   * - ``str\_ & operator=(const std::string &s)``
     - str\_ &
     - NP_STRING_TYPES.H:49
     - 
   * - ``operator std::string()``
     - 
     - NP_STRING_TYPES.H:56
     - 
   * - ``bool operator==(const str\_ &other)``
     - bool
     - NP_STRING_TYPES.H:61
     - 
   * - ``bool operator!=(const str\_ &other)``
     - bool
     - NP_STRING_TYPES.H:65
     - 
   * - ``bool operator<(const str\_ &other)``
     - bool
     - NP_STRING_TYPES.H:69
     - 
   * - ``bool operator<=(const str\_ &other)``
     - bool
     - NP_STRING_TYPES.H:73
     - 
   * - ``bool operator>(const str\_ &other)``
     - bool
     - NP_STRING_TYPES.H:77
     - 
   * - ``bool operator>=(const str\_ &other)``
     - bool
     - NP_STRING_TYPES.H:81
     - 
   * - ``str\_ operator+(const str\_ &other)``
     - str\_
     - NP_STRING_TYPES.H:86
     - 
   * - ``str\_ & operator+=(const str\_ &other)``
     - str\_ &
     - NP_STRING_TYPES.H:91
     - 
   * - ``str\_ operator-(const str\_ &other)``
     - str\_
     - NP_STRING_TYPES.H:99
     - 
   * - ``str\_ operator\*(const str\_ &other)``
     - str\_
     - NP_STRING_TYPES.H:104
     - 
   * - ``str\_ operator/(const str\_ &other)``
     - str\_
     - NP_STRING_TYPES.H:109
     - 
   * - ``char & operator[](size_tpos)``
     - char &
     - NP_STRING_TYPES.H:121
     - 
   * - ``const char & operator[](size_tpos)``
     - const char &
     - NP_STRING_TYPES.H:125
     - 

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

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

   * - Signature
     - Return Type
     - Location
     - Example
   * - ``bool empty()``
     - bool
     - NP_STRING_TYPES.H:119
     - :ref:`View <example-str_-empty-0>`

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

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

   * - Signature
     - Return Type
     - Location
     - Example
   * - ``char at_safe(size_tpos)``
     - char
     - NP_STRING_TYPES.H:140
     - :ref:`View <example-str_-at_safe-1>`

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

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

   * - Signature
     - Return Type
     - Location
     - Example
   * - ``const char \* c_str()``
     - const char \*
     - NP_STRING_TYPES.H:115
     - :ref:`View <example-str_-c_str-2>`
   * - ``void clear()``
     - void
     - NP_STRING_TYPES.H:171
     - :ref:`View <example-str_-clear-3>`
   * - ``size_t find(const str\_ &s)``
     - size_t
     - NP_STRING_TYPES.H:166
     - :ref:`View <example-str_-find-4>`
   * - ``size_t length()``
     - size_t
     - NP_STRING_TYPES.H:116
     - :ref:`View <example-str_-length-5>`
   * - ``size_t size()``
     - size_t
     - NP_STRING_TYPES.H:117
     - :ref:`View <example-str_-size-6>`
   * - ``str\_ slice(intstart, intstop = -1)``
     - str\_
     - NP_STRING_TYPES.H:148
     - :ref:`View <example-str_-slice-7>`
   * - ``str\_ substr(size_tpos, size_tlen = N)``
     - str\_
     - NP_STRING_TYPES.H:130
     - :ref:`View <example-str_-substr-8>`


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

The following examples are extracted from the test suite.

.. _example-str_-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-str_-at_safe-1:

.. dropdown:: at_safe (np_test_1_all.cpp:13109)
   :class-title: example-dropdown

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

          std::cout << " -> tests passed" << std::endl;
        }
      
        void test_character_access_bounds() {
          std::cout << "========= test_character_access_bounds =======================";
      
          vstring_ str1("abc");
      
          // Test safe character access within bounds
          try {
            char c1 = str1.at_safe(0);  // Should work
            if (!(c1 == 'a')) {
                std::string description = std::string("test_character_access_bounds():") + __FILE__ + ":" + std::to_string(__LINE__) + ": !(c1 == 'a')";
                std::cout << std::string("[FAIL] ") + description << std::endl;
                throw std::runtime_error(description);
            }
            // std::cout << "[OK] at_safe(0) on 'abc' returns 'a'\n";
      
            char c2 = str1.at_safe(2);  // Should work
            if (!(c2 == 'c')) {
                std::string description = std::string("test_character_access_bounds():") + __FILE__ + ":" + std::to_string(__LINE__) + ": !(c2 == 'c')";

.. _example-str_-c_str-2:

.. dropdown:: c_str (np_test_1_all.cpp:13064)
   :class-title: example-dropdown

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

        }
      
        void test_fixed_size_string_out_of_bounds() {
          std::cout << "========= test_fixed_size_string_out_of_bounds =======================";
      
          // Test str_<N>
          str_<10> str1("hello");  // length = 5, capacity = 10
      
          // Test substr out-of-bounds
          auto result1 = str1.substr(20, 5);
          if (!(std::string(result1.c_str()) == "")) {
              std::string description = std::string("test_fixed_size_string_out_of_bounds():") + __FILE__ + ":" + std::to_string(__LINE__) + ": !(std::string(result1.c_str()) == \"\")";
              std::cout << std::string("[FAIL] ") + description << std::endl;
              throw std::runtime_error(description);
          }
          // std::cout << "[OK] str_<10> substr(20, 5) on 'hello' returns empty string\n";
      
          // Test slice out-of-bounds
          auto result2 = str1.slice(10, 15);
          if (!(std::string(result2.c_str()) == "")) {
              std::string description = std::string("test_fixed_size_string_out_of_bounds():") + __FILE__ + ":" + std::to_string(__LINE__) + ": !(std::string(result2.c_str()) == \"\")";

.. _example-str_-clear-3:

.. dropdown:: clear (np_test_2_all.cpp:4161)
   :class-title: example-dropdown

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

              auto array = createFloat32Array({ 10, 10 }, static_cast<float>(i));
              temp_arrays.push_back(array);
      
              auto view = array.view();
              temp_views.push_back(view);
            }
      
            // std::cout << "Created 100 arrays and 100 views" << std::endl;
      
            // Clear all arrays (views will keep memory alive)
            temp_arrays.clear();
            // std::cout << "Cleared original arrays" << std::endl;
      
            // Verify views still work
            if (!(temp_views[50].getElementAt({ 5, 5 }) == 50.0f)) {
                std::string description = std::string("testMemoryLeakPrevention():") + __FILE__ + ":" + std::to_string(__LINE__) + ": !(temp_views[50].getElementAt({ 5, 5 }) == 50.0f)";
                std::cout << std::string("[FAIL] ") + description << std::endl;
                throw std::runtime_error(description);
            }
            // std::cout << "[OK] Views still valid after originals cleared";
      

.. _example-str_-find-4:

.. dropdown:: find (np_test_1_all.cpp:1324)
   :class-title: example-dropdown

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

          // Test incompatible shapes
          auto a = createFloat64Array({2, 3});
          auto b = createFloat64Array({4});  // Incompatible for broadcasting
      
          bool caught_exception = false;
          try {
              auto result = greater(a, b);
          } catch (const std::invalid_argument& e) {
              caught_exception = true;
              std::string msg(e.what());
              bool has_msg = msg.find("incompatible shapes") != std::string::npos;
              if (has_msg != true) {
                  std::cout << "[FAIL] in testComparisonErrorHandling(): exception message missing 'incompatible shapes', got: " << msg << std::endl;
                  throw std::runtime_error("testComparisonErrorHandling(): exception message incorrect");
              }
          }
          if (caught_exception != true) {
              std::cout << "[FAIL] in testComparisonErrorHandling(): expected exception not thrown" << std::endl;
              throw std::runtime_error("testComparisonErrorHandling(): shape incompatibility exception not thrown");
          }
          // std::cout << "[OK] Shape incompatibility exception handling" << std::endl;

.. _example-str_-length-5:

.. dropdown:: length (np_test_1_all.cpp:7335)
   :class-title: example-dropdown

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

      
          std::cout << " -> tests passed" << std::endl;
      }
      
      void testStringTruncationStringTypes() {
          std::cout << "========= testStringTruncationStringTypes =======================";
      
          // Test truncation behavior
          str8 small("This string is way too long for 8 characters");
          // std::cout << "Long string in str8: '" << small << "'" << std::endl;
          // std::cout << "Length: " << small.length() << " (max: " << str8::max_size << ")" << std::endl;
      
          str16 medium("This is a medium length string that should be truncated");
          // std::cout << "Medium string in str16: '" << medium << "'" << std::endl;
          // std::cout << "Length: " << medium.length() << " (max: " << str16::max_size << ")" << std::endl;
      
          std::cout << " -> tests passed" << std::endl;
      }
      
      void testStringComparisonsStringTypes() {
          std::cout << "========= testStringComparisonsStringTypes =======================";

.. _example-str_-size-6:

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

.. _example-str_-slice-7:

.. 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-str_-substr-8:

.. dropdown:: substr (np_test_1_all.cpp:7373)
   :class-title: example-dropdown

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

          str32 s2(" World");
      
          str32 s3 = s1 + s2;
          // std::cout << "'" << s1 << "' + '" << s2 << "' = '" << s3 << "'" << std::endl;
      
          s1 += s2;
          // std::cout << "After +=: '" << s1 << "'" << std::endl;
      
          // Test substring
          str32 full("Programming");
          str32 sub = full.substr(0, 7);
          // std::cout << "Substring of '" << full << "' (0,7): '" << sub << "'" << std::endl;
      
          // Test find
          str32 search("Hello World Programming");
          size_t pos = search.find(str32("World"));
          // std::cout << "Position of 'World' in '" << search << "': " << pos << std::endl;
      
          // Test utility functions
          str32 lower = to_lower(str32("UPPERCASE"));
          str32 upper = to_upper(str32("lowercase"));