Docs: Small-string safety comments

Author: ashvardanian

include/stringzilla/small_string.h

@@ -197,9 +197,9 @@ SZ_PUBLIC sz_ptr_t sz_string_expand( //
  *          Performs no allocations or deallocations and can't fail.
  *
  *  @param string       String to clean.
- *  @param offset       Offset of the first byte to remove.
+ *  @param offset       Offset of the first byte to remove. If >= length, no bytes are removed.
  *  @param length       Number of bytes to remove. Out-of-bound ranges will be capped.
- *  @return             Number of bytes removed.
+ *  @return             Number of bytes removed (0 if offset >= string length).
  */
 SZ_PUBLIC sz_size_t sz_string_erase(sz_string_t *string, sz_size_t offset, sz_size_t length);
 

include/stringzilla/stringzilla.hpp

@@ -3452,8 +3452,9 @@ class basic_string {
         // Update the string length appropriately
         if (actual_count > string_length) {
             string_start[actual_count] = '\0';
-            // ! Knowing the layout of the string, we can perform this operation safely,
-            // ! even if its located on stack.
+            // Safe for both SSO and heap strings: on little-endian, internal.length
+            // overlaps with LSB of external.length, so += affects only the length byte.
+            // On big-endian, the struct layout places them at matching positions.
             string_.external.length += actual_count - string_length;
         }
         else { sz_string_erase(&string_, actual_count, SZ_SIZE_MAX); }
@@ -4190,8 +4191,9 @@ bool basic_string<char_type_, allocator_>::try_resize(size_type count, value_typ
     if (count > string_length) {
         sz_fill(string_start + string_length, count - string_length, character);
         string_start[count] = '\0';
-        // Knowing the layout of the string, we can perform this operation safely,
-        // even if its located on stack.
+        // Safe for both SSO and heap strings: on little-endian, internal.length
+        // overlaps with LSB of external.length, so += affects only the length byte.
+        // On big-endian, the struct layout places them at matching positions.
         string_.external.length += count - string_length;
     }
     else { sz_string_erase(&string_, count, SZ_SIZE_MAX); }