toolkit: comparison ucx/cx/buffer.h

-:118e2386d5b4
+:063a9f29098c
 * 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
+/**
+* Function pointer for cxBufferWrite that is compatible with cx_write_func.
+* @see cx_write_func
+*/
+#define cxBufferWriteFunc  ((cx_write_func) cxBufferWrite)
+/**
+* Function pointer for cxBufferRead that is compatible with cx_read_func.
+* @see cx_read_func
+*/
+#define cxBufferReadFunc  ((cx_read_func) cxBufferRead)
 /**
 * Configuration for automatic flushing.
 */
 struct cx_buffer_flush_config_s {
 */
 cx_write_func wfunc;
 };
 /**
-* Type alais for the flush configuration struct.
+* Type alias for the flush configuration struct.
 *
 * @code
 * struct cx_buffer_flush_config_s {
 *     size_t threshold;
 *     size_t blksize;
 /**
 * Optional flush configuration
 *
 * @see cxBufferEnableFlushing()
 */
-CxBufferFlushConfig* flush;
+CxBufferFlushConfig *flush;
 /** Current position of the buffer. */
 size_t pos;
 /** Current capacity (i.e. maximum size) of the buffer. */
 size_t capacity;
 /** Current size of the buffer content. */
 * (if @c NULL, a default stdlib allocator 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_attr_export
 int cxBufferInit(
 CxBuffer *buffer,
 void *space,
 size_t capacity,
 const CxAllocator *allocator,
 * @retval non-zero failure
 * @see cxBufferFlush()
 * @see cxBufferWrite()
 */
 cx_attr_nonnull
+cx_attr_export
 int cxBufferEnableFlushing(
 CxBuffer *buffer,
 CxBufferFlushConfig config
 );
 *
 * @param buffer the buffer which contents shall be destroyed
 * @see cxBufferInit()
 */
 cx_attr_nonnull
+cx_attr_export
 void cxBufferDestroy(CxBuffer *buffer);
 /**
 * Deallocates the buffer.
 *
 * case it does nothing.
 *
 * @param buffer the buffer to deallocate
 * @see cxBufferCreate()
 */
+cx_attr_export
 void cxBufferFree(CxBuffer *buffer);
 /**
 * Allocates and initializes a fresh buffer.
 *
 * @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_attr_export
 CxBuffer *cxBufferCreate(
 void *space,
 size_t capacity,
 const CxAllocator *allocator,
 int flags
 * @retval non-zero if a required auto-extension or copy-on-write fails
 * @see cxBufferShiftLeft()
 * @see cxBufferShiftRight()
 */
 cx_attr_nonnull
+cx_attr_export
 int cxBufferShift(
 CxBuffer *buffer,
 off_t shift
 );
 * @retval zero success
 * @retval non-zero if a required auto-extension or copy-on-write fails
 * @see cxBufferShift()
 */
 cx_attr_nonnull
+cx_attr_export
 int cxBufferShiftRight(
 CxBuffer *buffer,
 size_t shift
 );
 * @retval zero success
 * @retval non-zero if the buffer uses copy-on-write and the allocation fails
 * @see cxBufferShift()
 */
 cx_attr_nonnull
+cx_attr_export
 int cxBufferShiftLeft(
 CxBuffer *buffer,
 size_t shift
 );
 * @retval zero success
 * @retval non-zero if the position is invalid
 *
 */
 cx_attr_nonnull
+cx_attr_export
 int cxBufferSeek(
 CxBuffer *buffer,
 off_t offset,
 int whence
 );
 *
 * @param buffer the buffer to be cleared
 * @see cxBufferReset()
 */
 cx_attr_nonnull
+cx_attr_export
 void cxBufferClear(CxBuffer *buffer);
 /**
 * Resets the buffer by resetting the position and size to zero.
 *
 *
 * @param buffer the buffer to be cleared
 * @see cxBufferClear()
 */
 cx_attr_nonnull
+cx_attr_export
 void cxBufferReset(CxBuffer *buffer);
 /**
 * Tests, if the buffer position has exceeded the buffer size.
 *
 * byte of the buffer's contents
 * @retval false otherwise
 */
 cx_attr_nonnull
 cx_attr_nodiscard
+cx_attr_export
 bool cxBufferEof(const CxBuffer *buffer);
 /**
 * Ensures that the buffer has a minimum capacity.
 * @param capacity the minimum required capacity for this buffer
 * @retval zero the capacity was already sufficient or successfully increased
 * @retval non-zero on allocation failure
 */
 cx_attr_nonnull
+cx_attr_export
 int cxBufferMinimumCapacity(
 CxBuffer *buffer,
 size_t capacity
 );
 *
 * If flushing is enabled and the buffer needs to flush, the data is flushed to
 * the target until the target signals that it cannot take more data by
 * returning zero via the respective write function. In that case, the remaining
 * data in this buffer is shifted to the beginning of this buffer so that the
-* newly available space can be used to append as much data as possible. This
+* newly available space can be used to append as much data as possible.
-* function only stops writing more elements, when the flush target and this
+*
+* This function only stops writing more elements, when the flush target and this
 * buffer are both incapable of taking more data or all data has been written.
-* If number of items that shall be written is larger than the buffer can hold,
+*
-* the first items from @c ptr are directly relayed to the flush target, if
+* If, after flushing, the number of items that shall be written still exceeds
-* possible.
+* the capacity or flush threshold, this function tries to write all items directly
-* The number returned by this function is only the number of elements from
+* to the flush target, if possible.
-* @c ptr that could be written to either the flush target or the buffer.
+*
+* The number returned by this function is the number of elements from
+* @c ptr that could be written to either the flush target or the buffer
+* (so it does not include the number of items that had been already in the buffer
+* in were flushed during the process).
+*
+* @attention
+* When @p size is larger than one and the contents of the buffer are not aligned
+* with @p size, flushing stops after all complete items have been flushed, leaving
+* the mis-aligned part in the buffer.
+* Afterward, this function only writes as many items as possible to the buffer.
 *
 * @note The signature is compatible with the fwrite() family of functions.
 *
 * @param ptr a pointer to the memory area containing the bytes to be written
 * @param size the length of one element
 * @return the total count of elements written
 * @see cxBufferAppend()
 * @see cxBufferRead()
 */
 cx_attr_nonnull
+cx_attr_export
 size_t cxBufferWrite(
 const void *ptr,
 size_t size,
 size_t nitems,
 CxBuffer *buffer
 * @return the total count of elements written
 * @see cxBufferWrite()
 * @see cxBufferRead()
 */
 cx_attr_nonnull
+cx_attr_export
 size_t cxBufferAppend(
 const void *ptr,
 size_t size,
 size_t nitems,
 CxBuffer *buffer
 * @param buffer the buffer
 * @return the number of successfully flushed bytes
 * @see cxBufferEnableFlushing()
 */
 cx_attr_nonnull
+cx_attr_export
 size_t cxBufferFlush(CxBuffer *buffer);
 /**
 * Reads data from a CxBuffer.
 *
 * @return the total number of elements read
 * @see cxBufferWrite()
 * @see cxBufferAppend()
 */
 cx_attr_nonnull
+cx_attr_export
 size_t cxBufferRead(
 void *ptr,
 size_t size,
 size_t nitems,
 CxBuffer *buffer
 * @return the byte that has been written or @c EOF when the end of the stream is
 * reached and automatic extension is not enabled or not possible
 * @see cxBufferTerminate()
 */
 cx_attr_nonnull
+cx_attr_export
 int cxBufferPut(
 CxBuffer *buffer,
 int c
 );
 *
 * @param buffer the buffer to write to
 * @return zero, if the terminator could be written, non-zero otherwise
 */
 cx_attr_nonnull
+cx_attr_export
 int cxBufferTerminate(CxBuffer *buffer);
 /**
 * Writes a string to a buffer.
 *
 * @param str the zero-terminated string
 * @return the number of bytes written
 */
 cx_attr_nonnull
 cx_attr_cstr_arg(2)
+cx_attr_export
 size_t cxBufferPutString(
 CxBuffer *buffer,
 const char *str
 );
 *
 * @param buffer the buffer to read from
 * @return the character or @c EOF, if the end of the buffer is reached
 */
 cx_attr_nonnull
+cx_attr_export
 int cxBufferGet(CxBuffer *buffer);
 #ifdef __cplusplus
 }
 #endif

Mercurial > hg > toolkit / file comparison

comparison: ucx/cx/buffer.h

ucx/cx/buffer.h