Function
GLibPtrArraysteal
since: 2.64
Declaration [src]
gpointer*
g_ptr_array_steal (
GPtrArray* array,
gsize* len
)
Description [src]
Frees the data in the array and resets the size to zero, while the underlying array is preserved for use elsewhere and returned to the caller.
Note that if the array is NULL
terminated this may still return
NULL
if the length of the array was zero and pdata was not yet allocated.
Even if set, the GDestroyNotify
function will never be called
on the current contents of the array and the caller is
responsible for freeing the array elements.
An example of use:
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);
Available since: 2.64
This function is not directly available to language bindings.
Parameters
array
-
Type: An array of
gpointer
A
GPtrArray
.The data is owned by the caller of the function. len
-
Type:
gsize*
Pointer to retrieve the number of elements of the original array.
The argument will be set by the function. The argument can be NULL
.
Return value
Type: An array of gpointer
The element data,
which should be freed using g_free(). This may be NULL
if the array
doesn’t have any elements (i.e. if *len
is zero).
The length of the array is in the len argument. |
The caller of the function takes ownership of the data, and is responsible for freeing it. |
The return value can be NULL . |