[glib/wip/ernestask/g_clear_list: 1/2] list: Add g_clear_list()

[Ernestas Kulik <ernestask src gnome org>]

commit 93875999442e2d1839321464196b626349d3a3e3
Author: Ernestas Kulik <ekulik redhat com>
Date:   Sat Nov 23 17:41:54 2019 +0100

    list: Add g_clear_list()
    
    Although not quite as often-occurring, this should help with constructs
    like this:
    
      if (list)
        {
          g_list_free_full (list, foo);
          list = NULL;
        }
    
    Closes https://gitlab.gnome.org/GNOME/glib/issues/1943

 docs/reference/glib/glib-sections.txt |  1 +
 glib/glist.c                          | 27 +++++++++++++++++++++++++++
 glib/glist.h                          |  4 ++++
 glib/tests/utils.c                    | 19 +++++++++++++++++++
 4 files changed, 51 insertions(+)
---
diff --git a/docs/reference/glib/glib-sections.txt b/docs/reference/glib/glib-sections.txt
index e9dfa73e9..d5b112964 100644
--- a/docs/reference/glib/glib-sections.txt
+++ b/docs/reference/glib/glib-sections.txt
@@ -2503,6 +2503,7 @@ g_list_delete_link
 g_list_remove_all
 g_list_free
 g_list_free_full
+g_clear_list
 
 <SUBSECTION>
 g_list_alloc
diff --git a/glib/glist.c b/glib/glist.c
index 39143fa7e..0dde96bcf 100644
--- a/glib/glist.c
+++ b/glib/glist.c
@@ -1313,3 +1313,30 @@ g_list_sort_with_data (GList            *list,
 {
   return g_list_sort_real (list, (GFunc) compare_func, user_data);
 }
+
+/**
+ * g_clear_list: (skip)
+ * @list_ptr: (not nullable): a #GList return location
+ * @destroy: (nullable): the function to pass to g_list_free_full() or %NULL to not free elements
+ *
+ * Clears a pointer to a #GList, freeing it and, optionally, freeing its elements using @destroy.
+ *
+ * If @list_ptr points to %NULL, this does nothing.
+ */
+void
+g_clear_list (GList          **list_ptr,
+              GDestroyNotify   destroy)
+{
+  GList *list;
+
+  list = *list_ptr;
+  if (list)
+    {
+      *list_ptr = NULL;
+
+      if (destroy)
+        g_list_free_full(list, destroy);
+      else
+        g_list_free(list);
+    }
+}
diff --git a/glib/glist.h b/glib/glist.h
index 8b4703e17..cf7766c7b 100644
--- a/glib/glist.h
+++ b/glib/glist.h
@@ -147,6 +147,10 @@ GLIB_AVAILABLE_IN_ALL
 gpointer g_list_nth_data                (GList            *list,
                                         guint             n);
 
+GLIB_AVAILABLE_IN_2_64
+void     g_clear_list                   (GList            **list_ptr,
+                                         GDestroyNotify     destroy);
+
 
 #define g_list_previous(list)          ((list) ? (((GList *)(list))->prev) : NULL)
 #define g_list_next(list)              ((list) ? (((GList *)(list))->next) : NULL)
diff --git a/glib/tests/utils.c b/glib/tests/utils.c
index cf8a5cbc3..f0908891f 100644
--- a/glib/tests/utils.c
+++ b/glib/tests/utils.c
@@ -760,6 +760,24 @@ test_int_limits (void)
   g_free (str);
 }
 
+static void
+test_clear_list (void)
+{
+    GList *list = NULL;
+
+    list = g_list_prepend (list, "test");
+    g_assert_nonnull (list);
+
+    g_clear_list (&list, NULL);
+    g_assert_null (list);
+
+    list = g_list_prepend (list, g_malloc (16));
+    g_assert_nonnull (list);
+
+    g_clear_list (&list, g_free);
+    g_assert_null (list);
+}
+
 int
 main (int   argc,
       char *argv[])
@@ -814,6 +832,7 @@ main (int   argc,
   g_test_add_func ("/utils/atexit", test_atexit);
   g_test_add_func ("/utils/check-setuid", test_check_setuid);
   g_test_add_func ("/utils/int-limits", test_int_limits);
+  g_test_add_func ("/utils/clear-list", test_clear_list);
 
   return g_test_run ();
 }