[glib/wip/gbytes-takeover: 2/3] GString: Tweak documentation, add g_string_free_to_bytes()

[Colin Walters <walters src gnome org>]

commit e324f8ffb04ce816181889da5335c92ca64abe4a
Author: Colin Walters <walters verbum org>
Date:   Tue May 29 17:58:41 2012 -0400

    GString: Tweak documentation, add g_string_free_to_bytes()
    
    The docs for GString should really mention GByteArray, and what makes
    it different.  Drop the comparison to Java which is dated and actually
    inaccurate (because StringBuffer operates on Unicode).
    
    While we're here, add g_string_free_to_bytes(), which further
    complements the spread of GBytes-based API.  For example, one can
    create a buffer using GString, then send it off via
    g_output_stream_write_bytes().
    
    https://bugzilla.gnome.org/show_bug.cgi?id=677064

 glib/gstring.c      |   48 ++++++++++++++++++++++++++++++++++++++++++------
 glib/gstring.h      |    3 +++
 glib/tests/string.c |   21 +++++++++++++++++++++
 3 files changed, 66 insertions(+), 6 deletions(-)
---
diff --git a/glib/gstring.c b/glib/gstring.c
index 9fac86c..4ab4e7e 100644
--- a/glib/gstring.c
+++ b/glib/gstring.c
@@ -50,12 +50,17 @@
  * @short_description: text buffers which grow automatically
  *     as text is added
  *
- * A #GString is an object that handles the memory management
- * of a C string for you. You can think of it as similar to a
- * Java StringBuffer. In addition to the string itself, GString
- * stores the length of the string, so can be used for binary
- * data with embedded nul bytes. To access the C string managed
- * by the GString @string, simply use @string->str.
+ * A #GString is an object that handles the memory management of a C
+ * string for you.  The emphasis of #GString is on text, typically
+ * UTF-8.  Crucially, the "str" member of a #GString is guaranteed to
+ * have a trailing NUL character, and it is therefore always safe to
+ * call functions such as strlen() or g_strdup() on it.
+ *
+ * However, a #GString can also hold arbitrary binary data, because it
+ * has a "len" member, which includes any possible embedded NUL
+ * characters in the data.  Conceptually then, #GString is effectively
+ * a #GByteArray with many convenience methods for text, and a
+ * guaranteed NUL terminator.
  */
 
 /**
@@ -227,6 +232,37 @@ g_string_free (GString  *string,
 }
 
 /**
+ * g_string_free_to_bytes:
+ * @string: a #GString
+ *
+ * Transfers ownership of the contents of @string to a newly allocated
+ * #GBytes.  The #GString structure itself is deallocated, and it is
+ * therefore invalid to use @string after invoking this function.
+ *
+ * Note that while #GString ensures that its buffer always has a
+ * trailing NUL character (not reflected in its "len"), the returned
+ * #GBytes does not include this extra NUL; i.e. it has length exactly
+ * equal to the "len" member.
+ *
+ * Returns: A newly allocated #GBytes containing contents of @string; @string itself is freed
+ * Since: 2.34
+ */
+GBytes*
+g_string_free_to_bytes (GString         *string)
+{
+  gsize len;
+  gchar *buf;
+
+  g_return_val_if_fail (string != NULL, NULL);
+
+  len = string->len;
+
+  buf = g_string_free (string, FALSE);
+
+  return g_bytes_new_take (buf, len);
+}
+
+/**
  * g_string_equal:
  * @v: a #GString
  * @v2: another #GString
diff --git a/glib/gstring.h b/glib/gstring.h
index 0797343..7543490 100644
--- a/glib/gstring.h
+++ b/glib/gstring.h
@@ -33,6 +33,7 @@
 
 #include <glib/gtypes.h>
 #include <glib/gunicode.h>
+#include <glib/gbytes.h>
 #include <glib/gutils.h>  /* for G_CAN_INLINE */
 
 G_BEGIN_DECLS
@@ -52,6 +53,8 @@ GString*     g_string_new_len           (const gchar     *init,
 GString*     g_string_sized_new         (gsize            dfl_size);
 gchar*       g_string_free              (GString         *string,
                                          gboolean         free_segment);
+GLIB_AVAILABLE_IN_2_34
+GBytes*      g_string_free_to_bytes     (GString         *string);
 gboolean     g_string_equal             (const GString   *v,
                                          const GString   *v2);
 guint        g_string_hash              (const GString   *str);
diff --git a/glib/tests/string.c b/glib/tests/string.c
index 19cb831..11c8da7 100644
--- a/glib/tests/string.c
+++ b/glib/tests/string.c
@@ -472,6 +472,26 @@ test_string_set_size (void)
   g_string_free (s, TRUE);
 }
 
+static void
+test_string_to_bytes (void)
+{
+  GString *s;
+  GBytes *bytes;
+  gconstpointer byte_data;
+  gsize byte_len;
+
+  s = g_string_new ("foo");
+  g_string_append (s, "-bar");
+
+  bytes = g_string_free_to_bytes (s);
+
+  byte_data = g_bytes_get_data (bytes, &byte_len);
+
+  g_assert_cmpint (byte_len, ==, 7);
+
+  g_assert_cmpint (memcmp (byte_data, "foo-bar", byte_len), ==, 0);
+}
+
 int
 main (int   argc,
       char *argv[])
@@ -495,6 +515,7 @@ main (int   argc,
   g_test_add_func ("/string/test-string-nul-handling", test_string_nul_handling);
   g_test_add_func ("/string/test-string-up-down", test_string_up_down);
   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);
 
   return g_test_run();
 }