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

<refnamediv>
<refname>Byte Arrays</refname><refpurpose>arrays of bytes, which grow automatically as elements are added.</refpurpose>
</refnamediv>

<refsynopsisdiv><title>Synopsis</title>

<synopsis>

#include &lt;glib.h&gt;


struct      <link linkend="GByteArray">GByteArray</link>;
<link linkend="GByteArray">GByteArray</link>* <link linkend="g-byte-array-new">g_byte_array_new</link>                (void);
<link linkend="GByteArray">GByteArray</link>* <link linkend="g-byte-array-sized-new">g_byte_array_sized_new</link>          (<link linkend="guint">guint</link> reserved_size);
<link linkend="GByteArray">GByteArray</link>* <link linkend="g-byte-array-append">g_byte_array_append</link>             (<link linkend="GByteArray">GByteArray</link> *array,
                                             const <link linkend="guint8">guint8</link> *data,
                                             <link linkend="guint">guint</link> len);
<link linkend="GByteArray">GByteArray</link>* <link linkend="g-byte-array-prepend">g_byte_array_prepend</link>            (<link linkend="GByteArray">GByteArray</link> *array,
                                             const <link linkend="guint8">guint8</link> *data,
                                             <link linkend="guint">guint</link> len);
<link linkend="GByteArray">GByteArray</link>* <link linkend="g-byte-array-remove-index">g_byte_array_remove_index</link>       (<link linkend="GByteArray">GByteArray</link> *array,
                                             <link linkend="guint">guint</link> index_);
<link linkend="GByteArray">GByteArray</link>* <link linkend="g-byte-array-remove-index-fast">g_byte_array_remove_index_fast</link>  (<link linkend="GByteArray">GByteArray</link> *array,
                                             <link linkend="guint">guint</link> index_);
<link linkend="GByteArray">GByteArray</link>* <link linkend="g-byte-array-remove-range">g_byte_array_remove_range</link>       (<link linkend="GByteArray">GByteArray</link> *array,
                                             <link linkend="guint">guint</link> index_,
                                             <link linkend="guint">guint</link> length);
<link linkend="void">void</link>        <link linkend="g-byte-array-sort">g_byte_array_sort</link>               (<link linkend="GByteArray">GByteArray</link> *array,
                                             <link linkend="GCompareFunc">GCompareFunc</link> compare_func);
<link linkend="void">void</link>        <link linkend="g-byte-array-sort-with-data">g_byte_array_sort_with_data</link>     (<link linkend="GByteArray">GByteArray</link> *array,
                                             <link linkend="GCompareDataFunc">GCompareDataFunc</link> compare_func,
                                             <link linkend="gpointer">gpointer</link> user_data);
<link linkend="GByteArray">GByteArray</link>* <link linkend="g-byte-array-set-size">g_byte_array_set_size</link>           (<link linkend="GByteArray">GByteArray</link> *array,
                                             <link linkend="guint">guint</link> length);
<link linkend="guint8">guint8</link>*     <link linkend="g-byte-array-free">g_byte_array_free</link>               (<link linkend="GByteArray">GByteArray</link> *array,
                                             <link linkend="gboolean">gboolean</link> free_segment);
</synopsis>
</refsynopsisdiv>









<refsect1>
<title>Description</title>
<para>
<link linkend="GByteArray"><type>GByteArray</type></link> is based on <link linkend="GArray"><type>GArray</type></link>, to provide arrays of bytes which grow
automatically as elements are added.
</para>
<para>
To create a new <link linkend="GByteArray"><type>GByteArray</type></link> use <link linkend="g-byte-array-new"><function>g_byte_array_new()</function></link>.
</para>
<para>
To add elements to a <link linkend="GByteArray"><type>GByteArray</type></link>, use <link linkend="g-byte-array-append"><function>g_byte_array_append()</function></link>, and
<link linkend="g-byte-array-prepend"><function>g_byte_array_prepend()</function></link>.
</para>
<para>
To set the size of a <link linkend="GByteArray"><type>GByteArray</type></link>, use <link linkend="g-byte-array-set-size"><function>g_byte_array_set_size()</function></link>.
</para>
<para>
To free a <link linkend="GByteArray"><type>GByteArray</type></link>, use <link linkend="g-byte-array-free"><function>g_byte_array_free()</function></link>.
</para>

<example>
<title>Using a <structname>GByteArray</structname></title>
<programlisting>
  GByteArray *gbarray;
  gint i;

  gbarray = g_byte_array_new (<!-- -->);
  for (i = 0; i &lt; 10000; i++)
    g_byte_array_append (gbarray, (guint8*) "abcd", 4);

  for (i = 0; i &lt; 10000; i++)
    {
      g_assert (gbarray->data[4*i] == 'a');
      g_assert (gbarray->data[4*i+1] == 'b');
      g_assert (gbarray->data[4*i+2] == 'c');
      g_assert (gbarray->data[4*i+3] == 'd');
    }

  g_byte_array_free (gbarray, TRUE);
</programlisting></example>
</refsect1>

<refsect1>
<title>Details</title>
<refsect2>
<title><anchor id="GByteArray"/>struct GByteArray</title>
<indexterm><primary>GByteArray</primary></indexterm><programlisting>struct GByteArray {

  guint8 *data;
  guint	  len;
};
</programlisting>
<para>
The <structname>GByteArray</structname> struct allows access to the public fields of a <structname>GByteArray</structname>.
</para><variablelist role="struct">
<varlistentry>
<term><link linkend="guint8">guint8</link> *<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="GByteArray"><type>GByteArray</type></link>.
</simpara></listitem>
</varlistentry>
<varlistentry>
<term><link linkend="guint">guint</link> <structfield>len</structfield></term>
<listitem><simpara>the number of elements in the <link linkend="GByteArray"><type>GByteArray</type></link>.

</simpara></listitem>
</varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-byte-array-new"/>g_byte_array_new ()</title>
<indexterm><primary>g_byte_array_new</primary></indexterm><programlisting><link linkend="GByteArray">GByteArray</link>* g_byte_array_new                (void);</programlisting>
<para>
Creates a new <link linkend="GByteArray"><type>GByteArray</type></link>.
</para><variablelist role="params">
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara>the new <link linkend="GByteArray"><type>GByteArray</type></link>.


</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-byte-array-sized-new"/>g_byte_array_sized_new ()</title>
<indexterm><primary>g_byte_array_sized_new</primary></indexterm><programlisting><link linkend="GByteArray">GByteArray</link>* g_byte_array_sized_new          (<link linkend="guint">guint</link> reserved_size);</programlisting>
<para>
Creates a new <link linkend="GByteArray"><type>GByteArray</type></link> with <parameter>reserved_size</parameter> bytes preallocated. This
avoids frequent reallocation, if you are going to add many bytes to
the array. Note however that the size of the array is still 0.
</para><variablelist role="params">
<varlistentry><term><parameter>reserved_size</parameter>&nbsp;:</term>
<listitem><simpara>number of bytes preallocated.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara>the new <link linkend="GByteArray"><type>GByteArray</type></link>.


</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-byte-array-append"/>g_byte_array_append ()</title>
<indexterm><primary>g_byte_array_append</primary></indexterm><programlisting><link linkend="GByteArray">GByteArray</link>* g_byte_array_append             (<link linkend="GByteArray">GByteArray</link> *array,
                                             const <link linkend="guint8">guint8</link> *data,
                                             <link linkend="guint">guint</link> len);</programlisting>
<para>
Adds the given bytes to the end of the <link linkend="GByteArray"><type>GByteArray</type></link>.
The array will grow in size automatically if necessary.
</para><variablelist role="params">
<varlistentry><term><parameter>array</parameter>&nbsp;:</term>
<listitem><simpara>a <link linkend="GByteArray"><type>GByteArray</type></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>data</parameter>&nbsp;:</term>
<listitem><simpara>the byte data to be added.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>len</parameter>&nbsp;:</term>
<listitem><simpara>the number of bytes to add.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara>the <link linkend="GByteArray"><type>GByteArray</type></link>.


</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-byte-array-prepend"/>g_byte_array_prepend ()</title>
<indexterm><primary>g_byte_array_prepend</primary></indexterm><programlisting><link linkend="GByteArray">GByteArray</link>* g_byte_array_prepend            (<link linkend="GByteArray">GByteArray</link> *array,
                                             const <link linkend="guint8">guint8</link> *data,
                                             <link linkend="guint">guint</link> len);</programlisting>
<para>
Adds the given data to the start of the <link linkend="GByteArray"><type>GByteArray</type></link>.
The array will grow in size automatically if necessary.
</para><variablelist role="params">
<varlistentry><term><parameter>array</parameter>&nbsp;:</term>
<listitem><simpara>a <link linkend="GByteArray"><type>GByteArray</type></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>data</parameter>&nbsp;:</term>
<listitem><simpara>the byte data to be added.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>len</parameter>&nbsp;:</term>
<listitem><simpara>the number of bytes to add.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara>the <link linkend="GByteArray"><type>GByteArray</type></link>.


</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-byte-array-remove-index"/>g_byte_array_remove_index ()</title>
<indexterm><primary>g_byte_array_remove_index</primary></indexterm><programlisting><link linkend="GByteArray">GByteArray</link>* g_byte_array_remove_index       (<link linkend="GByteArray">GByteArray</link> *array,
                                             <link linkend="guint">guint</link> index_);</programlisting>
<para>
Removes the byte at the given index from a <link linkend="GByteArray"><type>GByteArray</type></link>.
The following bytes are moved down one place.
</para><variablelist role="params">
<varlistentry><term><parameter>array</parameter>&nbsp;:</term>
<listitem><simpara>a <link linkend="GByteArray"><type>GByteArray</type></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>index_</parameter>&nbsp;:</term>
<listitem><simpara>the index of the byte to remove.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara>the <link linkend="GByteArray"><type>GByteArray</type></link>.


</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-byte-array-remove-index-fast"/>g_byte_array_remove_index_fast ()</title>
<indexterm><primary>g_byte_array_remove_index_fast</primary></indexterm><programlisting><link linkend="GByteArray">GByteArray</link>* g_byte_array_remove_index_fast  (<link linkend="GByteArray">GByteArray</link> *array,
                                             <link linkend="guint">guint</link> index_);</programlisting>
<para>
Removes the byte at the given index from a <link linkend="GByteArray"><type>GByteArray</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="GByteArray"><type>GByteArray</type></link>. But it is faster than
<link linkend="g-byte-array-remove-index"><function>g_byte_array_remove_index()</function></link>.
</para><variablelist role="params">
<varlistentry><term><parameter>array</parameter>&nbsp;:</term>
<listitem><simpara>a <link linkend="GByteArray"><type>GByteArray</type></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>index_</parameter>&nbsp;:</term>
<listitem><simpara>the index of the byte to remove.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara>the <link linkend="GByteArray"><type>GByteArray</type></link>.


</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-byte-array-remove-range"/>g_byte_array_remove_range ()</title>
<indexterm role="2.4"><primary>g_byte_array_remove_range</primary></indexterm><programlisting><link linkend="GByteArray">GByteArray</link>* g_byte_array_remove_range       (<link linkend="GByteArray">GByteArray</link> *array,
                                             <link linkend="guint">guint</link> index_,
                                             <link linkend="guint">guint</link> length);</programlisting>
<para>
Removes the given number of bytes starting at the given index from a
<link linkend="GByteArray"><type>GByteArray</type></link>.  The following elements are moved to close the gap.
</para><variablelist role="params">
<varlistentry><term><parameter>array</parameter>&nbsp;:</term>
<listitem><simpara>a <parameter>GByteArray</parameter>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>index_</parameter>&nbsp;:</term>
<listitem><simpara>the index of the first byte to remove.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>length</parameter>&nbsp;:</term>
<listitem><simpara>the number of bytes to remove.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara>the <link linkend="GByteArray"><type>GByteArray</type></link>.
</simpara></listitem></varlistentry>
</variablelist><para>Since 2.4


</para></refsect2>
<refsect2>
<title><anchor id="g-byte-array-sort"/>g_byte_array_sort ()</title>
<indexterm><primary>g_byte_array_sort</primary></indexterm><programlisting><link linkend="void">void</link>        g_byte_array_sort               (<link linkend="GByteArray">GByteArray</link> *array,
                                             <link linkend="GCompareFunc">GCompareFunc</link> compare_func);</programlisting>
<para>
Sorts a byte array, using <parameter>compare_func</parameter> which should be a <link linkend="qsort"><function>qsort()</function></link>-style
comparison function (returns -1 for first arg is less than second arg, 0 for
equal, 1 if first arg is greater than second arg).
</para><variablelist role="params">
<varlistentry><term><parameter>array</parameter>&nbsp;:</term>
<listitem><simpara>a <link linkend="GByteArray"><type>GByteArray</type></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>compare_func</parameter>&nbsp;:</term>
<listitem><simpara>comparison function.


</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-byte-array-sort-with-data"/>g_byte_array_sort_with_data ()</title>
<indexterm><primary>g_byte_array_sort_with_data</primary></indexterm><programlisting><link linkend="void">void</link>        g_byte_array_sort_with_data     (<link linkend="GByteArray">GByteArray</link> *array,
                                             <link linkend="GCompareDataFunc">GCompareDataFunc</link> compare_func,
                                             <link linkend="gpointer">gpointer</link> user_data);</programlisting>
<para>
Like <link linkend="g-byte-array-sort"><function>g_byte_array_sort()</function></link>, but the comparison function takes a user data argument.
</para><variablelist role="params">
<varlistentry><term><parameter>array</parameter>&nbsp;:</term>
<listitem><simpara>a <link linkend="GByteArray"><type>GByteArray</type></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>compare_func</parameter>&nbsp;:</term>
<listitem><simpara>comparison function.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>user_data</parameter>&nbsp;:</term>
<listitem><simpara>data to pass to <parameter>compare_func</parameter>.


</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-byte-array-set-size"/>g_byte_array_set_size ()</title>
<indexterm><primary>g_byte_array_set_size</primary></indexterm><programlisting><link linkend="GByteArray">GByteArray</link>* g_byte_array_set_size           (<link linkend="GByteArray">GByteArray</link> *array,
                                             <link linkend="guint">guint</link> length);</programlisting>
<para>
Sets the size of the <link linkend="GByteArray"><type>GByteArray</type></link>, expanding it if necessary.
</para><variablelist role="params">
<varlistentry><term><parameter>array</parameter>&nbsp;:</term>
<listitem><simpara>a <link linkend="GByteArray"><type>GByteArray</type></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>length</parameter>&nbsp;:</term>
<listitem><simpara>the new size of the <link linkend="GByteArray"><type>GByteArray</type></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara>the <link linkend="GByteArray"><type>GByteArray</type></link>.


</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="g-byte-array-free"/>g_byte_array_free ()</title>
<indexterm><primary>g_byte_array_free</primary></indexterm><programlisting><link linkend="guint8">guint8</link>*     g_byte_array_free               (<link linkend="GByteArray">GByteArray</link> *array,
                                             <link linkend="gboolean">gboolean</link> free_segment);</programlisting>
<para>
Frees the memory allocated by the <link linkend="GByteArray"><type>GByteArray</type></link>.
If <parameter>free_segment</parameter> is <literal>TRUE</literal> it frees the actual byte data.
</para><variablelist role="params">
<varlistentry><term><parameter>array</parameter>&nbsp;:</term>
<listitem><simpara>a <link linkend="GByteArray"><type>GByteArray</type></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>free_segment</parameter>&nbsp;:</term>
<listitem><simpara>if <literal>TRUE</literal> the actual byte data is freed as well.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara>


</simpara></listitem></varlistentry>
</variablelist></refsect2>

</refsect1>




</refentry>
