gnu/wget2
1
0
Fork 0
mirror of https://gitlab.com/gnuwget/wget2.git synced 2025-08-16 17:37:56 +00:00
Code Issues Packages Projects Releases Wiki Activity

Add docs for vector routines

Browse Source 
* docs/Makefile.am: Add man page
* include/wget/wget.h: Amend some vector functions
* libwget/vector.c: Add checks for parameters,
  add documentation
This commit is contained in:
Tim Rühsen
2018-03-24 22:39:10 +01:00
parent a2062b2f15
commit 7648c14f8e
3 changed files with 351 additions and 54 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1
docs/Makefile.am
View File

@ -21,6 +21,7 @@ man3_MANS =\
$(builddir)/man/man3/libwget-robots.3\
$(builddir)/man/man3/libwget-thread.3\
$(builddir)/man/man3/libwget-utils.3\
$(builddir)/man/man3/libwget-vector.3\
$(builddir)/man/man3/libwget-xalloc.3\
$(builddir)/man/man3/libwget-xml.3

6
include/wget/wget.h
View File

@ -624,11 +624,11 @@ WGETAPI int
WGETAPI int
wget_vector_add_noalloc(wget_vector_t *v, const void *elem) G_GNUC_WGET_NONNULL((2));
WGETAPI int
wget_vector_add_str(wget_vector_t *v, const char *s) G_GNUC_WGET_NONNULL((2));
wget_vector_add_str(wget_vector_t *v, const char *s);
WGETAPI int
wget_vector_add_vprintf(wget_vector_t *v, const char *fmt, va_list args) G_GNUC_WGET_PRINTF_FORMAT(2,0) G_GNUC_WGET_NONNULL((2));
wget_vector_add_vprintf(wget_vector_t *v, const char *fmt, va_list args) G_GNUC_WGET_PRINTF_FORMAT(2,0);
WGETAPI int
wget_vector_add_printf(wget_vector_t *v, const char *fmt, ...) G_GNUC_WGET_PRINTF_FORMAT(2,3) G_GNUC_WGET_NONNULL((2));
wget_vector_add_printf(wget_vector_t *v, const char *fmt, ...) G_GNUC_WGET_PRINTF_FORMAT(2,3);
WGETAPI int
wget_vector_replace(wget_vector_t *v, const void *elem, size_t size, int pos) G_GNUC_WGET_NONNULL((2));
WGETAPI int

384
libwget/vector.c
View File

@ -49,6 +49,15 @@ struct _wget_vector_st {
sorted : 1; // 1=list is sorted, 0=list is not sorted
};
/**
* \file
* \brief Vector functions
* \defgroup libwget-vector Vector functions
* @{
*
* Functions to realize vectors (growable arrays).
*/
// create vector with initial size <max>
// vector growth is specified by off:
// positive values: increase vector by <off> entries on each resize
@ -57,6 +66,16 @@ struct _wget_vector_st {
// or NULL if not needed.
// the vector plus content is freed by vec_free()
/**
* \param[in] max Initial number of pre-allocated entries.
* \param[in] off Vector growth mode:
* positive values: increase vector by \p off entries on each resize
* negative values: increase vector by multiplying \p -off, e.g. -2 doubles the size on each resize
* \param[in] cmp Comparison function for sorting/finding/sorted insertion or %NULL.
* \return New vector instance
*
* Create a new vector instance.
*/
wget_vector_t *wget_vector_create(int max, int off, wget_vector_compare_t cmp)
{
wget_vector_t *v = xcalloc(1, sizeof(wget_vector_t));
@ -120,11 +139,36 @@ static int G_GNUC_WGET_NONNULL((2)) _vec_insert_private(wget_vector_t *v, const
return pos; // return position of new element
}
/**
* \param[in] v Vector where \p elem is inserted into
* \param[in] elem Element to insert into \p v
* \param[in] size Size of \p elem
* \param[in] pos Position to insert \p elem at
* \return Index of inserted element or -1 on error
*
* Insert \p elem of given \p size at index \p pos.
*
* \p elem is cloned / copied (shallow).
*
* An error is returned if \p v is %NULL or \p pos is out of range (< 0 or > # of entries).
*/
int wget_vector_insert(wget_vector_t *v, const void *elem, size_t size, int pos)
{
return _vec_insert_private(v, elem, size, pos, 0, 1);
}
/**
* \param[in] v Vector where \p elem is inserted into
* \param[in] elem Element to insert into \p v
* \param[in] pos Position to insert \p elem at
* \return Index of inserted element or -1 on error
*
* Insert \p elem of at index \p pos.
*
* \p elem is *not* cloned, the vector takes 'ownership' of the element.
*
* An error is returned if \p v is %NULL or \p pos is out of range (< 0 or > # of entries).
*/
int wget_vector_insert_noalloc(wget_vector_t *v, const void *elem, int pos)
{
return _vec_insert_private(v, elem, 0, pos, 0, 0);
@ -132,18 +176,16 @@ int wget_vector_insert_noalloc(wget_vector_t *v, const void *elem, int pos)
static int G_GNUC_WGET_NONNULL((2)) _vec_insert_sorted_private(wget_vector_t *v, const void *elem, size_t size, int alloc)
{
int m = 0;
if (!v) return -1;
if (!v->cmp)
return _vec_insert_private(v, elem, size, v->cur, 0, alloc);
if (!v->sorted) wget_vector_sort(v);
// vec_sort will leave v->sorted alone if it fails, so check again
if (v->sorted) {
if (!v->sorted)
wget_vector_sort(v);
// binary search for element
int l = 0, r = v->cur - 1, res = 0;
int l = 0, r = v->cur - 1, m = 0, res = 0;
while (l <= r) {
m = (l + r) / 2;
@ -152,33 +194,139 @@ static int G_GNUC_WGET_NONNULL((2)) _vec_insert_sorted_private(wget_vector_t *v,
else return _vec_insert_private(v, elem, size, m, 0, alloc);
}
if (res > 0) m++;
}
return _vec_insert_private(v, elem, size, m, 0, alloc);
}
/**
* \param[in] v Vector where \p elem is inserted into
* \param[in] elem Element to insert into \p v
* \param[in] size Size of \p elem
* \return Index of inserted element or -1 on error
*
* Insert \p elem of given \p size at a position that keeps the sort order of the elements.
* If the vector has no comparison function, \p elem will be inserted as the last element.
* If the elements in the vector are not sorted, they will be sorted after returning from this function.
*
* \p elem is cloned / copied (shallow).
*
* An error is returned if \p v is %NULL.
*/
int wget_vector_insert_sorted(wget_vector_t *v, const void *elem, size_t size)
{
return _vec_insert_sorted_private(v, elem, size, 1);
}
/**
* \param[in] v Vector where \p elem is inserted into
* \param[in] elem Element to insert into \p v
* \return Index of inserted element or -1 on error
*
* Insert \p elem of at a position that keeps the sort order of the elements.
* If the vector has no comparison function, \p elem will be inserted as the last element.
* If the elements in the vector are not sorted, they will be sorted after returning from this function.
*
* \p elem is *not* cloned, the vector takes 'ownership' of the element.
*
* An error is returned if \p v is %NULL.
*/
int wget_vector_insert_sorted_noalloc(wget_vector_t *v, const void *elem)
{
return _vec_insert_sorted_private(v, elem, 0, 0);
}
/**
* \param[in] v Vector where \p elem is appended to
* \param[in] elem Element to append to a \p v
* \param[in] size Size of \p elem
* \return Index of appended element or -1 on error
*
* Append \p elem of given \p size to vector \p v.
*
* \p elem is cloned / copied (shallow).
*
* An error is returned if \p v is %NULL.
*/
int wget_vector_add(wget_vector_t *v, const void *elem, size_t size)
{
return v ? _vec_insert_private(v, elem, size, v->cur, 0, 1) : -1;
}
/**
* \param[in] v Vector where \p elem is appended to
* \param[in] elem Element to append to a \p v
* \return Index of appended element or -1 on error
*
* Append \p elem to vector \p v.
*
* \p elem is *not* cloned, the vector takes 'ownership' of the element.
*
* An error is returned if \p v is %NULL.
*/
int wget_vector_add_noalloc(wget_vector_t *v, const void *elem)
{
return v ? _vec_insert_private(v, elem, 0, v->cur, 0, 0) : -1;
}
/**
* \param[in] v Vector where \p s is appended to
* \param[in] s String to append to \p v
* \return Index of appended element or -1 on error
*
* Append string \p s as an element to vector \p v.
*
* \p s is cloned / copied.
*
* An error is returned if \p v or \p s is %NULL.
*/
int wget_vector_add_str(wget_vector_t *v, const char *s)
{
return v && s ? _vec_insert_private(v, s, strlen(s) + 1, v->cur, 0, 1) : -1;
}
/**
* \param[in] v Vector where \p s is appended to
* \param[in] fmt Printf-like format string
* \param[in] args Arguments for the \p fmt
* \return Index of appended element or -1 on error
*
* Construct string in a printf-like manner and append it as an element to vector \p v.
*
* An error is returned if \p v or \p fmt is %NULL.
*/
int wget_vector_add_vprintf(wget_vector_t *v, const char *fmt, va_list args)
{
return v && fmt ? _vec_insert_private(v, wget_vaprintf(fmt, args), 0, v->cur, 0, 0) : -1;
}
/**
* \param[in] v Vector where \p s is appended to
* \param[in] fmt Printf-like format string
* \param[in] ... Arguments for the \p fmt
* \return Index of appended element or -1 on error
*
* Construct string in a printf-like manner and append it as an element to vector \p v.
*
* An error is returned if \p v or \p fmt is %NULL.
*/
int wget_vector_add_printf(wget_vector_t *v, const char *fmt, ...)
{
if (!v || !fmt)
return -1;
va_list args;
va_start(args, fmt);
int pos = _vec_insert_private(v, wget_vaprintf(fmt, args), 0, v->cur, 0, 0);
va_end(args);
return pos;
}
static int _wget_vector_replace(wget_vector_t *v, const void *elem, size_t size, int pos, int alloc)
{
if (!v || pos < 0 || pos >= v->cur) return -1;
if (!v || pos < 0 || pos >= v->cur)
return -1;
if (v->destructor)
v->destructor(v->entry[pos]);
@ -188,40 +336,49 @@ static int _wget_vector_replace(wget_vector_t *v, const void *elem, size_t size,
return _vec_insert_private(v, elem, size, pos, 1, alloc); // replace existing entry
}
/**
* \param[in] v Vector where \p elem is inserted
* \param[in] elem Element to insert into \p v
* \param[in] size Size of \p elem
* \param[in] pos Position to insert \p elem at
* \return Index of inserted element (same as \p pos) or -1 on error
*
* Replace the element at position \p pos with \p elem of given \p size.
* If the vector has an element destructor function, this is called.
* The old element is free'd.
*
* \p elem is cloned / copied (shallow).
*
* An error is returned if \p v is %NULL or \p pos is out of range (< 0 or > # of entries).
*/
int wget_vector_replace(wget_vector_t *v, const void *elem, size_t size, int pos)
{
return _wget_vector_replace(v, elem, size, pos, 1);
}
/**
* \param[in] v Vector where \p elem is inserted
* \param[in] elem Element to insert into \p v
* \param[in] pos Position to insert \p elem at
* \return Index of inserted element (same as \p pos) or -1 on error
*
* Replace the element at position \p pos with \p elem.
* If the vector has an element destructor function, this is called.
* The old element is free'd.
*
* \p elem is *not* cloned, the vector takes 'ownership' of the element.
*
* An error is returned if \p v is %NULL or \p pos is out of range (< 0 or > # of entries).
*/
int wget_vector_replace_noalloc(wget_vector_t *v, const void *elem, int pos)
{
return _wget_vector_replace(v, elem, 0, pos, 0);
}
int wget_vector_add_vprintf(wget_vector_t *v, const char *fmt, va_list args)
{
return wget_vector_add_noalloc(v, wget_vaprintf(fmt, args));
}
int wget_vector_add_printf(wget_vector_t *v, const char *fmt, ...)
{
va_list args;
va_start(args, fmt);
int len = wget_vector_add_vprintf(v, fmt, args);
va_end(args);
return len;
}
int wget_vector_add_str(wget_vector_t *v, const char *s)
{
return wget_vector_add(v, s, strlen(s) + 1);
}
static int _vec_remove_private(wget_vector_t *v, int pos, int free_entry)
{
if (pos < 0 || !v || pos >= v->cur) return -1;
if (pos < 0 || !v || pos >= v->cur)
return -1;
if (free_entry) {
if (v->destructor)
@ -236,22 +393,56 @@ static int _vec_remove_private(wget_vector_t *v, int pos, int free_entry)
return pos;
}
/**
* \param[in] v Vector to remove an element from
* \param[in] pos Position of element to remove
* \return Index of removed element (same as \p pos) or -1 on error
*
* Remove the element at position \p pos.
* If the vector has an element destructor function, this is called.
* The element is free'd.
*
* An error is returned if \p v is %NULL or \p pos is out of range (< 0 or > # of entries).
*/
int wget_vector_remove(wget_vector_t *v, int pos)
{
return _vec_remove_private(v, pos, 1);
}
/**
* \param[in] v Vector to remove an element from
* \param[in] pos Position of element to remove
* \return Index of removed element (same as \p pos) or -1 on error
*
* Remove the element at position \p pos.
* No element destructor function is called, the element is not free'd.
*
* An error is returned if \p v is %NULL or \p pos is out of range (< 0 or > # of entries).
*/
int wget_vector_remove_nofree(wget_vector_t *v, int pos)
{
return _vec_remove_private(v, pos, 0);
}
/**
* \param[in] v Vector to act on
* \param[in] old_pos Position to move element from
* \param[in] new_pos Position to move element to
* \return Index of new position (same as \p new_pos) or -1 on error
*
* Move the element at position \p old_pos to \p new_pos.
*
* Other elements may change the position.
*
* An error is returned if \p v is %NULL or either \p old_pos or
* \p new_pos is out of range (< 0 or > # of entries).
*/
int wget_vector_move(wget_vector_t *v, int old_pos, int new_pos)
{
if (!v) return -1;
if (old_pos < 0 || old_pos >= v->cur) return -1;
if (new_pos < 0 || new_pos >= v->cur) return -1;
if (old_pos == new_pos) return 0;
if (old_pos == new_pos) return new_pos;
if (v->sorted && v->cmp && v->cmp(v->entry[old_pos], v->entry[new_pos]))
v->sorted = 0;
@ -266,15 +457,26 @@ int wget_vector_move(wget_vector_t *v, int old_pos, int new_pos)
v->entry[new_pos] = tmp;
}
return 0;
return new_pos;
}
/**
* \param[in] v Vector to act on
* \param[in] pos1 Position of element one
* \param[in] pos2 Position of element two
* \return Index of second position (same as \p pos2) or -1 on error
*
* Swap the two elements at position \p pos1 and \p pos2.
*
* An error is returned if \p v is %NULL or either \p pos1 or
* \p pos2 is out of range (< 0 or > # of entries).
*/
int wget_vector_swap(wget_vector_t *v, int pos1, int pos2)
{
if (!v) return -1;
if (pos1 < 0 || pos1 >= v->cur) return -1;
if (pos2 < 0 || pos2 >= v->cur) return -1;
if (pos1 == pos2) return 0;
if (pos1 == pos2) return pos2;
void *tmp = v->entry[pos1];
v->entry[pos1] = v->entry[pos2];
@ -283,9 +485,17 @@ int wget_vector_swap(wget_vector_t *v, int pos1, int pos2)
if (v->sorted && v->cmp && v->cmp(v->entry[pos1], v->entry[pos2]))
v->sorted = 0;
return 0;
return pos2;
}
/**
* \param[in] v Vector to be free'd
*
* Free the vector \p v and it's contents.
*
* For each element the destructor function is called and the element free'd thereafter.
* Then the vector itself is free'd and set to %NULL.
*/
void wget_vector_free(wget_vector_t **v)
{
if (v && *v) {
@ -297,8 +507,14 @@ void wget_vector_free(wget_vector_t **v)
}
}
// remove all elements
/**
* \param[in] v Vector to be cleared
*
* Free all elements of the vector \p v but not the vector itself.
*
* For each element the destructor function is called and the element free'd thereafter.
* The vector is then empty and can be reused.
*/
void wget_vector_clear(wget_vector_t *v)
{
if (v) {
@ -316,6 +532,14 @@ void wget_vector_clear(wget_vector_t *v)
}
}
/**
* \param[in] v Vector to be cleared
*
* Remove all elements of the vector \p v without free'ing them.
* The caller is responsible to care for the elements.
*
* The vector is then empty and can be reused.
*/
void wget_vector_clear_nofree(wget_vector_t *v)
{
if (v) {
@ -325,18 +549,48 @@ void wget_vector_clear_nofree(wget_vector_t *v)
}
}
/**
* \param[in] v Vector
* \return The number of elements in the vector \p v
*
* Retrieve the number of elements of the vector \p v.
* If \p v is %NULL, 0 is returned.
*/
int wget_vector_size(const wget_vector_t *v)
{
return v ? v->cur : 0;
}
/**
* \param[in] v Vector
* \param[in] pos Position of element to retrieve
* \return The element at position \p pos or %NULL on error
*
* Retrieve the element at position \p pos.
*
* %NULL is returned if \p v is %NULL or \p pos is out of range (< 0 or > # of entries).
*/
void *wget_vector_get(const wget_vector_t *v, int pos)
{
if (pos < 0 || !v || pos >= v->cur) return NULL;
if (pos < 0 || !v || pos >= v->cur)
return NULL;
return v->entry[pos];
}
/**
* \param[in] v Vector
* \param[in] browse Function to be called for each element of \p v
* \param[in] ctx Context variable use as param to \p browse
* \return Return value of the last call to \p browse
*
* Call function \p browse for each element of vector \v or until \p browse
* returns a value not equal to zero.
*
* \p browse is called with \p ctx and the pointer to the current element.
*
* The return value of the last call to \p browse is returned or 0 if \p v is %NULL.
*/
int wget_vector_browse(const wget_vector_t *v, wget_vector_browse_t browse, void *ctx)
{
if (v) {
@ -348,6 +602,12 @@ int wget_vector_browse(const wget_vector_t *v, wget_vector_browse_t browse, void
return 0;
}
/**
* \param[in] v Vector
* \param[in] cmp Function to compare elements
*
* Set the compare function used by wget_vector_sort().
*/
void wget_vector_setcmpfunc(wget_vector_t *v, wget_vector_compare_t cmp)
{
if (v) {
@ -360,6 +620,13 @@ void wget_vector_setcmpfunc(wget_vector_t *v, wget_vector_compare_t cmp)
}
}
/**
* \param[in] v Vector
* \param[in] destructor Function to be called for element destruction
*
* Set the destructor function that is called for each element to be removed.
* It should not free the element (pointer) itself.
*/
void wget_vector_set_destructor(wget_vector_t *v, wget_vector_destructor_t destructor)
{
if (v)
@ -371,6 +638,12 @@ static int G_GNUC_WGET_NONNULL_ALL _compare(const void *p1, const void *p2, void
return ((wget_vector_t *)v)->cmp(*((void **)p1), *((void **)p2));
}
/**
* \param[in] v Vector
*
* Sort the elements in vector \p v usign the compare function.
* Do nothing if \p v is %NULL or the compare function is not set.
*/
void wget_vector_sort(wget_vector_t *v)
{
if (v && v->cmp) {
@ -379,9 +652,15 @@ void wget_vector_sort(wget_vector_t *v)
}
}
// Find first entry that matches the specified element,
// using the compare function of the vector
/**
* \param[in] v Vector
* \param[in] elem Element to search for
* \return Index of the found element or -1 if not found
*
* Searches for the given element using the compare function of the vector.
*
* Returns -1 if \p v is %NULL or if the compare function is not set.
*/
int wget_vector_find(const wget_vector_t *v, const void *elem)
{
if (v && v->cmp) {
@ -405,15 +684,30 @@ int wget_vector_find(const wget_vector_t *v, const void *elem)
return -1; // not found
}
/**
* \param[in] v Vector
* \param[in] elem Element to check for
* \return 1 if element exists, else 0
*
* Checks whether the element \p elem exists or not.
*/
int wget_vector_contains(const wget_vector_t *v, const void *elem)
{
return wget_vector_find(v, elem) >= 0;
}
// Find entry, starting at specified position, scanning in the specified
// direction (0=up, 1=down) and using a custom function which returns 0
// when a matching element is passed to it.
/**
* \param[in] v Vector
* \param[in] start Index to start search from
* \param[in] direction Direction of search
* \param[in] find Function to be called for each element
* \return Index of the found element or -1 if not found
*
* Call \p find for each element starting at \p start.
* If \p find returns 0 the current index is returned.
*
* Returns -1 if \p v is %NULL or if the \p find didn't return 0.
*/
int wget_vector_findext(const wget_vector_t *v, int start, int direction, wget_vector_find_t find)
{
@ -433,3 +727,5 @@ int wget_vector_findext(const wget_vector_t *v, int start, int direction, wget_v
return -1;
}
/**@}*/