Merge branch 'gstring-free-and-steal' into 'main'

Add g_string_free_and_steal

See merge request GNOME/glib!3219

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

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

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

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();
 }