Add C API functions for safe string attribute retrieval

eisenhauer · claude · eisenhauer · commit 3dfd463004e7 · 2026-01-14T15:19:44.000-05:00
New functions that support a two-call pattern to retrieve string attribute
data of unknown length (first call with NULL buffer to get length, then
allocate and call again to get data):

- adios2_attribute_string_data() - for single-value string attributes
- adios2_attribute_string_data_array() - for string array attributes

Co-Authored-By: Claude Opus 4.5 &lt;noreply@anthropic.com&gt;
diff --git a/bindings/C/adios2/c/adios2_c_attribute.cpp b/bindings/C/adios2/c/adios2_c_attribute.cpp
@@ -192,6 +192,105 @@ adios2_error adios2_attribute_data(void *data, size_t *size, const adios2_attrib
     }
 }
 
+adios2_error adios2_attribute_string_data(const adios2_attribute *attribute, char *data,
+                                          size_t *length)
+{
+    try
+    {
+        adios2::helper::CheckForNullptr(attribute,
+                                        "for attribute, in call to adios2_attribute_string_data");
+        adios2::helper::CheckForNullptr(
+            length, "for size_t *length, in call to adios2_attribute_string_data");
+
+        const adios2::core::AttributeBase *attributeBase =
+            reinterpret_cast<const adios2::core::AttributeBase *>(attribute);
+
+        if (attributeBase->m_Type != adios2::helper::GetDataType<std::string>())
+        {
+            throw std::invalid_argument("ERROR: attribute " + attributeBase->m_Name +
+                                        " is not of string type, in call to "
+                                        "adios2_attribute_string_data\n");
+        }
+
+        if (!attributeBase->m_IsSingleValue)
+        {
+            throw std::invalid_argument("ERROR: attribute " + attributeBase->m_Name +
+                                        " is not a single value, use "
+                                        "adios2_attribute_string_data_array instead, in call to "
+                                        "adios2_attribute_string_data\n");
+        }
+
+        const adios2::core::Attribute<std::string> *attributeCpp =
+            dynamic_cast<const adios2::core::Attribute<std::string> *>(attributeBase);
+
+        *length = attributeCpp->m_DataSingleValue.size();
+
+        if (data != nullptr)
+        {
+            attributeCpp->m_DataSingleValue.copy(data, *length);
+        }
+
+        return adios2_error_none;
+    }
+    catch (...)
+    {
+        return static_cast<adios2_error>(
+            adios2::helper::ExceptionToError("adios2_attribute_string_data"));
+    }
+}
+
+adios2_error adios2_attribute_string_data_array(const adios2_attribute *attribute, char **data,
+                                                size_t *lengths)
+{
+    try
+    {
+        adios2::helper::CheckForNullptr(
+            attribute, "for attribute, in call to adios2_attribute_string_data_array");
+        adios2::helper::CheckForNullptr(
+            lengths, "for size_t *lengths, in call to adios2_attribute_string_data_array");
+
+        const adios2::core::AttributeBase *attributeBase =
+            reinterpret_cast<const adios2::core::AttributeBase *>(attribute);
+
+        if (attributeBase->m_Type != adios2::helper::GetDataType<std::string>())
+        {
+            throw std::invalid_argument("ERROR: attribute " + attributeBase->m_Name +
+                                        " is not of string type, in call to "
+                                        "adios2_attribute_string_data_array\n");
+        }
+
+        if (attributeBase->m_IsSingleValue)
+        {
+            throw std::invalid_argument("ERROR: attribute " + attributeBase->m_Name +
+                                        " is a single value, use "
+                                        "adios2_attribute_string_data instead, in call to "
+                                        "adios2_attribute_string_data_array\n");
+        }
+
+        const adios2::core::Attribute<std::string> *attributeCpp =
+            dynamic_cast<const adios2::core::Attribute<std::string> *>(attributeBase);
+
+        const size_t count = attributeCpp->m_Elements;
+
+        for (size_t i = 0; i < count; ++i)
+        {
+            lengths[i] = attributeCpp->m_DataArray[i].size();
+
+            if (data != nullptr)
+            {
+                attributeCpp->m_DataArray[i].copy(data[i], lengths[i]);
+            }
+        }
+
+        return adios2_error_none;
+    }
+    catch (...)
+    {
+        return static_cast<adios2_error>(
+            adios2::helper::ExceptionToError("adios2_attribute_string_data_array"));
+    }
+}
+
 #ifdef __cplusplus
 } // end extern C
 #endif
diff --git a/bindings/C/adios2/c/adios2_c_attribute.h b/bindings/C/adios2/c/adios2_c_attribute.h
@@ -78,6 +78,74 @@ adios2_error adios2_attribute_size(size_t *size, const adios2_attribute *attribu
  */
 adios2_error adios2_attribute_data(void *data, size_t *size, const adios2_attribute *attribute);
 
+/**
+ * Retrieve a single-value string attribute's data.
+ *
+ * This function supports a two-call pattern to safely retrieve string
+ * attributes of unknown length:
+ *   1. Call with data=NULL to get the string length
+ *   2. Allocate a buffer of at least (length + 1) bytes
+ *   3. Call again with the buffer to retrieve the string data
+ *
+ * The returned length does NOT include a null terminator. The caller
+ * is responsible for null-terminating the string if needed.
+ *
+ * @param attribute handler for a single-value string attribute
+ * @param data pre-allocated buffer for string data, or NULL to only query length
+ * @param length output: the string length in bytes (excludes null terminator)
+ * @return adios2_error 0: success, see enum adios2_error for errors
+ *
+ * Example usage:
+ * @code
+ *   size_t length;
+ *   adios2_attribute_string_data(attr, NULL, &length);  // get length
+ *   char *str = (char *)malloc(length + 1);
+ *   adios2_attribute_string_data(attr, str, &length);   // get data
+ *   str[length] = '\0';                                 // null terminate
+ * @endcode
+ */
+adios2_error adios2_attribute_string_data(const adios2_attribute *attribute, char *data,
+                                          size_t *length);
+
+/**
+ * Retrieve string data from a string array attribute.
+ *
+ * This function supports a two-call pattern to safely retrieve string
+ * arrays of unknown lengths:
+ *   1. Call adios2_attribute_size() to get the number of strings
+ *   2. Allocate a lengths array of that size
+ *   3. Call with data=NULL to get the length of each string
+ *   4. Allocate each string buffer based on the lengths
+ *   5. Call again with the allocated buffers to retrieve the string data
+ *
+ * The returned lengths do NOT include null terminators. The caller
+ * is responsible for null-terminating each string if needed.
+ *
+ * @param attribute handler for a string array attribute
+ * @param data array of pre-allocated buffers (char**), or NULL to only query lengths
+ * @param lengths output: array of string lengths in bytes (excludes null terminators).
+ *                Must be pre-allocated with size from adios2_attribute_size().
+ * @return adios2_error 0: success, see enum adios2_error for errors
+ *
+ * Example usage:
+ * @code
+ *   size_t count;
+ *   adios2_attribute_size(&count, attr);               // get array size
+ *   size_t *lengths = (size_t *)malloc(count * sizeof(size_t));
+ *   adios2_attribute_string_data_array(attr, NULL, lengths);  // get lengths
+ *   char **strings = (char **)malloc(count * sizeof(char*));
+ *   for (size_t i = 0; i < count; i++) {
+ *       strings[i] = (char *)malloc(lengths[i] + 1);
+ *   }
+ *   adios2_attribute_string_data_array(attr, strings, lengths);  // get data
+ *   for (size_t i = 0; i < count; i++) {
+ *       strings[i][lengths[i]] = '\0';                // null terminate
+ *   }
+ * @endcode
+ */
+adios2_error adios2_attribute_string_data_array(const adios2_attribute *attribute, char **data,
+                                                size_t *lengths);
+
 #ifdef __cplusplus
 } // end extern C
 #endif
diff --git a/docs/user_guide/source/introduction/whatsnew.rst b/docs/user_guide/source/introduction/whatsnew.rst
@@ -5,11 +5,16 @@ What's new in master?
 C API Improvements
 ------------------
 
-New ``adios2_get_string()`` function for safely retrieving string variables
-of unknown length. This function supports a two-call pattern: first call with
-a NULL buffer to query the string length, then call again with an allocated
-buffer to retrieve the data. This addresses a gap in the C API where string
-variable lengths could not be queried before reading.
+New functions for safely retrieving string data of unknown length using a
+two-call pattern (first call with NULL buffer to query length, then call
+again with allocated buffer to retrieve data):
+
+- ``adios2_get_string()`` - for string variables
+- ``adios2_attribute_string_data()`` - for single-value string attributes
+- ``adios2_attribute_string_data_array()`` - for string array attributes
+
+This addresses a gap in the C API where string lengths could not be queried
+before reading.
 
 
 ===================
diff --git a/testing/adios2/bindings/C/TestBPWriteTypes.cpp b/testing/adios2/bindings/C/TestBPWriteTypes.cpp
@@ -264,6 +264,56 @@ TEST_F(ADIOS2_C_API, ADIOS2BPWriteTypes)
         EXPECT_EQ(dataVector[3], "fourth");
         EXPECT_EQ(elements, 4);
 
+        // Test adios2_attribute_string_data with the two-call pattern (single value)
+        size_t attrStrLength = 0;
+        adios2_error errAttrStr = adios2_attribute_string_data(attrSingle, NULL, &attrStrLength);
+        EXPECT_EQ(errAttrStr, adios2_error_none);
+        EXPECT_EQ(attrStrLength, strlen("Hello Attribute"));
+
+        char *attrStrData = new char[attrStrLength + 1];
+        errAttrStr = adios2_attribute_string_data(attrSingle, attrStrData, &attrStrLength);
+        EXPECT_EQ(errAttrStr, adios2_error_none);
+        attrStrData[attrStrLength] = '\0';
+        EXPECT_EQ(std::string(attrStrData), "Hello Attribute");
+        delete[] attrStrData;
+
+        // Test adios2_attribute_string_data_array with the two-call pattern (array)
+        size_t attrArrayCount = 0;
+        adios2_attribute_size(&attrArrayCount, attrArray);
+        EXPECT_EQ(attrArrayCount, 4u);
+
+        size_t *attrArrayLengths = new size_t[attrArrayCount];
+        adios2_error errAttrArr =
+            adios2_attribute_string_data_array(attrArray, NULL, attrArrayLengths);
+        EXPECT_EQ(errAttrArr, adios2_error_none);
+        EXPECT_EQ(attrArrayLengths[0], strlen("first"));
+        EXPECT_EQ(attrArrayLengths[1], strlen("second"));
+        EXPECT_EQ(attrArrayLengths[2], strlen("third"));
+        EXPECT_EQ(attrArrayLengths[3], strlen("fourth"));
+
+        char **attrArrayData = new char *[attrArrayCount];
+        for (size_t i = 0; i < attrArrayCount; ++i)
+        {
+            attrArrayData[i] = new char[attrArrayLengths[i] + 1];
+        }
+        errAttrArr = adios2_attribute_string_data_array(attrArray, attrArrayData, attrArrayLengths);
+        EXPECT_EQ(errAttrArr, adios2_error_none);
+        for (size_t i = 0; i < attrArrayCount; ++i)
+        {
+            attrArrayData[i][attrArrayLengths[i]] = '\0';
+        }
+        EXPECT_EQ(std::string(attrArrayData[0]), "first");
+        EXPECT_EQ(std::string(attrArrayData[1]), "second");
+        EXPECT_EQ(std::string(attrArrayData[2]), "third");
+        EXPECT_EQ(std::string(attrArrayData[3]), "fourth");
+
+        for (size_t i = 0; i < attrArrayCount; ++i)
+        {
+            delete[] attrArrayData[i];
+        }
+        delete[] attrArrayData;
+        delete[] attrArrayLengths;
+
         // compare min and max
         auto mmI8 = std::minmax_element(&data_I8[0], &data_I8[data_Nx]);
         auto mmI16 = std::minmax_element(&data_I16[0], &data_I16[data_Nx]);
