Mercurial > code
view c/buf/buf.h.in @ 671:2bee2b6b6386
asprintf: fix Windows impl
author | David Demelier <markand@malikania.fr> |
---|---|
date | Thu, 24 Mar 2022 07:29:22 +0100 |
parents | 325be9bbc68f |
children |
line wrap: on
line source
/* * %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 */