Hash Data Functions

Functions that add, access or remove data from hashes. More...

Functions

EAPI Evas_Hashevas_hash_add (Evas_Hash *hash, const char *key, const void *data)
 Adds an entry to the given hash table.
EAPI Evas_Hashevas_hash_direct_add (Evas_Hash *hash, const char *key, const void *data)
 Adds an entry to the given hash table and does not duplicate the string key.
EAPI Evas_Hashevas_hash_del (Evas_Hash *hash, const char *key, const void *data)
 Removes the entry identified by key or data from the given hash table.
EAPI void * evas_hash_find (Evas_Hash *hash, const char *key)
 Retrieves a specific entry in the given hash table.
EAPI void * evas_hash_modify (Evas_Hash *hash, const char *key, const void *data)
 Modifies the entry pointer at the specified key and returns the old entry.

Detailed Description

Functions that add, access or remove data from hashes.

The following example shows how to add and then access data in a hash table:

 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");
   }

What follows is another example, showing how the evas_hash_del function is used:

 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);

Function Documentation

EAPI Evas_Hash* evas_hash_add ( Evas_Hash hash,
const char *  key,
const void *  data 
)

Adds an entry to the given hash table.

key is expected to be a unique string within the hash table. Otherwise, you cannot be sure which inserted data pointer will be accessed with evas_hash_find , and removed with evas_hash_del .

Key strings are case sensitive.

evas_hash_alloc_error should be used to determine if an allocation error occurred during this function.

Parameters:
hash The given hash table. Can be NULL, in which case a new hash table is allocated and returned.
key A unique string. Can be NULL.
data Data to associate with the string given by key.
Returns:
Either the given hash table, or if the given value for hash is NULL, then a new one. NULL will be returned if memory could not be allocated for a new table.

EAPI Evas_Hash* evas_hash_del ( Evas_Hash hash,
const char *  key,
const void *  data 
)

Removes the entry identified by key or data from the given hash table.

If key is NULL, then data is used to find a match to remove.

Parameters:
hash The given hash table.
key The key string. Can be NULL.
data The data pointer to remove if key is NULL. Otherwise, not required and can be NULL.
Returns:
The modified hash table. If there are no entries left, the hash table will be freed and NULL will be returned.

EAPI Evas_Hash* evas_hash_direct_add ( Evas_Hash hash,
const char *  key,
const void *  data 
)

Adds an entry to the given hash table and does not duplicate the string key.

key is expected to be a unique string within the hash table. Otherwise, you cannot be sure which inserted data pointer will be accessed with evas_hash_find , and removed with evas_hash_del . This call does nto make a copy of the key so it must be a string constant or stored elsewhere (in the object being added) etc.

Key strings are case sensitive.

evas_hash_alloc_error should be used to determine if an allocation error occurred during this function.

Parameters:
hash The given hash table. Can be NULL, in which case a new hash table is allocated and returned.
key A unique string. Can be NULL.
data Data to associate with the string given by key.
Returns:
Either the given hash table, or if the given value for hash is NULL, then a new one. NULL will be returned if memory could not be allocated for a new table.

EAPI void* evas_hash_find ( Evas_Hash hash,
const char *  key 
)

Retrieves a specific entry in the given hash table.

Parameters:
hash The given hash table.
key The key string of the entry to find.
Returns:
The data pointer for the stored entry, or NULL if not found.

EAPI void* evas_hash_modify ( Evas_Hash hash,
const char *  key,
const void *  data 
)

Modifies the entry pointer at the specified key and returns the old entry.

Parameters:
hash The given hash table.
key The key string of the entry to modify.
data The data to replace the old entry, if it exists.
Returns:
The data pointer for the old stored entry, or NULL if not found. If an existing entry is not found, nothing is added to the hash.