HashTableIter

A GHashTable provides associations between keys and values which is optimized so that given a key, the associated value can be found very quickly.

Note that neither keys nor values are copied when inserted into the GHashTable, so they must exist for the lifetime of the GHashTable. This means that the use of static strings is OK, but temporary strings (i.e. those created in buffers and those returned by GTK+ widgets) should be copied with g_strdup() before being inserted.

If keys or values are dynamically allocated, you must be careful to ensure that they are freed when they are removed from the GHashTable, and also when they are overwritten by new insertions into the GHashTable. It is also not advisable to mix static strings and dynamically-allocated strings in a GHashTable, because it then becomes difficult to determine whether the string should be freed.

To create a GHashTable, use g_hash_table_new().

To insert a key and value into a GHashTable, use g_hash_table_insert().

To lookup a value corresponding to a given key, use g_hash_table_lookup() and g_hash_table_lookup_extended().

g_hash_table_lookup_extended() can also be used to simply check if a key is present in the hash table.

To remove a key and value, use g_hash_table_remove().

To call a function for each key and value pair use g_hash_table_foreach() or use a iterator to iterate over the key/value pairs in the hash table, see GHashTableIter.

To destroy a GHashTable use g_hash_table_destroy().

A common use-case for hash tables is to store information about a set of keys, without associating any particular value with each key. GHashTable optimizes one way of doing so: If you store only key-value pairs where key == value, then GHashTable does not allocate memory to store the values, which can be a considerable space saving, if your set is large. The functions g_hash_table_add() and g_hash_table_contains() are designed to be used when using GHashTable this way.

Constructors

this
this(GHashTableIter* gHashTableIter)

Sets our main struct and passes it to the parent class

Members

Functions

getHashTable
HashTable getHashTable()

Returns the GHashTable associated with iter. Since 2.16

getHashTableIterStruct
GHashTableIter* getHashTableIterStruct()
Undocumented in source. Be warned that the author may not have intended to support it.
getStruct
void* getStruct()

the main Gtk struct as a void*

init
void init(HashTable hashTable)

Initializes a key/value pair iterator and associates it with hash_table. Modifying the hash table after calling this function invalidates the returned iterator. Since 2.16

next
int next(void** key, void** value)

Advances iter and retrieves the key and/or value that are now pointed to as a result of this advancement. If FALSE is returned, key and value are not set, and the iterator becomes invalid. Since 2.16

remove
void remove()

Removes the key/value pair currently pointed to by the iterator from its associated GHashTable. Can only be called after g_hash_table_iter_next() returned TRUE, and cannot be called more than once for the same key/value pair. If the GHashTable was created using g_hash_table_new_full(), the key and value are freed using the supplied destroy functions, otherwise you have to make sure that any dynamically allocated values are freed yourself. Since 2.16

replace
void replace(void* value)

Replaces the value currently pointed to by the iterator from its associated GHashTable. Can only be called after g_hash_table_iter_next() returned TRUE. If you supplied a value_destroy_func when creating the GHashTable, the old value is freed using that function. Since 2.30

steal
void steal()

Removes the key/value pair currently pointed to by the iterator from its associated GHashTable, without calling the key and value destroy functions. Can only be called after g_hash_table_iter_next() returned TRUE, and cannot be called more than once for the same key/value pair. Since 2.16

Variables

gHashTableIter
GHashTableIter* gHashTableIter;

the main Gtk struct

Meta