From 7bcd3aa81ac8bdcc8144a6caf917c8a249a5c3de Mon Sep 17 00:00:00 2001 From: ppisa Date: Fri, 24 Sep 2004 23:38:42 +0000 Subject: [PATCH] Structured comments updated --- ulut/ul_dbuff.h | 10 ++--- ulut/ul_dbufmore.c | 26 ++++++----- ulut/ul_evcbase.c | 2 + ulut/ul_gavl.c | 2 +- ulut/ul_gsa.c | 108 +++++++++++++++++++++++++++++++++++++++++++++ ulut/ul_gsa.h | 9 +++- 6 files changed, 139 insertions(+), 18 deletions(-) diff --git a/ulut/ul_dbuff.h b/ulut/ul_dbuff.h index 6e5f66a..3f0a16d 100644 --- a/ulut/ul_dbuff.h +++ b/ulut/ul_dbuff.h @@ -74,22 +74,22 @@ void ul_dbuff_cut_pos(ul_dbuff_t *fromdb, ul_dbuff_t *todb, int n); void ul_dbuff_cut_delimited(ul_dbuff_t *fromdb, ul_dbuff_t *todb, char delimiter, char quote); void ul_dbuff_cut_token(ul_dbuff_t *fromdb, ul_dbuff_t *todb); -/** +/* * ul_dbuff_ltrim - removes all white spaces from left of dbuff. * * Return Value: new len of dbuff (including terminating zero, if present) */ int ul_dbuff_ltrim(ul_dbuff_t *buf); -/** +/* * ul_dbuff_rtrim - removes all white spaces from right of dbuff. * If dbuff is zero terminated, trimmed dbuff is also zero terminated * * Return Value: new len of dbuff (including terminating zero, if present) */ int ul_dbuff_rtrim(ul_dbuff_t *buf); -/** - * ul_dbuff_rtrim - removes all white spaces from left and right of dbuff. - * If dbuff is zero terminated, trimmed dbuff is also zero terminated +/* + * ul_dbuff_trim - removes all white spaces from left and right of dbuff. + * If dbuff is zero terminated, trimmed dbuff is also zero terminated * * Return Value: new len of dbuff (including terminating zero, if present) */ diff --git a/ulut/ul_dbufmore.c b/ulut/ul_dbufmore.c index 99a98c7..5ce4d20 100644 --- a/ulut/ul_dbufmore.c +++ b/ulut/ul_dbufmore.c @@ -193,6 +193,7 @@ int ul_dbuff_cat(ul_dbuff_t *buf, const void *b, int n) //----------------------------------------------------------------- /** * ul_dbuff_strcat - appends str at dhe end of buffer and change its capacity if neccessary + * @buf: buffer structure * @str: string to append * * Returns number length of buffer (including terminating '\0') @@ -231,6 +232,7 @@ inline int ul_dbuff_strcat(ul_dbuff_t *buf, const char *str) //----------------------------------------------------------------- /** * ul_dbuff_strcpy - copy str to the buffer and change its capacity if neccessary + * @buf: buffer structure * @str: string to copy * * Returns number length of buffer (including terminating '\0') @@ -243,12 +245,12 @@ inline int ul_dbuff_strcpy(ul_dbuff_t *buf, const char *str) //----------------------------------------------------------------- /** -* ul_dbuff_append_byte - appends byte at dhe end of buffer and change its capacity if neccessary -* @buf: buffer structure -* @b: appended byte -* + * ul_dbuff_append_byte - appends byte at dhe end of buffer and change its capacity if neccessary + * @buf: buffer structure + * @b: appended byte + * * Returns number length of buffer (including terminating '\0') -*/ + */ inline int ul_dbuff_append_byte(ul_dbuff_t *buf, unsigned char b) { return ul_dbuff_cat(buf, &b, 1); @@ -276,9 +278,10 @@ int ul_dbuff_ltrim(ul_dbuff_t *buf) //----------------------------------------------------------------- /** * ul_dbuff_rtrim - remove all white space characters from the right - * if buffer is terminated by '\0', than is also terminated after rtrim * @buf: buffer structure * + * if buffer is terminated by '\0', than is also terminated after rtrim + * * Return: new length of buffer */ int ul_dbuff_rtrim(ul_dbuff_t *buf) @@ -393,12 +396,13 @@ int ul_str_pos(const unsigned char *str, const unsigned char *what, unsigned cha } //----------------------------------------------------------------- /** - * ul_str_ncpy - copyes string to the buffer
- * Standard strncpy function have some disadvatages - * (ie. do not append term. zero if copied string doesn't fit in to buffer, fills whole rest of buffer with zeros) + * ul_str_ncpy - copies string to the buffer * @to: buffer where to copy str * @from: zero terminated string - * @buff_size: size of the to buffer (including terminating zero) + * @buff_size: size of the @to buffer (including terminating zero) + * + * Standard strncpy function have some disadvatages + * (ie. do not append term. zero if copied string doesn't fit in to buffer, fills whole rest of buffer with zeros) * * Returns strlen(to) or negative value in case of error */ @@ -460,7 +464,7 @@ void ul_dbuff_cut_pos(ul_dbuff_t *fromdb, ul_dbuff_t *todb, int n) * @fromdb: buffer to cut from * @todb: buffer to copy to * @delimiter: delimiter char - * quote: quoted delimiters are ignored, @quote can be '\0', than it is ignored. + * @quote: quoted delimiters are ignored, @quote can be '\0', than it is ignored. */ void ul_dbuff_cut_delimited(ul_dbuff_t *fromdb, ul_dbuff_t *todb, char delimiter, char quote) { diff --git a/ulut/ul_evcbase.c b/ulut/ul_evcbase.c index 231da14..d5476b2 100644 --- a/ulut/ul_evcbase.c +++ b/ulut/ul_evcbase.c @@ -121,6 +121,8 @@ int evc_link_init_standalone(evc_link_t *link, evc_rx_fnc_t *rx_fnc, void *conte /** * evc_link_new_standalone - Allocates New Standalone Link + * @rx_fnc: callback function invoked if event is delivered + * @context: context provided to the callback function * * Link reference count is set to 1 by this function * Return Value: pointer to the new link or %NULL. diff --git a/ulut/ul_gavl.c b/ulut/ul_gavl.c index 41b0e81..88e714a 100644 --- a/ulut/ul_gavl.c +++ b/ulut/ul_gavl.c @@ -191,7 +191,7 @@ gavl_find_first(const gavl_root_t *root, const void *key) * @root: GAVL tree root * @key: key value searched for * - * same as above, but first matching item is found. + * same as above, but points to item with first key value above searched @key. * Return Value: pointer to the first item associated to key value. */ void * diff --git a/ulut/ul_gsa.c b/ulut/ul_gsa.c index 85d10f5..3c67d08 100644 --- a/ulut/ul_gsa.c +++ b/ulut/ul_gsa.c @@ -30,6 +30,13 @@ #define GSA_ALLOC_STEP 8 #define GSA_DEALLOC_STEP 32 +/** + * gsa_struct_init - Initialize GSA Structure + * @array: pointer to the array structure declared through %GSA_ARRAY_FOR + * @key_offs: offset to the order controlling field obtained by %UL_OFFSETOF + * @cmp_fnc: function defining order of items by comparing fields at offset + * @key_offs. + */ void gsa_struct_init(gsa_array_t *array, int key_offs, gsa_cmp_fnc_t *cmp_fnc) @@ -41,6 +48,13 @@ gsa_struct_init(gsa_array_t *array, int key_offs, array->items=NULL; }; +/** + * gsa_delete_all - Delete Pointers to the All Items in the Array + * @array: pointer to the array structure declared through %GSA_ARRAY_FOR + * + * This function releases all internally allocated memory, + * but does not release memory of the @array structure + */ void gsa_delete_all(gsa_array_t *array) { @@ -51,6 +65,28 @@ gsa_delete_all(gsa_array_t *array) } +/** + * gsa_bsearch_indx - Search for Item or Place for Item by Key + * @array: pointer to the array structure declared through %GSA_ARRAY_FOR + * @key: key value searched for + * @key_offs: offset to the order controlling field obtained by %UL_OFFSETOF + * @cmp_fnc: function defining order of items by comparing fields + * @mode: mode of the search operation + * @indx: pointer to place, where store value of found item array index + * or index where new item should be inserted + * + * Core search routine for GSA arrays + * binary searches for item with field at offset @key_off equal to @key value + * Values are compared by function pointed by *@cmp_fnc field in the array + * structure @array. + * Integer @mode modifies search algorithm: + * %GSA_FANY .. finds item with field value *@key, + * %GSA_FFIRST .. finds the first item with field value *@key, + * %GSA_FAFTER .. index points after last item with *@key value, + * reworded - index points at first item with higher + * value of field or after last item + * Return Value: Return of nonzero value indicates match found. + */ int gsa_bsearch_indx(gsa_array_t *array, void *key, int key_offs, gsa_cmp_fnc_t *cmp_fnc, int mode, unsigned *indx) @@ -109,6 +145,13 @@ gsa_bsearch_indx(gsa_array_t *array, void *key, int key_offs, return 1; } +/** + * gsa_find - Find Item for Provided Key + * @array: pointer to the array structure declared through %GSA_ARRAY_FOR + * @key: key value searched for + * + * Return Value: pointer to item associated to key value or %NULL. + */ void * gsa_find(gsa_array_t *array, void *key) { @@ -119,6 +162,14 @@ gsa_find(gsa_array_t *array, void *key) else return NULL; } +/** + * gsa_find_first - Find the First Item for Provided Key + * @array: pointer to the array structure declared through %GSA_ARRAY_FOR + * @key: key value searched for + * + * same as above, but first matching item is found. + * Return Value: pointer to the first item associated to key value or %NULL. + */ void * gsa_find_first(gsa_array_t *array, void *key) { @@ -129,6 +180,15 @@ gsa_find_first(gsa_array_t *array, void *key) else return NULL; } +/** + * gsa_find_indx - Find the First Item with Key Value and Return Its Index + * @array: pointer to the array structure declared through %GSA_ARRAY_FOR + * @key: key value searched for + * @indx: pointer to place for index, at which new item should be inserted + * + * same as above, but additionally stores item index value. + * Return Value: pointer to the first item associated to key value or %NULL. + */ void * gsa_find_indx(gsa_array_t *array, void *key, int *indx) { @@ -138,6 +198,14 @@ gsa_find_indx(gsa_array_t *array, void *key, int *indx) else return NULL; } +/** + * gsa_insert_at - Insert Existing Item to the Specified Array Index + * @array: pointer to the array structure declared through %GSA_ARRAY_FOR + * @item: pointer to inserted Item + * @where: at which index should be @item inserted + * + * Return Value: positive or zero value informs about success + */ int gsa_insert_at(gsa_array_t *array, void *item, unsigned where) { @@ -164,6 +232,15 @@ gsa_insert_at(gsa_array_t *array, void *item, unsigned where) return 0; } +/** + * gsa_insert - Insert Existing into Ordered Item Array + * @array: pointer to the array structure declared through %GSA_ARRAY_FOR + * @item: pointer to inserted Item + * @mode: if mode is %GSA_FAFTER, multiple items with same key can + * be stored into array, else strict ordering is required + * + * Return Value: positive or zero value informs about success + */ int gsa_insert(gsa_array_t *array, void *item, int mode) { @@ -179,6 +256,13 @@ gsa_insert(gsa_array_t *array, void *item, int mode) return res; } +/** + * gsa_delete_at - Delete Item from the Specified Array Index + * @array: pointer to the array structure declared through %GSA_ARRAY_FOR + * @indx: index of deleted item + * + * Return Value: positive or zero value informs about success + */ int gsa_delete_at(gsa_array_t *array, unsigned indx) { @@ -202,6 +286,13 @@ gsa_delete_at(gsa_array_t *array, unsigned indx) return 0; } +/** + * gsa_delete - Delete Item from the Array + * @array: pointer to the array structure declared through %GSA_ARRAY_FOR + * @item: pointer to deleted Item + * + * Return Value: positive or zero value informs about success + */ int gsa_delete(gsa_array_t *array, void *item) { @@ -223,6 +314,14 @@ gsa_delete(gsa_array_t *array, void *item) return gsa_delete_at(array,indx); } +/** + * gsa_resort_buble - Sort Again Array If Sorting Criteria Are Changed + * @array: pointer to the array structure declared through %GSA_ARRAY_FOR + * @key_offs: offset to the order controlling field obtained by %UL_OFFSETOF + * @cmp_fnc: function defining order of items by comparing fields + * + * Return Value: non-zero value informs, that resorting changed order + */ int gsa_resort_buble(gsa_array_t *array, int key_offs, gsa_cmp_fnc_t *cmp_fnc) @@ -265,6 +364,15 @@ gsa_resort_buble(gsa_array_t *array, int key_offs, }while(1); } +/** + * gsa_setsort - Change Array Sorting Criterion + * @array: pointer to the array structure declared through %GSA_ARRAY_FOR + * @key_offs: new value of offset to the order controlling field + * @cmp_fnc: new function defining order of items by comparing fields at + * offset @key_offs + * + * Return Value: non-zero value informs, that resorting changed order + */ int gsa_setsort(gsa_array_t *array, int key_offs, gsa_cmp_fnc_t *cmp_fnc) diff --git a/ulut/ul_gsa.h b/ulut/ul_gsa.h index 5626312..ec4e6f0 100644 --- a/ulut/ul_gsa.h +++ b/ulut/ul_gsa.h @@ -125,7 +125,14 @@ gsa_setsort(gsa_array_t *array, int key_offs, /*===========================================================*/ /* Macrodefinitions to prepare custom GSA arrays with */ -typedef struct { +/** + * struct gsa_array_field_t - Structure Representing Anchor of ustom GSA Array + * @items: pointer to array of pointers to individual items + * @count: number of items in the sorted array + * @alloc_count: allocated pointer array capacity + */ + +typedef struct gsa_array_field_t{ void **items; unsigned count; unsigned alloc_count; -- 2.39.2