forked from enlightenment/efl
parent
3dc1dcbd32
commit
bdb3096126
|
@ -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)
|
||||
{
|
||||
|
|
|
@ -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.
|
||||
*
|
||||
|
|
Loading…
Reference in New Issue