[glib: 1/2] gptrarray: Add an example to the g_ptr_array_steal() docs

[Philip Withnall <pwithnall src gnome org>]

commit 4c20fb990a0539c1e65e45a44434bc8500ad180f
Author: Philip Withnall <withnall endlessm com>
Date:   Fri Oct 18 11:45:30 2019 +0100

    gptrarray: Add an example to the g_ptr_array_steal() docs
    
    Signed-off-by: Philip Withnall <withnall endlessm com>

 glib/garray.c | 33 +++++++++++++++++++++++++++++++++
 1 file changed, 33 insertions(+)
---
diff --git a/glib/garray.c b/glib/garray.c
index d9963f8ac..d6b3bdafa 100644
--- a/glib/garray.c
+++ b/glib/garray.c
@@ -1078,6 +1078,39 @@ g_ptr_array_new (void)
  * on the current contents of the array and the caller is
  * responsible for freeing the array elements.
  *
+ * An example of use:
+ * |[<!-- language="C" -->
+ * g_autoptr(GPtrArray) chunk_buffer = g_ptr_array_new_with_free_func (g_bytes_unref);
+ *
+ * // Some part of your application appends a number of chunks to the pointer array.
+ * g_ptr_array_add (chunk_buffer, g_bytes_new_static ("hello", 5));
+ * g_ptr_array_add (chunk_buffer, g_bytes_new_static ("world", 5));
+ *
+ * …
+ *
+ * // Periodically, the chunks need to be sent as an array-and-length to some
+ * // other part of the program.
+ * GBytes **chunks;
+ * gsize n_chunks;
+ *
+ * chunks = g_ptr_array_steal (chunk_buffer, &n_chunks);
+ * for (gsize i = 0; i < n_chunks; i++)
+ *   {
+ *     // Do something with each chunk here, and then free them, since
+ *     // g_ptr_array_steal() transfers ownership of all the elements and the
+ *     // array to the caller.
+ *     …
+ *
+ *     g_bytes_unref (chunks[i]);
+ *   }
+ *
+ * g_free (chunks);
+ *
+ * // After calling g_ptr_array_steal(), the pointer array can be reused for the
+ * // next set of chunks.
+ * g_assert (chunk_buffer->len == 0);
+ * ]|
+ *
  * Returns: (transfer full): the element data, which should be
  *     freed using g_free().
  *