<refentry id="glib-Arrays">
<refmeta>
<refentrytitle role="top_of_page" id="glib-Arrays.top_of_page">Arrays</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>GLIB Library</refmiscinfo>
</refmeta>

<refnamediv>
<refname>Arrays</refname>
<refpurpose>arrays of arbitrary elements which grow automatically as elements are added</refpurpose>
</refnamediv>

<refsynopsisdiv id="glib-Arrays.synopsis" role="synopsis">
<title role="synopsis.title">Synopsis</title>

<synopsis>

#include &lt;glib.h&gt;

                    <link linkend="GArray">GArray</link>;
<link linkend="GArray">GArray</link>*             <link linkend="g-array-new">g_array_new</link>                         (<link linkend="gboolean">gboolean</link> zero_terminated,
                                                         <link linkend="gboolean">gboolean</link> clear_,
                                                         <link linkend="guint">guint</link> element_size);
<link linkend="GArray">GArray</link>*             <link linkend="g-array-sized-new">g_array_sized_new</link>                   (<link linkend="gboolean">gboolean</link> zero_terminated,
                                                         <link linkend="gboolean">gboolean</link> clear_,
                                                         <link linkend="guint">guint</link> element_size,
                                                         <link linkend="guint">guint</link> reserved_size);
<link linkend="GArray">GArray</link> *            <link linkend="g-array-ref">g_array_ref</link>                         (<link linkend="GArray">GArray</link> *array);
<link linkend="void">void</link>                <link linkend="g-array-unref">g_array_unref</link>                       (<link linkend="GArray">GArray</link> *array);
<link linkend="guint">guint</link>               <link linkend="g-array-get-element-size">g_array_get_element_size</link>            (<link linkend="GArray">GArray</link> *array);
#define             <link linkend="g-array-append-val">g_array_append_val</link>                  (a,v)
<link linkend="GArray">GArray</link>*             <link linkend="g-array-append-vals">g_array_append_vals</link>                 (<link linkend="GArray">GArray</link> *array,
                                                         <link linkend="gconstpointer">gconstpointer</link> data,
                                                         <link linkend="guint">guint</link> len);
#define             <link linkend="g-array-prepend-val">g_array_prepend_val</link>                 (a,v)
<link linkend="GArray">GArray</link>*             <link linkend="g-array-prepend-vals">g_array_prepend_vals</link>                (<link linkend="GArray">GArray</link> *array,
                                                         <link linkend="gconstpointer">gconstpointer</link> data,
                                                         <link linkend="guint">guint</link> len);
#define             <link linkend="g-array-insert-val">g_array_insert_val</link>                  (a,i,v)
<link linkend="GArray">GArray</link>*             <link linkend="g-array-insert-vals">g_array_insert_vals</link>                 (<link linkend="GArray">GArray</link> *array,
                                                         <link linkend="guint">guint</link> index_,
                                                         <link linkend="gconstpointer">gconstpointer</link> data,
                                                         <link linkend="guint">guint</link> len);
<link linkend="GArray">GArray</link>*             <link linkend="g-array-remove-index">g_array_remove_index</link>                (<link linkend="GArray">GArray</link> *array,
                                                         <link linkend="guint">guint</link> index_);
<link linkend="GArray">GArray</link>*             <link linkend="g-array-remove-index-fast">g_array_remove_index_fast</link>           (<link linkend="GArray">GArray</link> *array,
                                                         <link linkend="guint">guint</link> index_);
<link linkend="GArray">GArray</link>*             <link linkend="g-array-remove-range">g_array_remove_range</link>                (<link linkend="GArray">GArray</link> *array,
                                                         <link linkend="guint">guint</link> index_,
                                                         <link linkend="guint">guint</link> length);
<link linkend="void">void</link>                <link linkend="g-array-sort">g_array_sort</link>                        (<link linkend="GArray">GArray</link> *array,
                                                         <link linkend="GCompareFunc">GCompareFunc</link> compare_func);
<link linkend="void">void</link>                <link linkend="g-array-sort-with-data">g_array_sort_with_data</link>              (<link linkend="GArray">GArray</link> *array,
                                                         <link linkend="GCompareDataFunc">GCompareDataFunc</link> compare_func,
                                                         <link linkend="gpointer">gpointer</link> user_data);
#define             <link linkend="g-array-index">g_array_index</link>                       (a,t,i)
<link linkend="GArray">GArray</link>*             <link linkend="g-array-set-size">g_array_set_size</link>                    (<link linkend="GArray">GArray</link> *array,
                                                         <link linkend="guint">guint</link> length);
<link linkend="gchar">gchar</link>*              <link linkend="g-array-free">g_array_free</link>                        (<link linkend="GArray">GArray</link> *array,
                                                         <link linkend="gboolean">gboolean</link> free_segment);
</synopsis>
</refsynopsisdiv>









<refsect1 id="glib-Arrays.description" role="desc">
<title role="desc.title">Description</title>
<para>
Arrays are similar to standard C arrays, except that they grow automatically
as elements are added.
</para>
<para>
Array elements can be of any size (though all elements of one array are the
same size), and the array can be automatically cleared to '0's and
zero-terminated.
</para>
<para>
To create a new array use <link linkend="g-array-new"><function>g_array_new()</function></link>.
</para>
<para>
To add elements to an array, use <link linkend="g-array-append-val"><function>g_array_append_val()</function></link>, <link linkend="g-array-append-vals"><function>g_array_append_vals()</function></link>,
<link linkend="g-array-prepend-val"><function>g_array_prepend_val()</function></link>, and <link linkend="g-array-prepend-vals"><function>g_array_prepend_vals()</function></link>.
</para>
<para>
To access an element of an array, use <link linkend="g-array-index"><function>g_array_index()</function></link>.
</para>
<para>
To set the size of an array, use <link linkend="g-array-set-size"><function>g_array_set_size()</function></link>.
</para>
<para>
To free an array, use <link linkend="g-array-free"><function>g_array_free()</function></link>.
</para>
<example>
<title>Using a <structname>GArray</structname> to store <type>gint</type> values</title>
<programlisting>
  GArray *garray;
  gint i;
  /* We create a new array to store gint values.
     We don't want it zero-terminated or cleared to 0's. */
  garray = g_array_new (FALSE, FALSE, sizeof (gint));
  for (i = 0; i &lt; 10000; i++)
    g_array_append_val (garray, i);
  for (i = 0; i &lt; 10000; i++)
    if (g_array_index (garray, gint, i) != i)
      g_print ("ERROR: got &percnt;d instead of &percnt;d\n",
               g_array_index (garray, gint, i), i);
  g_array_free (garray, TRUE);
</programlisting></example>
</refsect1>

<refsect1 id="glib-Arrays.details" role="details">
<title role="details.title">Details</title>
<refsect2 id="GArray" role="struct">
<title>GArray</title>
<indexterm zone="GArray"><primary sortas="Array">GArray</primary></indexterm><programlisting>typedef struct {
  gchar *data;
  guint len;
} GArray;
</programlisting>
<para>
Contains the public fields of an <link linkend="glib-arrays">Array</link>.
</para><variablelist role="struct">
<varlistentry>
<term><link linkend="gchar">gchar</link>&#160;*<structfield>data</structfield>;</term>
<listitem><simpara>a pointer to the element data. The data may be moved as elements are
added to the <link linkend="GArray"><type>GArray</type></link>.
</simpara></listitem>
</varlistentry>
<varlistentry>
<term><link linkend="guint">guint</link>&#160;<structfield>len</structfield>;</term>
<listitem><simpara>the number of elements in the <link linkend="GArray"><type>GArray</type></link>.
</simpara></listitem>
</varlistentry>
</variablelist></refsect2>
<refsect2 id="g-array-new" role="function">
<title>g_array_new ()</title>
<indexterm zone="g-array-new"><primary sortas="array_new">g_array_new</primary></indexterm><programlisting><link linkend="GArray">GArray</link>*             g_array_new                         (<link linkend="gboolean">gboolean</link> zero_terminated,
                                                         <link linkend="gboolean">gboolean</link> clear_,
                                                         <link linkend="guint">guint</link> element_size);</programlisting>
<para>
Creates a new <link linkend="GArray"><type>GArray</type></link> with a reference count of 1.
</para><variablelist role="params">
<varlistentry><term><parameter>zero_terminated</parameter>&#160;:</term>
<listitem><simpara>%TRUE if the array should have an extra element at the end
which is set to 0.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>clear_</parameter>&#160;:</term>
<listitem><simpara>%TRUE if <link linkend="GArray"><type>GArray</type></link> elements should be automatically cleared to 0
when they are allocated.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>element_size</parameter>&#160;:</term>
<listitem><simpara>the size of each element in bytes.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>the new <link linkend="GArray"><type>GArray</type></link>.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-array-sized-new" role="function">
<title>g_array_sized_new ()</title>
<indexterm zone="g-array-sized-new"><primary sortas="array_sized_new">g_array_sized_new</primary></indexterm><programlisting><link linkend="GArray">GArray</link>*             g_array_sized_new                   (<link linkend="gboolean">gboolean</link> zero_terminated,
                                                         <link linkend="gboolean">gboolean</link> clear_,
                                                         <link linkend="guint">guint</link> element_size,
                                                         <link linkend="guint">guint</link> reserved_size);</programlisting>
<para>
Creates a new <link linkend="GArray"><type>GArray</type></link> with <parameter>reserved_size</parameter> elements
preallocated and a reference count of 1. This avoids frequent reallocation,
if you are going to add many elements to the array. Note however that the
size of the array is still 0.
</para><variablelist role="params">
<varlistentry><term><parameter>zero_terminated</parameter>&#160;:</term>
<listitem><simpara>%TRUE if the array should have an extra element at the end with all bits cleared.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>clear_</parameter>&#160;:</term>
<listitem><simpara>%TRUE if all bits in the array should be cleared to 0 on allocation.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>element_size</parameter>&#160;:</term>
<listitem><simpara>size of each element in the array.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>reserved_size</parameter>&#160;:</term>
<listitem><simpara>number of elements preallocated.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>the new <link linkend="GArray"><type>GArray</type></link>.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-array-ref" role="function" condition="since:2.22">
<title>g_array_ref ()</title>
<indexterm zone="g-array-ref" role="2.22"><primary sortas="array_ref">g_array_ref</primary></indexterm><programlisting><link linkend="GArray">GArray</link> *            g_array_ref                         (<link linkend="GArray">GArray</link> *array);</programlisting>
<para>
Atomically increments the reference count of <parameter>array</parameter> by one. This
function is MT-safe and may be called from any thread.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>array</parameter>&#160;:</term>
<listitem><simpara> A <link linkend="GArray"><type>GArray</type></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> The passed in <link linkend="GArray"><type>GArray</type></link>.

</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 2.22</para></refsect2>
<refsect2 id="g-array-unref" role="function" condition="since:2.22">
<title>g_array_unref ()</title>
<indexterm zone="g-array-unref" role="2.22"><primary sortas="array_unref">g_array_unref</primary></indexterm><programlisting><link linkend="void">void</link>                g_array_unref                       (<link linkend="GArray">GArray</link> *array);</programlisting>
<para>
Atomically decrements the reference count of <parameter>array</parameter> by one. If the
reference count drops to 0, all memory allocated by the array is
released. This function is MT-safe and may be called from any
thread.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>array</parameter>&#160;:</term>
<listitem><simpara> A <link linkend="GArray"><type>GArray</type></link>.
</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 2.22</para></refsect2>
<refsect2 id="g-array-get-element-size" role="function" condition="since:2.22">
<title>g_array_get_element_size ()</title>
<indexterm zone="g-array-get-element-size" role="2.22"><primary sortas="array_get_element_size">g_array_get_element_size</primary></indexterm><programlisting><link linkend="guint">guint</link>               g_array_get_element_size            (<link linkend="GArray">GArray</link> *array);</programlisting>
<para>
Gets the size of the elements in <parameter>array</parameter>.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>array</parameter>&#160;:</term>
<listitem><simpara> A <link linkend="GArray"><type>GArray</type></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> Size of each element, in bytes.

</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 2.22</para></refsect2>
<refsect2 id="g-array-append-val" role="macro">
<title>g_array_append_val()</title>
<indexterm zone="g-array-append-val"><primary sortas="array_append_val">g_array_append_val</primary></indexterm><programlisting>#define             g_array_append_val(a,v)</programlisting>
<para>
Adds the value on to the end of the array.
The array will grow in size automatically if necessary.
</para>
<note>
<para>
<link linkend="g-array-append-val"><function>g_array_append_val()</function></link> is a macro which uses a reference to the value
parameter <parameter>v</parameter>. This means that you cannot use it with literal values
such as "27". You must use variables.
</para>
</note><variablelist role="params">
<varlistentry><term><parameter>a</parameter>&#160;:</term>
<listitem><simpara>a <link linkend="GArray"><type>GArray</type></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>v</parameter>&#160;:</term>
<listitem><simpara>the value to append to the <link linkend="GArray"><type>GArray</type></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>the <link linkend="GArray"><type>GArray</type></link>.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-array-append-vals" role="function">
<title>g_array_append_vals ()</title>
<indexterm zone="g-array-append-vals"><primary sortas="array_append_vals">g_array_append_vals</primary></indexterm><programlisting><link linkend="GArray">GArray</link>*             g_array_append_vals                 (<link linkend="GArray">GArray</link> *array,
                                                         <link linkend="gconstpointer">gconstpointer</link> data,
                                                         <link linkend="guint">guint</link> len);</programlisting>
<para>
Adds <parameter>len</parameter> elements onto the end of the array.
</para><variablelist role="params">
<varlistentry><term><parameter>array</parameter>&#160;:</term>
<listitem><simpara>a <link linkend="GArray"><type>GArray</type></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>data</parameter>&#160;:</term>
<listitem><simpara>a pointer to the elements to append to the end of the array.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>len</parameter>&#160;:</term>
<listitem><simpara>the number of elements to append.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>the <link linkend="GArray"><type>GArray</type></link>.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-array-prepend-val" role="macro">
<title>g_array_prepend_val()</title>
<indexterm zone="g-array-prepend-val"><primary sortas="array_prepend_val">g_array_prepend_val</primary></indexterm><programlisting>#define             g_array_prepend_val(a,v)</programlisting>
<para>
Adds the value on to the start of the array.
The array will grow in size automatically if necessary.
</para>
<para>
This operation is slower than <link linkend="g-array-append-val"><function>g_array_append_val()</function></link> since the existing elements
in the array have to be moved to make space for the new element.
</para>
<note>
<para>
<link linkend="g-array-prepend-val"><function>g_array_prepend_val()</function></link> is a macro which uses a reference to the value
parameter <parameter>v</parameter>. This means that you cannot use it with literal values
such as "27". You must use variables.
</para>
</note><variablelist role="params">
<varlistentry><term><parameter>a</parameter>&#160;:</term>
<listitem><simpara>a <link linkend="GArray"><type>GArray</type></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>v</parameter>&#160;:</term>
<listitem><simpara>the value to prepend to the <link linkend="GArray"><type>GArray</type></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>the <link linkend="GArray"><type>GArray</type></link>.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-array-prepend-vals" role="function">
<title>g_array_prepend_vals ()</title>
<indexterm zone="g-array-prepend-vals"><primary sortas="array_prepend_vals">g_array_prepend_vals</primary></indexterm><programlisting><link linkend="GArray">GArray</link>*             g_array_prepend_vals                (<link linkend="GArray">GArray</link> *array,
                                                         <link linkend="gconstpointer">gconstpointer</link> data,
                                                         <link linkend="guint">guint</link> len);</programlisting>
<para>
Adds <parameter>len</parameter> elements onto the start of the array.
</para>
<para>
This operation is slower than <link linkend="g-array-append-vals"><function>g_array_append_vals()</function></link> since the existing elements
in the array have to be moved to make space for the new elements.
</para><variablelist role="params">
<varlistentry><term><parameter>array</parameter>&#160;:</term>
<listitem><simpara>a <link linkend="GArray"><type>GArray</type></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>data</parameter>&#160;:</term>
<listitem><simpara>a pointer to the elements to prepend to the start of the array.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>len</parameter>&#160;:</term>
<listitem><simpara>the number of elements to prepend.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>the <link linkend="GArray"><type>GArray</type></link>.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-array-insert-val" role="macro">
<title>g_array_insert_val()</title>
<indexterm zone="g-array-insert-val"><primary sortas="array_insert_val">g_array_insert_val</primary></indexterm><programlisting>#define             g_array_insert_val(a,i,v)</programlisting>
<para>
Inserts an element into an array at the given index.
</para>
<note>
<para>
<link linkend="g-array-insert-val"><function>g_array_insert_val()</function></link> is a macro which uses a reference to the value
parameter <parameter>v</parameter>. This means that you cannot use it with literal values
such as "27". You must use variables.
</para>
</note><variablelist role="params">
<varlistentry><term><parameter>a</parameter>&#160;:</term>
<listitem><simpara>a <link linkend="GArray"><type>GArray</type></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>i</parameter>&#160;:</term>
<listitem><simpara>the index to place the element at.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>v</parameter>&#160;:</term>
<listitem><simpara>the value to insert into the array.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>the <link linkend="GArray"><type>GArray</type></link>.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-array-insert-vals" role="function">
<title>g_array_insert_vals ()</title>
<indexterm zone="g-array-insert-vals"><primary sortas="array_insert_vals">g_array_insert_vals</primary></indexterm><programlisting><link linkend="GArray">GArray</link>*             g_array_insert_vals                 (<link linkend="GArray">GArray</link> *array,
                                                         <link linkend="guint">guint</link> index_,
                                                         <link linkend="gconstpointer">gconstpointer</link> data,
                                                         <link linkend="guint">guint</link> len);</programlisting>
<para>
Inserts <parameter>len</parameter> elements into a <link linkend="GArray"><type>GArray</type></link> at the given index.
</para><variablelist role="params">
<varlistentry><term><parameter>array</parameter>&#160;:</term>
<listitem><simpara>a <link linkend="GArray"><type>GArray</type></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>index_</parameter>&#160;:</term>
<listitem><simpara>the index to place the elements at.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>data</parameter>&#160;:</term>
<listitem><simpara>a pointer to the elements to insert.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>len</parameter>&#160;:</term>
<listitem><simpara>the number of elements to insert.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>the <link linkend="GArray"><type>GArray</type></link>.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-array-remove-index" role="function">
<title>g_array_remove_index ()</title>
<indexterm zone="g-array-remove-index"><primary sortas="array_remove_index">g_array_remove_index</primary></indexterm><programlisting><link linkend="GArray">GArray</link>*             g_array_remove_index                (<link linkend="GArray">GArray</link> *array,
                                                         <link linkend="guint">guint</link> index_);</programlisting>
<para>
Removes the element at the given index from a <link linkend="GArray"><type>GArray</type></link>.
The following elements are moved down one place.
</para><variablelist role="params">
<varlistentry><term><parameter>array</parameter>&#160;:</term>
<listitem><simpara>a <link linkend="GArray"><type>GArray</type></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>index_</parameter>&#160;:</term>
<listitem><simpara>the index of the element to remove.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>the <link linkend="GArray"><type>GArray</type></link>.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-array-remove-index-fast" role="function">
<title>g_array_remove_index_fast ()</title>
<indexterm zone="g-array-remove-index-fast"><primary sortas="array_remove_index_fast">g_array_remove_index_fast</primary></indexterm><programlisting><link linkend="GArray">GArray</link>*             g_array_remove_index_fast           (<link linkend="GArray">GArray</link> *array,
                                                         <link linkend="guint">guint</link> index_);</programlisting>
<para>
Removes the element at the given index from a <link linkend="GArray"><type>GArray</type></link>.
The last element in the array is used to fill in the space, so this function
does not preserve the order of the <link linkend="GArray"><type>GArray</type></link>. But it is faster than
<link linkend="g-array-remove-index"><function>g_array_remove_index()</function></link>.
</para><variablelist role="params">
<varlistentry><term><parameter>array</parameter>&#160;:</term>
<listitem><simpara>a <parameter>GArray</parameter>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>index_</parameter>&#160;:</term>
<listitem><simpara>the index of the element to remove.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>the <link linkend="GArray"><type>GArray</type></link>.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-array-remove-range" role="function" condition="since:2.4">
<title>g_array_remove_range ()</title>
<indexterm zone="g-array-remove-range" role="2.4"><primary sortas="array_remove_range">g_array_remove_range</primary></indexterm><programlisting><link linkend="GArray">GArray</link>*             g_array_remove_range                (<link linkend="GArray">GArray</link> *array,
                                                         <link linkend="guint">guint</link> index_,
                                                         <link linkend="guint">guint</link> length);</programlisting>
<para>
Removes the given number of elements starting at the given index from a
<link linkend="GArray"><type>GArray</type></link>.  The following elements are moved to close the gap.
</para><variablelist role="params">
<varlistentry><term><parameter>array</parameter>&#160;:</term>
<listitem><simpara>a <parameter>GArray</parameter>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>index_</parameter>&#160;:</term>
<listitem><simpara>the index of the first element to remove.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>length</parameter>&#160;:</term>
<listitem><simpara>the number of elements to remove.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>the <link linkend="GArray"><type>GArray</type></link>.
</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 2.4</para></refsect2>
<refsect2 id="g-array-sort" role="function">
<title>g_array_sort ()</title>
<indexterm zone="g-array-sort"><primary sortas="array_sort">g_array_sort</primary></indexterm><programlisting><link linkend="void">void</link>                g_array_sort                        (<link linkend="GArray">GArray</link> *array,
                                                         <link linkend="GCompareFunc">GCompareFunc</link> compare_func);</programlisting>
<para>
Sorts a <link linkend="GArray"><type>GArray</type></link> using <parameter>compare_func</parameter> which should be a <link linkend="qsort"><function>qsort()</function></link>-style comparison
function (returns less than zero for first arg is less than second arg,
zero for equal, greater zero if first arg is greater than second arg).
</para>
<para>
If two array elements compare equal, their order in the sorted array is
undefined.
</para><variablelist role="params">
<varlistentry><term><parameter>array</parameter>&#160;:</term>
<listitem><simpara>a <link linkend="GArray"><type>GArray</type></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>compare_func</parameter>&#160;:</term>
<listitem><simpara>comparison function.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-array-sort-with-data" role="function">
<title>g_array_sort_with_data ()</title>
<indexterm zone="g-array-sort-with-data"><primary sortas="array_sort_with_data">g_array_sort_with_data</primary></indexterm><programlisting><link linkend="void">void</link>                g_array_sort_with_data              (<link linkend="GArray">GArray</link> *array,
                                                         <link linkend="GCompareDataFunc">GCompareDataFunc</link> compare_func,
                                                         <link linkend="gpointer">gpointer</link> user_data);</programlisting>
<para>
Like <link linkend="g-array-sort"><function>g_array_sort()</function></link>, but the comparison function receives an extra user data
argument.
</para><variablelist role="params">
<varlistentry><term><parameter>array</parameter>&#160;:</term>
<listitem><simpara>a <link linkend="GArray"><type>GArray</type></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>compare_func</parameter>&#160;:</term>
<listitem><simpara>comparison function.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>user_data</parameter>&#160;:</term>
<listitem><simpara>data to pass to <parameter>compare_func</parameter>.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-array-index" role="macro">
<title>g_array_index()</title>
<indexterm zone="g-array-index"><primary sortas="array_index">g_array_index</primary></indexterm><programlisting>#define             g_array_index(a,t,i)</programlisting>
<para>
Returns the element of a <link linkend="GArray"><type>GArray</type></link> at the given index.
The return value is cast to the given type.
<example>
<title>Getting a pointer to an element in a <structname>GArray</structname></title>
<programlisting>
  EDayViewEvent *event;
  /* This gets a pointer to the 4th element in the array of EDayViewEvent
     structs. */
  event = &amp;g_array_index (events, EDayViewEvent, 3);
</programlisting>
</example>
</para><variablelist role="params">
<varlistentry><term><parameter>a</parameter>&#160;:</term>
<listitem><simpara>a <link linkend="GArray"><type>GArray</type></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>t</parameter>&#160;:</term>
<listitem><simpara>the type of the elements.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>i</parameter>&#160;:</term>
<listitem><simpara>the index of the element to return.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>the element of the <link linkend="GArray"><type>GArray</type></link> at the index given by <parameter>i</parameter>.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-array-set-size" role="function">
<title>g_array_set_size ()</title>
<indexterm zone="g-array-set-size"><primary sortas="array_set_size">g_array_set_size</primary></indexterm><programlisting><link linkend="GArray">GArray</link>*             g_array_set_size                    (<link linkend="GArray">GArray</link> *array,
                                                         <link linkend="guint">guint</link> length);</programlisting>
<para>
Sets the size of the array, expanding it if necessary.
If the array was created with <parameter>clear_</parameter> set to <link linkend="TRUE--CAPS"><literal>TRUE</literal></link>, the new elements are set to 0.
</para><variablelist role="params">
<varlistentry><term><parameter>array</parameter>&#160;:</term>
<listitem><simpara>a <link linkend="GArray"><type>GArray</type></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>length</parameter>&#160;:</term>
<listitem><simpara>the new size of the <link linkend="GArray"><type>GArray</type></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>the <link linkend="GArray"><type>GArray</type></link>.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-array-free" role="function">
<title>g_array_free ()</title>
<indexterm zone="g-array-free"><primary sortas="array_free">g_array_free</primary></indexterm><programlisting><link linkend="gchar">gchar</link>*              g_array_free                        (<link linkend="GArray">GArray</link> *array,
                                                         <link linkend="gboolean">gboolean</link> free_segment);</programlisting>
<para>
Frees the memory allocated for the <link linkend="GArray"><type>GArray</type></link>.
If <parameter>free_segment</parameter> is <link linkend="TRUE--CAPS"><literal>TRUE</literal></link> it frees the memory block holding the elements
as well and also each element if <parameter>array</parameter> has a <parameter>element_free_func</parameter> set.
Pass <link linkend="FALSE--CAPS"><literal>FALSE</literal></link> if you want to free the <link linkend="GArray"><type>GArray</type></link> wrapper but preserve
the underlying array for use elsewhere. If the reference count of <parameter>array</parameter>
is greater than one, the <link linkend="GArray"><type>GArray</type></link> wrapper is preserved but the size of
<parameter>array</parameter> will be set to zero.
</para>
<note>
<para>
If array elements contain dynamically-allocated memory, they should be freed
separately.
</para>
</note><variablelist role="params">
<varlistentry><term><parameter>array</parameter>&#160;:</term>
<listitem><simpara>a <link linkend="GArray"><type>GArray</type></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>free_segment</parameter>&#160;:</term>
<listitem><simpara>if <link linkend="TRUE--CAPS"><literal>TRUE</literal></link> the actual element data is freed as well.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>the element data if <parameter>free_segment</parameter> is <link linkend="FALSE--CAPS"><literal>FALSE</literal></link>, otherwise <link linkend="NULL--CAPS"><literal>NULL</literal></link>.
	The element data should be freed using <link linkend="g-free"><function>g_free()</function></link>.
</simpara></listitem></varlistentry>
</variablelist></refsect2>

</refsect1>




</refentry>
