wget2: Vector functions

| wget2 2.0.0

- Main Page
- Modules
- Data Structures
- Files

Functions
Vector functions

## Functions
wget_vector * | wget_vector_create (int max, wget_vector_compare_fn *cmp)
void | wget_vector_set_resize_factor (wget_vector *v, float factor)
int | wget_vector_insert (wget_vector *v, const void *elem, int pos)
int | wget_vector_insert_sorted (wget_vector *v, const void *elem)
int | wget_vector_add_memdup (wget_vector *v, const void *elem, size_t size)
int | wget_vector_add (wget_vector *v, const void *elem)
int | wget_vector_add_vprintf (wget_vector *v, const char *fmt, va_list args)
int | wget_vector_add_printf (wget_vector *v, const char *fmt,...)
int | wget_vector_replace (wget_vector *v, const void *elem, int pos)
int | wget_vector_remove (wget_vector *v, int pos)
int | wget_vector_remove_nofree (wget_vector *v, int pos)
int | wget_vector_move (wget_vector *v, int old_pos, int new_pos)
int | wget_vector_swap (wget_vector *v, int pos1, int pos2)
void | wget_vector_free (wget_vector **v)
void | wget_vector_clear (wget_vector *v)
void | wget_vector_clear_nofree (wget_vector *v)
int | wget_vector_size (const wget_vector *v)
void * | wget_vector_get (const wget_vector *v, int pos)
int | wget_vector_browse (const wget_vector *v, wget_vector_browse_fn *browse, void *ctx)
void | wget_vector_setcmpfunc (wget_vector *v, wget_vector_compare_fn *cmp)
void | wget_vector_set_destructor (wget_vector *v, wget_vector_destructor *destructor)
void | wget_vector_sort (wget_vector *v)
int | wget_vector_find (const wget_vector *v, const void *elem)
bool | wget_vector_contains (const wget_vector *v, const void *elem)
int | wget_vector_findext (const wget_vector *v, int start, int direction, wget_vector_find_fn *find)

## Detailed Description

Functions to realize vectors (growable arrays).

## Function Documentation

## ◆ wget_vector_create()

wget_vector* wget_vector_create | ( | int | max,
|  | wget_vector_compare_fn * | cmp
| ) |  |

Parameters

  [in] | max | Initial number of pre-allocated entries.
  [in] | cmp | Comparison function for sorting/finding/sorted insertion or NULL.

Returns
  New vector instance

Create a new vector instance, to be free'd after use with wget_vector_free().

## ◆ wget_vector_set_resize_factor()

void wget_vector_set_resize_factor | ( | wget_vector * | v,
|  | float | factor
| ) |  |

Parameters

  [in] | v | Vector
  [in] | factor | Vector growth factor

Set the factor for resizing the vector when it is full.

The new size is 'factor * oldsize'. If the new size is less or equal the old size, the involved insertion function will return an error and the internal state of the vector will not change.

Default is 2.

## ◆ wget_vector_insert()

int wget_vector_insert | ( | wget_vector * | v,
|  | const void * | elem,
|  | int | pos
| ) |  |

Parameters

  [in] | v | Vector where `elem` is inserted into
  [in] | elem | Element to insert into `v`
  [in] | pos | Position to insert `elem` at

Returns
  Index of inserted element (>= 0) or WGET_E_* on error (< 0)

Insert `elem` of at index `pos`.

`elem` is not cloned, the vector takes 'ownership' of the element.

An error is returned if `v` is NULL or `pos` is out of range (< 0 or > # of entries).

## ◆ wget_vector_insert_sorted()

int wget_vector_insert_sorted | ( | wget_vector * | v,
|  | const void * | elem
| ) |  |

Parameters

  [in] | v | Vector where `elem` is inserted into
  [in] | elem | Element to insert into `v`

Returns
  Index of inserted element (>= 0) or WGET_E_* on error (< 0)

Insert `elem` of at a position that keeps the sort order of the elements. If the vector has no comparison function, `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.

`elem` is not cloned, the vector takes 'ownership' of the element.

An error is returned if `v` is NULL.

## ◆ wget_vector_add_memdup()

int wget_vector_add_memdup | ( | wget_vector * | v,
|  | const void * | elem,
|  | size_t | size
| ) |  |

Parameters

  [in] | v | Vector where `elem` is appended to
  [in] | elem | Element to append to a `v`
  [in] | size | Size of `elem`

Returns
  Index of inserted element (>= 0) or WGET_E_* on error (< 0)

Append `elem` of given `size` to vector `v`.

`elem` is cloned / copied (shallow).

An error is returned if `v` is NULL.

## ◆ wget_vector_add()

int wget_vector_add | ( | wget_vector * | v,
|  | const void * | elem
| ) |  |

Parameters

  [in] | v | Vector where `elem` is appended to
  [in] | elem | Element to append to a `v`

Returns
  Index of inserted element (>= 0) or WGET_E_* on error (< 0)

Append `elem` to vector `v`.

`elem` is not cloned, the vector takes 'ownership' of the element.

An error is returned if `v` is NULL.

## ◆ wget_vector_add_vprintf()

int wget_vector_add_vprintf | ( | wget_vector * | v,
|  | const char * | fmt,
|  | va_list | args
| ) |  |

Parameters

  [in] | v | Vector where `s` is appended to
  [in] | fmt | Printf-like format string
  [in] | args | Arguments for the `fmt`

Returns
  Index of appended element (>= 0) or WGET_E_* on error (< 0)

Construct string in a printf-like manner and append it as an element to vector `v`.

An error is returned if `v` or `fmt` is NULL.

## ◆ wget_vector_add_printf()

int wget_vector_add_printf | ( | wget_vector * | v,
|  | const char * | fmt,
|  |  | ...
| ) |  |

Parameters

  [in] | v | Vector where `s` is appended to
  [in] | fmt | Printf-like format string
  [in] | ... | Arguments for the `fmt`

Returns
  Index of appended element (>= 0) or WGET_E_* on error (< 0)

Construct string in a printf-like manner and append it as an element to vector `v`.

An error is returned if `v` or `fmt` is NULL.

## ◆ wget_vector_replace()

int wget_vector_replace | ( | wget_vector * | v,
|  | const void * | elem,
|  | int | pos
| ) |  |

Parameters

  [in] | v | Vector where `elem` is inserted
  [in] | elem | Element to insert into `v`
  [in] | pos | Position to insert `elem` at

Returns
  Index of inserted element (same as `pos`) (>= 0) or WGET_E_* on error (< 0)

Replace the element at position `pos` with `elem`. If the vector has an element destructor function, this is called. The old element is free'd.

`elem` is not cloned, the vector takes 'ownership' of the element.

An error is returned if `v` is NULL or `pos` is out of range (< 0 or > # of entries).

## ◆ wget_vector_remove()

int wget_vector_remove | ( | wget_vector * | v,
|  | int | pos
| ) |  |

Parameters

  [in] | v | Vector to remove an element from
  [in] | pos | Position of element to remove

Returns
  Index of appended element (>= 0) or WGET_E_* on error (< 0)

Remove the element at position `pos`. If the vector has an element destructor function, this is called. The element is free'd.

An error is returned if `v` is NULL or `pos` is out of range (< 0 or > # of entries).

## ◆ wget_vector_remove_nofree()

int wget_vector_remove_nofree | ( | wget_vector * | v,
|  | int | pos
| ) |  |

Parameters

  [in] | v | Vector to remove an element from
  [in] | pos | Position of element to remove

Returns
  Index of removed element (same as `pos`) (>= 0) or WGET_E_* on error (< 0)

Remove the element at position `pos`. No element destructor function is called, the element is not free'd.

An error is returned if `v` is NULL or `pos` is out of range (< 0 or > # of entries).

## ◆ wget_vector_move()

int wget_vector_move | ( | wget_vector * | v,
|  | int | old_pos,
|  | int | new_pos
| ) |  |

Parameters

  [in] | v | Vector to act on
  [in] | old_pos | Position to move element from
  [in] | new_pos | Position to move element to

Returns
  Index of new position (same as `new_pos`) (>= 0) or WGET_E_* on error (< 0)

Move the element at position `old_pos` to `new_pos`.

Other elements may change the position.

An error is returned if `v` is NULL or either `old_pos` or `new_pos` is out of range (< 0 or > # of entries).

## ◆ wget_vector_swap()

int wget_vector_swap | ( | wget_vector * | v,
|  | int | pos1,
|  | int | pos2
| ) |  |

Parameters

  [in] | v | Vector to act on
  [in] | pos1 | Position of element one
  [in] | pos2 | Position of element two

Returns
  Index of second position (same as `pos2`) (>= 0) or WGET_E_* on error (< 0)

Swap the two elements at position `pos1` and `pos2`.

An error is returned if `v` is NULL or either `pos1` or `pos2` is out of range (< 0 or > # of entries).

## ◆ wget_vector_free()

void wget_vector_free | ( | wget_vector ** | v | ) |

Parameters

  [in] | v | Vector to be free'd

Free the vector `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.

## ◆ wget_vector_clear()

void wget_vector_clear | ( | wget_vector * | v | ) |

Parameters

  [in] | v | Vector to be cleared

Free all elements of the vector `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.

## ◆ wget_vector_clear_nofree()

void wget_vector_clear_nofree | ( | wget_vector * | v | ) |

Parameters

  [in] | v | Vector to be cleared

Remove all elements of the vector `v` without free'ing them. The caller is responsible to care for the elements.

The vector is then empty and can be reused.

## ◆ wget_vector_size()

int wget_vector_size | ( | const wget_vector * | v | ) |

Parameters

  [in] | v | Vector

Returns
  The number of elements in the vector `v`

Retrieve the number of elements of the vector `v`. If `v` is NULL, 0 is returned.

## ◆ wget_vector_get()

void* wget_vector_get | ( | const wget_vector * | v,
|  | int | pos
| ) |  |

Parameters

  [in] | v | Vector
  [in] | pos | Position of element to retrieve

Returns
  The element at position `pos` or NULL on error

Retrieve the element at position `pos`.

NULL is returned if `v` is NULL or `pos` is out of range (< 0 or > # of entries).

## ◆ wget_vector_browse()

int wget_vector_browse | ( | const wget_vector * | v,
|  | wget_vector_browse_fn * | browse,
|  | void * | ctx
| ) |  |

Parameters

  [in] | v | Vector
  [in] | browse | Function to be called for each element of `v`
  [in] | ctx | Context variable use as param to `browse`

Returns
  Return value of the last call to `browse`

Call function `browse` for each element of vector `v` or until `browse` returns a value not equal to zero.

`browse` is called with `ctx` and the pointer to the current element.

The return value of the last call to `browse` is returned or 0 if `v` is NULL.

## ◆ wget_vector_setcmpfunc()

void wget_vector_setcmpfunc | ( | wget_vector * | v,
|  | wget_vector_compare_fn * | cmp
| ) |  |

Parameters

  [in] | v | Vector
  [in] | cmp | Function to compare elements

Set the compare function used by wget_vector_sort().

## ◆ wget_vector_set_destructor()

void wget_vector_set_destructor | ( | wget_vector * | v,
|  | wget_vector_destructor * | destructor
| ) |  |

Parameters

  [in] | v | Vector
  [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.

## ◆ wget_vector_sort()

void wget_vector_sort | ( | wget_vector * | v | ) |

Parameters

  [in] | v | Vector

Sort the elements in vector `v` using the compare function. Do nothing if `v` is NULL or the compare function is not set.

## ◆ wget_vector_find()

int wget_vector_find | ( | const wget_vector * | v,
|  | const void * | elem
| ) |  |

Parameters

  [in] | v | Vector
  [in] | elem | Element to search for

Returns
  Index of the found element, WGET_E_UNKNOWN if not found or WGET_E_INVALID if v was NULL or there was no comparison function set

Searches for the given element using the compare function of the vector.

## ◆ wget_vector_contains()

bool wget_vector_contains | ( | const wget_vector * | v,
|  | const void * | elem
| ) |  |

Parameters

  [in] | v | Vector
  [in] | elem | Element to check for

Returns
  True if element exists, else false

Checks whether the element `elem` exists or not.

## ◆ wget_vector_findext()

int wget_vector_findext | ( | const wget_vector * | v,
|  | int | start,
|  | int | direction,
|  | wget_vector_find_fn * | find
| ) |  |

Parameters

  [in] | v | Vector
  [in] | start | Index to start search from
  [in] | direction | Direction of search
  [in] | find | Function to be called for each element

Returns
  Index of the found element, WGET_E_UNKNOWN if not found or WGET_E_INVALID if v was NULL or there was no comparison function set

Call `find` for each element starting at `start`. If `find` returns 0 the current index is returned.