Return value of g_slist_append()

Platform
1

Something I’ve never fully understood about g_slist_append(). According to the description,

Adds a new element on to the end of the list.

The return value is the new start of the list, which may have changed, so make sure you store the new value.

If g_slist_append() adds a new element to the end of the list, why would there be a new start of the list?

2

If the original list was empty.

1 Like
3

Thank you for the clarification.

4

I think the documentation for doubly-linked list is clearer, and should be replicated for singly-linked list.

Doubly-linked list:

Function Return note Returns:
g_list_append Note that the return value is the new start of the list, if @list was empty; make sure you store the new value Returns: either @list or the new start of the #GList if @list was %NULL
g_list_prepend Note that the return value is the new start of the list, which will have changed, so make sure you store the new value. Returns: a pointer to the newly prepended element, which is the new start of the #GList
g_list_insert - Returns: the (possibly changed) start of the #GList

Singly-linked list:

Function Return note Returns:
g_slist_append The return value is the new start of the list, which may have changed, so make sure you store the new value. Returns: the new start of the #GSList
g_slist_prepend same as above ^ same as above ^
g_slist_insert - Returns: the new start of the #GSList
5

Yes, that is much clearer and arguably more accurate. I’d like to make that update.

(I once tried to do a local update to the GTK documentation set with assistance from Emmanuele Bassi, but wasn’t able to get a clean build. If you know of someone who could give me step-by-step guidance, I can contribute updates as necessary.)

6

Refer instructions in https://welcome.gnome.org/en/app/Papers/#submitting-your-work to submit changes. The page is for Papers app, but the instructions are generic enough.

You can fork from https://gitlab.gnome.org/GNOME/glib.