Function Macro
GLibsteal_pointer
since: 2.44
Description
Sets pp to NULL, returning the value that was there before.
Conceptually, this transfers the ownership of the pointer from the referenced variable to the “caller” of the macro (ie: “steals” the reference).
The return value will be properly typed, according to the type of
pp.
This can be very useful when combined with g_autoptr() to prevent the
return value of a function from being automatically freed. Consider
the following example (which only works on GCC and clang):
GObject *
create_object (void)
{
g_autoptr(GObject) obj = g_object_new (G_TYPE_OBJECT, NULL);
if (early_error_case)
return NULL;
return g_steal_pointer (&obj);
}
It can also be used in similar ways for ‘out’ parameters and is particularly useful for dealing with optional out parameters:
gboolean
get_object (GObject **obj_out)
{
g_autoptr(GObject) obj = g_object_new (G_TYPE_OBJECT, NULL);
if (early_error_case)
return FALSE;
if (obj_out)
*obj_out = g_steal_pointer (&obj);
return TRUE;
}
In the above example, the object will be automatically freed in the
early error case and also in the case that NULL was given for
obj_out.
Available since: 2.44
This function is not directly available to language bindings.