#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_reset.
 */
typedef struct LSUP_Buffer {
    /*@null@*/ void *addr;
    size_t size;
} LSUP_Buffer;


/** Reuse an initialized buffer handle.
 *
 * The data block is resized without being freed (with realloc). If the new
 * size is not smaller than the old one and the data parameter is NULL, the
 * existing data are preserved. If the size is increased, the new memory is not
 * initialized.
 *
 * The handle must be 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.
 */
LSUP_rc
LSUP_buffer_reset (LSUP_Buffer *buf, const size_t size, const void *data);


/** Initialize an allocated buffer handle.
 *
 * The handle must be freed with #LSUP_buffer_done after use.
 *
 * @param buf[in] A manually (stack or heap) allocated buffer handle.
 *
 * @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.
 */
inline LSUP_rc
LSUP_buffer_init (LSUP_Buffer *buf, const size_t size, const void *data)
{
    buf->addr = NULL;
    return LSUP_buffer_reset(buf, size, data);
}


/** @brief Create a new buffer and optionally populate it with data.
 *
 * To change the buffer size later call #LSUP_buffer_reset.
 *
 * 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.
 *
 * @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;
    CRITICAL (buf = malloc (sizeof (*buf)));

    if (LSUP_buffer_init (buf, size, data) != LSUP_OK) {
        free (buf);
        return NULL;
    }

    return buf;
}


/** @brief Dummy buffer to be used with #LSUP_buffer_reset.
 */
#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 returns immediately if
 * the sizes of the buffers differ.
 */
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