docs: Move the refstring SECTION

Move the contents to the data-structures.md file.

Helps: #3037

docs/reference/glib/data-structures.md

@@ -5,6 +5,7 @@ SPDX-FileCopyrightText: 2011 Collabora, Ltd.
 SPDX-FileCopyrightText: 2012 Olivier Sessink
 SPDX-FileCopyrightText: 2010, 2011, 2014 Matthias Clasen
 SPDX-FileCopyrightText: 2018 Sébastien Wilmet
+SPDX-FileCopyrightText: 2018 Emmanuele Bassi
 SPDX-FileCopyrightText: 2019 Emmanuel Fleury
 SPDX-FileCopyrightText: 2017, 2018, 2019 Endless Mobile, Inc.
 SPDX-FileCopyrightText: 2020 Endless OS Foundation, LLC
@@ -455,3 +456,62 @@ any sequence.
 To sort the data, either use [method@GLib.Sequence.insert_sorted] or [method@GLib.Sequence.insert_sorted_iter]
 to add data to the `GSequence` or, if you want to add a large amount of data, it is more efficient to call
 [method@GLib.Sequence.sort] or [method@GLib.Sequence.sort_iter] after doing unsorted insertions.
+
+## Reference-counted strings
+
+Reference-counted strings are normal C strings that have been augmented with a reference count to manage
+their resources. You allocate a new reference counted string and acquire and release references as needed,
+instead of copying the string among callers; when the last reference on the string is released, the resources
+allocated for it are freed.
+
+Typically, reference-counted strings can be used when parsing data from files and storing them into data
+structures that are passed to various callers:
+
+```c
+PersonDetails *
+person_details_from_data (const char *data)
+{
+  // Use g_autoptr() to simplify error cases
+  g_autoptr(GRefString) full_name = NULL;
+  g_autoptr(GRefString) address =  NULL;
+  g_autoptr(GRefString) city = NULL;
+  g_autoptr(GRefString) state = NULL;
+  g_autoptr(GRefString) zip_code = NULL;
+
+  // parse_person_details() is defined elsewhere; returns refcounted strings
+  if (!parse_person_details (data, &full_name, &address, &city, &state, &zip_code))
+    return NULL;
+
+  if (!validate_zip_code (zip_code))
+    return NULL;
+
+  // add_address_to_cache() and add_full_name_to_cache() are defined
+  // elsewhere; they add strings to various caches, using refcounted
+  // strings to avoid copying data over and over again
+  add_address_to_cache (address, city, state, zip_code);
+  add_full_name_to_cache (full_name);
+
+  // person_details_new() is defined elsewhere; it takes a reference
+  // on each string
+  PersonDetails *res = person_details_new (full_name,
+                                           address,
+                                           city,
+                                           state,
+                                           zip_code);
+
+  return res;
+}
+```
+
+In the example above, we have multiple functions taking the same strings for different uses; with typical
+C strings, we'd have to copy the strings every time the life time rules of the data differ from the
+life-time of the string parsed from the original buffer. With reference counted strings, each caller can
+ake a reference on the data, and keep it as long as it needs to own the string.
+
+Reference-counted strings can also be "interned" inside a global table owned by GLib; while an interned
+string has at least a reference, creating a new interned reference-counted string with the same contents
+will return a reference to the existing string instead of creating a new reference-counted string instance.
+Once the string loses its last reference, it will be automatically removed from the global interned strings
+table.
+
+Reference-counted strings were added to GLib in 2.58.

glib/grefstring.c

@@ -18,74 +18,6 @@
  * License along with this library; if not, see <http://www.gnu.org/licenses/>.
  */
 
-/**
- * SECTION:refstring
- * @Title: Reference counted strings
- * @Short_description: Strings with reference counted memory management
- *
- * Reference counted strings are normal C strings that have been augmented
- * with a reference counter to manage their resources. You allocate a new
- * reference counted string and acquire and release references as needed,
- * instead of copying the string among callers; when the last reference on
- * the string is released, the resources allocated for it are freed.
- *
- * Typically, reference counted strings can be used when parsing data from
- * files and storing them into data structures that are passed to various
- * callers:
- *
- * |[<!-- language="C" -->
- * PersonDetails *
- * person_details_from_data (const char *data)
- * {
- *   // Use g_autoptr() to simplify error cases
- *   g_autoptr(GRefString) full_name = NULL;
- *   g_autoptr(GRefString) address =  NULL;
- *   g_autoptr(GRefString) city = NULL;
- *   g_autoptr(GRefString) state = NULL;
- *   g_autoptr(GRefString) zip_code = NULL;
- *
- *   // parse_person_details() is defined elsewhere; returns refcounted strings
- *   if (!parse_person_details (data, &full_name, &address, &city, &state, &zip_code))
- *     return NULL;
- *
- *   if (!validate_zip_code (zip_code))
- *     return NULL;
- *
- *   // add_address_to_cache() and add_full_name_to_cache() are defined
- *   // elsewhere; they add strings to various caches, using refcounted
- *   // strings to avoid copying data over and over again
- *   add_address_to_cache (address, city, state, zip_code);
- *   add_full_name_to_cache (full_name);
- *
- *   // person_details_new() is defined elsewhere; it takes a reference
- *   // on each string
- *   PersonDetails *res = person_details_new (full_name,
- *                                            address,
- *                                            city,
- *                                            state,
- *                                            zip_code);
- *
- *   return res;
- * }
- * ]|
- *
- * In the example above, we have multiple functions taking the same strings
- * for different uses; with typical C strings, we'd have to copy the strings
- * every time the life time rules of the data differ from the life time of
- * the string parsed from the original buffer. With reference counted strings,
- * each caller can take a reference on the data, and keep it as long as it
- * needs to own the string.
- *
- * Reference counted strings can also be "interned" inside a global table
- * owned by GLib; while an interned string has at least a reference, creating
- * a new interned reference counted string with the same contents will return
- * a reference to the existing string instead of creating a new reference
- * counted string instance. Once the string loses its last reference, it will
- * be automatically removed from the global interned strings table.
- *
- * Since: 2.58
- */
-
 #include "config.h"
 
 #include "grefstring.h"