Mercurial > hg > toolkit / file diff

--- a/ucx/cx/buffer.h	Fri Dec 12 12:44:03 2025 +0100
+++ b/ucx/cx/buffer.h	Sat Dec 13 12:11:40 2025 +0100
@@ -48,6 +48,7 @@
 
 #include "common.h"
 #include "allocator.h"
+#include "string.h"
 
 #ifdef __cplusplus
 extern "C" {
@@ -89,6 +90,13 @@
 #define CX_BUFFER_COPY_ON_EXTEND 0x08
 
 /**
+ * If this flag is enabled, the buffer will never free its contents regardless of #CX_BUFFER_FREE_CONTENTS.
+ *
+ * This is useful, for example, when you want to keep a pointer to the data after destroying the buffer.
+ */
+#define CX_BUFFER_DO_NOT_FREE 0x10
+
+/**
  * Function pointer for cxBufferWrite that is compatible with cx_write_func.
  * @see cx_write_func
  */
@@ -538,29 +546,61 @@
 /**
  * Writes a terminating zero to a buffer at the current position.
  *
- * If successful, sets the size to the current position and advances
- * the position by one.
+ * If successful, also sets the size to the current position and shrinks the buffer.
  *
  * The purpose of this function is to have the written data ready to be used as
  * a C string with the buffer's size being the length of that string.
  *
  * @param buffer the buffer to write to
  * @return zero, if the terminator could be written, non-zero otherwise
+ * @see cxBufferShrink()
  */
 cx_attr_nonnull
 CX_EXPORT int cxBufferTerminate(CxBuffer *buffer);
 
 /**
- * Writes a string to a buffer.
- *
- * This is a convenience function for <code>cxBufferWrite(str, 1, strlen(str), buffer)</code>.
+ * Internal function - do not use.
  *
  * @param buffer the buffer
- * @param str the zero-terminated string
+ * @param str the string
  * @return the number of bytes written
+ * @see cxBufferPutString()
+ */
+cx_attr_nonnull
+CX_EXPORT size_t cx_buffer_put_string(CxBuffer *buffer, cxstring str);
+
+/**
+ * Writes a string to a buffer with cxBufferWrite().
+ *
+ * @param buffer (@c CxBuffer*) the buffer
+ * @param str (any string) the zero-terminated string
+ * @return (@c size_t) the number of bytes written
+ * @see cxBufferWrite()
+ * @see cx_strcast()
  */
-cx_attr_nonnull cx_attr_cstr_arg(2)
-CX_EXPORT size_t cxBufferPutString(CxBuffer *buffer, const char *str);
+#define cxBufferPutString(buffer, str) cx_buffer_put_string(buffer, cx_strcast(str))
+
+/**
+ * Internal function - do not use.
+ *
+ * @param buffer the buffer
+ * @param str the string
+ * @return the number of bytes written
+ * @see cxBufferPutString()
+ */
+cx_attr_nonnull
+CX_EXPORT size_t cx_buffer_append_string(CxBuffer *buffer, cxstring str);
+
+/**
+ * Appends a string to a buffer with cxBufferAppend().
+ *
+ * @param buffer (@c CxBuffer*) the buffer
+ * @param str (any string) the zero-terminated string
+ * @return (@c size_t) the number of bytes written
+ * @see cxBufferAppend()
+ * @see cx_strcast()
+ */
+#define cxBufferAppendString(buffer, str) cx_buffer_append_string(buffer, cx_strcast(str))
 
 /**
  * Gets a character from a buffer.