wget2/libwget/buffer.c

/*
 * Copyright (c) 2012 Tim Ruehsen
 * Copyright (c) 2015-2024 Free Software Foundation, Inc.
 *
 * This file is part of libwget.
 *
 * Libwget is free software: you can redistribute it and/or modify
 * it under the terms of the GNU Lesser General Public License as published by
 * the Free Software Foundation, either version 3 of the License, or
 * (at your option) any later version.
 *
 * Libwget is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public License
 * along with libwget.  If not, see <https://www.gnu.org/licenses/>.
 *
 *
 * Memory buffer data structure routines
 *
 * Changelog
 * 22.08.2012  Tim Ruehsen  created
 *
 */

#include <config.h>

#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <ctype.h>

#include <wget.h>
#include "private.h"

/**
 * \file
 * \brief Buffer management functions
 * \defgroup libwget-buffer Buffer management functions
 * @{
 *
 * A buffer (represented with an opaque `wget_buffer`) is a managed memory area.
 *
 * Apart from a pointer to a raw chunk of memory (`char *`), it also has some metadata attached
 * such as the length of the buffer and the actual occupied positions.
 *
 * Actually, when we talk about the **length** of the buffer, we refer to the actual number of bytes stored
 * in it by the user. On the other hand, the **size** is the total number of slots in the buffer, either occupied
 * or not.
 *
 * The stored data is always 0-terminated, so you safely use it with standard string functions.
 *
 * The functions here allow you to easily work with buffers, providing shortcuts to commonly used
 * memory and string management operations and avoiding usual pitfalls, such as buffer overflows.
 * They provide a higher-level abstraction to working with memory than the @link libwget-mem memory management functions@endlink.
 *
 * If your application uses memory allocation functions that may return %NULL values (e.g. like the standard libc functions),
 * you have to check the `error` value before using the result. If set, it indicates that a memory allocation failure
 * occurred during internal (re-)allocation.
 *
 * Example with wget_buffer on the stack (initial 16 bytes heap allocation)
 * ```
 * wget_buffer buf;
 *
 * wet_buffer_init(&buf, NULL, 16);
 *
 * wget_buffer_strcpy(&buf, "A");
 * wget_buffer_strcat(&buf, "B");
 * wget_buffer_memcat(&buf, "C", 1);
 * wget_buffer_memset_append(&buf, 'D', 1);
 * wget_buffer_printf_append(&buf, "%s", "E");
 *
 * // buf.data now contains the 0-terminated string "ABCDE"
 * printf("buf.data = %s\n", buf.data);
 *
 * wget_buffer_deinit(&buf);
 * ```
 *
 * Example with wget_buffer on the stack and 16 bytes initial stack buffer (no heap allocation is needed)
 * ```
 * wget_buffer buf;
 * char sbuf[16];
 *
 * wet_buffer_init(&buf, sbuf, sizeof(sbuf));
 *
 * wget_buffer_strcpy(&buf, "A");
 * wget_buffer_strcat(&buf, "B");
 * wget_buffer_memcat(&buf, "C", 1);
 * wget_buffer_memset_append(&buf, 'D', 1);
 * wget_buffer_printf_append(&buf, "%s", "E");
 *
 * // buf.data now contains the 0-terminated string "ABCDE"
 * printf("buf.data = %s\n", buf.data);
 *
 * wget_buffer_deinit(&buf);
 * ```
 *
 * Example on how to check for memory failure and how to transfer buffer data
 * ```
 * wget_buffer buf;
 *
 * wet_buffer_init(&buf, NULL, 16);
 *
 * wget_buffer_strcpy(&buf, "A");
 * wget_buffer_strcat(&buf, "B");
 * wget_buffer_memcat(&buf, "C", 1);
 * wget_buffer_memset_append(&buf, 'D', 1);
 * wget_buffer_printf_append(&buf, "%s", "E");
 *
 *	if (buf.error)
 *		panic("No memory !");
 *
 *	// transfer ownership away from wget_buffer
 *	char *ret = buf.data;
 *	buf.data = NULL; // avoid double frees
 *
 * wget_buffer_deinit(&buf);
 *
 *	return ret; // the caller must free() this value after use
 * ```
 */

/**
 * \param[in] buf Pointer to the buffer that should become initialized.
 * \param[in] data Initial contents of the buffer. Might be NULL.
 * \param[in] size Initial length of the buffer. Might be zero (will default to 128 bytes).
 * \return WGET_E_SUCCESS or WGET_E_MEMORY in case of a memory allocation failure.
 *
 * Create a new buffer.
 *
 * If \p data is NULL, the buffer will be empty, but it will be pre-allocated with \p size bytes.
 * This will make future operations on the buffer faster since there will be less re-allocations needed.
 *
 * <b>If \p size is zero, the buffer will be pre-allocated with 128 bytes.</b>
 *
 * You may provide some \p data to fill the buffer with it. The contents of the \p data pointer
 * are not copied, but rather the pointer itself is referenced directly within the buffer. If you modify the contents
 * of \p data, those changes will be reflected in the buffer as they both point to the same memory area.
 *
 * Apart from that, there are other concerns you should keep in mind if you provide your own \p data here:
 *
 *  - wget_buffer_deinit() _will not_ free that memory when you call it. So if you provide
 * a \p data pointer, you must free it yourself before your program ends.
 *  - wget_buffer_realloc() will also not free that memory. It will allocate a new buffer and copy the contents
 *  there, but will not touch the old buffer. The new buffer _will_ be freed by these functions since it's been
 *  allocated by libwget internally and thus it knows it can be freed without harm.
 *
 * If an existing buffer is provided in \p buf, it will be initialized with the provided \p data and \p size
 * according to the rules stated above.
 */
int wget_buffer_init(wget_buffer *buf, char *data, size_t size)
{
	if (data && likely(size)) {
		buf->size = size - 1;
		buf->data = data;
		*buf->data = 0; // always 0 terminate data to allow string functions
		buf->release_data = 0;
	} else {
		if (!size)
			size = 127;
		buf->size = size;
		if (!(buf->data = wget_malloc(size + 1))) {
			buf->error = 1;
			return WGET_E_MEMORY;
		}
		*buf->data = 0; // always 0 terminate data to allow string functions
		buf->release_data = 1;
	}

	buf->error = 0;
	buf->release_buf = 0;
	buf->length = 0;

	return WGET_E_SUCCESS;
}

/**
 * \param[in] size Initial length of the buffer.
 * \return A new buffer.
 *
 * Allocates a new buffer of size \p size bytes.
 *
 * The buffer will be pre-allocated with that many bytes, all zeros.
 *
 * This is equivalent to wget_buffer_init(NULL, NULL, size).
 */
wget_buffer *wget_buffer_alloc(size_t size)
{
	wget_buffer *buf;

	if (!(buf = wget_malloc(sizeof(wget_buffer))))
		return NULL;

	if (wget_buffer_init(buf, NULL, size) < 0) {
		xfree(buf);
		return NULL;
	}

	buf->release_buf = 1;

	return buf;
}

static int buffer_realloc(wget_buffer *buf, size_t size)
{
	char *old_data = buf->data;

	if (buf->release_data)
		buf->data = wget_realloc(buf->data, size + 1);
	else
		buf->data = wget_malloc(size + 1);

	if (!buf->data) {
		buf->data = old_data;
		buf->error = 1;
		return WGET_E_MEMORY;
	}

	if (!buf->release_data) {
		if (likely(old_data) && buf->length)
			memcpy(buf->data, old_data, buf->length + 1);
		else
			*buf->data = 0; // always 0 terminate data to allow string functions

		buf->release_data = 1;
	}

	buf->size = size;

	return WGET_E_SUCCESS;
}

/**
 * \param[in] buf A buffer, created with wget_buffer_init() or wget_buffer_alloc()
 * \param[in] size Total size (in bytes) required in the buffer
 * \return WGET_E_SUCCESS on success, else WGET_E_MEMORY if the memory allocation failed
 *
 * Make sure the buffer \p buf has at least a **size** of \p size bytes.
 *
 * If the buffer's size is less than that, it will automatically enlarge it
 * (with wget_buffer_realloc()) to make it at least as long.
 */
int wget_buffer_ensure_capacity(wget_buffer *buf, size_t size)
{
	if (likely(buf)) {
		if (buf->size < size)
			return buffer_realloc(buf, size);
	}

	return WGET_E_SUCCESS;
}

/**
 * \param[in] buf A buffer, created with wget_buffer_init() or wget_buffer_alloc()
 *
 * Free the buffer, and all its contents.
 *
 * If you provided your own data when calling wget_buffer_init() (you passed a non-NULL \p data pointer)
 * then **that buffer will not be freed**. As stated in the description of wget_buffer_init() you
 * must free that buffer yourself: this function will only free the `wget_buffer` structure.
 *
 * Similarly, if you provided your own buffer when calling wget_buffer_init() (\p buf was non-NULL)
 * the buffer (the `wget_buffer` structure) **will not** be freed, and the data might or might not be freed
 * depending on the above condition.
 */
void wget_buffer_deinit(wget_buffer *buf)
{
	if (buf->release_data) {
		xfree(buf->data);
		buf->release_data = 0;
	}

	if (buf->release_buf)
		wget_free(buf); // do not use xfree() since buf is NONNULL
}

/**
 * \param[in] buf A double pointer to a buffer
 *
 * Free the buffer, and all its contents.
 *
 * It behaves like wget_buffer_deinit() but it also sets the \p buf pointer to NULL.
 *
 * This function is equivalent to:
 *
 *     wget_buffer_deinit(*buf);
 *     *buf = NULL;
 */
void wget_buffer_free(wget_buffer **buf)
{
	if (likely(buf && *buf)) {
		wget_buffer_deinit(*buf);
		*buf = NULL;
	}
}

/**
 * \param[in] buf A buffer, created with wget_buffer_init() or wget_buffer_alloc()
 *
 * Release the buffer's data, but keep the buffer itself (the `wget_buffer` structure).
 *
 * The **length** of the buffer will be maintained, but after this function succeeds, the **size**
 * will obviously be zero.
 *
 * The same rules that apply to wget_buffer_deinit() also apply here: if you provided your own data
 * when calling wget_buffer_init() (ie. \p data was non-NULL) then **that data will not be freed**, and this
 * function will essentially be a no-op.
 */
void wget_buffer_free_data(wget_buffer *buf)
{
	if (likely(buf)) {
		if (buf->release_data) {
			xfree(buf->data);
			buf->release_data = 0;
			buf->size = 0;
		}
	}
}

/**
 * \param[in] buf A buffer, created with wget_buffer_init() or wget_buffer_alloc()
 *
 * This function is lighter than wget_buffer_free_data(). It does not free the data buffer, it just
 * sets its first byte to zero, as well as the length.
 *
 * This function is equivalent to:
 *
 *     buf->length = 0;
 *     *buf->data = 0;
 */
void wget_buffer_reset(wget_buffer *buf)
{
	if (likely(buf)) {
		buf->length = 0;
		*buf->data = 0;
	}
}

/**
 * \param[in] buf  A buffer, created with wget_buffer_init() or wget_buffer_alloc()
 * \param[in] data A pointer to the data to be copied
 * \param[in] length How many bytes from \p data (starting at the beginning) should be copied
 * \return The new length of the buffer after copying the data
 *
 * Copy the contents in the pointer \p data to the buffer \p buf,
 * clobbering the previous contents.
 *
 * The first \p length bytes of \p data are written to \p buf.
 * The content of \p buf is overwritten with the new \p data.
 *
 * If the buffer is not large enough to store that amount of data,
 * it is enlarged automatically at least \p length bytes (with wget_buffer_realloc()).
 */
size_t wget_buffer_memcpy(wget_buffer *buf, const void *data, size_t length)
{
	if (unlikely(!buf))
		return 0;

	buf->length = 0;

	return wget_buffer_memcat(buf, data, length);
}

/**
 * \param[in] buf A buffer, created with wget_buffer_init() or wget_buffer_alloc()
 * \param[in] data A pointer to the data to be appended
 * \param[in] length How many bytes of \p data should be written to \p buf
 * \return The new length of the buffer after appending the data
 *
 * Append the provided \p data to the end of the buffer \p buf (preserving contents).
 *
 * If there's not enough space in \p buf, it is enlarged automatically
 * (with wget_buffer_realloc()) at least \p length bytes, so that the whole
 * data can be written.
 */
size_t wget_buffer_memcat(wget_buffer *buf, const void *data, size_t length)
{
	if (unlikely(!buf))
		return 0;

	if (likely(length)) {
		if (buf->size < buf->length + length)
			if (buffer_realloc(buf, buf->size * 2 + length) != WGET_E_SUCCESS)
				return buf->length;

		if (likely(data))
			memcpy(buf->data + buf->length, data, length);
		else
			memset(buf->data + buf->length, 0, length);
		buf->length += length;
	}
	buf->data[buf->length] = 0; // always 0 terminate data to allow string functions

	return buf->length;
}

/**
 * \param[in] buf A buffer, created with wget_buffer_init() or wget_buffer_alloc()
 * \param[in] s A NULL-terminated string
 * \return The new length of the buffer after copying the string
 *
 * Copy the NULL-terminated string \p s to the buffer \p buf,
 * overwriting its original contents.
 *
 * If the buffer is not large enough it is enlarged automatically.
 *
 * This is essentially equivalent to:
 *
 *     buf->length = 0;
 *     wget_buffer_memcat(buf, s, strlen(s));
 */
size_t wget_buffer_strcpy(wget_buffer *buf, const char *s)
{
	if (likely(buf))
		buf->length = 0;

	return wget_buffer_memcat(buf, s, likely(s) ? strlen(s) : 0);
}

/**
 * \param[in] buf A buffer, created with wget_buffer_init() or wget_buffer_alloc()
 * \param[in] s A NULL-terminated string
 * \return The new length of the buffer after appending the string
 *
 * Append the NULL-terminated string \p s to the end of the buffer  \p buf
 * (preserving its contents).
 *
 * If the buffer is not large enough it is enlarged automatically.
 *
 * This is essentially equivalent to calling wget_buffer_memcat() with length equal to `strlen(s)`:
 *
 *     wget_buffer_memcat(buf, s, strlen(s));
 */
size_t wget_buffer_strcat(wget_buffer *buf, const char *s)
{
	return wget_buffer_memcat(buf, s, likely(s) ? strlen(s) : 0);
}

/**
 * \param[in] buf The destination buffer
 * \param[in] src The source buffer
 * \return The new length of the destination buffer \p buf after copying the contents of \p src
 *
 * Copy the contents of the buffer \p src in the buffer \p buf,
 * clobbering its previous contents.
 *
 * If the buffer \p buf is not large enough it is enlarged automatically.
 *
 * This is equivalent to:
 *
 *     wget_buffer_memcpy(buf, src->data, src->length);
 */
size_t wget_buffer_bufcpy(wget_buffer *buf, wget_buffer *src)
{
	if (likely(src))
		return wget_buffer_memcpy(buf, src->data, src->length);
	else
		return wget_buffer_memcpy(buf, NULL, 0);
}

/**
 * \param[in] buf The destination buffer
 * \param[in] src The source buffer
 * \return The new length of the destination buffer \p buf after appending the contents of \p src
 *
 * Append the contents of the buffer \p src to the end of the buffer \p buf.
 *
 * If the buffer \p buf is not large enough it is enlarged automatically.
 *
 * This is equivalent to:
 *
 *     wget_buffer_memcat(buf, src->data, src->length);
 */
size_t wget_buffer_bufcat(wget_buffer *buf, wget_buffer *src)
{
	if (likely(src))
		return wget_buffer_memcat(buf, src->data, src->length);
	else
		return wget_buffer_memcat(buf, NULL, 0);
}

/**
 * \param[in] buf A buffer, created with wget_buffer_init() or wget_buffer_alloc()
 * \param[in] c The byte to be copied at the end of the buffer
 * \param[in] length How many times will the byte \p c be copied.
 * \return The new length of the buffer \p buf.
 *
 * Copy the byte \p c repeatedly \p length times **starting at the beginning of the buffer**,
 * so the first \p length bytes of the buffer are overwritten.
 *
 * If there's not enough space in \p buf, it is enlarged automatically
 * (with wget_buffer_realloc()) at least \p length bytes.
 */
size_t wget_buffer_memset(wget_buffer *buf, char c, size_t length)
{
	if (likely(buf))
		buf->length = 0;

	return wget_buffer_memset_append(buf, c, length);
}

/**
 * \param[in] buf A buffer, created with wget_buffer_init() or wget_buffer_alloc()
 * \param[in] c The byte to be copied at the end of the buffer
 * \param[in] length How many times will the byte \p c be copied.
 * \return The new length of the buffer \p buf.
 *
 * Copy the byte \p c at the end of the buffer \p buf repeatedly \p length times.
 *
 * If there's not enough space in \p buf, it is enlarged automatically
 * (with wget_buffer_realloc()) at least \p length bytes.
 */
size_t wget_buffer_memset_append(wget_buffer *buf, char c, size_t length)
{
	if (unlikely(!buf))
		return 0;

	if (likely(length)) {
		if (unlikely(buf->size < buf->length + length))
			if (buffer_realloc(buf, buf->size * 2 + length) != WGET_E_SUCCESS)
				return buf->length;

		memset(buf->data + buf->length, c, length);
		buf->length += length;
	}
	buf->data[buf->length] = 0; // always 0 terminate data to allow string functions

	return buf->length;
}

/**
 * \param[in] buf A buffer, created with wget_buffer_init() or wget_buffer_alloc()
 * \return The buffer's new contents
 *
 * Remove all leading and trailing whitespace from the buffer \p buf.
 *
 * The transformation is done in-place, that is, the buffer's original content is overwritten
 * with the new trimmed content.
 */
char *wget_buffer_trim(wget_buffer *buf)
{
	if (unlikely(!buf))
		return NULL;

	while (buf->length > 0 && isspace(buf->data[buf->length - 1])) {
		buf->length--;
	}
	buf->data[buf->length] = 0;

	size_t spaces = 0;
	while (buf->length > 0 && isspace(buf->data[spaces]))
		spaces++;

	if (spaces) {
		buf->length -= spaces;
		/* Include trailing 0 */
		memmove(buf->data, buf->data + spaces, buf->length + 1);
	}

	return buf->data;
}
/** @} */