mirror of
https://gitlab.gnome.org/GNOME/glib.git
synced 2025-03-28 10:30:03 +01:00
e773d7dba6
Mon Dec 11 04:44:11 2000 Tim Janik <timj@gtk.org> * gboxed.c: fixed dealing with collection/lcopy of NULL values. * gclosure.h: removed insane ramblings, added G_CALLBACK() a casting convenience macro. * Makefile.am: cleanups, marshaller generation rules. * gmarshal.[hc]: new files with GRuntime standard marshallers. * glib-genmarshal.c: fix log domain, support gruntime standard marshallers, suport G_TYPE_PARAM, come with extern "C" and #include gmarshal.h. * glib-genmarshal.1: reflect glib-genmarshal.c updates. * gobject.[hc]: implement object constructor. rework parameter changed notification queueing, we support queue freezes now and don't dispatch from an idle handler anymore. parameter->property rename hassle. implemented ::properties_changed and ::notify::* signals for property change notification (the later supports property names as details). added signal connection and named data properties. (g_signal_connect_object): new function to setup while_alive connections. (g_object_class_install_property): sink properties now, since they are initially floating. (g_object_steal_data): (g_object_set_data_full): (g_object_set_data): (g_object_get_data): set/get data by using g_datalist_*() functions directly. (g_object_queue_param_changed): nuked. (g_object_freeze_notify): start queueing of property changes (freeze/ thaw calls stack). (g_object_notify): announce changes of a certain property directly. (g_object_thaw_notify): process queue of property changes, therefore emitting GObject::notify::detail with detail being the changed properties names. (G_OBJECT_WARN_INVALID_PROPERTY_ID): saner macro variant of former G_WARN_INVALID_PARAM_ID(). * gparam.[hc]: param specs are now initially floating and need to be sunken with g_param_spec_sink(), support G_TYPE_PARAM values. added G_PARAM_CONSTRUCT and G_PARAM_CONSTRUCT_ONLY parameter flags, required by GObjectClass.constructor(). * gparamspecs.[hc]: added GParamSpecParam, GParamSpecPointer and GParamSpecCCallback, param specs for G_TYPE_PARAM, G_TYPE_POINTER and G_TYPE_CCALLBACK respectively. * gsignal.[hc]: cleanups. (signal_id_lookup): after walking the anchestry, try interfaces as well. (g_signal_new): new function to create signals from varargs type list. (g_signal_connect_closure): closure connection variant that works from signal name+detail. (g_signal_connect_data): c handler connection variant that works from signal name+detail. (g_signal_emit_valist): emit signal for an instance with paraneters collected from a va_list. (g_signal_emit): emit signal, taking parameters from varargs list. (g_signal_emit_by_name): same as g_signal_emit, working from signal name+detail. (signal_emit_R): return whether return_value needs to be altered. * gtype.[hc]: set log-domain to GRuntime, i'm slowly getting to all the points that need to reflect the upcoming rename. melt g_type_conforms_to() functionality into g_type_is_a(), as that is what we really want (liskov substitution principle). assorted changes to other files due to conforms_to->is_a. * gvalue.[hc]: implemented g_value_set_instance() that sets a value from an instantiatable type via the value_table's collect_value() function (based on an idea from James Henstridge <james@daa.com.au>). cleanups/fixes. * gvaluetypes.[hc]: implement G_TYPE_CCALLBACK and G_TYPE_PARAM.
189 lines
4.7 KiB
Plaintext
189 lines
4.7 KiB
Plaintext
<!-- ##### SECTION Title ##### -->
|
|
Pointer Arrays
|
|
|
|
<!-- ##### SECTION Short_Description ##### -->
|
|
arrays of pointers to any type of data, which grow automatically as new
|
|
elements are added.
|
|
|
|
<!-- ##### SECTION Long_Description ##### -->
|
|
<para>
|
|
Pointer Arrays are similar to Arrays but are used only for storing pointers.
|
|
</para>
|
|
<note>
|
|
<para>
|
|
If you remove elements from the array, elements at the end of the array
|
|
are moved into the space previously occupied by the removed element.
|
|
This means that you should not rely on the index of particular elements
|
|
remaining the same. You should also be careful when deleting elements while
|
|
iterating over the array.
|
|
</para>
|
|
</note>
|
|
<para>
|
|
To create a pointer array, use g_ptr_array_new().
|
|
</para>
|
|
<para>
|
|
To add elements to a pointer array, use g_ptr_array_add().
|
|
</para>
|
|
<para>
|
|
To remove elements from a pointer array, use g_ptr_array_remove(),
|
|
g_ptr_array_remove_index() or g_ptr_array_remove_index_fast().
|
|
</para>
|
|
<para>
|
|
To access an element of a pointer array, use g_ptr_array_index().
|
|
</para>
|
|
<para>
|
|
To set the size of a pointer array, use g_ptr_array_set_size().
|
|
</para>
|
|
<para>
|
|
To free a pointer array, use g_ptr_array_free().
|
|
</para>
|
|
<example>
|
|
<title>Using a GPtrArray.</title>
|
|
<programlisting>
|
|
GPtrArray *gparray;
|
|
gchar *string1 = "one", *string2 = "two", *string3 = "three";
|
|
|
|
gparray = g_ptr_array_new ();
|
|
g_ptr_array_add (gparray, (gpointer) string1);
|
|
g_ptr_array_add (gparray, (gpointer) string2);
|
|
g_ptr_array_add (gparray, (gpointer) string3);
|
|
|
|
if (g_ptr_array_index (gparray, 0) != (gpointer) string1)
|
|
g_print ("ERROR: got %p instead of %p\n",
|
|
g_ptr_array_index (gparray, 0), string1);
|
|
|
|
g_ptr_array_free (gparray, TRUE);
|
|
</programlisting></example>
|
|
|
|
<!-- ##### SECTION See_Also ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
<!-- ##### STRUCT GPtrArray ##### -->
|
|
<para>
|
|
Contains the public fields of a pointer array.
|
|
The <structfield>pdata</structfield> field points to the array of pointers,
|
|
which may as when the array grows.
|
|
The <structfield>len</structfield> field is the number of pointers in the
|
|
array.
|
|
</para>
|
|
|
|
@pdata:
|
|
@len:
|
|
|
|
<!-- ##### FUNCTION g_ptr_array_new ##### -->
|
|
<para>
|
|
Creates a new #GPtrArray.
|
|
</para>
|
|
|
|
@Returns: the new #GPtrArray.
|
|
|
|
|
|
<!-- ##### FUNCTION g_ptr_array_sized_new ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@reserved_size:
|
|
@Returns:
|
|
|
|
|
|
<!-- ##### FUNCTION g_ptr_array_add ##### -->
|
|
<para>
|
|
Adds a pointer to the end of the pointer array.
|
|
The array will grow in size automatically if necessary.
|
|
</para>
|
|
|
|
@array: a #GPtrArray.
|
|
@data: the pointer to add.
|
|
|
|
|
|
<!-- ##### FUNCTION g_ptr_array_remove ##### -->
|
|
<para>
|
|
Removes the first occurrence of the given pointer from the pointer array.
|
|
The following elements are moved down one place.
|
|
</para>
|
|
<para>
|
|
It returns TRUE if the pointer was removed, or FALSE if the pointer
|
|
was not found.
|
|
</para>
|
|
|
|
@array: a #GPtrArray.
|
|
@data: the pointer to remove.
|
|
@Returns: TRUE if the pointer is removed. FALSE if the pointer is not found
|
|
in the array.
|
|
|
|
|
|
<!-- ##### FUNCTION g_ptr_array_remove_index ##### -->
|
|
<para>
|
|
Removes the pointer at the given index from the pointer array.
|
|
The following elements are moved down one place.
|
|
</para>
|
|
|
|
@array: a #GPtrArray.
|
|
@index: the index of the pointer to remove.
|
|
@Returns: the pointer which was removed.
|
|
|
|
|
|
<!-- ##### FUNCTION g_ptr_array_remove_fast ##### -->
|
|
<para>
|
|
Removes the first occurrence of the given pointer from the pointer 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().
|
|
</para>
|
|
<para>
|
|
It returns TRUE if the pointer was removed, or FALSE if the pointer
|
|
was not found.
|
|
</para>
|
|
|
|
@array: a #GPtrArray.
|
|
@data: the pointer to remove.
|
|
@Returns: TRUE if the pointer was found in the array.
|
|
|
|
|
|
<!-- ##### FUNCTION g_ptr_array_remove_index_fast ##### -->
|
|
<para>
|
|
Removes the pointer at the given index from the pointer 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().
|
|
</para>
|
|
|
|
@array: a #GPtrArray.
|
|
@index: the index of the pointer to remove.
|
|
@Returns: the pointer which was removed.
|
|
|
|
|
|
<!-- ##### FUNCTION g_ptr_array_set_size ##### -->
|
|
<para>
|
|
Sets the size of the array, expanding it if necessary.
|
|
New elements are set to NULL.
|
|
</para>
|
|
|
|
@array: a #GPtrArray.
|
|
@length: the new length of the pointer array.
|
|
|
|
|
|
<!-- ##### MACRO g_ptr_array_index ##### -->
|
|
<para>
|
|
Returns the pointer at the given index of the pointer array.
|
|
</para>
|
|
|
|
@array: a #GPtrArray.
|
|
@index: the index of the pointer to return.
|
|
@Returns: the pointer at the given index.
|
|
|
|
|
|
<!-- ##### FUNCTION g_ptr_array_free ##### -->
|
|
<para>
|
|
Frees all of the memory allocated for the pointer array.
|
|
</para>
|
|
|
|
@array: a #GPtrArray.
|
|
@free_seg: if TRUE the actual element data is freed as well.
|
|
@Returns:
|
|
|
|
|