glist: Add docs examples of how to combine with g_steal_pointer()

As suggested by Simon McVittie and triggered by Marco Trevisan.

Signed-off-by: Philip Withnall <withnall@endlessm.com>

See: https://gitlab.gnome.org/GNOME/glib/merge_requests/818
This commit is contained in:
Philip Withnall 2020-02-07 14:09:41 +00:00
parent fbe5f2a167
commit 6bd29c2db9
2 changed files with 32 additions and 0 deletions

View File

@ -175,6 +175,13 @@ g_list_alloc (void)
* *
* If list elements contain dynamically-allocated memory, you should * If list elements contain dynamically-allocated memory, you should
* either use g_list_free_full() or free them manually first. * either use g_list_free_full() or free them manually first.
*
* It can be combined with g_steal_pointer() to ensure the list head pointer
* is not left dangling:
* |[<!-- language="C" -->
* GList *list_of_borrowed_things = ; /<!-- -->* (transfer container) *<!-- -->/
* g_list_free (g_steal_pointer (&list_of_borrowed_things));
* ]|
*/ */
void void
g_list_free (GList *list) g_list_free (GList *list)
@ -214,6 +221,15 @@ g_list_free_1 (GList *list)
* @free_func must not modify the list (eg, by removing the freed * @free_func must not modify the list (eg, by removing the freed
* element from it). * element from it).
* *
* It can be combined with g_steal_pointer() to ensure the list head pointer
* is not left dangling ­ this also has the nice property that the head pointer
* is cleared before any of the list elements are freed, to prevent double frees
* from @free_func:
* |[<!-- language="C" -->
* GList *list_of_owned_things = ; /<!-- -->* (transfer full) (element-type GObject) *<!-- -->/
* g_list_free_full (g_steal_pointer (&list_of_owned_things), g_object_unref);
* ]|
*
* Since: 2.28 * Since: 2.28
*/ */
void void

View File

@ -130,6 +130,13 @@ g_slist_alloc (void)
* If list elements contain dynamically-allocated memory, * If list elements contain dynamically-allocated memory,
* you should either use g_slist_free_full() or free them manually * you should either use g_slist_free_full() or free them manually
* first. * first.
*
* It can be combined with g_steal_pointer() to ensure the list head pointer
* is not left dangling:
* |[<!-- language="C" -->
* GSList *list_of_borrowed_things = ; /<!-- -->* (transfer container) *<!-- -->/
* g_slist_free (g_steal_pointer (&list_of_borrowed_things));
* ]|
*/ */
void void
g_slist_free (GSList *list) g_slist_free (GSList *list)
@ -168,6 +175,15 @@ g_slist_free_1 (GSList *list)
* @free_func must not modify the list (eg, by removing the freed * @free_func must not modify the list (eg, by removing the freed
* element from it). * element from it).
* *
* It can be combined with g_steal_pointer() to ensure the list head pointer
* is not left dangling ­ this also has the nice property that the head pointer
* is cleared before any of the list elements are freed, to prevent double frees
* from @free_func:
* |[<!-- language="C" -->
* GSList *list_of_owned_things = ; /<!-- -->* (transfer full) (element-type GObject) *<!-- -->/
* g_slist_free_full (g_steal_pointer (&list_of_owned_things), g_object_unref);
* ]|
*
* Since: 2.28 * Since: 2.28
**/ **/
void void