Mercurial > hg > ucx / changeset

--- a/src/cx/properties.h	Fri Dec 20 21:09:20 2024 +0100
+++ b/src/cx/properties.h	Fri Dec 20 21:22:25 2024 +0100
@@ -367,17 +367,19 @@
 /**
  * Fills the input buffer with data.
  *
- * Currently unprocessed data is copied to a temporary buffer.
- * This temporary buffer is allocated on the heap, unless you specified
- * a buffer on the stack with #cxPropertiesUseStack().
- * In that case, the stack buffer is used, until the capacity is not sufficient
- * anymore.
+ * After calling this function, you can parse the data by calling
+ * cxPropertiesNext().
  *
- * After calling this function, you can parse the data by calling
- * cxPropertiesNext() until the status is #CX_PROPERTIES_NO_DATA.
+ * @attention The properties interface tries to avoid allocations.
+ * When you use this function and cxPropertiesNext() interleaving,
+ * no allocations are performed. However, you must not free the
+ * pointer to the data in that case. When you invoke the fill
+ * function more than once before calling cxPropertiesNext(),
+ * the additional data is appended - inevitably leading to
+ * an allocation of a new buffer and copying the previous contents.
  *
  * @param prop the properties interface
- * @param buf a pointer to data
+ * @param buf a pointer to the data
  * @param len the length of the data
  * @return non-zero when a memory allocation was necessary but failed
  */
@@ -391,19 +393,6 @@
 
 #ifdef __cplusplus
 } // extern "C"
-/**
- * Fills the input buffer with a string.
- *
- * Currently unprocessed data is copied to a temporary buffer.
- * This temporary buffer is allocated on the heap, unless you specified
- * a buffer on the stack with #cxPropertiesUseStack().
- * In that case, the stack buffer is used, until the capacity is not sufficient
- * anymore.
- *
- * @param prop the properties interface
- * @param str the string
- * @return non-zero when a memory allocation was necessary but failed
- */
 cx_attr_nonnull
 static inline int cxPropertiesFill(
         CxProperties *prop,
@@ -412,19 +401,6 @@
     return cxPropertiesFilln(prop, str.ptr, str.length);
 }
 
-/**
- * Fills the input buffer with a string.
- *
- * Currently unprocessed data is copied to a temporary buffer.
- * This temporary buffer is allocated on the heap, unless you specified
- * a buffer on the stack with #cxPropertiesUseStack().
- * In that case, the stack buffer is used, until the capacity is not sufficient
- * anymore.
- *
- * @param prop the properties interface
- * @param str the string
- * @return non-zero when a memory allocation was necessary but failed
- */
 cx_attr_nonnull
 static inline int cxPropertiesFill(
         CxProperties *prop,
@@ -433,19 +409,6 @@
     return cxPropertiesFilln(prop, str.ptr, str.length);
 }
 
-/**
- * Fills the input buffer with a string.
- *
- * Currently unprocessed data is copied to a temporary buffer.
- * This temporary buffer is allocated on the heap, unless you specified
- * a buffer on the stack with #cxPropertiesUseStack().
- * In that case, the stack buffer is used, until the capacity is not sufficient
- * anymore.
- *
- * @param prop the properties interface
- * @param str the string
- * @return non-zero when a memory allocation was necessary but failed
- */
 cx_attr_nonnull
 cx_attr_cstr_arg(2)
 static inline int cxPropertiesFill(
@@ -458,16 +421,21 @@
 extern "C" {
 #else // __cplusplus
 /**
- * Fills the input buffer with a string.
+ * Fills the input buffer with data.
+ *
+ * After calling this function, you can parse the data by calling
+ * cxPropertiesNext().
  *
- * Currently unprocessed data is copied to a temporary buffer.
- * This temporary buffer is allocated on the heap, unless you specified
- * a buffer on the stack with #cxPropertiesUseStack().
- * In that case, the stack buffer is used, until the capacity is not sufficient
- * anymore.
+ * @attention The properties interface tries to avoid allocations.
+ * When you use this function and cxPropertiesNext() interleaving,
+ * no allocations are performed. However, you must not free the
+ * pointer to the data in that case. When you invoke the fill
+ * function more than once before calling cxPropertiesNext(),
+ * the additional data is appended - inevitably leading to
+ * an allocation of a new buffer and copying the previous contents.
  *
  * @param prop the properties interface
- * @param str the string
+ * @param str the text to fill in
  * @return non-zero when a memory allocation was necessary but failed
  */
 #define cxPropertiesFill(prop, str) _Generic((str), \
@@ -478,11 +446,7 @@
     (prop, str)
 
 /**
- * Implementation of cxPropertiesFill() for cxstring.
- *
- * @param prop the properties interface
- * @param str the string
- * @return non-zero when a memory allocation was necessary but failed
+ * @copydoc cxPropertiesFill()
  */
 cx_attr_nonnull
 static inline int cx_properties_fill_cxstr(
@@ -493,11 +457,7 @@
 }
 
 /**
- * Implementation of cxPropertiesFill() for cxmutstr.
- *
- * @param prop the properties interface
- * @param str the string
- * @return non-zero when a memory allocation was necessary but failed
+ * @copydoc cxPropertiesFill()
  */
 cx_attr_nonnull
 static inline int cx_properties_fill_mutstr(
@@ -508,11 +468,7 @@
 }
 
 /**
- * Implementation of cxPropertiesFill() for zero terminated C strings.
- *
- * @param prop the properties interface
- * @param str the string
- * @return non-zero when a memory allocation was necessary but failed
+ * @copydoc cxPropertiesFill()
  */
 cx_attr_nonnull
 cx_attr_cstr_arg(2)
@@ -545,8 +501,12 @@
  * If no more key/value-pairs are found, #CX_PROPERTIES_NO_DATA is returned.
  *
  * When an incomplete line is encountered, #CX_PROPERTIES_INCOMPLETE_DATA is
- * returned and the position of the input buffer will be the start of the
- * affected line. You can then add more data with #cxPropertiesFill().
+ * returned, and you can add more data with #cxPropertiesFill().
+ *
+ * \remark The incomplete line will be stored in an internal buffer, which is
+ * allocated on the heap, by default. If you want to avoid allocations,
+ * you can specify sufficient space with cxPropertiesUseStack() after
+ * initialization with cxPropertiesInit().
  *
  * \attention The returned strings will point into a buffer that might not be
  * available later. It is strongly recommended to copy the strings for further