dbutils: comparison ucx/cx/buffer.h

-:d33eaaec15da
+:287484519844
 #ifndef UCX_BUFFER_H
 #define UCX_BUFFER_H
 #include "common.h"
 #include "allocator.h"
+#include "string.h"
 #ifdef __cplusplus
 extern "C" {
 #endif
 * After performing the copy, the flag is automatically cleared.
 * This flag has no effect on buffers which do not have #CX_BUFFER_AUTO_EXTEND set, which is why
 * buffers automatically admit the auto-extend flag when initialized with copy-on-extend enabled.
 */
 #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
 */
 * the #CX_BUFFER_FREE_CONTENTS flag. In that case, specifying
 * copy-on-write should be avoided, because the allocated
 * space will be leaking after the copy-on-write operation.
 *
 * @param buffer the buffer to initialize
+* @param allocator the allocator this buffer shall use for automatic
+* memory management
+* (if @c NULL, the cxDefaultAllocator will be used)
 * @param space pointer to the memory area, or @c NULL to allocate
 * new memory
 * @param capacity the capacity of the buffer
-* @param allocator the allocator this buffer shall use for automatic
-* memory management
-* (if @c NULL, the cxDefaultAllocator will be used)
 * @param flags buffer features (see cx_buffer_s.flags)
 * @return zero on success, non-zero if a required allocation failed
 */
 cx_attr_nonnull_arg(1)
-CX_EXPORT int cxBufferInit(CxBuffer *buffer, void *space, size_t capacity,
+CX_EXPORT int cxBufferInit(CxBuffer *buffer, const CxAllocator *allocator,
-const CxAllocator *allocator, int flags);
+void *space, size_t capacity, int flags);
 /**
 * Destroys the buffer contents.
 *
 * Has no effect if the #CX_BUFFER_FREE_CONTENTS feature is not enabled.
 *
 * @note You may provide @c NULL as the argument for @p space.
 * Then this function will allocate the space and enforce
 * the #CX_BUFFER_FREE_CONTENTS flag.
 *
+* @param allocator the allocator to use for allocating the structure and the automatic
+* memory management within the buffer
+* (if @c NULL, the cxDefaultAllocator will be used)
 * @param space pointer to the memory area, or @c NULL to allocate
 * new memory
 * @param capacity the capacity of the buffer
-* @param allocator the allocator to use for allocating the structure and the automatic
-* memory management within the buffer
-* (if @c NULL, the cxDefaultAllocator will be used)
 * @param flags buffer features (see cx_buffer_s.flags)
 * @return a pointer to the buffer on success, @c NULL if a required allocation failed
 */
 cx_attr_malloc cx_attr_dealloc(cxBufferFree, 1) cx_attr_nodiscard
-CX_EXPORT CxBuffer *cxBufferCreate(void *space, size_t capacity,
+CX_EXPORT CxBuffer *cxBufferCreate(const CxAllocator *allocator, void *space,
-const CxAllocator *allocator, int flags);
+size_t capacity, int flags);
 /**
 * Shifts the contents of the buffer by the given offset.
 *
 * If the offset is positive, the contents are shifted to the right.
 CX_EXPORT int cxBufferPut(CxBuffer *buffer, int c);
 /**
 * Writes a terminating zero to a buffer at the current position.
 *
-* If successful, sets the size to the current position and advances
+* If successful, also sets the size to the current position and shrinks the buffer.
-* the position by one.
 *
 * 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.
+* Internal function - do not use.
 *
-* This is a convenience function for <code>cxBufferWrite(str, 1, strlen(str), buffer)</code>.
+* @param buffer the buffer
-*
+* @param str the string
-* @param buffer the buffer
-* @param str the zero-terminated string
 * @return the number of bytes written
-*/
+* @see cxBufferPutString()
-cx_attr_nonnull cx_attr_cstr_arg(2)
+*/
-CX_EXPORT size_t cxBufferPutString(CxBuffer *buffer, const char *str);
+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()
+*/
+#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.
 *
 * The current position of the buffer is increased after a successful read.

Mercurial > hg > dbutils / file comparison

comparison: ucx/cx/buffer.h

ucx/cx/buffer.h