123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113 |
- #ifndef _LSUP_BUFFER_H
- #define _LSUP_BUFFER_H
- #include "core.h"
- /** @brief General-purpose data buffer.
- *
- * The structure is transparently exposed so that the related API only defines
- * few basic helper methods. Other operations, such as appending, may be
- * performed by simply using the addr and size attributes.
- *
- * A buffer can be initialized once and reused multiple times, e.g. in a loop,
- * without being freed between iterations, by using #LSUP_buffer_init.
- */
- typedef struct LSUP_Buffer {
- /*@null@*/ void *addr;
- size_t size;
- } LSUP_Buffer;
- /** Initialize or reuse a buffer handle.
- *
- * The handle must have been created with #LSUP_buffer_new*().
- *
- * The data block is resized without being freed first. The handle must be
- * eventually freed with #LSUP_buffer_done() after use.
- *
- * @param buf[in] A buffer handle obtained with #LSUP_buffer_new or by manual
- * allocation.
- *
- * @param size[in] New size.
- *
- * @param data[in] If not NULL, data to replace the existing ones. The size
- * of the data to be copied is determined by the size parameter. If NULL, the
- * existing data are preserved as with a normal realloc().
- */
- LSUP_rc
- LSUP_buffer_init (LSUP_Buffer *buf, const size_t size, const void *data);
- /** @brief Create a new buffer and optionally populate it with data.
- *
- * To change the buffer size and/or data later call #LSUP_buffer_init.
- *
- * To copy a buffer just do buf2 = LSUP_buffer_new (buf1->size, buf1->addr);
- *
- * @param size[in] Length of the data.
- *
- * @param data[in] Optional data to initially populate the object with. If
- * NULL, the buffer data are garbage.
- *
- * @return LSUP_Buffer pointer. It must be freed with #LSUP_buffer_free. NULL
- * on error.
- */
- inline LSUP_Buffer *
- LSUP_buffer_new (const size_t size, const void *data)
- {
- LSUP_Buffer *buf = calloc (1, sizeof (*buf));
- if (!buf) return NULL;
- if (LSUP_buffer_init (buf, size, data) != LSUP_OK) {
- free (buf->addr);
- free (buf);
- return NULL;
- }
- return buf;
- }
- /** @brief Dummy buffer to be used with #LSUP_buffer_init.
- */
- #define BUF_DUMMY LSUP_buffer_new (0, NULL)
- /** @brief Free the content of a buffer.
- */
- void LSUP_buffer_done (LSUP_Buffer *buf);
- /** @brief Free a buffer.
- */
- void LSUP_buffer_free (LSUP_Buffer *buf);
- /** @brief Print a byte string of a given length in a human-readable format.
- *
- * The string is printed in Python style: printable characters are output
- * literally, and non-printable ones as hex sequences.
- */
- void LSUP_buffer_print (const LSUP_Buffer *buf);
- /** @brief Compare two buffers.
- *
- * The return value is the same as memcmp.
- */
- inline int LSUP_buffer_cmp (const LSUP_Buffer *buf1, const LSUP_Buffer *buf2)
- { return memcmp (buf1->addr, buf2->addr, max (buf1->size, buf2->size)); }
- /** @brief Return whether two buffers are equal.
- *
- * This may be faster than #LSUP_buffer_cmp() because it does a size comparison
- * first.
- */
- inline bool LSUP_buffer_eq (const LSUP_Buffer *buf1, const LSUP_Buffer *buf2)
- {
- if (buf1->size != buf2->size) return false;
- return (LSUP_buffer_cmp (buf1, buf2) == 0) ? true : false;
- }
- #endif
|