Commit e6200eae authored by Philip Withnall's avatar Philip Withnall

garray: Document that return value of g_ptr_array_remove() may be junk

If using g_ptr_array_remove*() with a non-NULL GDestroyNotify function,
the value returned will probably be freed memory (depending on what the
GDestroyNotify) function actually does. Warn about that in the
documentation. We can’t just unconditionally return NULL in these cases,
though, since the user might have set the GDestroyNotify to a nifty
function which doesn’t actually free the element; so returning it might
still be valid and useful.

Also add missing (nullable) annotations to that documentation.
Signed-off-by: Philip Withnall's avatarPhilip Withnall <withnall@endlessm.com>

https://bugzilla.gnome.org/show_bug.cgi?id=795376
parent 2c9a84e5
......@@ -1231,9 +1231,10 @@ ptr_array_remove_index (GPtrArray *array,
* Removes the pointer at the given index from the pointer array.
* The following elements are moved down one place. If @array has
* a non-%NULL #GDestroyNotify function it is called for the removed
* element.
* element. If so, the return value from this function will potentially point
* to freed memory (depending on the #GDestroyNotify implementation).
*
* Returns: the pointer which was removed
* Returns: (nullable): the pointer which was removed
*/
gpointer
g_ptr_array_remove_index (GPtrArray *array,
......@@ -1251,9 +1252,11 @@ g_ptr_array_remove_index (GPtrArray *array,
* The last element in the array is used to fill in the space, so
* this function does not preserve the order of the array. But it
* is faster than g_ptr_array_remove_index(). If @array has a non-%NULL
* #GDestroyNotify function it is called for the removed element.
* #GDestroyNotify function it is called for the removed element. If so, the
* return value from this function will potentially point to freed memory
* (depending on the #GDestroyNotify implementation).
*
* Returns: the pointer which was removed
* Returns: (nullable): the pointer which was removed
*/
gpointer
g_ptr_array_remove_index_fast (GPtrArray *array,
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment