[glib: 1/2] ghash: Document the iteration order over a hash table is not defined

[Emmanuele Bassi <ebassi src gnome org>]

commit d630c5802156fb2c46503337c41a6f5d8552bfba
Author: Philip Withnall <withnall endlessm com>
Date:   Wed Dec 4 10:44:33 2019 +0000

    ghash: Document the iteration order over a hash table is not defined
    
    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 <withnall endlessm com>

 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.
+ *
  * |[<!-- language="C" -->
  * 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().
  */