#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 Format a buffer into anb ASCII string.
 *
 * The string has non-printable characters escaped as "\xNN".
 *
 * @param buf[in] Buffer to convert.
 *
 * @return Formatted string. It must be freed with free().
 */
char *
LSUP_buffer_as_str (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