glist: Mention that g_list_length() is bad for checking list emptiness

Despite linked lists being a fairly fundamental computer science
concept, some developers insist on using:
    g_list_length (list) > 0
to determine whether a list is non-empty, rather than using:
    list != NULL

Add a comment to the documentation for g_list_length() and
g_slist_length() pointing out the better alternative in the hope that it
will prevent some of this abuse.

https://bugzilla.gnome.org/show_bug.cgi?id=741024

diff --git a/glib/glist.c b/glib/glist.c
index 18e25da..2f3a49b 100644 (file)
--- a/glib/glist.c
+++ b/glib/glist.c
@@ -947,7 +947,8 @@ g_list_first (GList *list)
  *
  * This function iterates over the whole list to count its elements.
  * Use a #GQueue instead of a GList if you regularly need the number
- * of items. 
+ * of items. To check whether the list is non-empty, it is faster to check
+ * @list against %NULL.
  *
  * Returns: the number of elements in the #GList
  */

diff --git a/glib/gslist.c b/glib/gslist.c
index 4fb7e41..0757f64 100644 (file)
--- a/glib/gslist.c
+++ b/glib/gslist.c
@@ -839,7 +839,8 @@ g_slist_last (GSList *list)
  * Gets the number of elements in a #GSList.
  *
  * This function iterates over the whole list to
- * count its elements.
+ * count its elements. To check whether the list is non-empty, it is faster to
+ * check @list against %NULL.
  *
  * Returns: the number of elements in the #GSList
  */