Mercurial > hg > ucx / file diff

--- a/src/cx/json.h	Fri Dec 27 12:23:14 2024 +0100
+++ b/src/cx/json.h	Fri Dec 27 13:01:31 2024 +0100
@@ -398,6 +398,10 @@
      */
     CX_JSON_OK,
     /**
+     * The input buffer has never been filled.
+     */
+    CX_JSON_NULL_DATA,
+    /**
      * Allocating memory for the internal buffer failed.
      */
     CX_JSON_BUFFER_ALLOC_FAILED,
@@ -455,9 +459,15 @@
 }
 
 /**
- * Adds more data to the input buffer.
+ * Fills the input buffer.
  *
- * The data will be copied.
+ * @remark The JSON interface tries to avoid copying the input data.
+ * When you use this function and cxJsonNext() interleaving,
+ * no copies 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 cxJsonNext(),
+ * the additional data is appended - inevitably leading to
+ * an allocation of a new buffer and copying the previous contents.
  *
  * @param json the json interface
  * @param buf the source buffer
@@ -500,12 +510,18 @@
 extern "C" {
 #else // __cplusplus
 /**
- * Adds more data to the input buffer.
+ * Fills the input buffer.
  *
- * The data will be copied.
+ * @remark The JSON interface tries to avoid copying the input data.
+ * When you use this function and cxJsonNext() interleaving,
+ * no copies 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 cxJsonNext(),
+ * the additional data is appended - inevitably leading to
+ * an allocation of a new buffer and copying the previous contents.
  *
  * @param json the json interface
- * @param str the string to add to the buffer
+ * @param buf the source string
  * @return zero on success, non-zero on internal allocation error
  * @see cxJsonFilln()
  */