<?xml version="1.0"?>
<!DOCTYPE refentry PUBLIC '-//OASIS//DTD DocBook XML V4.5//EN'
                      'http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd' [
<!ENTITY % local.common.attrib "xmlns:xi  CDATA  #FIXED 'http://www.w3.org/2003/XInclude'">
<!ENTITY version SYSTEM "version.xml">
]>
<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>

<refsect1 id="glib-Arrays.functions" role="functions_proto">
<title role="functions_proto.title">Functions</title>
<informaltable pgwide="1" frame="none">
<tgroup cols="2">
<colspec colname="functions_proto_type" colwidth="150px"/>
<colspec colname="functions_proto_name"/>
<tbody>
<row><entry role="function_type"><link linkend="GArray"><returnvalue>GArray</returnvalue></link>&#160;*
</entry><entry role="function_name"><link linkend="g-array-new">g_array_new</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="GArray"><returnvalue>GArray</returnvalue></link>&#160;*
</entry><entry role="function_name"><link linkend="g-array-sized-new">g_array_sized_new</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="GArray"><returnvalue>GArray</returnvalue></link>&#160;*
</entry><entry role="function_name"><link linkend="g-array-copy">g_array_copy</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="GArray"><returnvalue>GArray</returnvalue></link>&#160;*
</entry><entry role="function_name"><link linkend="g-array-ref">g_array_ref</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="void"><returnvalue>void</returnvalue></link>
</entry><entry role="function_name"><link linkend="g-array-unref">g_array_unref</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="guint"><returnvalue>guint</returnvalue></link>
</entry><entry role="function_name"><link linkend="g-array-get-element-size">g_array_get_element_size</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="define_keyword">#define</entry><entry role="function_name"><link linkend="g-array-append-val">g_array_append_val</link><phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="GArray"><returnvalue>GArray</returnvalue></link>&#160;*
</entry><entry role="function_name"><link linkend="g-array-append-vals">g_array_append_vals</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="define_keyword">#define</entry><entry role="function_name"><link linkend="g-array-prepend-val">g_array_prepend_val</link><phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="GArray"><returnvalue>GArray</returnvalue></link>&#160;*
</entry><entry role="function_name"><link linkend="g-array-prepend-vals">g_array_prepend_vals</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="define_keyword">#define</entry><entry role="function_name"><link linkend="g-array-insert-val">g_array_insert_val</link><phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="GArray"><returnvalue>GArray</returnvalue></link>&#160;*
</entry><entry role="function_name"><link linkend="g-array-insert-vals">g_array_insert_vals</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="GArray"><returnvalue>GArray</returnvalue></link>&#160;*
</entry><entry role="function_name"><link linkend="g-array-remove-index">g_array_remove_index</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="GArray"><returnvalue>GArray</returnvalue></link>&#160;*
</entry><entry role="function_name"><link linkend="g-array-remove-index-fast">g_array_remove_index_fast</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="GArray"><returnvalue>GArray</returnvalue></link>&#160;*
</entry><entry role="function_name"><link linkend="g-array-remove-range">g_array_remove_range</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="void"><returnvalue>void</returnvalue></link>
</entry><entry role="function_name"><link linkend="g-array-sort">g_array_sort</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="void"><returnvalue>void</returnvalue></link>
</entry><entry role="function_name"><link linkend="g-array-sort-with-data">g_array_sort_with_data</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="gboolean"><returnvalue>gboolean</returnvalue></link>
</entry><entry role="function_name"><link linkend="g-array-binary-search">g_array_binary_search</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="define_keyword">#define</entry><entry role="function_name"><link linkend="g-array-index">g_array_index</link><phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="GArray"><returnvalue>GArray</returnvalue></link>&#160;*
</entry><entry role="function_name"><link linkend="g-array-set-size">g_array_set_size</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="void"><returnvalue>void</returnvalue></link>
</entry><entry role="function_name"><link linkend="g-array-set-clear-func">g_array_set_clear_func</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="gchar"><returnvalue>gchar</returnvalue></link>&#160;*
</entry><entry role="function_name"><link linkend="g-array-free">g_array_free</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>

</tbody>
</tgroup>
</informaltable>
</refsect1>
<refsect1 id="glib-Arrays.other" role="other_proto">
<title role="other_proto.title">Types and Values</title>
<informaltable pgwide="1" frame="none">
<tgroup cols="2">
<colspec colname="other_proto_type" colwidth="150px"/>
<colspec colname="other_proto_name"/>
<tbody>
<row><entry role="datatype_keyword">struct</entry><entry role="function_name"><link linkend="GArray">GArray</link></entry></row>

</tbody>
</tgroup>
</informaltable>
</refsect1>

<refsect1 id="glib-Arrays.includes"><title>Includes</title><synopsis>#include &lt;gmodule.h&gt;
</synopsis></refsect1>

<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>
<para>Here is an example that stores integers in a <link linkend="GArray"><type>GArray</type></link>:</para>
<informalexample><programlisting role="example"><![CDATA[
  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 < 10000; i++)
    g_array_append_val (garray, i);
  for (i = 0; i < 10000; i++)
    if (g_array_index (garray, gint, i) != i)
      g_print ("ERROR: got %d instead of %d\n",
               g_array_index (garray, gint, i), i);
  g_array_free (garray, TRUE);
]]></programlisting></informalexample>
<para></para>

</refsect1>
<refsect1 id="glib-Arrays.functions_details" role="details">
<title role="details.title">Functions</title>
<refsect2 id="g-array-new" role="function">
<title>g_array_new&#160;()</title>
<indexterm zone="g-array-new"><primary sortas="array_new">g_array_new</primary></indexterm>
<programlisting language="C"><link linkend="GArray"><returnvalue>GArray</returnvalue></link>&#160;*
g_array_new (<parameter><link linkend="gboolean"><type>gboolean</type></link> zero_terminated</parameter>,
             <parameter><link linkend="gboolean"><type>gboolean</type></link> clear_</parameter>,
             <parameter><link linkend="guint"><type>guint</type></link> element_size</parameter>);</programlisting>
<para>Creates a new <link linkend="GArray"><type>GArray</type></link> with a reference count of 1.</para>
<refsect3 id="g-array-new.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>zero_terminated</para></entry>
<entry role="parameter_description"><para><link linkend="TRUE:CAPS"><literal>TRUE</literal></link> if the array should have an extra element at
the end which is set to 0</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>clear_</para></entry>
<entry role="parameter_description"><para><link linkend="TRUE:CAPS"><literal>TRUE</literal></link> if <link linkend="GArray"><type>GArray</type></link> elements should be automatically cleared
to 0 when they are allocated</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>element_size</para></entry>
<entry role="parameter_description"><para>the size of each element in bytes</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-array-new.returns" role="returns">
<title>Returns</title>
<para> the new <link linkend="GArray"><type>GArray</type></link></para>
</refsect3></refsect2>
<refsect2 id="g-array-sized-new" role="function">
<title>g_array_sized_new&#160;()</title>
<indexterm zone="g-array-sized-new"><primary sortas="array_sized_new">g_array_sized_new</primary></indexterm>
<programlisting language="C"><link linkend="GArray"><returnvalue>GArray</returnvalue></link>&#160;*
g_array_sized_new (<parameter><link linkend="gboolean"><type>gboolean</type></link> zero_terminated</parameter>,
                   <parameter><link linkend="gboolean"><type>gboolean</type></link> clear_</parameter>,
                   <parameter><link linkend="guint"><type>guint</type></link> element_size</parameter>,
                   <parameter><link linkend="guint"><type>guint</type></link> reserved_size</parameter>);</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>
<refsect3 id="g-array-sized-new.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>zero_terminated</para></entry>
<entry role="parameter_description"><para><link linkend="TRUE:CAPS"><literal>TRUE</literal></link> if the array should have an extra element at
the end with all bits cleared</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>clear_</para></entry>
<entry role="parameter_description"><para><link linkend="TRUE:CAPS"><literal>TRUE</literal></link> if all bits in the array should be cleared to 0 on
allocation</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>element_size</para></entry>
<entry role="parameter_description"><para>size of each element in the array</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>reserved_size</para></entry>
<entry role="parameter_description"><para>number of elements preallocated</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-array-sized-new.returns" role="returns">
<title>Returns</title>
<para> the new <link linkend="GArray"><type>GArray</type></link></para>
</refsect3></refsect2>
<refsect2 id="g-array-copy" role="function" condition="since:2.62">
<title>g_array_copy&#160;()</title>
<indexterm zone="g-array-copy" role="2.62"><primary sortas="array_copy">g_array_copy</primary></indexterm>
<programlisting language="C"><link linkend="GArray"><returnvalue>GArray</returnvalue></link>&#160;*
g_array_copy (<parameter><link linkend="GArray"><type>GArray</type></link> *array</parameter>);</programlisting>
<para>Create a shallow copy of a <link linkend="GArray"><type>GArray</type></link>. If the array elements consist of
pointers to data, the pointers are copied but the actual data is not.</para>
<refsect3 id="g-array-copy.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>array</para></entry>
<entry role="parameter_description"><para>A <link linkend="GArray"><type>GArray</type></link>.</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-array-copy.returns" role="returns">
<title>Returns</title>
<para>A copy of <parameter>array</parameter>
. </para>
<para><emphasis role="annotation">[<acronym>transfer container</acronym>]</emphasis></para>
</refsect3><para role="since">Since: <link linkend="api-index-2.62">2.62</link></para></refsect2>
<refsect2 id="g-array-ref" role="function" condition="since:2.22">
<title>g_array_ref&#160;()</title>
<indexterm zone="g-array-ref" role="2.22"><primary sortas="array_ref">g_array_ref</primary></indexterm>
<programlisting language="C"><link linkend="GArray"><returnvalue>GArray</returnvalue></link>&#160;*
g_array_ref (<parameter><link linkend="GArray"><type>GArray</type></link> *array</parameter>);</programlisting>
<para>Atomically increments the reference count of <parameter>array</parameter>
 by one.
This function is thread-safe and may be called from any thread.</para>
<refsect3 id="g-array-ref.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>array</para></entry>
<entry role="parameter_description"><para>A <link linkend="GArray"><type>GArray</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-array-ref.returns" role="returns">
<title>Returns</title>
<para> The passed in <link linkend="GArray"><type>GArray</type></link></para>
</refsect3><para role="since">Since: <link linkend="api-index-2.22">2.22</link></para></refsect2>
<refsect2 id="g-array-unref" role="function" condition="since:2.22">
<title>g_array_unref&#160;()</title>
<indexterm zone="g-array-unref" role="2.22"><primary sortas="array_unref">g_array_unref</primary></indexterm>
<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link>
g_array_unref (<parameter><link linkend="GArray"><type>GArray</type></link> *array</parameter>);</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 thread-safe and may be called from any
thread.</para>
<refsect3 id="g-array-unref.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>array</para></entry>
<entry role="parameter_description"><para>A <link linkend="GArray"><type>GArray</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><para role="since">Since: <link linkend="api-index-2.22">2.22</link></para></refsect2>
<refsect2 id="g-array-get-element-size" role="function" condition="since:2.22">
<title>g_array_get_element_size&#160;()</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 language="C"><link linkend="guint"><returnvalue>guint</returnvalue></link>
g_array_get_element_size (<parameter><link linkend="GArray"><type>GArray</type></link> *array</parameter>);</programlisting>
<para>Gets the size of the elements in <parameter>array</parameter>
.</para>
<refsect3 id="g-array-get-element-size.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>array</para></entry>
<entry role="parameter_description"><para>A <link linkend="GArray"><type>GArray</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-array-get-element-size.returns" role="returns">
<title>Returns</title>
<para> Size of each element, in bytes</para>
</refsect3><para role="since">Since: <link linkend="api-index-2.22">2.22</link></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 language="C">#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>
<para>g_array_append_val() 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>
<refsect3 id="g-array-append-val.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>a</para></entry>
<entry role="parameter_description"><para>a <link linkend="GArray"><type>GArray</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>v</para></entry>
<entry role="parameter_description"><para>the value to append to the <link linkend="GArray"><type>GArray</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-array-append-val.returns" role="returns">
<title>Returns</title>
<para> the <link linkend="GArray"><type>GArray</type></link></para>
</refsect3></refsect2>
<refsect2 id="g-array-append-vals" role="function">
<title>g_array_append_vals&#160;()</title>
<indexterm zone="g-array-append-vals"><primary sortas="array_append_vals">g_array_append_vals</primary></indexterm>
<programlisting language="C"><link linkend="GArray"><returnvalue>GArray</returnvalue></link>&#160;*
g_array_append_vals (<parameter><link linkend="GArray"><type>GArray</type></link> *array</parameter>,
                     <parameter><link linkend="gconstpointer"><type>gconstpointer</type></link> data</parameter>,
                     <parameter><link linkend="guint"><type>guint</type></link> len</parameter>);</programlisting>
<para>Adds <parameter>len</parameter>
 elements onto the end of the array.</para>
<refsect3 id="g-array-append-vals.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>array</para></entry>
<entry role="parameter_description"><para>a <link linkend="GArray"><type>GArray</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>data</para></entry>
<entry role="parameter_description"><para>a pointer to the elements to append to the end of the array. </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>not nullable</acronym>]</emphasis></entry></row>
<row><entry role="parameter_name"><para>len</para></entry>
<entry role="parameter_description"><para>the number of elements to append</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-array-append-vals.returns" role="returns">
<title>Returns</title>
<para> the <link linkend="GArray"><type>GArray</type></link></para>
</refsect3></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 language="C">#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>
<para>g_array_prepend_val() 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>
<refsect3 id="g-array-prepend-val.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>a</para></entry>
<entry role="parameter_description"><para>a <link linkend="GArray"><type>GArray</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>v</para></entry>
<entry role="parameter_description"><para>the value to prepend to the <link linkend="GArray"><type>GArray</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-array-prepend-val.returns" role="returns">
<title>Returns</title>
<para> the <link linkend="GArray"><type>GArray</type></link></para>
</refsect3></refsect2>
<refsect2 id="g-array-prepend-vals" role="function">
<title>g_array_prepend_vals&#160;()</title>
<indexterm zone="g-array-prepend-vals"><primary sortas="array_prepend_vals">g_array_prepend_vals</primary></indexterm>
<programlisting language="C"><link linkend="GArray"><returnvalue>GArray</returnvalue></link>&#160;*
g_array_prepend_vals (<parameter><link linkend="GArray"><type>GArray</type></link> *array</parameter>,
                      <parameter><link linkend="gconstpointer"><type>gconstpointer</type></link> data</parameter>,
                      <parameter><link linkend="guint"><type>guint</type></link> len</parameter>);</programlisting>
<para>Adds <parameter>len</parameter>
 elements onto the start of the array.</para>
<para><parameter>data</parameter>
 may be <link linkend="NULL:CAPS"><literal>NULL</literal></link> if (and only if) <parameter>len</parameter>
 is zero. If <parameter>len</parameter>
 is zero, this
function is a no-op.</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>
<refsect3 id="g-array-prepend-vals.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>array</para></entry>
<entry role="parameter_description"><para>a <link linkend="GArray"><type>GArray</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>data</para></entry>
<entry role="parameter_description"><para>a pointer to the elements to prepend to the start of the array. </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>nullable</acronym>]</emphasis></entry></row>
<row><entry role="parameter_name"><para>len</para></entry>
<entry role="parameter_description"><para>the number of elements to prepend, which may be zero</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-array-prepend-vals.returns" role="returns">
<title>Returns</title>
<para> the <link linkend="GArray"><type>GArray</type></link></para>
</refsect3></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 language="C">#define             g_array_insert_val(a,i,v)</programlisting>
<para>Inserts an element into an array at the given index.</para>
<para>g_array_insert_val() 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>
<refsect3 id="g-array-insert-val.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>a</para></entry>
<entry role="parameter_description"><para>a <link linkend="GArray"><type>GArray</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>i</para></entry>
<entry role="parameter_description"><para>the index to place the element at</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>v</para></entry>
<entry role="parameter_description"><para>the value to insert into the array</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-array-insert-val.returns" role="returns">
<title>Returns</title>
<para> the <link linkend="GArray"><type>GArray</type></link></para>
</refsect3></refsect2>
<refsect2 id="g-array-insert-vals" role="function">
<title>g_array_insert_vals&#160;()</title>
<indexterm zone="g-array-insert-vals"><primary sortas="array_insert_vals">g_array_insert_vals</primary></indexterm>
<programlisting language="C"><link linkend="GArray"><returnvalue>GArray</returnvalue></link>&#160;*
g_array_insert_vals (<parameter><link linkend="GArray"><type>GArray</type></link> *array</parameter>,
                     <parameter><link linkend="guint"><type>guint</type></link> index_</parameter>,
                     <parameter><link linkend="gconstpointer"><type>gconstpointer</type></link> data</parameter>,
                     <parameter><link linkend="guint"><type>guint</type></link> len</parameter>);</programlisting>
<para>Inserts <parameter>len</parameter>
 elements into a <link linkend="GArray"><type>GArray</type></link> at the given index.</para>
<para>If <parameter>index_</parameter>
 is greater than the array’s current length, the array is expanded.
The elements between the old end of the array and the newly inserted elements
will be initialised to zero if the array was configured to clear elements;
otherwise their values will be undefined.</para>
<para><parameter>data</parameter>
 may be <link linkend="NULL:CAPS"><literal>NULL</literal></link> if (and only if) <parameter>len</parameter>
 is zero. If <parameter>len</parameter>
 is zero, this
function is a no-op.</para>
<refsect3 id="g-array-insert-vals.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>array</para></entry>
<entry role="parameter_description"><para>a <link linkend="GArray"><type>GArray</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>index_</para></entry>
<entry role="parameter_description"><para>the index to place the elements at</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>data</para></entry>
<entry role="parameter_description"><para>a pointer to the elements to insert. </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>nullable</acronym>]</emphasis></entry></row>
<row><entry role="parameter_name"><para>len</para></entry>
<entry role="parameter_description"><para>the number of elements to insert</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-array-insert-vals.returns" role="returns">
<title>Returns</title>
<para> the <link linkend="GArray"><type>GArray</type></link></para>
</refsect3></refsect2>
<refsect2 id="g-array-remove-index" role="function">
<title>g_array_remove_index&#160;()</title>
<indexterm zone="g-array-remove-index"><primary sortas="array_remove_index">g_array_remove_index</primary></indexterm>
<programlisting language="C"><link linkend="GArray"><returnvalue>GArray</returnvalue></link>&#160;*
g_array_remove_index (<parameter><link linkend="GArray"><type>GArray</type></link> *array</parameter>,
                      <parameter><link linkend="guint"><type>guint</type></link> index_</parameter>);</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>
<refsect3 id="g-array-remove-index.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>array</para></entry>
<entry role="parameter_description"><para>a <link linkend="GArray"><type>GArray</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>index_</para></entry>
<entry role="parameter_description"><para>the index of the element to remove</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-array-remove-index.returns" role="returns">
<title>Returns</title>
<para> the <link linkend="GArray"><type>GArray</type></link></para>
</refsect3></refsect2>
<refsect2 id="g-array-remove-index-fast" role="function">
<title>g_array_remove_index_fast&#160;()</title>
<indexterm zone="g-array-remove-index-fast"><primary sortas="array_remove_index_fast">g_array_remove_index_fast</primary></indexterm>
<programlisting language="C"><link linkend="GArray"><returnvalue>GArray</returnvalue></link>&#160;*
g_array_remove_index_fast (<parameter><link linkend="GArray"><type>GArray</type></link> *array</parameter>,
                           <parameter><link linkend="guint"><type>guint</type></link> index_</parameter>);</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>
<refsect3 id="g-array-remove-index-fast.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>array</para></entry>
<entry role="parameter_description"><para>a <parameter>GArray</parameter>
</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>index_</para></entry>
<entry role="parameter_description"><para>the index of the element to remove</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-array-remove-index-fast.returns" role="returns">
<title>Returns</title>
<para> the <link linkend="GArray"><type>GArray</type></link></para>
</refsect3></refsect2>
<refsect2 id="g-array-remove-range" role="function" condition="since:2.4">
<title>g_array_remove_range&#160;()</title>
<indexterm zone="g-array-remove-range" role="2.4"><primary sortas="array_remove_range">g_array_remove_range</primary></indexterm>
<programlisting language="C"><link linkend="GArray"><returnvalue>GArray</returnvalue></link>&#160;*
g_array_remove_range (<parameter><link linkend="GArray"><type>GArray</type></link> *array</parameter>,
                      <parameter><link linkend="guint"><type>guint</type></link> index_</parameter>,
                      <parameter><link linkend="guint"><type>guint</type></link> length</parameter>);</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>
<refsect3 id="g-array-remove-range.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>array</para></entry>
<entry role="parameter_description"><para>a <parameter>GArray</parameter>
</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>index_</para></entry>
<entry role="parameter_description"><para>the index of the first element to remove</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>length</para></entry>
<entry role="parameter_description"><para>the number of elements to remove</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-array-remove-range.returns" role="returns">
<title>Returns</title>
<para> the <link linkend="GArray"><type>GArray</type></link></para>
</refsect3><para role="since">Since: <link linkend="api-index-2.4">2.4</link></para></refsect2>
<refsect2 id="g-array-sort" role="function">
<title>g_array_sort&#160;()</title>
<indexterm zone="g-array-sort"><primary sortas="array_sort">g_array_sort</primary></indexterm>
<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link>
g_array_sort (<parameter><link linkend="GArray"><type>GArray</type></link> *array</parameter>,
              <parameter><link linkend="GCompareFunc"><type>GCompareFunc</type></link> compare_func</parameter>);</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>This is guaranteed to be a stable sort since version 2.32.</para>
<refsect3 id="g-array-sort.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>array</para></entry>
<entry role="parameter_description"><para>a <link linkend="GArray"><type>GArray</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>compare_func</para></entry>
<entry role="parameter_description"><para>comparison function</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3></refsect2>
<refsect2 id="g-array-sort-with-data" role="function">
<title>g_array_sort_with_data&#160;()</title>
<indexterm zone="g-array-sort-with-data"><primary sortas="array_sort_with_data">g_array_sort_with_data</primary></indexterm>
<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link>
g_array_sort_with_data (<parameter><link linkend="GArray"><type>GArray</type></link> *array</parameter>,
                        <parameter><link linkend="GCompareDataFunc"><type>GCompareDataFunc</type></link> compare_func</parameter>,
                        <parameter><link linkend="gpointer"><type>gpointer</type></link> user_data</parameter>);</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>
<para>This is guaranteed to be a stable sort since version 2.32.</para>
<para>There used to be a comment here about making the sort stable by
using the addresses of the elements in the comparison function.
This did not actually work, so any such code should be removed.</para>
<refsect3 id="g-array-sort-with-data.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>array</para></entry>
<entry role="parameter_description"><para>a <link linkend="GArray"><type>GArray</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>compare_func</para></entry>
<entry role="parameter_description"><para>comparison function</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>user_data</para></entry>
<entry role="parameter_description"><para>data to pass to <parameter>compare_func</parameter>
</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3></refsect2>
<refsect2 id="g-array-binary-search" role="function" condition="since:2.62">
<title>g_array_binary_search&#160;()</title>
<indexterm zone="g-array-binary-search" role="2.62"><primary sortas="array_binary_search">g_array_binary_search</primary></indexterm>
<programlisting language="C"><link linkend="gboolean"><returnvalue>gboolean</returnvalue></link>
g_array_binary_search (<parameter><link linkend="GArray"><type>GArray</type></link> *array</parameter>,
                       <parameter><link linkend="gconstpointer"><type>gconstpointer</type></link> target</parameter>,
                       <parameter><link linkend="GCompareFunc"><type>GCompareFunc</type></link> compare_func</parameter>,
                       <parameter><link linkend="guint"><type>guint</type></link> *out_match_index</parameter>);</programlisting>
<para>Checks whether <parameter>target</parameter>
 exists in <parameter>array</parameter>
 by performing a binary
search based on the given comparison function <parameter>compare_func</parameter>
 which
get pointers to items as arguments. If the element is found, <link linkend="TRUE:CAPS"><literal>TRUE</literal></link>
is returned and the element’s index is returned in <parameter>out_match_index</parameter>

(if non-<link linkend="NULL:CAPS"><literal>NULL</literal></link>). Otherwise, <link linkend="FALSE:CAPS"><literal>FALSE</literal></link> is returned and <parameter>out_match_index</parameter>

is undefined. If <parameter>target</parameter>
 exists multiple times in <parameter>array</parameter>
, the index
of the first instance is returned. This search is using a binary
search, so the <parameter>array</parameter>
 must absolutely be sorted to return a correct
result (if not, the function may produce false-negative).</para>
<para>This example defines a comparison function and search an element in a <link linkend="GArray"><type>GArray</type></link>:</para>
<informalexample><programlisting role="example"><![CDATA[
static gint*
cmpint (gconstpointer a, gconstpointer b)
{
  const gint *_a = a;
  const gint *_b = b;

  return *_a - *_b;
}
...
gint i = 424242;
guint matched_index;
gboolean result = g_array_binary_search (garray, &i, cmpint, &matched_index);
...
]]></programlisting></informalexample>
<para></para>
<refsect3 id="g-array-binary-search.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>array</para></entry>
<entry role="parameter_description"><para>a <link linkend="GArray"><type>GArray</type></link>.</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>target</para></entry>
<entry role="parameter_description"><para>a pointer to the item to look up.</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>compare_func</para></entry>
<entry role="parameter_description"><para>A <link linkend="GCompareFunc"><type>GCompareFunc</type></link> used to locate <parameter>target</parameter>
.</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>out_match_index</para></entry>
<entry role="parameter_description"><para>return location
for the index of the element, if found. </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>optional</acronym>][<acronym>out caller-allocates</acronym>]</emphasis></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-array-binary-search.returns" role="returns">
<title>Returns</title>
<para> <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> if <parameter>target</parameter>
is one of the elements of <parameter>array</parameter>
, <link linkend="FALSE:CAPS"><literal>FALSE</literal></link> otherwise.</para>
</refsect3><para role="since">Since: <link linkend="api-index-2.62">2.62</link></para></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 language="C">#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.</para>
<para>This example gets a pointer to an element in a <link linkend="GArray"><type>GArray</type></link>:</para>
<informalexample><programlisting role="example"><![CDATA[
  EDayViewEvent *event;
  // This gets a pointer to the 4th element in the array of
  // EDayViewEvent structs.
  event = &g_array_index (events, EDayViewEvent, 3);
]]></programlisting></informalexample>
<para></para>
<refsect3 id="g-array-index.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>a</para></entry>
<entry role="parameter_description"><para>a <link linkend="GArray"><type>GArray</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>t</para></entry>
<entry role="parameter_description"><para>the type of the elements</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>i</para></entry>
<entry role="parameter_description"><para>the index of the element to return</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-array-index.returns" role="returns">
<title>Returns</title>
<para> the element of the <link linkend="GArray"><type>GArray</type></link> at the index given by <parameter>i</parameter>
</para>
</refsect3></refsect2>
<refsect2 id="g-array-set-size" role="function">
<title>g_array_set_size&#160;()</title>
<indexterm zone="g-array-set-size"><primary sortas="array_set_size">g_array_set_size</primary></indexterm>
<programlisting language="C"><link linkend="GArray"><returnvalue>GArray</returnvalue></link>&#160;*
g_array_set_size (<parameter><link linkend="GArray"><type>GArray</type></link> *array</parameter>,
                  <parameter><link linkend="guint"><type>guint</type></link> length</parameter>);</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>
<refsect3 id="g-array-set-size.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>array</para></entry>
<entry role="parameter_description"><para>a <link linkend="GArray"><type>GArray</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>length</para></entry>
<entry role="parameter_description"><para>the new size of the <link linkend="GArray"><type>GArray</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-array-set-size.returns" role="returns">
<title>Returns</title>
<para> the <link linkend="GArray"><type>GArray</type></link></para>
</refsect3></refsect2>
<refsect2 id="g-array-set-clear-func" role="function" condition="since:2.32">
<title>g_array_set_clear_func&#160;()</title>
<indexterm zone="g-array-set-clear-func" role="2.32"><primary sortas="array_set_clear_func">g_array_set_clear_func</primary></indexterm>
<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link>
g_array_set_clear_func (<parameter><link linkend="GArray"><type>GArray</type></link> *array</parameter>,
                        <parameter><link linkend="GDestroyNotify"><type>GDestroyNotify</type></link> clear_func</parameter>);</programlisting>
<para>Sets a function to clear an element of <parameter>array</parameter>
.</para>
<para>The <parameter>clear_func</parameter>
 will be called when an element in the array
data segment is removed and when the array is freed and data
segment is deallocated as well. <parameter>clear_func</parameter>
 will be passed a
pointer to the element to clear, rather than the element itself.</para>
<para>Note that in contrast with other uses of <link linkend="GDestroyNotify"><type>GDestroyNotify</type></link>
functions, <parameter>clear_func</parameter>
 is expected to clear the contents of
the array element it is given, but not free the element itself.</para>
<refsect3 id="g-array-set-clear-func.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>array</para></entry>
<entry role="parameter_description"><para>A <link linkend="GArray"><type>GArray</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>clear_func</para></entry>
<entry role="parameter_description"><para>a function to clear an element of <parameter>array</parameter>
</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><para role="since">Since: <link linkend="api-index-2.32">2.32</link></para></refsect2>
<refsect2 id="g-array-free" role="function">
<title>g_array_free&#160;()</title>
<indexterm zone="g-array-free"><primary sortas="array_free">g_array_free</primary></indexterm>
<programlisting language="C"><link linkend="gchar"><returnvalue>gchar</returnvalue></link>&#160;*
g_array_free (<parameter><link linkend="GArray"><type>GArray</type></link> *array</parameter>,
              <parameter><link linkend="gboolean"><type>gboolean</type></link> free_segment</parameter>);</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. 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>
<para>If array contents point to dynamically-allocated memory, they should
be freed separately if <parameter>free_seg</parameter>
 is <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> and no <parameter>clear_func</parameter>

function has been set for <parameter>array</parameter>
.</para>
<para>This function is not thread-safe. If using a <link linkend="GArray"><type>GArray</type></link> from multiple
threads, use only the atomic <link linkend="g-array-ref"><function>g_array_ref()</function></link> and <link linkend="g-array-unref"><function>g_array_unref()</function></link>
functions.</para>
<refsect3 id="g-array-free.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>array</para></entry>
<entry role="parameter_description"><para>a <link linkend="GArray"><type>GArray</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>free_segment</para></entry>
<entry role="parameter_description"><para>if <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> the actual element data is freed as well</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-array-free.returns" role="returns">
<title>Returns</title>
<para> 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>.</para>
</refsect3></refsect2>

</refsect1>
<refsect1 id="glib-Arrays.other_details" role="details">
<title role="details.title">Types and Values</title>
<refsect2 id="GArray" role="struct">
<title>struct GArray</title>
<indexterm zone="GArray"><primary sortas="Array">GArray</primary></indexterm>
<programlisting language="C">struct GArray {
  gchar *data;
  guint len;
};
</programlisting>
<para>Contains the public fields of a GArray.</para>
<refsect3 id="GArray.members" role="struct_members">
<title>Members</title>
<informaltable role="struct_members_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="struct_members_name" colwidth="300px"/>
<colspec colname="struct_members_description"/>
<colspec colname="struct_members_annotations" colwidth="200px"/>
<tbody>
<row role="member"><entry role="struct_member_name"><para><link linkend="gchar"><type>gchar</type></link>&#160;*<structfield id="GArray.data">data</structfield>;</para></entry>
<entry role="struct_member_description"><para>a pointer to the element data. The data may be moved as
elements are added to the <link linkend="GArray"><type>GArray</type></link>.</para></entry>
<entry role="struct_member_annotations"></entry>
</row>
<row role="member"><entry role="struct_member_name"><para><link linkend="guint"><type>guint</type></link>&#160;<structfield id="GArray.len">len</structfield>;</para></entry>
<entry role="struct_member_description"><para>the number of elements in the <link linkend="GArray"><type>GArray</type></link> not including the
possible terminating zero element.</para></entry>
<entry role="struct_member_annotations"></entry>
</row>
</tbody></tgroup></informaltable>
</refsect3>
</refsect2>

</refsect1>

</refentry>
