ucx: comparison src/cx/properties.h

-:83620ba72cc1
+:8cab3d8e0af4
 cxPropertiesInit(prop, cx_properties_config_default)
 /**
 * 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() until the status is #CX_PROPERTIES_NO_DATA.
+* cxPropertiesNext().
 *
-* @param prop the properties interface
+* @attention The properties interface tries to avoid allocations.
-* @param buf a pointer to data
+* 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 the data
 * @param len the length of the data
 * @return non-zero when a memory allocation was necessary but failed
 */
 cx_attr_nonnull
 cx_attr_access_r(2, 3)
 size_t len
 );
 #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,
 cxstring str
 ) {
 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,
 cxmutstr str
 ) {
 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(
 CxProperties *prop,
 const char *str
 }
 extern "C" {
 #else // __cplusplus
 /**
-* Fills the input buffer with a string.
+* Fills the input buffer with data.
 *
-* Currently unprocessed data is copied to a temporary buffer.
+* After calling this function, you can parse the data by calling
-* This temporary buffer is allocated on the heap, unless you specified
+* cxPropertiesNext().
-* a buffer on the stack with #cxPropertiesUseStack().
+*
-* In that case, the stack buffer is used, until the capacity is not sufficient
+* @attention The properties interface tries to avoid allocations.
-* anymore.
+* When you use this function and cxPropertiesNext() interleaving,
-*
+* no allocations are performed. However, you must not free the
-* @param prop the properties interface
+* pointer to the data in that case. When you invoke the fill
-* @param str the string
+* 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 text to fill in
 * @return non-zero when a memory allocation was necessary but failed
 */
 #define cxPropertiesFill(prop, str) _Generic((str), \
 cxstring: cx_properties_fill_cxstr,             \
 cxmutstr: cx_properties_fill_mutstr,            \
 char*: cx_properties_fill_str,                  \
 const char*: cx_properties_fill_str)            \
 (prop, str)
 /**
-* Implementation of cxPropertiesFill() for cxstring.
+* @copydoc cxPropertiesFill()
-*
-* @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 cx_properties_fill_cxstr(
 CxProperties *prop,
 cxstring str
 ) {
 return cxPropertiesFilln(prop, str.ptr, str.length);
 }
 /**
-* Implementation of cxPropertiesFill() for cxmutstr.
+* @copydoc cxPropertiesFill()
-*
-* @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 cx_properties_fill_mutstr(
 CxProperties *prop,
 cxmutstr str
 ) {
 return cxPropertiesFilln(prop, str.ptr, str.length);
 }
 /**
-* Implementation of cxPropertiesFill() for zero terminated C strings.
+* @copydoc cxPropertiesFill()
-*
-* @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 cx_properties_fill_str(
 CxProperties *prop,
 *
 * This function returns zero as long as there are key/value-pairs found.
 * 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
+* returned, and you can add more data with #cxPropertiesFill().
-* affected line. You can then 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
 * use.
 *

Mercurial > hg > ucx / file comparison

comparison: src/cx/properties.h

src/cx/properties.h