From 58dd3d39655ebae5c71cc62df4f27eac7c3a6d78 Mon Sep 17 00:00:00 2001
From: Matthias Clasen <mclasen@redhat.com>
Date: Thu, 19 Jan 2023 14:47:11 +0000
Subject: [PATCH] Add g_string_free_and_steal

---
 docs/reference/glib/glib-sections.txt.in |  1 +
 glib/gstring.c                           | 22 +++++++++++++++++++
 glib/gstring.h                           |  2 ++
 glib/tests/string.c                      | 27 ++++++++++++++++++++++++
 4 files changed, 52 insertions(+)

diff --git a/docs/reference/glib/glib-sections.txt.in b/docs/reference/glib/glib-sections.txt.in
index 6795a141f..072084b2e 100644
--- a/docs/reference/glib/glib-sections.txt.in
+++ b/docs/reference/glib/glib-sections.txt.in
@@ -2652,6 +2652,7 @@ g_string_truncate
 g_string_set_size
 g_string_free
 g_string_free_to_bytes
+g_string_free_and_steal
 
 <SUBSECTION>
 g_string_up
diff --git a/glib/gstring.c b/glib/gstring.c
index 8967ce12b..5fb7c3d1e 100644
--- a/glib/gstring.c
+++ b/glib/gstring.c
@@ -199,6 +199,9 @@ g_string_new_len (const gchar *init,
  * it's %FALSE, the caller gains ownership of the buffer and must
  * free it after use with g_free().
  *
+ * Instead of passing %FALSE to this function, consider using
+ * g_string_free_and_steal().
+ *
  * Returns: (nullable): the character data of @string
  *          (i.e. %NULL if @free_segment is %TRUE)
  */
@@ -223,6 +226,25 @@ g_string_free (GString  *string,
   return segment;
 }
 
+/**
+ * g_string_free_and_steal:
+ * @string: (transfer full): a #GString
+ *
+ * Frees the memory allocated for the #GString.
+ *
+ * The caller gains ownership of the buffer and
+ * must free it after use with g_free().
+ *
+ * Returns: (transfer full): the character data of @string
+ *
+ * Since: 2.76
+ */
+gchar *
+g_string_free_and_steal (GString *string)
+{
+  return g_string_free (string, FALSE);
+}
+
 /**
  * g_string_free_to_bytes:
  * @string: (transfer full): a #GString
diff --git a/glib/gstring.h b/glib/gstring.h
index 7b8455360..ef219a62a 100644
--- a/glib/gstring.h
+++ b/glib/gstring.h
@@ -58,6 +58,8 @@ GString*     g_string_sized_new         (gsize            dfl_size);
 GLIB_AVAILABLE_IN_ALL
 gchar*       g_string_free              (GString         *string,
                                          gboolean         free_segment);
+GLIB_AVAILABLE_IN_2_76
+gchar*       g_string_free_and_steal    (GString         *string) G_GNUC_WARN_UNUSED_RESULT;
 GLIB_AVAILABLE_IN_2_34
 GBytes*      g_string_free_to_bytes     (GString         *string);
 GLIB_AVAILABLE_IN_ALL
diff --git a/glib/tests/string.c b/glib/tests/string.c
index 7d690e0e5..92138c0ba 100644
--- a/glib/tests/string.c
+++ b/glib/tests/string.c
@@ -630,6 +630,32 @@ test_string_replace (void)
     }
 }
 
+static void
+test_string_steal (void)
+{
+  GString *string;
+  char *str;
+
+  string = g_string_new ("One");
+  g_string_append (string, ", two");
+  g_string_append (string, ", three");
+  g_string_append_c (string, '.');
+
+  str = g_string_free (string, FALSE);
+
+  g_assert_cmpstr (str, ==, "One, two, three.");
+  g_free (str);
+
+  string = g_string_new ("1");
+  g_string_append (string, " 2");
+  g_string_append (string, " 3");
+
+  str = g_string_free_and_steal (string);
+
+  g_assert_cmpstr (str, ==, "1 2 3");
+  g_free (str);
+}
+
 int
 main (int   argc,
       char *argv[])
@@ -656,6 +682,7 @@ main (int   argc,
   g_test_add_func ("/string/test-string-set-size", test_string_set_size);
   g_test_add_func ("/string/test-string-to-bytes", test_string_to_bytes);
   g_test_add_func ("/string/test-string-replace", test_string_replace);
+  g_test_add_func ("/string/test-string-steal", test_string_steal);
 
   return g_test_run();
 }