From d630c5802156fb2c46503337c41a6f5d8552bfba Mon Sep 17 00:00:00 2001 From: Philip Withnall Date: Wed, 4 Dec 2019 10:44:33 +0000 Subject: [PATCH] ghash: Document the iteration order over a hash table is not defined MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit It’s quite surprising that this wasn’t documented already. Hash tables are unordered, and any recognisable iteration ordering is not guaranteed and might change in future releases. Signed-off-by: Philip Withnall --- glib/ghash.c | 14 +++++++++++++- 1 file changed, 13 insertions(+), 1 deletion(-) diff --git a/glib/ghash.c b/glib/ghash.c index 549baa9ea..0f1562a06 100644 --- a/glib/ghash.c +++ b/glib/ghash.c @@ -99,7 +99,9 @@ * * To call a function for each key and value pair use * g_hash_table_foreach() or use an iterator to iterate over the - * key/value pairs in the hash table, see #GHashTableIter. + * key/value pairs in the hash table, see #GHashTableIter. The iteration order + * of a hash table is not defined, and you must not rely on iterating over + * keys/values in the same order as they were inserted. * * To destroy a #GHashTable use g_hash_table_destroy(). * @@ -209,6 +211,9 @@ * to iterate over the elements of a #GHashTable. GHashTableIter * structures are typically allocated on the stack and then initialized * with g_hash_table_iter_init(). + * + * The iteration order of a #GHashTableIter over the keys/values in a hash + * table is not defined. */ /** @@ -1088,6 +1093,10 @@ g_hash_table_new_full (GHashFunc hash_func, * Initializes a key/value pair iterator and associates it with * @hash_table. Modifying the hash table after calling this function * invalidates the returned iterator. + * + * The iteration order of a #GHashTableIter over the keys/values in a hash + * table is not defined. + * * |[ * GHashTableIter iter; * gpointer key, value; @@ -2023,6 +2032,9 @@ g_hash_table_foreach_steal (GHashTable *hash_table, * items). To remove all items matching a predicate, use * g_hash_table_foreach_remove(). * + * The order in which g_hash_table_foreach() iterates over the keys/values in + * the hash table is not defined. + * * See g_hash_table_find() for performance caveats for linear * order searches in contrast to g_hash_table_lookup(). */