/*
* Copyright(c) 2012 Tim Ruehsen
* Copyright(c) 2015-2019 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 .
*
*
* Memory buffer data structure routines
*
* Changelog
* 22.08.2012 Tim Ruehsen created
*
*/
#include
#include
#include
#include
#include
#include
#include "private.h"
/**
* \file
* \brief Buffer management functions
* \defgroup libwget-buffer Buffer management functions
* @{
*
* A buffer (represented with an opaque `wget_buffer_t`) 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 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.
*/
/**
* \param[in] buf An existing buffer, or NULL.
* \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 A new buffer (if \p buf is NULL), or the provided buffer, with new contents.
*
* Create a new buffer.
*
* If \p data is NULL, the buffer will be empty, but it will be pre-allocated with \p size bytes,
* all filled with zeros. This will make future operations on the buffer faster since there will be
* less re-allocations needed.
*
* If \p size is zero, the buffer will be pre-allocated with 128 bytes.
*
* 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 re-allocated with the provided \p data and \p size
* according to the rules stated above.
*/
wget_buffer_t *wget_buffer_init(wget_buffer_t *buf, char *data, size_t size)
{
if (!buf) {
if (!(buf = wget_malloc(sizeof(wget_buffer_t))))
return NULL;
buf->release_buf = 1;
} else {
buf->release_buf = 0;
}
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 = 128;
buf->size = size;
if (!(buf->data = wget_malloc(size + 1)))
return NULL;
*buf->data = 0; // always 0 terminate data to allow string functions
buf->release_data = 1;
}
buf->length = 0;
return buf;
}
/**
* \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_t *wget_buffer_alloc(size_t size)
{
return wget_buffer_init(NULL, NULL, size);
}
static int _buffer_realloc(wget_buffer_t *buf, size_t size)
{
char *old_data = buf->data;
if (!(buf->data = wget_malloc(size + 1))) {
buf->data = old_data;
return WGET_E_MEMORY;
}
buf->size = size;
if (likely(old_data)) {
if (buf->length)
memcpy(buf->data, old_data, buf->length + 1);
else
*buf->data = 0; // always 0 terminate data to allow string functions
if (buf->release_data)
xfree(old_data);
} else {
*buf->data = 0; // always 0 terminate data to allow string functions
}
buf->release_data = 1;
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_t *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_t` structure.
*
* Similarly, if you provided your own buffer when calling wget_buffer_init() (\p buf was non-NULL)
* the buffer (the `wget_buffer_t` 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_t *buf)
{
if (likely(!buf))
return;
if (buf->release_data) {
xfree(buf->data);
buf->release_data = 0;
}
if (buf->release_buf)
xfree(buf);
}
/**
* \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_t **buf)
{
if (likely(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_t` 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_t *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_t *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_t *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_t *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_t *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_t *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_t *buf, wget_buffer_t *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_t *buf, wget_buffer_t *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_t *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_t *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_t *buf)
{
if (unlikely(!buf))
return NULL;
if (buf->length) {
char *start = buf->data;
char *end = start + buf->length - 1;
if (isspace(*end)) {
/* Skip trailing spaces */
for (; isspace(*end) && end >= start; end--)
;
end[1] = 0;
buf->length = (size_t) (end - start + 1);
}
if (isspace(*start)) {
/* Skip leading spaces */
for (; isspace(*start) && end >= start; start++)
;
buf->length = (size_t) (end - start + 1);
/* Include trailing 0 */
memmove(buf->data, start, buf->length + 1);
}
}
return buf->data;
}
/** @} */