.TH "libwget-vector" 3 "Tue Jan 26 2021" "Version 1.99.1" "wget2" \" -*- nroff -*-
.ad l
.nh
.SH NAME
libwget-vector \- Vector functions
.SH SYNOPSIS
.br
.PP
.SS "Functions"

.in +1c
.ti -1c
.RI "wget_vector_t * \fBwget_vector_create\fP (int max, wget_vector_compare_t cmp)"
.br
.ti -1c
.RI "void \fBwget_vector_set_growth_policy\fP (wget_vector_t *v, int off)"
.br
.ti -1c
.RI "int \fBwget_vector_insert\fP (wget_vector_t *v, const void *elem, size_t size, int pos)"
.br
.ti -1c
.RI "int \fBwget_vector_insert_noalloc\fP (wget_vector_t *v, const void *elem, int pos)"
.br
.ti -1c
.RI "int \fBwget_vector_insert_sorted\fP (wget_vector_t *v, const void *elem, size_t size)"
.br
.ti -1c
.RI "int \fBwget_vector_insert_sorted_noalloc\fP (wget_vector_t *v, const void *elem)"
.br
.ti -1c
.RI "int \fBwget_vector_add\fP (wget_vector_t *v, const void *elem, size_t size)"
.br
.ti -1c
.RI "int \fBwget_vector_add_noalloc\fP (wget_vector_t *v, const void *elem)"
.br
.ti -1c
.RI "int \fBwget_vector_add_str\fP (wget_vector_t *v, const char *s)"
.br
.ti -1c
.RI "int \fBwget_vector_add_vprintf\fP (wget_vector_t *v, const char *fmt, va_list args)"
.br
.ti -1c
.RI "int \fBwget_vector_add_printf\fP (wget_vector_t *v, const char *fmt,\&.\&.\&.)"
.br
.ti -1c
.RI "int \fBwget_vector_replace\fP (wget_vector_t *v, const void *elem, size_t size, int pos)"
.br
.ti -1c
.RI "int \fBwget_vector_replace_noalloc\fP (wget_vector_t *v, const void *elem, int pos)"
.br
.ti -1c
.RI "int \fBwget_vector_remove\fP (wget_vector_t *v, int pos)"
.br
.ti -1c
.RI "int \fBwget_vector_remove_nofree\fP (wget_vector_t *v, int pos)"
.br
.ti -1c
.RI "int \fBwget_vector_move\fP (wget_vector_t *v, int old_pos, int new_pos)"
.br
.ti -1c
.RI "int \fBwget_vector_swap\fP (wget_vector_t *v, int pos1, int pos2)"
.br
.ti -1c
.RI "void \fBwget_vector_free\fP (wget_vector_t **v)"
.br
.ti -1c
.RI "void \fBwget_vector_clear\fP (wget_vector_t *v)"
.br
.ti -1c
.RI "void \fBwget_vector_clear_nofree\fP (wget_vector_t *v)"
.br
.ti -1c
.RI "int \fBwget_vector_size\fP (const wget_vector_t *v)"
.br
.ti -1c
.RI "void * \fBwget_vector_get\fP (const wget_vector_t *v, int pos)"
.br
.ti -1c
.RI "int \fBwget_vector_browse\fP (const wget_vector_t *v, wget_vector_browse_t browse, void *ctx)"
.br
.ti -1c
.RI "void \fBwget_vector_setcmpfunc\fP (wget_vector_t *v, wget_vector_compare_t cmp)"
.br
.ti -1c
.RI "void \fBwget_vector_set_destructor\fP (wget_vector_t *v, wget_vector_destructor_t destructor)"
.br
.ti -1c
.RI "void \fBwget_vector_sort\fP (wget_vector_t *v)"
.br
.ti -1c
.RI "int \fBwget_vector_find\fP (const wget_vector_t *v, const void *elem)"
.br
.ti -1c
.RI "int \fBwget_vector_contains\fP (const wget_vector_t *v, const void *elem)"
.br
.ti -1c
.RI "int \fBwget_vector_findext\fP (const wget_vector_t *v, int start, int direction, wget_vector_find_t find)"
.br
.in -1c
.SH "Detailed Description"
.PP 
Functions to realize vectors (growable arrays)\&. 
.SH "Function Documentation"
.PP 
.SS "wget_vector_t* wget_vector_create (int max, wget_vector_compare_t cmp)"

.PP
\fBParameters\fP
.RS 4
\fImax\fP Initial number of pre-allocated entries\&. 
.br
\fIcmp\fP Comparison function for sorting/finding/sorted insertion or NULL\&. 
.RE
.PP
\fBReturns\fP
.RS 4
New vector instance
.RE
.PP
Create a new vector instance, to be free'd after use with \fBwget_vector_free()\fP\&. 
.SS "void wget_vector_set_growth_policy (wget_vector_t * v, int off)"

.PP
\fBParameters\fP
.RS 4
\fIv\fP Vector 
.br
\fIoff\fP Vector growth mode: positive values: increase vector by \fCoff\fP entries on each resize negative values: increase vector by multiplying \fC-off\fP, e\&.g\&. -2 doubles the size on each resize
.RE
.PP
Set the growth policy for internal memory\&. 
.SS "int wget_vector_insert (wget_vector_t * v, const void * elem, size_t size, int pos)"

.PP
\fBParameters\fP
.RS 4
\fIv\fP Vector where \fCelem\fP is inserted into 
.br
\fIelem\fP Element to insert into \fCv\fP 
.br
\fIsize\fP Size of \fCelem\fP 
.br
\fIpos\fP Position to insert \fCelem\fP at 
.RE
.PP
\fBReturns\fP
.RS 4
Index of inserted element or -1 on error
.RE
.PP
Insert \fCelem\fP of given \fCsize\fP at index \fCpos\fP\&.
.PP
\fCelem\fP is cloned / copied (shallow)\&.
.PP
An error is returned if \fCv\fP is NULL or \fCpos\fP is out of range (< 0 or > # of entries)\&. 
.SS "int wget_vector_insert_noalloc (wget_vector_t * v, const void * elem, int pos)"

.PP
\fBParameters\fP
.RS 4
\fIv\fP Vector where \fCelem\fP is inserted into 
.br
\fIelem\fP Element to insert into \fCv\fP 
.br
\fIpos\fP Position to insert \fCelem\fP at 
.RE
.PP
\fBReturns\fP
.RS 4
Index of inserted element or -1 on error
.RE
.PP
Insert \fCelem\fP of at index \fCpos\fP\&.
.PP
\fCelem\fP is \fInot\fP cloned, the vector takes 'ownership' of the element\&.
.PP
An error is returned if \fCv\fP is NULL or \fCpos\fP is out of range (< 0 or > # of entries)\&. 
.SS "int wget_vector_insert_sorted (wget_vector_t * v, const void * elem, size_t size)"

.PP
\fBParameters\fP
.RS 4
\fIv\fP Vector where \fCelem\fP is inserted into 
.br
\fIelem\fP Element to insert into \fCv\fP 
.br
\fIsize\fP Size of \fCelem\fP 
.RE
.PP
\fBReturns\fP
.RS 4
Index of inserted element or -1 on error
.RE
.PP
Insert \fCelem\fP of given \fCsize\fP at a position that keeps the sort order of the elements\&. If the vector has no comparison function, \fCelem\fP 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\&.
.PP
\fCelem\fP is cloned / copied (shallow)\&.
.PP
An error is returned if \fCv\fP is NULL\&. 
.SS "int wget_vector_insert_sorted_noalloc (wget_vector_t * v, const void * elem)"

.PP
\fBParameters\fP
.RS 4
\fIv\fP Vector where \fCelem\fP is inserted into 
.br
\fIelem\fP Element to insert into \fCv\fP 
.RE
.PP
\fBReturns\fP
.RS 4
Index of inserted element or -1 on error
.RE
.PP
Insert \fCelem\fP of at a position that keeps the sort order of the elements\&. If the vector has no comparison function, \fCelem\fP 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\&.
.PP
\fCelem\fP is \fInot\fP cloned, the vector takes 'ownership' of the element\&.
.PP
An error is returned if \fCv\fP is NULL\&. 
.SS "int wget_vector_add (wget_vector_t * v, const void * elem, size_t size)"

.PP
\fBParameters\fP
.RS 4
\fIv\fP Vector where \fCelem\fP is appended to 
.br
\fIelem\fP Element to append to a \fCv\fP 
.br
\fIsize\fP Size of \fCelem\fP 
.RE
.PP
\fBReturns\fP
.RS 4
Index of appended element or -1 on error
.RE
.PP
Append \fCelem\fP of given \fCsize\fP to vector \fCv\fP\&.
.PP
\fCelem\fP is cloned / copied (shallow)\&.
.PP
An error is returned if \fCv\fP is NULL\&. 
.SS "int wget_vector_add_noalloc (wget_vector_t * v, const void * elem)"

.PP
\fBParameters\fP
.RS 4
\fIv\fP Vector where \fCelem\fP is appended to 
.br
\fIelem\fP Element to append to a \fCv\fP 
.RE
.PP
\fBReturns\fP
.RS 4
Index of appended element or -1 on error
.RE
.PP
Append \fCelem\fP to vector \fCv\fP\&.
.PP
\fCelem\fP is \fInot\fP cloned, the vector takes 'ownership' of the element\&.
.PP
An error is returned if \fCv\fP is NULL\&. 
.SS "int wget_vector_add_str (wget_vector_t * v, const char * s)"

.PP
\fBParameters\fP
.RS 4
\fIv\fP Vector where \fCs\fP is appended to 
.br
\fIs\fP String to append to \fCv\fP 
.RE
.PP
\fBReturns\fP
.RS 4
Index of appended element or -1 on error
.RE
.PP
Append string \fCs\fP as an element to vector \fCv\fP\&.
.PP
\fCs\fP is cloned / copied\&.
.PP
An error is returned if \fCv\fP or \fCs\fP is NULL\&. 
.SS "int wget_vector_add_vprintf (wget_vector_t * v, const char * fmt, va_list args)"

.PP
\fBParameters\fP
.RS 4
\fIv\fP Vector where \fCs\fP is appended to 
.br
\fIfmt\fP Printf-like format string 
.br
\fIargs\fP Arguments for the \fCfmt\fP 
.RE
.PP
\fBReturns\fP
.RS 4
Index of appended element or -1 on error
.RE
.PP
Construct string in a printf-like manner and append it as an element to vector \fCv\fP\&.
.PP
An error is returned if \fCv\fP or \fCfmt\fP is NULL\&. 
.SS "int wget_vector_add_printf (wget_vector_t * v, const char * fmt,  \&.\&.\&.)"

.PP
\fBParameters\fP
.RS 4
\fIv\fP Vector where \fCs\fP is appended to 
.br
\fIfmt\fP Printf-like format string 
.br
\fI\&.\&.\&.\fP Arguments for the \fCfmt\fP 
.RE
.PP
\fBReturns\fP
.RS 4
Index of appended element or -1 on error
.RE
.PP
Construct string in a printf-like manner and append it as an element to vector \fCv\fP\&.
.PP
An error is returned if \fCv\fP or \fCfmt\fP is NULL\&. 
.SS "int wget_vector_replace (wget_vector_t * v, const void * elem, size_t size, int pos)"

.PP
\fBParameters\fP
.RS 4
\fIv\fP Vector where \fCelem\fP is inserted 
.br
\fIelem\fP Element to insert into \fCv\fP 
.br
\fIsize\fP Size of \fCelem\fP 
.br
\fIpos\fP Position to insert \fCelem\fP at 
.RE
.PP
\fBReturns\fP
.RS 4
Index of inserted element (same as \fCpos\fP) or -1 on error
.RE
.PP
Replace the element at position \fCpos\fP with \fCelem\fP of given \fCsize\fP\&. If the vector has an element destructor function, this is called\&. The old element is free'd\&.
.PP
\fCelem\fP is cloned / copied (shallow)\&.
.PP
An error is returned if \fCv\fP is NULL or \fCpos\fP is out of range (< 0 or > # of entries)\&. 
.SS "int wget_vector_replace_noalloc (wget_vector_t * v, const void * elem, int pos)"

.PP
\fBParameters\fP
.RS 4
\fIv\fP Vector where \fCelem\fP is inserted 
.br
\fIelem\fP Element to insert into \fCv\fP 
.br
\fIpos\fP Position to insert \fCelem\fP at 
.RE
.PP
\fBReturns\fP
.RS 4
Index of inserted element (same as \fCpos\fP) or -1 on error
.RE
.PP
Replace the element at position \fCpos\fP with \fCelem\fP\&. If the vector has an element destructor function, this is called\&. The old element is free'd\&.
.PP
\fCelem\fP is \fInot\fP cloned, the vector takes 'ownership' of the element\&.
.PP
An error is returned if \fCv\fP is NULL or \fCpos\fP is out of range (< 0 or > # of entries)\&. 
.SS "int wget_vector_remove (wget_vector_t * v, int pos)"

.PP
\fBParameters\fP
.RS 4
\fIv\fP Vector to remove an element from 
.br
\fIpos\fP Position of element to remove 
.RE
.PP
\fBReturns\fP
.RS 4
Index of removed element (same as \fCpos\fP) or -1 on error
.RE
.PP
Remove the element at position \fCpos\fP\&. If the vector has an element destructor function, this is called\&. The element is free'd\&.
.PP
An error is returned if \fCv\fP is NULL or \fCpos\fP is out of range (< 0 or > # of entries)\&. 
.SS "int wget_vector_remove_nofree (wget_vector_t * v, int pos)"

.PP
\fBParameters\fP
.RS 4
\fIv\fP Vector to remove an element from 
.br
\fIpos\fP Position of element to remove 
.RE
.PP
\fBReturns\fP
.RS 4
Index of removed element (same as \fCpos\fP) or -1 on error
.RE
.PP
Remove the element at position \fCpos\fP\&. No element destructor function is called, the element is not free'd\&.
.PP
An error is returned if \fCv\fP is NULL or \fCpos\fP is out of range (< 0 or > # of entries)\&. 
.SS "int wget_vector_move (wget_vector_t * v, int old_pos, int new_pos)"

.PP
\fBParameters\fP
.RS 4
\fIv\fP Vector to act on 
.br
\fIold_pos\fP Position to move element from 
.br
\fInew_pos\fP Position to move element to 
.RE
.PP
\fBReturns\fP
.RS 4
Index of new position (same as \fCnew_pos\fP) or -1 on error
.RE
.PP
Move the element at position \fCold_pos\fP to \fCnew_pos\fP\&.
.PP
Other elements may change the position\&.
.PP
An error is returned if \fCv\fP is NULL or either \fCold_pos\fP or \fCnew_pos\fP is out of range (< 0 or > # of entries)\&. 
.SS "int wget_vector_swap (wget_vector_t * v, int pos1, int pos2)"

.PP
\fBParameters\fP
.RS 4
\fIv\fP Vector to act on 
.br
\fIpos1\fP Position of element one 
.br
\fIpos2\fP Position of element two 
.RE
.PP
\fBReturns\fP
.RS 4
Index of second position (same as \fCpos2\fP) or -1 on error
.RE
.PP
Swap the two elements at position \fCpos1\fP and \fCpos2\fP\&.
.PP
An error is returned if \fCv\fP is NULL or either \fCpos1\fP or \fCpos2\fP is out of range (< 0 or > # of entries)\&. 
.SS "void wget_vector_free (wget_vector_t ** v)"

.PP
\fBParameters\fP
.RS 4
\fIv\fP Vector to be free'd
.RE
.PP
Free the vector \fCv\fP and it's contents\&.
.PP
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\&. 
.SS "void wget_vector_clear (wget_vector_t * v)"

.PP
\fBParameters\fP
.RS 4
\fIv\fP Vector to be cleared
.RE
.PP
Free all elements of the vector \fCv\fP but not the vector itself\&.
.PP
For each element the destructor function is called and the element free'd thereafter\&. The vector is then empty and can be reused\&. 
.SS "void wget_vector_clear_nofree (wget_vector_t * v)"

.PP
\fBParameters\fP
.RS 4
\fIv\fP Vector to be cleared
.RE
.PP
Remove all elements of the vector \fCv\fP without free'ing them\&. The caller is responsible to care for the elements\&.
.PP
The vector is then empty and can be reused\&. 
.SS "int wget_vector_size (const wget_vector_t * v)"

.PP
\fBParameters\fP
.RS 4
\fIv\fP Vector 
.RE
.PP
\fBReturns\fP
.RS 4
The number of elements in the vector \fCv\fP 
.RE
.PP
Retrieve the number of elements of the vector \fCv\fP\&. If \fCv\fP is NULL, 0 is returned\&. 
.SS "void* wget_vector_get (const wget_vector_t * v, int pos)"

.PP
\fBParameters\fP
.RS 4
\fIv\fP Vector 
.br
\fIpos\fP Position of element to retrieve 
.RE
.PP
\fBReturns\fP
.RS 4
The element at position \fCpos\fP or NULL on error
.RE
.PP
Retrieve the element at position \fCpos\fP\&.
.PP
NULL is returned if \fCv\fP is NULL or \fCpos\fP is out of range (< 0 or > # of entries)\&. 
.SS "int wget_vector_browse (const wget_vector_t * v, wget_vector_browse_t browse, void * ctx)"

.PP
\fBParameters\fP
.RS 4
\fIv\fP Vector 
.br
\fIbrowse\fP Function to be called for each element of \fCv\fP 
.br
\fIctx\fP Context variable use as param to \fCbrowse\fP 
.RE
.PP
\fBReturns\fP
.RS 4
Return value of the last call to \fCbrowse\fP 
.RE
.PP
Call function \fCbrowse\fP for each element of vector \fCv\fP or until \fCbrowse\fP returns a value not equal to zero\&.
.PP
\fCbrowse\fP is called with \fCctx\fP and the pointer to the current element\&.
.PP
The return value of the last call to \fCbrowse\fP is returned or 0 if \fCv\fP is NULL\&. 
.SS "void wget_vector_setcmpfunc (wget_vector_t * v, wget_vector_compare_t cmp)"

.PP
\fBParameters\fP
.RS 4
\fIv\fP Vector 
.br
\fIcmp\fP Function to compare elements
.RE
.PP
Set the compare function used by \fBwget_vector_sort()\fP\&. 
.SS "void wget_vector_set_destructor (wget_vector_t * v, wget_vector_destructor_t destructor)"

.PP
\fBParameters\fP
.RS 4
\fIv\fP Vector 
.br
\fIdestructor\fP Function to be called for element destruction
.RE
.PP
Set the destructor function that is called for each element to be removed\&. It should not free the element (pointer) itself\&. 
.SS "void wget_vector_sort (wget_vector_t * v)"

.PP
\fBParameters\fP
.RS 4
\fIv\fP Vector
.RE
.PP
Sort the elements in vector \fCv\fP usign the compare function\&. Do nothing if \fCv\fP is NULL or the compare function is not set\&. 
.SS "int wget_vector_find (const wget_vector_t * v, const void * elem)"

.PP
\fBParameters\fP
.RS 4
\fIv\fP Vector 
.br
\fIelem\fP Element to search for 
.RE
.PP
\fBReturns\fP
.RS 4
Index of the found element or -1 if not found
.RE
.PP
Searches for the given element using the compare function of the vector\&.
.PP
Returns -1 if \fCv\fP is NULL or if the compare function is not set\&. 
.SS "int wget_vector_contains (const wget_vector_t * v, const void * elem)"

.PP
\fBParameters\fP
.RS 4
\fIv\fP Vector 
.br
\fIelem\fP Element to check for 
.RE
.PP
\fBReturns\fP
.RS 4
1 if element exists, else 0
.RE
.PP
Checks whether the element \fCelem\fP exists or not\&. 
.SS "int wget_vector_findext (const wget_vector_t * v, int start, int direction, wget_vector_find_t find)"

.PP
\fBParameters\fP
.RS 4
\fIv\fP Vector 
.br
\fIstart\fP Index to start search from 
.br
\fIdirection\fP Direction of search 
.br
\fIfind\fP Function to be called for each element 
.RE
.PP
\fBReturns\fP
.RS 4
Index of the found element or -1 if not found
.RE
.PP
Call \fCfind\fP for each element starting at \fCstart\fP\&. If \fCfind\fP returns 0 the current index is returned\&.
.PP
Returns -1 if \fCv\fP is NULL or if the \fCfind\fP didn't return 0\&. 
.SH "Author"
.PP 
Generated automatically by Doxygen for wget2 from the source code\&.