Article directory

1 Introduction to Hash Table
2 Glib HashTable
3 examples

Reference link:
1. Source code
https://gitlab.gnome.org/GNOME/glib/
2. Official website introduction
https://docs.gtk.org/glib/struct.HashTable.html

1 Introduction to Hash Table

A hash table is a data structure based on key-value access, which can speed up the lookup. Therefore, in some scenarios that need to quickly find out whether there are duplicate elements, a hash table is often used to implement it.

2 Glib HashTable

Glib provides many convenient functions, and encapsulates the linked lists and data structures we often use. This article briefly introduces the functions related to the hash table in Glib for future use.

2.0 Function Overview

function	illustrate
g_hash_table_new	create
g_hash_table_new_full	create
g_hash_table_new_similar	create
g_hash_table_destroy	delete all keys
g_hash_table_remove	Delete the specified key
g_hash_table_remove_all	delete all keys
g_hash_table_steal	Delete the specified key from GHashTable
g_hash_table_steal_all	Delete all keys from GHashTable
g_hash_table_steal_extended	Delete the specified key from GHashTable
g_hash_table_add	Add to
g_hash_table_replace	Revise
g_hash_table_insert	insert
g_hash_table_lookup	Find the value corresponding to the key
g_hash_table_lookup_extended	Find the value corresponding to the key
g_hash_table_find	Search by custom search rules
g_hash_table_get_keys	Find all keys in the hash table
g_hash_table_get_keys_as_array	Retrieve each key in the hash table as an array
g_hash_table_get_values	Find all values in the hash table
g_hash_table_foreach	Loop through each key/value in the hash table
g_hash_table_foreach_remove	Loop through each key/value in the hash table and delete the key/value that matches func
g_hash_table_foreach_steal	Loop through each key/value in the hash table and delete the key/value that matches func
g_hash_table_contains	Check if the key exists in the hash table
g_hash_table_size	The number of key/value in the hash table

2.1 Create a hash table

Three different functions are provided in glib for creating hash tables: g_hash_table_new, g_hash_table_new_full, g_hash_table_new_similar.

2.1.1 g_hash_table_new

GHashTable *
g_hash_table_new (GHashFunc  hash_func,
                  GEqualFunc key_equal_func);

Creates a new HashTable with a reference count of 1.
hash_func converts the key value into key_hash, and generally uses the g_str_hash function as an input parameter;
key_equal_func is used to compare key values, and this function is called during operations such as insertion and deletion, and generally uses the g_str_equal function as an input parameter.

2.1.2 g_hash_table_new_full

GHashTable *
g_hash_table_new_full (GHashFunc      hash_func,
                       GEqualFunc     key_equal_func,
                       GDestroyNotify key_destroy_func,
                       GDestroyNotify value_destroy_func);

Creates a new HashTable with a reference count of 1, and allows specifying functions to free memory allocated by key and value that are called when entries are deleted from the GHashTable.
The functions of hash_func and key_equal_func have been introduced above and will not be repeated;
key_destroy_func is the release of the key value memory, and the g_free function is generally used as an input parameter;
value_destroy_func is the release of the value value memory.

2.1.3 g_hash_table_new_similar

GHashTable *
g_hash_table_new_similar (GHashTable *other_hash_table);

Create a new HashTable with a reference count of 1, where functions such as hash_func, key_equal_func, key_destroy_func, and value_destroy_func come from other_hash_table.

2.2 Delete the hash table

Deleting a hash table provides several different functions: g_hash_table_destroy, g_hash_table_remove, g_hash_table_remove_all.

2.2.1 g_hash_table_destroy

void
g_hash_table_destroy (GHashTable *hash_table);

Destroy all keys and values in GHashTable. If the key and value are allocated dynamically, they need to be released first or this function will use the key_destroy_func and value_destroy_func input function when the g_hash_table_new_full function is called at the time of creation to automatically destroy.

2.2.2 g_hash_table_remove

gboolean
g_hash_table_remove (GHashTable    *hash_table,
                     gconstpointer  key);

Delete the specified key from GHashTable. If the key is allocated dynamically, you need to release the memory first or this function will use the key_destroy_func and value_destroy_func input function when the g_hash_table_new_full function is called during creation to automatically destroy it.

2.2.3 g_hash_table_remove_all

void
g_hash_table_remove_all (GHashTable *hash_table);

Delete all keys from GHashTable. If the key is allocated dynamically, you need to release the memory first or this function will use the key_destroy_func and value_destroy_func input function when the g_hash_table_new_full function is called during creation to automatically destroy it.

2.2.4 g_hash_table_steal

gboolean
g_hash_table_steal (GHashTable    *hash_table,
                    gconstpointer  key);

Delete the specified key from GHashTable. But the function will not be called to release the key/value memory.

2.2.5 g_hash_table_steal_all

void
g_hash_table_steal_all (GHashTable *hash_table);
Delete all keys from GHashTable. But the function will not be called to release the key/value memory.

2.2.6 g_hash_table_steal_extended

gboolean
g_hash_table_steal_extended (GHashTable    *hash_table,
                             gconstpointer  lookup_key,
                             gpointer      *stolen_key,
                             gpointer      *stolen_value);

Delete the specified key from GHashTable. But the function will not be called to release the key/value memory. At the same time, stolen_key and stolen_value will be output to indicate the found key/value;

2.3 add

Adding a hash table provides several different functions: g_hash_table_add, g_hash_table_replace, g_hash_table_insert.

2.3.1 g_hash_table_add

gboolean
g_hash_table_add (GHashTable *hash_table,
                  gpointer    key);

Add a key. If the key already exists in the hash table, release the old key and overwrite it with the new key.

2.3.2 g_hash_table_replace

gboolean
g_hash_table_replace (GHashTable *hash_table,
                      gpointer    key,
                      gpointer    value);

Insert a new key and value into GHashTable. If there is an old key in GHashTable, it will be replaced by the new key, and the old key and value will be automatically destroyed. This function will use the g_hash_table_new_full function when it is created When the key_destroy_func and value_destroy_func enter the parameter function to automatically destroy.

2.3.3 g_hash_table_insert

gboolean
g_hash_table_insert (GHashTable *hash_table,
                     gpointer    key,
                     gpointer    value);

Insert a new key and value into GHashTable. If there is an old key, the value will be overwritten with the new value.

2.4 Search

Several different functions are provided in glib for lookup: g_hash_table_lookup_extended, g_hash_table_lookup, g_hash_table_find.

2.4.1 g_hash_table_lookup

gpointer
g_hash_table_lookup (GHashTable    *hash_table,
                     gconstpointer  key);

Look up a key in GHashTable. This function cannot distinguish between a key that does not exist and a key that exists, but the vlaue is empty, because the return value in both cases is NULL.

2.4.2 g_hash_table_lookup_extended

gboolean
g_hash_table_lookup_extended (GHashTable    *hash_table,
                              gconstpointer  lookup_key,
                              gpointer      *orig_key,
                              gpointer      *value);

orig_key is the output, that is, the found key;
value is the output, that is, the found value;
the return value is TRUE, indicating that the original key has been found.

2.4.3 g_hash_table_find

gpointer
g_hash_table_find (GHashTable *hash_table,
                   GHRFunc     predicate,
                   gpointer    user_data);

Search according to the custom search rule function predicate. If the predicate returns TRUE, it means that the corresponding key is found, and g_hash_table_find returns the corresponding value; if the predicate always returns FALSE, it means that it has not been found.

2.4.4 g_hash_table_get_keys

GList *
g_hash_table_get_keys (GHashTable *hash_table);

Find all keys in the hash table.

2.4.5 g_hash_table_get_keys_as_array

gpointer *
g_hash_table_get_keys_as_array (GHashTable *hash_table,
                                guint      *length);

Retrieve each key in the hash table in the form of an array, and length indicates the length of the array.

2.4.6 g_hash_table_get_values

GList *
g_hash_table_get_values (GHashTable *hash_table);

Find the values corresponding to all keys in the hash table.

2.5 traversal

2.5.1 g_hash_table_foreach

void
g_hash_table_foreach (GHashTable *hash_table,
                      GHFunc      func,
                      gpointer    user_data);

Loop through each key/value in the hash table.

2.5.2 g_hash_table_foreach_remove

guint
g_hash_table_foreach_remove (GHashTable *hash_table,
                             GHRFunc     func,
                             gpointer    user_data);

Loop through each key/value in the hash table and delete the key/value that matches func. If it matches, func returns TRUE, and this function deletes the matching key/value, which will be automatically destroyed by using the key_destroy_func and value_destroy_func input parameters when the g_hash_table_new_full function is called during creation.

2.5.3 g_hash_table_foreach_steal

guint
g_hash_table_foreach_steal (GHashTable *hash_table,
                            GHRFunc     func,
                            gpointer    user_data);

Loop through each key/value in the hash table and delete the key/value that matches func. Conformity means that func returns TRUE, and this function will not call the function to release the key/value.

3 examples

A simple example program.

#include <stdio.h>
#include <glib.h>
#include <stdlib.h>
#include <string.h>

static GHashTable *gpHash;


void iterator(gpointer key, gpointer value ,gpointer user_data)
{
	printf("%s, key:%s, value:%s", user_data, key, value);
}

int main()
{
	//创建
	gpHash = g_hash_table_new_full(g_str_hash, g_str_equal,
                                         g_free, NULL);
	//插入
	g_hash_table_insert(gpHash, "1","test1");
	g_hash_table_insert(gpHash, "2","test2");
	g_hash_table_insert(gpHash, "3","test3");
	g_hash_table_insert(gpHash, "4","test4");
	g_hash_table_insert(gpHash, "5","test5");
	
	//获取大小
	printf("hash num:%d\n", ,g_hash_table_size(gpHash);
	
	//查找指定key对应的value
	g_printf("key:%s, value:%s\n", "1", g_hash_table_lookup(gpHash, "1");
	
	//删除指定key
	gboolean found = g_hash_table_remove(gpHash, "1");
	g_printf("del:%s, state:%d\n", "1", found);
	
	//遍历全部的key
	g_hash_table_foreach(gpHash, (GHFunc)iterator, "test");
	
	//删除全部key
	g_hash_table_destroy(gpHash);
	return 0;
}

C function learning (2): GLib HashTable function