From bdb30961264df54c72c8c49475a2c393cf9d513f Mon Sep 17 00:00:00 2001 From: Carsten Haitzler Date: Wed, 20 Nov 2002 04:34:05 +0000 Subject: [PATCH] more documentation. SVN revision: 6453 --- legacy/evas/src/lib/data/evas_hash.c | 185 ++++++++++++++++++++++++++- legacy/evas/src/lib/data/evas_list.c | 3 +- 2 files changed, 186 insertions(+), 2 deletions(-) diff --git a/legacy/evas/src/lib/data/evas_hash.c b/legacy/evas/src/lib/data/evas_hash.c index ad26cf32f0..3167317999 100644 --- a/legacy/evas/src/lib/data/evas_hash.c +++ b/legacy/evas/src/lib/data/evas_hash.c @@ -20,7 +20,46 @@ evas_hash_gen(const char *key) return (int)hash_num; } -/* FIXME: document this file next */ +/** + * Add an entry to the hash table. + * @param hash The hash table handle to hold the entry + * @param key The key string for the entry + * @param data The pointer to the data to be stored + * @return The modified hash table handle + * + * This function takes the data pointed to by @p data and inserts it into the + * hash table @p hash, under the string key @p key. It will return a modified + * hash table handle when done. An empty hash table starts as a NULL pointer. + * + * It is expected that the @p key will be a unique string within the hash table + * otherwise it is not deterministic as to which inserted data pointer will be + * returned when evas_hash_find() is called, or which one wil be removed on + * evas_hash_del() being called. A @p key of NULL is allowed, but will mean + * unique lookups are impossible (unless the entry is the only one with a NULL + * key in the hash table). Key strings are casesensitive. + * + * If a memory allocation failure occurs, the old hash table pointer will be + * returned, with the hash table contents unchanged, and the programmer should + * use evas_hash_alloc_error() to determine if an allocation error occured and + * recover from this situation. + * + * Example: + * @code + * Evas_Hash *hash = NULL; + * extern void *my_data; + * + * hash = evas_hash_add(hash, "My Data", my_data); + * if (evas_hash_alloc_error()) + * { + * fprintf(stderr, "ERROR: Memory is low. Hash allocation failed.\n"); + * exit(-1); + * } + * if (evas_hash_find(hash, "My Data") == my_data) + * { + * printf("My Data inserted and successfully found.\n"); + * } + * @endcode + */ Evas_Hash * evas_hash_add(Evas_Hash *hash, const char *key, void *data) { @@ -76,6 +115,37 @@ evas_hash_add(Evas_Hash *hash, const char *key, void *data) return hash; } +/** + * Remove an entry from the hash table + * @param hash The hash table handle to remove the entry from + * @param key The key string for the entry + * @param data The pointer to the data to be removed + * @return The modified hash table handle + * + * This function removed an entry from the hash table pointed to by @p hash. + * The key is identified by its string @p key. If the @p key is NULL, then the + * data pointer @p data must be provided for a match to be possible so the + * entry can be removed. As long as the @p key is not NULL, the @p data pointer + * is not required and can be NULL. Remember than key strings are case + * sensitive. + * + * This function returns the modified hash table after removal. + * + * Example: + * @code + * extern Evas_Hash *hash; + * extern void *data; + * + * printf("Insert some data...\n"); + * hash = evas_hash_add(hash, "My Data", my_data); + * printf("Removing by key...\n"); + * hash = evas_hash_del(hash, "My Data", NULL); + * printf("Insert some more data as a NULL key...\n"); + * hash = evas_hash_add(hash, NULL, my_data); + * printf("Removing by data as a NULL key...\n"); + * hash = evas_hash_del(hash, NULL, my_data); + * @endcode + */ Evas_Hash * evas_hash_del(Evas_Hash *hash, const char *key, void *data) { @@ -106,6 +176,28 @@ evas_hash_del(Evas_Hash *hash, const char *key, void *data) return hash; } +/** + * Find a specified entry in a hash table + * @param hash The hash table handle to find the entry in + * @param key The key string for the entry + * @return The data pointer for the stored entry, or NULL if not found. + * + * This function finds an entry by its @p key, which is case sensitive. If the + * entry in the hash table @p hash is found, the data pointer that was stored + * under than entry is returned, otherwise NULL is returned. + * + * Example: + * @code + * extern Evas_Hash *hash; + * extern void *data; + * + * hash = evas_hash_add(hash, "My Data", my_data); + * if (evas_hash_find(hash, "My Data") == my_data) + * { + * printf("Found stored entry!\n"); + * } + * @endcode + */ void * evas_hash_find(Evas_Hash *hash, const char *key) { @@ -139,6 +231,20 @@ evas_hash_find(Evas_Hash *hash, const char *key) return NULL; } +/** + * Return the number of buckets in the hash table + * @param hash The hash table to return the bucket count of + * @return The number of buckets in the hash table + * + * This function returns the number of buckes in he hash table @p hash. + * + * Example: + * @code + * extern Evas_Hash *hash; + * + * printf("Hash bucket count: %i\n", evas_hash_size(hash)); + * @endcode + */ int evas_hash_size(Evas_Hash *hash) { @@ -146,6 +252,24 @@ evas_hash_size(Evas_Hash *hash) return 256; } +/** + * Free an entire hash table + * @param hash The hash table to be freed + * + * This function frees up all the memory allocated to storing the specified + * hash tale pointed to by @p hash. Any entries in the table that the program + * has no more pointers for elsewhere may now be lost, so this should only be + * called if the program has lready freed any allocated data in the hash table + * or has the pointers for data in teh table stored elswehere as well. + * + * Example: + * @code + * extern Evas_Hash *hash; + * + * evas_hash_free(hash); + * hash = NULL; + * @endcode + */ void evas_hash_free(Evas_Hash *hash) { @@ -168,6 +292,38 @@ evas_hash_free(Evas_Hash *hash) free(hash); } +/** + * Call a function on every member stored in the hash table + * @param hash The hash table whose members will be walked + * @param func The function to call on each parameter + * @param fdata The data pointer to pass to the function being called + * + * This function goes through every entry in the hash table @p hash and calls + * the function @p func on each member. The function should NOT modify the + * hash table contents if it reeturns 1. IF the hash table contents are + * modified by this function or the function wishes to stop processing it must + * return 0, otherwise return 1 to keep processing. + * + * Example: + * @code + * extern Evas_Hash *hash; + * + * int hash_fn(Evas_Hash *hash, const char *key, void *data, void *fdata) + * { + * printf("Func data: %s, Hash entry: %s / %p\n", fdata, key, data); + * return 1; + * } + * + * int main(int argc, char **argv) + * { + * char *hash_fn_data; + * + * hash_fn_data = strdup("Hello World"); + * evas_hash_foreach(hash, hash_fn, hash_fn_data); + * free(hash_fn_data); + * } + * @endcode + */ void evas_hash_foreach(Evas_Hash *hash, int (*func) (Evas_Hash *hash, const char *key, void *data, void *fdata), void *fdata) { @@ -191,6 +347,33 @@ evas_hash_foreach(Evas_Hash *hash, int (*func) (Evas_Hash *hash, const char *key } } +/** + * Return memory allocation failure flag after an function requiring allocation + * @return The state of the allocation flag + * + * This function returns the state of the memory allocation flag. This flag is + * set if memory allocations fail during evas_hash_add() calls. If they do, 1 + * will be returned, otherwise 0 will be returned. The flag will remain in its + * current state until the next call that requires allocation is called, and + * is then reset. + * + * Example: + * @code + * Evas_Hash *hash = NULL; + * extern void *my_data; + * + * hash = evas_hash_add(hash, "My Data", my_data); + * if (evas_hash_alloc_error()) + * { + * fprintf(stderr, "ERROR: Memory is low. Hash allocation failed.\n"); + * exit(-1); + * } + * if (evas_hash_find(hash, "My Data") == my_data) + * { + * printf("My Data inserted and successfully found.\n"); + * } + * @endcode + */ int evas_hash_alloc_error(void) { diff --git a/legacy/evas/src/lib/data/evas_list.c b/legacy/evas/src/lib/data/evas_list.c index 7788683c94..39b59345e0 100644 --- a/legacy/evas/src/lib/data/evas_list.c +++ b/legacy/evas/src/lib/data/evas_list.c @@ -569,6 +569,7 @@ evas_list_prev(Evas_List *list) * It is equivalent to list->data. * * Example: + * @code * extern Evas_List *list; * Evas_List *l; * @@ -725,7 +726,7 @@ evas_list_reverse(Evas_List *list) * This function returns the state of the memory allocation flag. This flag is * set if memory allocations during evas_list_append(), evas_list_prepend(), * evas_list_append_relative(), or evas_list_prepend_relative() fail. If they - * do fail, 1 will be returned, otherwise 0 will be returned. the flag will + * do fail, 1 will be returned, otherwise 0 will be returned. The flag will * remain in its current state until the next call that requires allocation * is called, and is then reset. *