<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 <glib.h> 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 < 10000; i++) g_byte_array_append (gbarray, (guint8*) "abcd", 4); for (i = 0; i < 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> :</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> :</term> <listitem><simpara>a <link linkend="GByteArray"><type>GByteArray</type></link>. </simpara></listitem></varlistentry> <varlistentry><term><parameter>data</parameter> :</term> <listitem><simpara>the byte data to be added. </simpara></listitem></varlistentry> <varlistentry><term><parameter>len</parameter> :</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> :</term> <listitem><simpara>a <link linkend="GByteArray"><type>GByteArray</type></link>. </simpara></listitem></varlistentry> <varlistentry><term><parameter>data</parameter> :</term> <listitem><simpara>the byte data to be added. </simpara></listitem></varlistentry> <varlistentry><term><parameter>len</parameter> :</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> :</term> <listitem><simpara>a <link linkend="GByteArray"><type>GByteArray</type></link>. </simpara></listitem></varlistentry> <varlistentry><term><parameter>index_</parameter> :</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> :</term> <listitem><simpara>a <link linkend="GByteArray"><type>GByteArray</type></link>. </simpara></listitem></varlistentry> <varlistentry><term><parameter>index_</parameter> :</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> :</term> <listitem><simpara>a <parameter>GByteArray</parameter>. </simpara></listitem></varlistentry> <varlistentry><term><parameter>index_</parameter> :</term> <listitem><simpara>the index of the first byte to remove. </simpara></listitem></varlistentry> <varlistentry><term><parameter>length</parameter> :</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> :</term> <listitem><simpara>a <link linkend="GByteArray"><type>GByteArray</type></link>. </simpara></listitem></varlistentry> <varlistentry><term><parameter>compare_func</parameter> :</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> :</term> <listitem><simpara>a <link linkend="GByteArray"><type>GByteArray</type></link>. </simpara></listitem></varlistentry> <varlistentry><term><parameter>compare_func</parameter> :</term> <listitem><simpara>comparison function. </simpara></listitem></varlistentry> <varlistentry><term><parameter>user_data</parameter> :</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> :</term> <listitem><simpara>a <link linkend="GByteArray"><type>GByteArray</type></link>. </simpara></listitem></varlistentry> <varlistentry><term><parameter>length</parameter> :</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> :</term> <listitem><simpara>a <link linkend="GByteArray"><type>GByteArray</type></link>. </simpara></listitem></varlistentry> <varlistentry><term><parameter>free_segment</parameter> :</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>