ucx: comparison src/cx/buffer.h

-:e8f354a25ac8
+:68754c7de906
 #include "common.h"
 #include "allocator.h"
 #include <sys/types.h>
-#ifdef    __cplusplus
+#ifdef __cplusplus
 extern "C" {
 #endif
 /**
 * No buffer features enabled (all flags cleared).
 * @param allocator the allocator this buffer shall use for automatic
 * memory management. If \c NULL, the default heap allocator will be used.
 * @param flags buffer features (see cx_buffer_s.flags)
 * @return zero on success, non-zero if a required allocation failed
 */
-__attribute__((__nonnull__(1)))
+cx_attr_nonnull_arg(1)
 int cxBufferInit(
 CxBuffer *buffer,
 void *space,
 size_t capacity,
 const CxAllocator *allocator,
 int flags
 );
+/**
+* Destroys the buffer contents.
+*
+* Has no effect if the #CX_BUFFER_FREE_CONTENTS feature is not enabled.
+* If you want to free the memory of the entire buffer, use cxBufferFree().
+*
+* @param buffer the buffer which contents shall be destroyed
+* @see cxBufferInit()
+*/
+cx_attr_nonnull
+void cxBufferDestroy(CxBuffer *buffer);
+/**
+* Deallocates the buffer.
+*
+* If the #CX_BUFFER_FREE_CONTENTS feature is enabled, this function also destroys
+* the contents. If you \em only want to destroy the contents, use cxBufferDestroy().
+*
+* \remark As with all free() functions, this accepts \c NULL arguments in which
+* case it does nothing.
+*
+* @param buffer the buffer to deallocate
+* @see cxBufferCreate()
+*/
+void cxBufferFree(CxBuffer *buffer);
 /**
 * Allocates and initializes a fresh buffer.
 *
 * \note You may provide \c NULL as argument for \p space.
 * @param allocator the allocator to use for allocating the structure and the automatic
 * memory management within the buffer. If \c NULL, the default heap allocator 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
 CxBuffer *cxBufferCreate(
 void *space,
 size_t capacity,
 const CxAllocator *allocator,
 int flags
 );
-/**
-* Destroys the buffer contents.
-*
-* Has no effect if the #CX_BUFFER_FREE_CONTENTS feature is not enabled.
-* If you want to free the memory of the entire buffer, use cxBufferFree().
-*
-* @param buffer the buffer which contents shall be destroyed
-* @see cxBufferInit()
-*/
-__attribute__((__nonnull__))
-void cxBufferDestroy(CxBuffer *buffer);
-/**
-* Deallocates the buffer.
-*
-* If the #CX_BUFFER_FREE_CONTENTS feature is enabled, this function also destroys
-* the contents. If you \em only want to destroy the contents, use cxBufferDestroy().
-*
-* @param buffer the buffer to deallocate
-* @see cxBufferCreate()
-*/
-__attribute__((__nonnull__))
-void cxBufferFree(CxBuffer *buffer);
 /**
 * Shifts the contents of the buffer by the given offset.
 *
 * If the offset is positive, the contents are shifted to the right.
 *
 * @param buffer the buffer
 * @param shift the shift offset (negative means left shift)
 * @return 0 on success, non-zero if a required auto-extension fails
 */
-__attribute__((__nonnull__))
+cx_attr_nonnull
 int cxBufferShift(
 CxBuffer *buffer,
 off_t shift
 );
 * @param buffer the buffer
 * @param shift the shift offset
 * @return 0 on success, non-zero if a required auto-extension fails
 * @see cxBufferShift()
 */
-__attribute__((__nonnull__))
+cx_attr_nonnull
 int cxBufferShiftRight(
 CxBuffer *buffer,
 size_t shift
 );
 * @param buffer the buffer
 * @param shift the positive shift offset
 * @return always zero
 * @see cxBufferShift()
 */
-__attribute__((__nonnull__))
+cx_attr_nonnull
 int cxBufferShiftLeft(
 CxBuffer *buffer,
 size_t shift
 );
 * @param offset position offset relative to \p whence
 * @param whence one of \c SEEK_SET, \c SEEK_CUR or \c SEEK_END
 * @return 0 on success, non-zero if the position is invalid
 *
 */
-__attribute__((__nonnull__))
+cx_attr_nonnull
 int cxBufferSeek(
 CxBuffer *buffer,
 off_t offset,
 int whence
 );
 * If you do not need that, you can use the faster cxBufferReset().
 *
 * @param buffer the buffer to be cleared
 * @see cxBufferReset()
 */
-__attribute__((__nonnull__))
+cx_attr_nonnull
 void cxBufferClear(CxBuffer *buffer);
 /**
 * Resets the buffer by resetting the position and size to zero.
 *
 * reset of the buffer, use cxBufferClear().
 *
 * @param buffer the buffer to be cleared
 * @see cxBufferClear()
 */
-__attribute__((__nonnull__))
+cx_attr_nonnull
 void cxBufferReset(CxBuffer *buffer);
 /**
 * Tests, if the buffer position has exceeded the buffer size.
 *
 * @param buffer the buffer to test
 * @return non-zero, if the current buffer position has exceeded the last
 * byte of the buffer's contents.
 */
-__attribute__((__nonnull__))
+cx_attr_nonnull
+cx_attr_nodiscard
 int cxBufferEof(const CxBuffer *buffer);
 /**
 * Ensures that the buffer has a minimum capacity.
 *
 * @param buffer the buffer
 * @param capacity the minimum required capacity for this buffer
 * @return 0 on success or a non-zero value on failure
 */
-__attribute__((__nonnull__))
+cx_attr_nonnull
 int cxBufferMinimumCapacity(
 CxBuffer *buffer,
 size_t capacity
 );
 * @param size the length of one element
 * @param nitems the element count
 * @param buffer the CxBuffer to write to
 * @return the total count of elements written
 */
-__attribute__((__nonnull__))
+cx_attr_nonnull
 size_t cxBufferWrite(
 const void *ptr,
 size_t size,
 size_t nitems,
 CxBuffer *buffer
 * @param size the length of one element
 * @param nitems the element count
 * @param buffer the CxBuffer to read from
 * @return the total number of elements read
 */
-__attribute__((__nonnull__))
+cx_attr_nonnull
 size_t cxBufferRead(
 void *ptr,
 size_t size,
 size_t nitems,
 CxBuffer *buffer
 * @param buffer the buffer to write to
 * @param c the character to write
 * @return the byte that has bean written or \c EOF when the end of the stream is
 * reached and automatic extension is not enabled or not possible
 */
-__attribute__((__nonnull__))
+cx_attr_nonnull
 int cxBufferPut(
 CxBuffer *buffer,
 int c
 );
 *
 * @param buffer the buffer
 * @param str the zero-terminated string
 * @return the number of bytes written
 */
-__attribute__((__nonnull__))
+cx_attr_nonnull
+cx_attr_cstr_arg(2)
 size_t cxBufferPutString(
 CxBuffer *buffer,
 const char *str
 );
 * The current position of the buffer is increased after a successful read.
 *
 * @param buffer the buffer to read from
 * @return the character or \c EOF, if the end of the buffer is reached
 */
-__attribute__((__nonnull__))
+cx_attr_nonnull
 int cxBufferGet(CxBuffer *buffer);
 #ifdef __cplusplus
 }
 #endif

Mercurial > hg > ucx / file comparison

comparison: src/cx/buffer.h

src/cx/buffer.h