Commit 40983d96 authored by giles's avatar giles

Add doxygen headers to the internal vector module.


git-svn-id: http://svn.annodex.net/liboggz/trunk@3716 8158c8cd-e7e1-0310-9fa4-c5954c97daef
parent a9132f51
......@@ -40,9 +40,17 @@ typedef int (*OggzFunc1) (void * data, void *arg);
typedef int (*OggzFindFunc) (void * data, long serialno);
typedef int (*OggzCmpFunc) (const void * a, const void * b, void * user_data);
/**
* Create a new vector object.
* \retval a pointer to the new vector.
* \retval NULL on failure.
*/
OggzVector *
oggz_vector_new (void);
/**
* Destroy a vector object.
*/
void
oggz_vector_delete (OggzVector * vector);
......@@ -61,19 +69,41 @@ oggz_vector_nth_p (OggzVector * vector, int n);
long
oggz_vector_nth_l (OggzVector * vector, int n);
/**
* Call a function on each element of a vector, in order.
* \param vector The OggzVector to iterate over
* \param func The OggzFunc to be called on each element
* \retval 0 on success
*/
int
oggz_vector_foreach (OggzVector * vector, OggzFunc func);
/**
* Call a function with a userdata pointer on each element
* of a vector, in order. This allows the function to access
* shared data when operating on the element sequence.
* \param vector The OggzVector to iterate over
* \param func The OggzFunc1 to be called on each element
* \param arg The userdata pointer to be passed to the function
* along with the vector member
* \retval 0 on success
*/
int
oggz_vector_foreach1 (OggzVector * vector, OggzFunc1 func, void *arg);
/**
* Return the number of elements in a vector.
* \param vector The vector to query
* \retval The number of elements
*/
int
oggz_vector_size (OggzVector * vector);
/**
* Add an element to a vector. If the vector has a comparison function,
* the new element is inserted in sorted order, otherwise it is appended
* to the tail.
* to the tail. Use this function to add pointer elements to the vector.
* Use ogg_vector_insert_l for long values.
* \param vector An OggzVector
* \param data The new element to add
* \retval data If the element was successfully added
......@@ -82,6 +112,16 @@ oggz_vector_size (OggzVector * vector);
void *
oggz_vector_insert_p (OggzVector * vector, void * data);
/**
* Add an element to a vector. If the vector has a comparison function,
* the new element is inserted in sorted order, otherwise it is appended
* to the tail. Use this function to add long value elements to the
* vector. Use ogg_vector_insert_p for pointer values.
* \param vector An OggzVector
* \param ldata The new element to add
* \retval ldata If the element was successfully added
* \retval -1L If adding the element failed
*/
long
oggz_vector_insert_l (OggzVector * vector, long ldata);
......@@ -101,10 +141,29 @@ oggz_vector_remove_p (OggzVector * vector, void * data);
OggzVector *
oggz_vector_remove_l (OggzVector * vector, long ldata);
/**
* Set a comparison function for a vector.
* Vectors can be sorted, or stored in append order, depending on
* whether they have a comparison function defined. When a comparison
* function is first set, it will be used to sort the entire vector,
* and subsequence insertions will maintain the sort. If no comparison
* function is set, new elements are appended at the end of the vector.
* Call oggz_vector_set_cmp(vector, NULL, NULL) to remove the current
* comparison function. This does not affect the member order.
* \param vector the vector to associate the comparison function with
* \param compare the OggzCmpFunc to use for comparisons
* \param user_data private data pointer for the compare function
* \retval 0 on success
*/
int
oggz_vector_set_cmp (OggzVector * vector, OggzCmpFunc compare,
void * user_data);
/**
* Pop a member off a vector.
* \retval pointer to the popped member
* \retval NULL if the vector is empty
*/
void *
oggz_vector_pop (OggzVector * vector);
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment