/*
 * %ns%buf.h -- simple string buffer for C
 *
 * Copyright (c) 2016-2019 David Demelier <markand@malikania.fr>
 *
 * Permission to use, copy, modify, and/or distribute this software for any
 * purpose with or without fee is hereby granted, provided that the above
 * copyright notice and this permission notice appear in all copies.
 *
 * THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
 * WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
 * MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
 * ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
 * WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
 * ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 */

#ifndef %NS%BUF_H
#define %NS%BUF_H

/**
 * \file %ns%buf.h
 * \brief Simple string buffer for C
 *
 * This module is meant to be copied directly into your source code and adapted
 * to your needs.
 *
 * # Allocation strategy
 *
 * This module will always try to allocate twice the existing buffer capacity
 * unless it reaches an overflow. If overflow occurs, it will try to reallocate
 * only the required portion instead. In any case, on 64-bits machine the
 * maximum number is usually around 18.5PB which is far from what the system
 * will allow.
 *
 * Functions use standard `malloc(3)`, `realloc(3)` and `free(3)` functions, if
 * custom allocations are desired, simply edit %ns%buf.c and adapt BUF_ macros
 * at the top of the file.
 */

#include <stdarg.h>
#include <stdbool.h>
#include <stddef.h>

/**
 * \brief Buffer structure.
 *
 * You can initialize this structure with 0 before use.
 *
 * You may modify the data member yourself but make sure length member is set
 * accordingly if you change its length.
 *
 * The capacity member contains the available size **without** including the
 * null terminator, this means that a capacity of 5 means you can write 5
 * characters plus the null terminator as every function always allocate one
 * more byte to terminate strings.
 */
struct %ns%buf {
	char *data;             /*!< (RW) String data. */
	size_t length;          /*!< (RO) String length */
	size_t capacity;        /*!< (RO) Capacity **not** including null */
};

/**
 * Initialize the string.
 *
 * This is equivalent to `memset(b, 0, sizeof (struct buf))`.
 *
 * \pre b != NULL
 * \param b the buffer to initialize to 0
 */
void
%ns%buf_init(struct %ns%buf *b);

/**
 * Reserve more storage to avoid reallocations.
 *
 * This function only change capacity and may reallocate the buffer, length
 * is unchanged.
 *
 * \pre b != NULL
 * \param b the buffer to grow
 * \param desired the additional space to request
 * \return false on error and sets errno
 */
bool
%ns%buf_reserve(struct %ns%buf *b, size_t desired);

/**
 * Resize the string and sets character into the new storage area.
 *
 * In contrast to \ref %ns%buf_reserve, this function change the string length
 * and update the new storage with the given character. Use '\0' if you only
 * want to change the length.
 *
 * \pre b != NULL
 * \param b the buffer to grow
 * \param desired the additional space to request
 * \param ch the character to fill (use '\0' if not needed)
 * \return false on error and sets errno
 */
bool
%ns%buf_resize(struct %ns%buf *b, size_t desired, char ch);

/**
 * Reallocate the string to the string's length.
 *
 * If the function could not reallocate the memory, the old string buffer is
 * kept so it is not strictly necessary to check the result.
 *
 * \pre b != NULL
 * \param b the buffer to grow
 * \return true if the string buffer was actually shrinked
 */
bool
%ns%buf_shrink(struct %ns%buf *b);

/**
 * Erase a portion of the string.
 *
 * \pre b != NULL
 * \pre pos <= b->length
 * \param b the string buffer
 * \param pos the beginning of the portion
 * \param count the number of characters to remove or -1 to remove up to the end
 */
void
%ns%buf_erase(struct %ns%buf *b, size_t pos, size_t count);

/**
 * Put a single character.
 *
 * \note This function can be slow for large amount of data
 * \pre b != NULL
 * \param b the string buffer
 * \param c the character to append
 * \return false on error and sets errno
 */
bool
%ns%buf_putc(struct %ns%buf *b, char c);

/**
 * Put a string.
 *
 * \pre b != NULL
 * \pre s != NULL
 * \param b the string buffer
 * \param s the string to append
 * \return false on error and sets errno
 */
bool
%ns%buf_puts(struct %ns%buf *b, const char *s);

/**
 * Append to the string using printf(3) format.
 *
 * \pre b != NULL
 * \pre fmt != NULL
 * \param b the string buffer
 * \param fmt the printf(3) format string
 * \param ... additional arguments
 * \return false on error and sets errno
 */
bool
%ns%buf_printf(struct %ns%buf *b, const char *fmt, ...);

/**
 * Similar to \ref %ns%buf_printf but using `va_list`.
 *
 * \pre b != NULL
 * \pre fmt != NULL
 * \param b the string buffer
 * \param fmt the printf(3) format string
 * \param ap the variadic arguments pointer
 * \return false on error and sets errno
 */
bool
%ns%buf_vprintf(struct %ns%buf *b, const char *fmt, va_list ap);

/**
 * Cut a portion of the string pointed by src into b.
 *
 * The pointer b must not contain data as it will be overriden and may be let
 * uninitialized.
 *
 * \pre b != NULL
 * \pre src != NULL
 * \pre pos <= b->length
 * \param b the string buffer
 * \param src the source origin
 * \param pos the beginning of the portion
 * \param count the number of characters to remove or -1 to split up to the end
 * \return false on error and sets errno
 */
bool
%ns%buf_sub(struct %ns%buf *b, const struct %ns%buf *src, size_t pos, size_t count);

/**
 * Duplicate a string buffer.
 *
 * The pointer b must not contain data as it will be overriden and may be let
 * uninitialized.
 *
 * \pre b != NULL
 * \pre src != NULL
 * \param b the string buffer
 * \param src the source origin
 * \return false on error and sets errno
 */
bool
%ns%buf_dup(struct %ns%buf *b, const struct %ns%buf *src);

/**
 * Clear the buffer.
 *
 * This function only change the string length, use \ref %ns%buf_shrink if you
 * want to reduce memory usage.
 *
 * \pre b != NULL
 * \param b the string to update
 */
void
%ns%buf_clear(struct %ns%buf *b);

/**
 * Clear the buffer.
 *
 * This function will effectively free the data member and set all members to
 * 0.
 *
 * \pre b != NULL
 * \param b the buffer to clear
 */
void
%ns%buf_finish(struct %ns%buf *b);

#endif /* !%NS%BUF_H */