⚝
One Hat Cyber Team
⚝
Your IP:
216.73.216.83
Server IP:
157.245.101.34
Server:
Linux skvinfotech-website 5.4.0-131-generic #147-Ubuntu SMP Fri Oct 14 17:07:22 UTC 2022 x86_64
Server Software:
Apache/2.4.41 (Ubuntu)
PHP Version:
7.4.33
Buat File
|
Buat Folder
Eksekusi
Dir :
~
/
usr
/
share
/
doc
/
libgtk-3-dev
/
glib
/
View File Name :
glib-Pointer-Arrays.html
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> <html> <head> <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> <title>Pointer Arrays: GLib Reference Manual</title> <meta name="generator" content="DocBook XSL Stylesheets V1.79.1"> <link rel="home" href="index.html" title="GLib Reference Manual"> <link rel="up" href="glib-data-types.html" title="GLib Data Types"> <link rel="prev" href="glib-Arrays.html" title="Arrays"> <link rel="next" href="glib-Byte-Arrays.html" title="Byte Arrays"> <meta name="generator" content="GTK-Doc V1.32 (XML mode)"> <link rel="stylesheet" href="style.css" type="text/css"> </head> <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> <table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="5"><tr valign="middle"> <td width="100%" align="left" class="shortcuts"> <a href="#" class="shortcut">Top</a><span id="nav_description"> <span class="dim">|</span> <a href="#glib-Pointer-Arrays.description" class="shortcut">Description</a></span> </td> <td><a accesskey="h" href="index.html"><img src="home.png" width="16" height="16" border="0" alt="Home"></a></td> <td><a accesskey="u" href="glib-data-types.html"><img src="up.png" width="16" height="16" border="0" alt="Up"></a></td> <td><a accesskey="p" href="glib-Arrays.html"><img src="left.png" width="16" height="16" border="0" alt="Prev"></a></td> <td><a accesskey="n" href="glib-Byte-Arrays.html"><img src="right.png" width="16" height="16" border="0" alt="Next"></a></td> </tr></table> <div class="refentry"> <a name="glib-Pointer-Arrays"></a><div class="titlepage"></div> <div class="refnamediv"><table width="100%"><tr> <td valign="top"> <h2><span class="refentrytitle"><a name="glib-Pointer-Arrays.top_of_page"></a>Pointer Arrays</span></h2> <p>Pointer Arrays — arrays of pointers to any type of data, which grow automatically as new elements are added</p> </td> <td class="gallery_image" valign="top" align="right"></td> </tr></table></div> <div class="refsect1"> <a name="glib-Pointer-Arrays.functions"></a><h2>Functions</h2> <div class="informaltable"><table class="informaltable" width="100%" border="0"> <colgroup> <col width="150px" class="functions_proto_type"> <col class="functions_proto_name"> </colgroup> <tbody> <tr> <td class="function_type"> <a class="link" href="glib-Pointer-Arrays.html#GPtrArray" title="struct GPtrArray"><span class="returnvalue">GPtrArray</span></a> * </td> <td class="function_name"> <a class="link" href="glib-Pointer-Arrays.html#g-ptr-array-new" title="g_ptr_array_new ()">g_ptr_array_new</a> <span class="c_punctuation">()</span> </td> </tr> <tr> <td class="function_type"> <a class="link" href="glib-Basic-Types.html#gpointer" title="gpointer"><span class="returnvalue">gpointer</span></a> * </td> <td class="function_name"> <a class="link" href="glib-Pointer-Arrays.html#g-ptr-array-steal" title="g_ptr_array_steal ()">g_ptr_array_steal</a> <span class="c_punctuation">()</span> </td> </tr> <tr> <td class="function_type"> <a class="link" href="glib-Pointer-Arrays.html#GPtrArray" title="struct GPtrArray"><span class="returnvalue">GPtrArray</span></a> * </td> <td class="function_name"> <a class="link" href="glib-Pointer-Arrays.html#g-ptr-array-sized-new" title="g_ptr_array_sized_new ()">g_ptr_array_sized_new</a> <span class="c_punctuation">()</span> </td> </tr> <tr> <td class="function_type"> <a class="link" href="glib-Pointer-Arrays.html#GPtrArray" title="struct GPtrArray"><span class="returnvalue">GPtrArray</span></a> * </td> <td class="function_name"> <a class="link" href="glib-Pointer-Arrays.html#g-ptr-array-new-with-free-func" title="g_ptr_array_new_with_free_func ()">g_ptr_array_new_with_free_func</a> <span class="c_punctuation">()</span> </td> </tr> <tr> <td class="function_type"> <a class="link" href="glib-Pointer-Arrays.html#GPtrArray" title="struct GPtrArray"><span class="returnvalue">GPtrArray</span></a> * </td> <td class="function_name"> <a class="link" href="glib-Pointer-Arrays.html#g-ptr-array-copy" title="g_ptr_array_copy ()">g_ptr_array_copy</a> <span class="c_punctuation">()</span> </td> </tr> <tr> <td class="function_type"> <a class="link" href="glib-Pointer-Arrays.html#GPtrArray" title="struct GPtrArray"><span class="returnvalue">GPtrArray</span></a> * </td> <td class="function_name"> <a class="link" href="glib-Pointer-Arrays.html#g-ptr-array-new-full" title="g_ptr_array_new_full ()">g_ptr_array_new_full</a> <span class="c_punctuation">()</span> </td> </tr> <tr> <td class="function_type"> <span class="returnvalue">void</span> </td> <td class="function_name"> <a class="link" href="glib-Pointer-Arrays.html#g-ptr-array-set-free-func" title="g_ptr_array_set_free_func ()">g_ptr_array_set_free_func</a> <span class="c_punctuation">()</span> </td> </tr> <tr> <td class="function_type"> <a class="link" href="glib-Pointer-Arrays.html#GPtrArray" title="struct GPtrArray"><span class="returnvalue">GPtrArray</span></a> * </td> <td class="function_name"> <a class="link" href="glib-Pointer-Arrays.html#g-ptr-array-ref" title="g_ptr_array_ref ()">g_ptr_array_ref</a> <span class="c_punctuation">()</span> </td> </tr> <tr> <td class="function_type"> <span class="returnvalue">void</span> </td> <td class="function_name"> <a class="link" href="glib-Pointer-Arrays.html#g-ptr-array-unref" title="g_ptr_array_unref ()">g_ptr_array_unref</a> <span class="c_punctuation">()</span> </td> </tr> <tr> <td class="function_type"> <span class="returnvalue">void</span> </td> <td class="function_name"> <a class="link" href="glib-Pointer-Arrays.html#g-ptr-array-add" title="g_ptr_array_add ()">g_ptr_array_add</a> <span class="c_punctuation">()</span> </td> </tr> <tr> <td class="function_type"> <span class="returnvalue">void</span> </td> <td class="function_name"> <a class="link" href="glib-Pointer-Arrays.html#g-ptr-array-extend" title="g_ptr_array_extend ()">g_ptr_array_extend</a> <span class="c_punctuation">()</span> </td> </tr> <tr> <td class="function_type"> <span class="returnvalue">void</span> </td> <td class="function_name"> <a class="link" href="glib-Pointer-Arrays.html#g-ptr-array-extend-and-steal" title="g_ptr_array_extend_and_steal ()">g_ptr_array_extend_and_steal</a> <span class="c_punctuation">()</span> </td> </tr> <tr> <td class="function_type"> <span class="returnvalue">void</span> </td> <td class="function_name"> <a class="link" href="glib-Pointer-Arrays.html#g-ptr-array-insert" title="g_ptr_array_insert ()">g_ptr_array_insert</a> <span class="c_punctuation">()</span> </td> </tr> <tr> <td class="function_type"> <a class="link" href="glib-Basic-Types.html#gboolean" title="gboolean"><span class="returnvalue">gboolean</span></a> </td> <td class="function_name"> <a class="link" href="glib-Pointer-Arrays.html#g-ptr-array-remove" title="g_ptr_array_remove ()">g_ptr_array_remove</a> <span class="c_punctuation">()</span> </td> </tr> <tr> <td class="function_type"> <a class="link" href="glib-Basic-Types.html#gpointer" title="gpointer"><span class="returnvalue">gpointer</span></a> </td> <td class="function_name"> <a class="link" href="glib-Pointer-Arrays.html#g-ptr-array-remove-index" title="g_ptr_array_remove_index ()">g_ptr_array_remove_index</a> <span class="c_punctuation">()</span> </td> </tr> <tr> <td class="function_type"> <a class="link" href="glib-Basic-Types.html#gboolean" title="gboolean"><span class="returnvalue">gboolean</span></a> </td> <td class="function_name"> <a class="link" href="glib-Pointer-Arrays.html#g-ptr-array-remove-fast" title="g_ptr_array_remove_fast ()">g_ptr_array_remove_fast</a> <span class="c_punctuation">()</span> </td> </tr> <tr> <td class="function_type"> <a class="link" href="glib-Basic-Types.html#gpointer" title="gpointer"><span class="returnvalue">gpointer</span></a> </td> <td class="function_name"> <a class="link" href="glib-Pointer-Arrays.html#g-ptr-array-remove-index-fast" title="g_ptr_array_remove_index_fast ()">g_ptr_array_remove_index_fast</a> <span class="c_punctuation">()</span> </td> </tr> <tr> <td class="function_type"> <a class="link" href="glib-Pointer-Arrays.html#GPtrArray" title="struct GPtrArray"><span class="returnvalue">GPtrArray</span></a> * </td> <td class="function_name"> <a class="link" href="glib-Pointer-Arrays.html#g-ptr-array-remove-range" title="g_ptr_array_remove_range ()">g_ptr_array_remove_range</a> <span class="c_punctuation">()</span> </td> </tr> <tr> <td class="function_type"> <a class="link" href="glib-Basic-Types.html#gpointer" title="gpointer"><span class="returnvalue">gpointer</span></a> </td> <td class="function_name"> <a class="link" href="glib-Pointer-Arrays.html#g-ptr-array-steal-index" title="g_ptr_array_steal_index ()">g_ptr_array_steal_index</a> <span class="c_punctuation">()</span> </td> </tr> <tr> <td class="function_type"> <a class="link" href="glib-Basic-Types.html#gpointer" title="gpointer"><span class="returnvalue">gpointer</span></a> </td> <td class="function_name"> <a class="link" href="glib-Pointer-Arrays.html#g-ptr-array-steal-index-fast" title="g_ptr_array_steal_index_fast ()">g_ptr_array_steal_index_fast</a> <span class="c_punctuation">()</span> </td> </tr> <tr> <td class="function_type"> <span class="returnvalue">void</span> </td> <td class="function_name"> <a class="link" href="glib-Pointer-Arrays.html#g-ptr-array-sort" title="g_ptr_array_sort ()">g_ptr_array_sort</a> <span class="c_punctuation">()</span> </td> </tr> <tr> <td class="function_type"> <span class="returnvalue">void</span> </td> <td class="function_name"> <a class="link" href="glib-Pointer-Arrays.html#g-ptr-array-sort-with-data" title="g_ptr_array_sort_with_data ()">g_ptr_array_sort_with_data</a> <span class="c_punctuation">()</span> </td> </tr> <tr> <td class="function_type"> <span class="returnvalue">void</span> </td> <td class="function_name"> <a class="link" href="glib-Pointer-Arrays.html#g-ptr-array-set-size" title="g_ptr_array_set_size ()">g_ptr_array_set_size</a> <span class="c_punctuation">()</span> </td> </tr> <tr> <td class="define_keyword">#define</td> <td class="function_name"> <a class="link" href="glib-Pointer-Arrays.html#g-ptr-array-index" title="g_ptr_array_index()">g_ptr_array_index</a><span class="c_punctuation">()</span> </td> </tr> <tr> <td class="function_type"> <a class="link" href="glib-Basic-Types.html#gpointer" title="gpointer"><span class="returnvalue">gpointer</span></a> * </td> <td class="function_name"> <a class="link" href="glib-Pointer-Arrays.html#g-ptr-array-free" title="g_ptr_array_free ()">g_ptr_array_free</a> <span class="c_punctuation">()</span> </td> </tr> <tr> <td class="function_type"> <span class="returnvalue">void</span> </td> <td class="function_name"> <a class="link" href="glib-Pointer-Arrays.html#g-ptr-array-foreach" title="g_ptr_array_foreach ()">g_ptr_array_foreach</a> <span class="c_punctuation">()</span> </td> </tr> <tr> <td class="function_type"> <a class="link" href="glib-Basic-Types.html#gboolean" title="gboolean"><span class="returnvalue">gboolean</span></a> </td> <td class="function_name"> <a class="link" href="glib-Pointer-Arrays.html#g-ptr-array-find" title="g_ptr_array_find ()">g_ptr_array_find</a> <span class="c_punctuation">()</span> </td> </tr> <tr> <td class="function_type"> <a class="link" href="glib-Basic-Types.html#gboolean" title="gboolean"><span class="returnvalue">gboolean</span></a> </td> <td class="function_name"> <a class="link" href="glib-Pointer-Arrays.html#g-ptr-array-find-with-equal-func" title="g_ptr_array_find_with_equal_func ()">g_ptr_array_find_with_equal_func</a> <span class="c_punctuation">()</span> </td> </tr> </tbody> </table></div> </div> <div class="refsect1"> <a name="glib-Pointer-Arrays.other"></a><h2>Types and Values</h2> <div class="informaltable"><table class="informaltable" width="100%" border="0"> <colgroup> <col width="150px" class="other_proto_type"> <col class="other_proto_name"> </colgroup> <tbody><tr> <td class="datatype_keyword">struct</td> <td class="function_name"><a class="link" href="glib-Pointer-Arrays.html#GPtrArray" title="struct GPtrArray">GPtrArray</a></td> </tr></tbody> </table></div> </div> <div class="refsect1"> <a name="glib-Pointer-Arrays.includes"></a><h2>Includes</h2> <pre class="synopsis">#include <gmodule.h> </pre> </div> <div class="refsect1"> <a name="glib-Pointer-Arrays.description"></a><h2>Description</h2> <p>Pointer Arrays are similar to Arrays but are used only for storing pointers.</p> <p>If you remove elements from the array, elements at the end of the array are moved into the space previously occupied by the removed element. This means that you should not rely on the index of particular elements remaining the same. You should also be careful when deleting elements while iterating over the array.</p> <p>To create a pointer array, use <a class="link" href="glib-Pointer-Arrays.html#g-ptr-array-new" title="g_ptr_array_new ()"><code class="function">g_ptr_array_new()</code></a>.</p> <p>To add elements to a pointer array, use <a class="link" href="glib-Pointer-Arrays.html#g-ptr-array-add" title="g_ptr_array_add ()"><code class="function">g_ptr_array_add()</code></a>.</p> <p>To remove elements from a pointer array, use <a class="link" href="glib-Pointer-Arrays.html#g-ptr-array-remove" title="g_ptr_array_remove ()"><code class="function">g_ptr_array_remove()</code></a>, <a class="link" href="glib-Pointer-Arrays.html#g-ptr-array-remove-index" title="g_ptr_array_remove_index ()"><code class="function">g_ptr_array_remove_index()</code></a> or <a class="link" href="glib-Pointer-Arrays.html#g-ptr-array-remove-index-fast" title="g_ptr_array_remove_index_fast ()"><code class="function">g_ptr_array_remove_index_fast()</code></a>.</p> <p>To access an element of a pointer array, use <a class="link" href="glib-Pointer-Arrays.html#g-ptr-array-index" title="g_ptr_array_index()"><code class="function">g_ptr_array_index()</code></a>.</p> <p>To set the size of a pointer array, use <a class="link" href="glib-Pointer-Arrays.html#g-ptr-array-set-size" title="g_ptr_array_set_size ()"><code class="function">g_ptr_array_set_size()</code></a>.</p> <p>To free a pointer array, use <a class="link" href="glib-Pointer-Arrays.html#g-ptr-array-free" title="g_ptr_array_free ()"><code class="function">g_ptr_array_free()</code></a>.</p> <p>An example using a <a class="link" href="glib-Pointer-Arrays.html#GPtrArray" title="struct GPtrArray"><span class="type">GPtrArray</span></a>:</p> <div class="informalexample"> <table class="listing_frame" border="0" cellpadding="0" cellspacing="0"> <tbody> <tr> <td class="listing_lines" align="right"><pre>1 2 3 4 5 6 7 8 9 10 11 12 13 14 15</pre></td> <td class="listing_code"><pre class="programlisting"><span class="n">GPtrArray</span> <span class="o">*</span><span class="n">array</span><span class="p">;</span> <span class="n">gchar</span> <span class="o">*</span><span class="n">string1</span> <span class="o">=</span> <span class="s">"one"</span><span class="p">;</span> <span class="n">gchar</span> <span class="o">*</span><span class="n">string2</span> <span class="o">=</span> <span class="s">"two"</span><span class="p">;</span> <span class="n">gchar</span> <span class="o">*</span><span class="n">string3</span> <span class="o">=</span> <span class="s">"three"</span><span class="p">;</span> <span class="n">array</span> <span class="o">=</span> <span class="n">g_ptr_array_new</span> <span class="p">();</span> <span class="n">g_ptr_array_add</span> <span class="p">(</span><span class="n">array</span><span class="p">,</span> <span class="p">(</span><span class="n">gpointer</span><span class="p">)</span> <span class="n">string1</span><span class="p">);</span> <span class="n">g_ptr_array_add</span> <span class="p">(</span><span class="n">array</span><span class="p">,</span> <span class="p">(</span><span class="n">gpointer</span><span class="p">)</span> <span class="n">string2</span><span class="p">);</span> <span class="n">g_ptr_array_add</span> <span class="p">(</span><span class="n">array</span><span class="p">,</span> <span class="p">(</span><span class="n">gpointer</span><span class="p">)</span> <span class="n">string3</span><span class="p">);</span> <span class="k">if</span> <span class="p">(</span><span class="n">g_ptr_array_index</span> <span class="p">(</span><span class="n">array</span><span class="p">,</span> <span class="mi">0</span><span class="p">)</span> <span class="o">!=</span> <span class="p">(</span><span class="n">gpointer</span><span class="p">)</span> <span class="n">string1</span><span class="p">)</span> <span class="n">g_print</span> <span class="p">(</span><span class="s">"ERROR: got %p instead of %p</span><span class="se">\n</span><span class="s">"</span><span class="p">,</span> <span class="n">g_ptr_array_index</span> <span class="p">(</span><span class="n">array</span><span class="p">,</span> <span class="mi">0</span><span class="p">),</span> <span class="n">string1</span><span class="p">);</span> <span class="n">g_ptr_array_free</span> <span class="p">(</span><span class="n">array</span><span class="p">,</span> <span class="n">TRUE</span><span class="p">);</span></pre></td> </tr> </tbody> </table> </div> <p></p> </div> <div class="refsect1"> <a name="glib-Pointer-Arrays.functions_details"></a><h2>Functions</h2> <div class="refsect2"> <a name="g-ptr-array-new"></a><h3>g_ptr_array_new ()</h3> <pre class="programlisting"><a class="link" href="glib-Pointer-Arrays.html#GPtrArray" title="struct GPtrArray"><span class="returnvalue">GPtrArray</span></a> * g_ptr_array_new (<em class="parameter"><code><span class="type">void</span></code></em>);</pre> <p>Creates a new <a class="link" href="glib-Pointer-Arrays.html#GPtrArray" title="struct GPtrArray"><span class="type">GPtrArray</span></a> with a reference count of 1.</p> <div class="refsect3"> <a name="g-ptr-array-new.returns"></a><h4>Returns</h4> <p> the new <a class="link" href="glib-Pointer-Arrays.html#GPtrArray" title="struct GPtrArray"><span class="type">GPtrArray</span></a></p> </div> </div> <hr> <div class="refsect2"> <a name="g-ptr-array-steal"></a><h3>g_ptr_array_steal ()</h3> <pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gpointer" title="gpointer"><span class="returnvalue">gpointer</span></a> * g_ptr_array_steal (<em class="parameter"><code><a class="link" href="glib-Pointer-Arrays.html#GPtrArray" title="struct GPtrArray"><span class="type">GPtrArray</span></a> *array</code></em>, <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gsize" title="gsize"><span class="type">gsize</span></a> *len</code></em>);</pre> <p>Frees the data in the array and resets the size to zero, while the underlying array is preserved for use elsewhere and returned to the caller.</p> <p>Even if set, the <a class="link" href="glib-Datasets.html#GDestroyNotify" title="GDestroyNotify ()"><span class="type">GDestroyNotify</span></a> function will never be called on the current contents of the array and the caller is responsible for freeing the array elements.</p> <p>An example of use:</p> <div class="informalexample"> <table class="listing_frame" border="0" cellpadding="0" cellspacing="0"> <tbody> <tr> <td class="listing_lines" align="right"><pre>1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29</pre></td> <td class="listing_code"><pre class="programlisting"><span class="n">g_autoptr</span><span class="p">(</span><span class="n">GPtrArray</span><span class="p">)</span> <span class="n">chunk_buffer</span> <span class="o">=</span> <span class="n">g_ptr_array_new_with_free_func</span> <span class="p">(</span><span class="n">g_bytes_unref</span><span class="p">);</span> <span class="c1">// Some part of your application appends a number of chunks to the pointer array.</span> <span class="n">g_ptr_array_add</span> <span class="p">(</span><span class="n">chunk_buffer</span><span class="p">,</span> <span class="n">g_bytes_new_static</span> <span class="p">(</span><span class="s">"hello"</span><span class="p">,</span> <span class="mi">5</span><span class="p">));</span> <span class="n">g_ptr_array_add</span> <span class="p">(</span><span class="n">chunk_buffer</span><span class="p">,</span> <span class="n">g_bytes_new_static</span> <span class="p">(</span><span class="s">"world"</span><span class="p">,</span> <span class="mi">5</span><span class="p">));</span> <span class="err">…</span> <span class="c1">// Periodically, the chunks need to be sent as an array-and-length to some</span> <span class="c1">// other part of the program.</span> <span class="n">GBytes</span> <span class="o">**</span><span class="n">chunks</span><span class="p">;</span> <span class="n">gsize</span> <span class="n">n_chunks</span><span class="p">;</span> <span class="n">chunks</span> <span class="o">=</span> <span class="n">g_ptr_array_steal</span> <span class="p">(</span><span class="n">chunk_buffer</span><span class="p">,</span> <span class="o">&</span><span class="n">n_chunks</span><span class="p">);</span> <span class="k">for</span> <span class="p">(</span><span class="n">gsize</span> <span class="n">i</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span> <span class="n">i</span> <span class="o"><</span> <span class="n">n_chunks</span><span class="p">;</span> <span class="n">i</span><span class="o">++</span><span class="p">)</span> <span class="p">{</span> <span class="c1">// Do something with each chunk here, and then free them, since</span> <span class="c1">// g_ptr_array_steal() transfers ownership of all the elements and the</span> <span class="c1">// array to the caller.</span> <span class="err">…</span> <span class="n">g_bytes_unref</span> <span class="p">(</span><span class="n">chunks</span><span class="p">[</span><span class="n">i</span><span class="p">]);</span> <span class="p">}</span> <span class="n">g_free</span> <span class="p">(</span><span class="n">chunks</span><span class="p">);</span> <span class="c1">// After calling g_ptr_array_steal(), the pointer array can be reused for the</span> <span class="c1">// next set of chunks.</span> <span class="n">g_assert</span> <span class="p">(</span><span class="n">chunk_buffer</span><span class="o">-></span><span class="n">len</span> <span class="o">==</span> <span class="mi">0</span><span class="p">);</span></pre></td> </tr> </tbody> </table> </div> <p></p> <div class="refsect3"> <a name="g-ptr-array-steal.parameters"></a><h4>Parameters</h4> <div class="informaltable"><table class="informaltable" width="100%" border="0"> <colgroup> <col width="150px" class="parameters_name"> <col class="parameters_description"> <col width="200px" class="parameters_annotations"> </colgroup> <tbody> <tr> <td class="parameter_name"><p>array</p></td> <td class="parameter_description"><p>a <a class="link" href="glib-Pointer-Arrays.html#GPtrArray" title="struct GPtrArray"><span class="type">GPtrArray</span></a>.</p></td> <td class="parameter_annotations"> </td> </tr> <tr> <td class="parameter_name"><p>len</p></td> <td class="parameter_description"><p>pointer to retrieve the number of elements of the original array. </p></td> <td class="parameter_annotations"><span class="annotation">[<acronym title="NULL may be passed instead of a pointer to a location."><span class="acronym">optional</span></acronym>][<acronym title="Out parameter, where caller must allocate storage."><span class="acronym">out caller-allocates</span></acronym>]</span></td> </tr> </tbody> </table></div> </div> <div class="refsect3"> <a name="g-ptr-array-steal.returns"></a><h4>Returns</h4> <p>the element data, which should be freed using <a class="link" href="glib-Memory-Allocation.html#g-free" title="g_free ()"><code class="function">g_free()</code></a>. </p> <p><span class="annotation">[<acronym title="Free data after the code is done."><span class="acronym">transfer full</span></acronym>]</span></p> </div> <p class="since">Since: <a class="link" href="api-index-2-64.html#api-index-2.64">2.64</a></p> </div> <hr> <div class="refsect2"> <a name="g-ptr-array-sized-new"></a><h3>g_ptr_array_sized_new ()</h3> <pre class="programlisting"><a class="link" href="glib-Pointer-Arrays.html#GPtrArray" title="struct GPtrArray"><span class="returnvalue">GPtrArray</span></a> * g_ptr_array_sized_new (<em class="parameter"><code><a class="link" href="glib-Basic-Types.html#guint" title="guint"><span class="type">guint</span></a> reserved_size</code></em>);</pre> <p>Creates a new <a class="link" href="glib-Pointer-Arrays.html#GPtrArray" title="struct GPtrArray"><span class="type">GPtrArray</span></a> with <em class="parameter"><code>reserved_size</code></em> pointers preallocated and a reference count of 1. This avoids frequent reallocation, if you are going to add many pointers to the array. Note however that the size of the array is still 0.</p> <div class="refsect3"> <a name="g-ptr-array-sized-new.parameters"></a><h4>Parameters</h4> <div class="informaltable"><table class="informaltable" width="100%" border="0"> <colgroup> <col width="150px" class="parameters_name"> <col class="parameters_description"> <col width="200px" class="parameters_annotations"> </colgroup> <tbody><tr> <td class="parameter_name"><p>reserved_size</p></td> <td class="parameter_description"><p>number of pointers preallocated</p></td> <td class="parameter_annotations"> </td> </tr></tbody> </table></div> </div> <div class="refsect3"> <a name="g-ptr-array-sized-new.returns"></a><h4>Returns</h4> <p> the new <a class="link" href="glib-Pointer-Arrays.html#GPtrArray" title="struct GPtrArray"><span class="type">GPtrArray</span></a></p> </div> </div> <hr> <div class="refsect2"> <a name="g-ptr-array-new-with-free-func"></a><h3>g_ptr_array_new_with_free_func ()</h3> <pre class="programlisting"><a class="link" href="glib-Pointer-Arrays.html#GPtrArray" title="struct GPtrArray"><span class="returnvalue">GPtrArray</span></a> * g_ptr_array_new_with_free_func (<em class="parameter"><code><a class="link" href="glib-Datasets.html#GDestroyNotify" title="GDestroyNotify ()"><span class="type">GDestroyNotify</span></a> element_free_func</code></em>);</pre> <p>Creates a new <a class="link" href="glib-Pointer-Arrays.html#GPtrArray" title="struct GPtrArray"><span class="type">GPtrArray</span></a> with a reference count of 1 and use <em class="parameter"><code>element_free_func</code></em> for freeing each element when the array is destroyed either via <a class="link" href="glib-Pointer-Arrays.html#g-ptr-array-unref" title="g_ptr_array_unref ()"><code class="function">g_ptr_array_unref()</code></a>, when <a class="link" href="glib-Pointer-Arrays.html#g-ptr-array-free" title="g_ptr_array_free ()"><code class="function">g_ptr_array_free()</code></a> is called with <em class="parameter"><code>free_segment</code></em> set to <a class="link" href="glib-Standard-Macros.html#TRUE:CAPS" title="TRUE"><code class="literal">TRUE</code></a> or when removing elements.</p> <div class="refsect3"> <a name="g-ptr-array-new-with-free-func.parameters"></a><h4>Parameters</h4> <div class="informaltable"><table class="informaltable" width="100%" border="0"> <colgroup> <col width="150px" class="parameters_name"> <col class="parameters_description"> <col width="200px" class="parameters_annotations"> </colgroup> <tbody><tr> <td class="parameter_name"><p>element_free_func</p></td> <td class="parameter_description"><p>A function to free elements with destroy <em class="parameter"><code>array</code></em> or <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a>. </p></td> <td class="parameter_annotations"><span class="annotation">[<acronym title="NULL may be passed as the value in, out, in-out; or as a return value."><span class="acronym">nullable</span></acronym>]</span></td> </tr></tbody> </table></div> </div> <div class="refsect3"> <a name="g-ptr-array-new-with-free-func.returns"></a><h4>Returns</h4> <p> A new <a class="link" href="glib-Pointer-Arrays.html#GPtrArray" title="struct GPtrArray"><span class="type">GPtrArray</span></a></p> </div> <p class="since">Since: <a class="link" href="api-index-2-22.html#api-index-2.22">2.22</a></p> </div> <hr> <div class="refsect2"> <a name="g-ptr-array-copy"></a><h3>g_ptr_array_copy ()</h3> <pre class="programlisting"><a class="link" href="glib-Pointer-Arrays.html#GPtrArray" title="struct GPtrArray"><span class="returnvalue">GPtrArray</span></a> * g_ptr_array_copy (<em class="parameter"><code><a class="link" href="glib-Pointer-Arrays.html#GPtrArray" title="struct GPtrArray"><span class="type">GPtrArray</span></a> *array</code></em>, <em class="parameter"><code><a class="link" href="glib-N-ary-Trees.html#GCopyFunc" title="GCopyFunc ()"><span class="type">GCopyFunc</span></a> func</code></em>, <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gpointer" title="gpointer"><span class="type">gpointer</span></a> user_data</code></em>);</pre> <p>Makes a full (deep) copy of a <a class="link" href="glib-Pointer-Arrays.html#GPtrArray" title="struct GPtrArray"><span class="type">GPtrArray</span></a>.</p> <p><em class="parameter"><code>func</code></em> , as a <a class="link" href="glib-N-ary-Trees.html#GCopyFunc" title="GCopyFunc ()"><span class="type">GCopyFunc</span></a>, takes two arguments, the data to be copied and a <em class="parameter"><code>user_data</code></em> pointer. On common processor architectures, it's safe to pass <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a> as <em class="parameter"><code>user_data</code></em> if the copy function takes only one argument. You may get compiler warnings from this though if compiling with GCC’s <code class="literal">-Wcast-function-type</code> warning.</p> <p>If <em class="parameter"><code>func</code></em> is <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a>, then only the pointers (and not what they are pointing to) are copied to the new <a class="link" href="glib-Pointer-Arrays.html#GPtrArray" title="struct GPtrArray"><span class="type">GPtrArray</span></a>.</p> <p>The copy of <em class="parameter"><code>array</code></em> will have the same <a class="link" href="glib-Datasets.html#GDestroyNotify" title="GDestroyNotify ()"><span class="type">GDestroyNotify</span></a> for its elements as <em class="parameter"><code>array</code></em> .</p> <div class="refsect3"> <a name="g-ptr-array-copy.parameters"></a><h4>Parameters</h4> <div class="informaltable"><table class="informaltable" width="100%" border="0"> <colgroup> <col width="150px" class="parameters_name"> <col class="parameters_description"> <col width="200px" class="parameters_annotations"> </colgroup> <tbody> <tr> <td class="parameter_name"><p>array</p></td> <td class="parameter_description"><p><a class="link" href="glib-Pointer-Arrays.html#GPtrArray" title="struct GPtrArray"><span class="type">GPtrArray</span></a> to duplicate</p></td> <td class="parameter_annotations"> </td> </tr> <tr> <td class="parameter_name"><p>func</p></td> <td class="parameter_description"><p>a copy function used to copy every element in the array. </p></td> <td class="parameter_annotations"><span class="annotation">[<acronym title="NULL may be passed as the value in, out, in-out; or as a return value."><span class="acronym">nullable</span></acronym>]</span></td> </tr> <tr> <td class="parameter_name"><p>user_data</p></td> <td class="parameter_description"><p>user data passed to the copy function <em class="parameter"><code>func</code></em> , or <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a></p></td> <td class="parameter_annotations"> </td> </tr> </tbody> </table></div> </div> <div class="refsect3"> <a name="g-ptr-array-copy.returns"></a><h4>Returns</h4> <p>a deep copy of the initial <a class="link" href="glib-Pointer-Arrays.html#GPtrArray" title="struct GPtrArray"><span class="type">GPtrArray</span></a>. </p> <p><span class="annotation">[<acronym title="Free data after the code is done."><span class="acronym">transfer full</span></acronym>]</span></p> </div> <p class="since">Since: <a class="link" href="api-index-2-62.html#api-index-2.62">2.62</a></p> </div> <hr> <div class="refsect2"> <a name="g-ptr-array-new-full"></a><h3>g_ptr_array_new_full ()</h3> <pre class="programlisting"><a class="link" href="glib-Pointer-Arrays.html#GPtrArray" title="struct GPtrArray"><span class="returnvalue">GPtrArray</span></a> * g_ptr_array_new_full (<em class="parameter"><code><a class="link" href="glib-Basic-Types.html#guint" title="guint"><span class="type">guint</span></a> reserved_size</code></em>, <em class="parameter"><code><a class="link" href="glib-Datasets.html#GDestroyNotify" title="GDestroyNotify ()"><span class="type">GDestroyNotify</span></a> element_free_func</code></em>);</pre> <p>Creates a new <a class="link" href="glib-Pointer-Arrays.html#GPtrArray" title="struct GPtrArray"><span class="type">GPtrArray</span></a> with <em class="parameter"><code>reserved_size</code></em> pointers preallocated and a reference count of 1. This avoids frequent reallocation, if you are going to add many pointers to the array. Note however that the size of the array is still 0. It also set <em class="parameter"><code>element_free_func</code></em> for freeing each element when the array is destroyed either via <a class="link" href="glib-Pointer-Arrays.html#g-ptr-array-unref" title="g_ptr_array_unref ()"><code class="function">g_ptr_array_unref()</code></a>, when <a class="link" href="glib-Pointer-Arrays.html#g-ptr-array-free" title="g_ptr_array_free ()"><code class="function">g_ptr_array_free()</code></a> is called with <em class="parameter"><code>free_segment</code></em> set to <a class="link" href="glib-Standard-Macros.html#TRUE:CAPS" title="TRUE"><code class="literal">TRUE</code></a> or when removing elements.</p> <div class="refsect3"> <a name="g-ptr-array-new-full.parameters"></a><h4>Parameters</h4> <div class="informaltable"><table class="informaltable" width="100%" border="0"> <colgroup> <col width="150px" class="parameters_name"> <col class="parameters_description"> <col width="200px" class="parameters_annotations"> </colgroup> <tbody> <tr> <td class="parameter_name"><p>reserved_size</p></td> <td class="parameter_description"><p>number of pointers preallocated</p></td> <td class="parameter_annotations"> </td> </tr> <tr> <td class="parameter_name"><p>element_free_func</p></td> <td class="parameter_description"><p>A function to free elements with destroy <em class="parameter"><code>array</code></em> or <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a>. </p></td> <td class="parameter_annotations"><span class="annotation">[<acronym title="NULL may be passed as the value in, out, in-out; or as a return value."><span class="acronym">nullable</span></acronym>]</span></td> </tr> </tbody> </table></div> </div> <div class="refsect3"> <a name="g-ptr-array-new-full.returns"></a><h4>Returns</h4> <p> A new <a class="link" href="glib-Pointer-Arrays.html#GPtrArray" title="struct GPtrArray"><span class="type">GPtrArray</span></a></p> </div> <p class="since">Since: <a class="link" href="api-index-2-30.html#api-index-2.30">2.30</a></p> </div> <hr> <div class="refsect2"> <a name="g-ptr-array-set-free-func"></a><h3>g_ptr_array_set_free_func ()</h3> <pre class="programlisting"><span class="returnvalue">void</span> g_ptr_array_set_free_func (<em class="parameter"><code><a class="link" href="glib-Pointer-Arrays.html#GPtrArray" title="struct GPtrArray"><span class="type">GPtrArray</span></a> *array</code></em>, <em class="parameter"><code><a class="link" href="glib-Datasets.html#GDestroyNotify" title="GDestroyNotify ()"><span class="type">GDestroyNotify</span></a> element_free_func</code></em>);</pre> <p>Sets a function for freeing each element when <em class="parameter"><code>array</code></em> is destroyed either via <a class="link" href="glib-Pointer-Arrays.html#g-ptr-array-unref" title="g_ptr_array_unref ()"><code class="function">g_ptr_array_unref()</code></a>, when <a class="link" href="glib-Pointer-Arrays.html#g-ptr-array-free" title="g_ptr_array_free ()"><code class="function">g_ptr_array_free()</code></a> is called with <em class="parameter"><code>free_segment</code></em> set to <a class="link" href="glib-Standard-Macros.html#TRUE:CAPS" title="TRUE"><code class="literal">TRUE</code></a> or when removing elements.</p> <div class="refsect3"> <a name="g-ptr-array-set-free-func.parameters"></a><h4>Parameters</h4> <div class="informaltable"><table class="informaltable" width="100%" border="0"> <colgroup> <col width="150px" class="parameters_name"> <col class="parameters_description"> <col width="200px" class="parameters_annotations"> </colgroup> <tbody> <tr> <td class="parameter_name"><p>array</p></td> <td class="parameter_description"><p>A <a class="link" href="glib-Pointer-Arrays.html#GPtrArray" title="struct GPtrArray"><span class="type">GPtrArray</span></a></p></td> <td class="parameter_annotations"> </td> </tr> <tr> <td class="parameter_name"><p>element_free_func</p></td> <td class="parameter_description"><p>A function to free elements with destroy <em class="parameter"><code>array</code></em> or <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a>. </p></td> <td class="parameter_annotations"><span class="annotation">[<acronym title="NULL may be passed as the value in, out, in-out; or as a return value."><span class="acronym">nullable</span></acronym>]</span></td> </tr> </tbody> </table></div> </div> <p class="since">Since: <a class="link" href="api-index-2-22.html#api-index-2.22">2.22</a></p> </div> <hr> <div class="refsect2"> <a name="g-ptr-array-ref"></a><h3>g_ptr_array_ref ()</h3> <pre class="programlisting"><a class="link" href="glib-Pointer-Arrays.html#GPtrArray" title="struct GPtrArray"><span class="returnvalue">GPtrArray</span></a> * g_ptr_array_ref (<em class="parameter"><code><a class="link" href="glib-Pointer-Arrays.html#GPtrArray" title="struct GPtrArray"><span class="type">GPtrArray</span></a> *array</code></em>);</pre> <p>Atomically increments the reference count of <em class="parameter"><code>array</code></em> by one. This function is thread-safe and may be called from any thread.</p> <div class="refsect3"> <a name="g-ptr-array-ref.parameters"></a><h4>Parameters</h4> <div class="informaltable"><table class="informaltable" width="100%" border="0"> <colgroup> <col width="150px" class="parameters_name"> <col class="parameters_description"> <col width="200px" class="parameters_annotations"> </colgroup> <tbody><tr> <td class="parameter_name"><p>array</p></td> <td class="parameter_description"><p>a <a class="link" href="glib-Pointer-Arrays.html#GPtrArray" title="struct GPtrArray"><span class="type">GPtrArray</span></a></p></td> <td class="parameter_annotations"> </td> </tr></tbody> </table></div> </div> <div class="refsect3"> <a name="g-ptr-array-ref.returns"></a><h4>Returns</h4> <p> The passed in <a class="link" href="glib-Pointer-Arrays.html#GPtrArray" title="struct GPtrArray"><span class="type">GPtrArray</span></a></p> </div> <p class="since">Since: <a class="link" href="api-index-2-22.html#api-index-2.22">2.22</a></p> </div> <hr> <div class="refsect2"> <a name="g-ptr-array-unref"></a><h3>g_ptr_array_unref ()</h3> <pre class="programlisting"><span class="returnvalue">void</span> g_ptr_array_unref (<em class="parameter"><code><a class="link" href="glib-Pointer-Arrays.html#GPtrArray" title="struct GPtrArray"><span class="type">GPtrArray</span></a> *array</code></em>);</pre> <p>Atomically decrements the reference count of <em class="parameter"><code>array</code></em> by one. If the reference count drops to 0, the effect is the same as calling <a class="link" href="glib-Pointer-Arrays.html#g-ptr-array-free" title="g_ptr_array_free ()"><code class="function">g_ptr_array_free()</code></a> with <em class="parameter"><code>free_segment</code></em> set to <a class="link" href="glib-Standard-Macros.html#TRUE:CAPS" title="TRUE"><code class="literal">TRUE</code></a>. This function is thread-safe and may be called from any thread.</p> <div class="refsect3"> <a name="g-ptr-array-unref.parameters"></a><h4>Parameters</h4> <div class="informaltable"><table class="informaltable" width="100%" border="0"> <colgroup> <col width="150px" class="parameters_name"> <col class="parameters_description"> <col width="200px" class="parameters_annotations"> </colgroup> <tbody><tr> <td class="parameter_name"><p>array</p></td> <td class="parameter_description"><p>A <a class="link" href="glib-Pointer-Arrays.html#GPtrArray" title="struct GPtrArray"><span class="type">GPtrArray</span></a></p></td> <td class="parameter_annotations"> </td> </tr></tbody> </table></div> </div> <p class="since">Since: <a class="link" href="api-index-2-22.html#api-index-2.22">2.22</a></p> </div> <hr> <div class="refsect2"> <a name="g-ptr-array-add"></a><h3>g_ptr_array_add ()</h3> <pre class="programlisting"><span class="returnvalue">void</span> g_ptr_array_add (<em class="parameter"><code><a class="link" href="glib-Pointer-Arrays.html#GPtrArray" title="struct GPtrArray"><span class="type">GPtrArray</span></a> *array</code></em>, <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gpointer" title="gpointer"><span class="type">gpointer</span></a> data</code></em>);</pre> <p>Adds a pointer to the end of the pointer array. The array will grow in size automatically if necessary.</p> <div class="refsect3"> <a name="g-ptr-array-add.parameters"></a><h4>Parameters</h4> <div class="informaltable"><table class="informaltable" width="100%" border="0"> <colgroup> <col width="150px" class="parameters_name"> <col class="parameters_description"> <col width="200px" class="parameters_annotations"> </colgroup> <tbody> <tr> <td class="parameter_name"><p>array</p></td> <td class="parameter_description"><p>a <a class="link" href="glib-Pointer-Arrays.html#GPtrArray" title="struct GPtrArray"><span class="type">GPtrArray</span></a></p></td> <td class="parameter_annotations"> </td> </tr> <tr> <td class="parameter_name"><p>data</p></td> <td class="parameter_description"><p>the pointer to add</p></td> <td class="parameter_annotations"> </td> </tr> </tbody> </table></div> </div> </div> <hr> <div class="refsect2"> <a name="g-ptr-array-extend"></a><h3>g_ptr_array_extend ()</h3> <pre class="programlisting"><span class="returnvalue">void</span> g_ptr_array_extend (<em class="parameter"><code><a class="link" href="glib-Pointer-Arrays.html#GPtrArray" title="struct GPtrArray"><span class="type">GPtrArray</span></a> *array_to_extend</code></em>, <em class="parameter"><code><a class="link" href="glib-Pointer-Arrays.html#GPtrArray" title="struct GPtrArray"><span class="type">GPtrArray</span></a> *array</code></em>, <em class="parameter"><code><a class="link" href="glib-N-ary-Trees.html#GCopyFunc" title="GCopyFunc ()"><span class="type">GCopyFunc</span></a> func</code></em>, <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gpointer" title="gpointer"><span class="type">gpointer</span></a> user_data</code></em>);</pre> <p>Adds all pointers of <em class="parameter"><code>array</code></em> to the end of the array <em class="parameter"><code>array_to_extend</code></em> . The array will grow in size automatically if needed. <em class="parameter"><code>array_to_extend</code></em> is modified in-place.</p> <p><em class="parameter"><code>func</code></em> , as a <a class="link" href="glib-N-ary-Trees.html#GCopyFunc" title="GCopyFunc ()"><span class="type">GCopyFunc</span></a>, takes two arguments, the data to be copied and a <em class="parameter"><code>user_data</code></em> pointer. On common processor architectures, it's safe to pass <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a> as <em class="parameter"><code>user_data</code></em> if the copy function takes only one argument. You may get compiler warnings from this though if compiling with GCC’s <code class="literal">-Wcast-function-type</code> warning.</p> <p>If <em class="parameter"><code>func</code></em> is <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a>, then only the pointers (and not what they are pointing to) are copied to the new <a class="link" href="glib-Pointer-Arrays.html#GPtrArray" title="struct GPtrArray"><span class="type">GPtrArray</span></a>.</p> <div class="refsect3"> <a name="g-ptr-array-extend.parameters"></a><h4>Parameters</h4> <div class="informaltable"><table class="informaltable" width="100%" border="0"> <colgroup> <col width="150px" class="parameters_name"> <col class="parameters_description"> <col width="200px" class="parameters_annotations"> </colgroup> <tbody> <tr> <td class="parameter_name"><p>array_to_extend</p></td> <td class="parameter_description"><p>a <a class="link" href="glib-Pointer-Arrays.html#GPtrArray" title="struct GPtrArray"><span class="type">GPtrArray</span></a>.</p></td> <td class="parameter_annotations"> </td> </tr> <tr> <td class="parameter_name"><p>array</p></td> <td class="parameter_description"><p>a <a class="link" href="glib-Pointer-Arrays.html#GPtrArray" title="struct GPtrArray"><span class="type">GPtrArray</span></a> to add to the end of <em class="parameter"><code>array_to_extend</code></em> . </p></td> <td class="parameter_annotations"><span class="annotation">[<acronym title="Don't free data after the code is done."><span class="acronym">transfer none</span></acronym>]</span></td> </tr> <tr> <td class="parameter_name"><p>func</p></td> <td class="parameter_description"><p>a copy function used to copy every element in the array. </p></td> <td class="parameter_annotations"><span class="annotation">[<acronym title="NULL may be passed as the value in, out, in-out; or as a return value."><span class="acronym">nullable</span></acronym>]</span></td> </tr> <tr> <td class="parameter_name"><p>user_data</p></td> <td class="parameter_description"><p>user data passed to the copy function <em class="parameter"><code>func</code></em> , or <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a></p></td> <td class="parameter_annotations"> </td> </tr> </tbody> </table></div> </div> <p class="since">Since: <a class="link" href="api-index-2-62.html#api-index-2.62">2.62</a></p> </div> <hr> <div class="refsect2"> <a name="g-ptr-array-extend-and-steal"></a><h3>g_ptr_array_extend_and_steal ()</h3> <pre class="programlisting"><span class="returnvalue">void</span> g_ptr_array_extend_and_steal (<em class="parameter"><code><a class="link" href="glib-Pointer-Arrays.html#GPtrArray" title="struct GPtrArray"><span class="type">GPtrArray</span></a> *array_to_extend</code></em>, <em class="parameter"><code><a class="link" href="glib-Pointer-Arrays.html#GPtrArray" title="struct GPtrArray"><span class="type">GPtrArray</span></a> *array</code></em>);</pre> <p>Adds all the pointers in <em class="parameter"><code>array</code></em> to the end of <em class="parameter"><code>array_to_extend</code></em> , transferring ownership of each element from <em class="parameter"><code>array</code></em> to <em class="parameter"><code>array_to_extend</code></em> and modifying <em class="parameter"><code>array_to_extend</code></em> in-place. <em class="parameter"><code>array</code></em> is then freed.</p> <p>As with <a class="link" href="glib-Pointer-Arrays.html#g-ptr-array-free" title="g_ptr_array_free ()"><code class="function">g_ptr_array_free()</code></a>, <em class="parameter"><code>array</code></em> will be destroyed if its reference count is 1. If its reference count is higher, it will be decremented and the length of <em class="parameter"><code>array</code></em> set to zero.</p> <div class="refsect3"> <a name="g-ptr-array-extend-and-steal.parameters"></a><h4>Parameters</h4> <div class="informaltable"><table class="informaltable" width="100%" border="0"> <colgroup> <col width="150px" class="parameters_name"> <col class="parameters_description"> <col width="200px" class="parameters_annotations"> </colgroup> <tbody> <tr> <td class="parameter_name"><p>array_to_extend</p></td> <td class="parameter_description"><p>a <a class="link" href="glib-Pointer-Arrays.html#GPtrArray" title="struct GPtrArray"><span class="type">GPtrArray</span></a>. </p></td> <td class="parameter_annotations"><span class="annotation">[<acronym title="Don't free data after the code is done."><span class="acronym">transfer none</span></acronym>]</span></td> </tr> <tr> <td class="parameter_name"><p>array</p></td> <td class="parameter_description"><p>a <a class="link" href="glib-Pointer-Arrays.html#GPtrArray" title="struct GPtrArray"><span class="type">GPtrArray</span></a> to add to the end of <em class="parameter"><code>array_to_extend</code></em> . </p></td> <td class="parameter_annotations"><span class="annotation">[<acronym title="Free data container after the code is done."><span class="acronym">transfer container</span></acronym>]</span></td> </tr> </tbody> </table></div> </div> <p class="since">Since: <a class="link" href="api-index-2-62.html#api-index-2.62">2.62</a></p> </div> <hr> <div class="refsect2"> <a name="g-ptr-array-insert"></a><h3>g_ptr_array_insert ()</h3> <pre class="programlisting"><span class="returnvalue">void</span> g_ptr_array_insert (<em class="parameter"><code><a class="link" href="glib-Pointer-Arrays.html#GPtrArray" title="struct GPtrArray"><span class="type">GPtrArray</span></a> *array</code></em>, <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gint" title="gint"><span class="type">gint</span></a> index_</code></em>, <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gpointer" title="gpointer"><span class="type">gpointer</span></a> data</code></em>);</pre> <p>Inserts an element into the pointer array at the given index. The array will grow in size automatically if necessary.</p> <div class="refsect3"> <a name="g-ptr-array-insert.parameters"></a><h4>Parameters</h4> <div class="informaltable"><table class="informaltable" width="100%" border="0"> <colgroup> <col width="150px" class="parameters_name"> <col class="parameters_description"> <col width="200px" class="parameters_annotations"> </colgroup> <tbody> <tr> <td class="parameter_name"><p>array</p></td> <td class="parameter_description"><p>a <a class="link" href="glib-Pointer-Arrays.html#GPtrArray" title="struct GPtrArray"><span class="type">GPtrArray</span></a></p></td> <td class="parameter_annotations"> </td> </tr> <tr> <td class="parameter_name"><p>index_</p></td> <td class="parameter_description"><p>the index to place the new element at, or -1 to append</p></td> <td class="parameter_annotations"> </td> </tr> <tr> <td class="parameter_name"><p>data</p></td> <td class="parameter_description"><p>the pointer to add.</p></td> <td class="parameter_annotations"> </td> </tr> </tbody> </table></div> </div> <p class="since">Since: <a class="link" href="api-index-2-40.html#api-index-2.40">2.40</a></p> </div> <hr> <div class="refsect2"> <a name="g-ptr-array-remove"></a><h3>g_ptr_array_remove ()</h3> <pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gboolean" title="gboolean"><span class="returnvalue">gboolean</span></a> g_ptr_array_remove (<em class="parameter"><code><a class="link" href="glib-Pointer-Arrays.html#GPtrArray" title="struct GPtrArray"><span class="type">GPtrArray</span></a> *array</code></em>, <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gpointer" title="gpointer"><span class="type">gpointer</span></a> data</code></em>);</pre> <p>Removes the first occurrence of the given pointer from the pointer array. The following elements are moved down one place. If <em class="parameter"><code>array</code></em> has a non-<a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a> <a class="link" href="glib-Datasets.html#GDestroyNotify" title="GDestroyNotify ()"><span class="type">GDestroyNotify</span></a> function it is called for the removed element.</p> <p>It returns <a class="link" href="glib-Standard-Macros.html#TRUE:CAPS" title="TRUE"><code class="literal">TRUE</code></a> if the pointer was removed, or <a class="link" href="glib-Standard-Macros.html#FALSE:CAPS" title="FALSE"><code class="literal">FALSE</code></a> if the pointer was not found.</p> <div class="refsect3"> <a name="g-ptr-array-remove.parameters"></a><h4>Parameters</h4> <div class="informaltable"><table class="informaltable" width="100%" border="0"> <colgroup> <col width="150px" class="parameters_name"> <col class="parameters_description"> <col width="200px" class="parameters_annotations"> </colgroup> <tbody> <tr> <td class="parameter_name"><p>array</p></td> <td class="parameter_description"><p>a <a class="link" href="glib-Pointer-Arrays.html#GPtrArray" title="struct GPtrArray"><span class="type">GPtrArray</span></a></p></td> <td class="parameter_annotations"> </td> </tr> <tr> <td class="parameter_name"><p>data</p></td> <td class="parameter_description"><p>the pointer to remove</p></td> <td class="parameter_annotations"> </td> </tr> </tbody> </table></div> </div> <div class="refsect3"> <a name="g-ptr-array-remove.returns"></a><h4>Returns</h4> <p> <a class="link" href="glib-Standard-Macros.html#TRUE:CAPS" title="TRUE"><code class="literal">TRUE</code></a> if the pointer is removed, <a class="link" href="glib-Standard-Macros.html#FALSE:CAPS" title="FALSE"><code class="literal">FALSE</code></a> if the pointer is not found in the array</p> </div> </div> <hr> <div class="refsect2"> <a name="g-ptr-array-remove-index"></a><h3>g_ptr_array_remove_index ()</h3> <pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gpointer" title="gpointer"><span class="returnvalue">gpointer</span></a> g_ptr_array_remove_index (<em class="parameter"><code><a class="link" href="glib-Pointer-Arrays.html#GPtrArray" title="struct GPtrArray"><span class="type">GPtrArray</span></a> *array</code></em>, <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#guint" title="guint"><span class="type">guint</span></a> index_</code></em>);</pre> <p>Removes the pointer at the given index from the pointer array. The following elements are moved down one place. If <em class="parameter"><code>array</code></em> has a non-<a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a> <a class="link" href="glib-Datasets.html#GDestroyNotify" title="GDestroyNotify ()"><span class="type">GDestroyNotify</span></a> function it is called for the removed element. If so, the return value from this function will potentially point to freed memory (depending on the <a class="link" href="glib-Datasets.html#GDestroyNotify" title="GDestroyNotify ()"><span class="type">GDestroyNotify</span></a> implementation).</p> <div class="refsect3"> <a name="g-ptr-array-remove-index.parameters"></a><h4>Parameters</h4> <div class="informaltable"><table class="informaltable" width="100%" border="0"> <colgroup> <col width="150px" class="parameters_name"> <col class="parameters_description"> <col width="200px" class="parameters_annotations"> </colgroup> <tbody> <tr> <td class="parameter_name"><p>array</p></td> <td class="parameter_description"><p>a <a class="link" href="glib-Pointer-Arrays.html#GPtrArray" title="struct GPtrArray"><span class="type">GPtrArray</span></a></p></td> <td class="parameter_annotations"> </td> </tr> <tr> <td class="parameter_name"><p>index_</p></td> <td class="parameter_description"><p>the index of the pointer to remove</p></td> <td class="parameter_annotations"> </td> </tr> </tbody> </table></div> </div> <div class="refsect3"> <a name="g-ptr-array-remove-index.returns"></a><h4>Returns</h4> <p>the pointer which was removed. </p> <p><span class="annotation">[<acronym title="NULL may be passed as the value in, out, in-out; or as a return value."><span class="acronym">nullable</span></acronym>]</span></p> </div> </div> <hr> <div class="refsect2"> <a name="g-ptr-array-remove-fast"></a><h3>g_ptr_array_remove_fast ()</h3> <pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gboolean" title="gboolean"><span class="returnvalue">gboolean</span></a> g_ptr_array_remove_fast (<em class="parameter"><code><a class="link" href="glib-Pointer-Arrays.html#GPtrArray" title="struct GPtrArray"><span class="type">GPtrArray</span></a> *array</code></em>, <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gpointer" title="gpointer"><span class="type">gpointer</span></a> data</code></em>);</pre> <p>Removes the first occurrence of the given pointer from the pointer array. The last element in the array is used to fill in the space, so this function does not preserve the order of the array. But it is faster than <a class="link" href="glib-Pointer-Arrays.html#g-ptr-array-remove" title="g_ptr_array_remove ()"><code class="function">g_ptr_array_remove()</code></a>. If <em class="parameter"><code>array</code></em> has a non-<a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a> <a class="link" href="glib-Datasets.html#GDestroyNotify" title="GDestroyNotify ()"><span class="type">GDestroyNotify</span></a> function it is called for the removed element.</p> <p>It returns <a class="link" href="glib-Standard-Macros.html#TRUE:CAPS" title="TRUE"><code class="literal">TRUE</code></a> if the pointer was removed, or <a class="link" href="glib-Standard-Macros.html#FALSE:CAPS" title="FALSE"><code class="literal">FALSE</code></a> if the pointer was not found.</p> <div class="refsect3"> <a name="g-ptr-array-remove-fast.parameters"></a><h4>Parameters</h4> <div class="informaltable"><table class="informaltable" width="100%" border="0"> <colgroup> <col width="150px" class="parameters_name"> <col class="parameters_description"> <col width="200px" class="parameters_annotations"> </colgroup> <tbody> <tr> <td class="parameter_name"><p>array</p></td> <td class="parameter_description"><p>a <a class="link" href="glib-Pointer-Arrays.html#GPtrArray" title="struct GPtrArray"><span class="type">GPtrArray</span></a></p></td> <td class="parameter_annotations"> </td> </tr> <tr> <td class="parameter_name"><p>data</p></td> <td class="parameter_description"><p>the pointer to remove</p></td> <td class="parameter_annotations"> </td> </tr> </tbody> </table></div> </div> <div class="refsect3"> <a name="g-ptr-array-remove-fast.returns"></a><h4>Returns</h4> <p> <a class="link" href="glib-Standard-Macros.html#TRUE:CAPS" title="TRUE"><code class="literal">TRUE</code></a> if the pointer was found in the array</p> </div> </div> <hr> <div class="refsect2"> <a name="g-ptr-array-remove-index-fast"></a><h3>g_ptr_array_remove_index_fast ()</h3> <pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gpointer" title="gpointer"><span class="returnvalue">gpointer</span></a> g_ptr_array_remove_index_fast (<em class="parameter"><code><a class="link" href="glib-Pointer-Arrays.html#GPtrArray" title="struct GPtrArray"><span class="type">GPtrArray</span></a> *array</code></em>, <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#guint" title="guint"><span class="type">guint</span></a> index_</code></em>);</pre> <p>Removes the pointer at the given index from the pointer array. The last element in the array is used to fill in the space, so this function does not preserve the order of the array. But it is faster than <a class="link" href="glib-Pointer-Arrays.html#g-ptr-array-remove-index" title="g_ptr_array_remove_index ()"><code class="function">g_ptr_array_remove_index()</code></a>. If <em class="parameter"><code>array</code></em> has a non-<a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a> <a class="link" href="glib-Datasets.html#GDestroyNotify" title="GDestroyNotify ()"><span class="type">GDestroyNotify</span></a> function it is called for the removed element. If so, the return value from this function will potentially point to freed memory (depending on the <a class="link" href="glib-Datasets.html#GDestroyNotify" title="GDestroyNotify ()"><span class="type">GDestroyNotify</span></a> implementation).</p> <div class="refsect3"> <a name="g-ptr-array-remove-index-fast.parameters"></a><h4>Parameters</h4> <div class="informaltable"><table class="informaltable" width="100%" border="0"> <colgroup> <col width="150px" class="parameters_name"> <col class="parameters_description"> <col width="200px" class="parameters_annotations"> </colgroup> <tbody> <tr> <td class="parameter_name"><p>array</p></td> <td class="parameter_description"><p>a <a class="link" href="glib-Pointer-Arrays.html#GPtrArray" title="struct GPtrArray"><span class="type">GPtrArray</span></a></p></td> <td class="parameter_annotations"> </td> </tr> <tr> <td class="parameter_name"><p>index_</p></td> <td class="parameter_description"><p>the index of the pointer to remove</p></td> <td class="parameter_annotations"> </td> </tr> </tbody> </table></div> </div> <div class="refsect3"> <a name="g-ptr-array-remove-index-fast.returns"></a><h4>Returns</h4> <p>the pointer which was removed. </p> <p><span class="annotation">[<acronym title="NULL may be passed as the value in, out, in-out; or as a return value."><span class="acronym">nullable</span></acronym>]</span></p> </div> </div> <hr> <div class="refsect2"> <a name="g-ptr-array-remove-range"></a><h3>g_ptr_array_remove_range ()</h3> <pre class="programlisting"><a class="link" href="glib-Pointer-Arrays.html#GPtrArray" title="struct GPtrArray"><span class="returnvalue">GPtrArray</span></a> * g_ptr_array_remove_range (<em class="parameter"><code><a class="link" href="glib-Pointer-Arrays.html#GPtrArray" title="struct GPtrArray"><span class="type">GPtrArray</span></a> *array</code></em>, <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#guint" title="guint"><span class="type">guint</span></a> index_</code></em>, <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#guint" title="guint"><span class="type">guint</span></a> length</code></em>);</pre> <p>Removes the given number of pointers starting at the given index from a <a class="link" href="glib-Pointer-Arrays.html#GPtrArray" title="struct GPtrArray"><span class="type">GPtrArray</span></a>. The following elements are moved to close the gap. If <em class="parameter"><code>array</code></em> has a non-<a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a> <a class="link" href="glib-Datasets.html#GDestroyNotify" title="GDestroyNotify ()"><span class="type">GDestroyNotify</span></a> function it is called for the removed elements.</p> <div class="refsect3"> <a name="g-ptr-array-remove-range.parameters"></a><h4>Parameters</h4> <div class="informaltable"><table class="informaltable" width="100%" border="0"> <colgroup> <col width="150px" class="parameters_name"> <col class="parameters_description"> <col width="200px" class="parameters_annotations"> </colgroup> <tbody> <tr> <td class="parameter_name"><p>array</p></td> <td class="parameter_description"><p>a <em class="parameter"><code>GPtrArray</code></em> </p></td> <td class="parameter_annotations"> </td> </tr> <tr> <td class="parameter_name"><p>index_</p></td> <td class="parameter_description"><p>the index of the first pointer to remove</p></td> <td class="parameter_annotations"> </td> </tr> <tr> <td class="parameter_name"><p>length</p></td> <td class="parameter_description"><p>the number of pointers to remove</p></td> <td class="parameter_annotations"> </td> </tr> </tbody> </table></div> </div> <div class="refsect3"> <a name="g-ptr-array-remove-range.returns"></a><h4>Returns</h4> <p> the <em class="parameter"><code>array</code></em> </p> </div> <p class="since">Since: <a class="link" href="api-index-2-4.html#api-index-2.4">2.4</a></p> </div> <hr> <div class="refsect2"> <a name="g-ptr-array-steal-index"></a><h3>g_ptr_array_steal_index ()</h3> <pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gpointer" title="gpointer"><span class="returnvalue">gpointer</span></a> g_ptr_array_steal_index (<em class="parameter"><code><a class="link" href="glib-Pointer-Arrays.html#GPtrArray" title="struct GPtrArray"><span class="type">GPtrArray</span></a> *array</code></em>, <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#guint" title="guint"><span class="type">guint</span></a> index_</code></em>);</pre> <p>Removes the pointer at the given index from the pointer array. The following elements are moved down one place. The <a class="link" href="glib-Datasets.html#GDestroyNotify" title="GDestroyNotify ()"><span class="type">GDestroyNotify</span></a> for <em class="parameter"><code>array</code></em> is *not* called on the removed element; ownership is transferred to the caller of this function.</p> <div class="refsect3"> <a name="g-ptr-array-steal-index.parameters"></a><h4>Parameters</h4> <div class="informaltable"><table class="informaltable" width="100%" border="0"> <colgroup> <col width="150px" class="parameters_name"> <col class="parameters_description"> <col width="200px" class="parameters_annotations"> </colgroup> <tbody> <tr> <td class="parameter_name"><p>array</p></td> <td class="parameter_description"><p>a <a class="link" href="glib-Pointer-Arrays.html#GPtrArray" title="struct GPtrArray"><span class="type">GPtrArray</span></a></p></td> <td class="parameter_annotations"> </td> </tr> <tr> <td class="parameter_name"><p>index_</p></td> <td class="parameter_description"><p>the index of the pointer to steal</p></td> <td class="parameter_annotations"> </td> </tr> </tbody> </table></div> </div> <div class="refsect3"> <a name="g-ptr-array-steal-index.returns"></a><h4>Returns</h4> <p>the pointer which was removed. </p> <p><span class="annotation">[<acronym title="Free data after the code is done."><span class="acronym">transfer full</span></acronym>][<acronym title="NULL may be passed as the value in, out, in-out; or as a return value."><span class="acronym">nullable</span></acronym>]</span></p> </div> <p class="since">Since: <a class="link" href="api-index-2-58.html#api-index-2.58">2.58</a></p> </div> <hr> <div class="refsect2"> <a name="g-ptr-array-steal-index-fast"></a><h3>g_ptr_array_steal_index_fast ()</h3> <pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gpointer" title="gpointer"><span class="returnvalue">gpointer</span></a> g_ptr_array_steal_index_fast (<em class="parameter"><code><a class="link" href="glib-Pointer-Arrays.html#GPtrArray" title="struct GPtrArray"><span class="type">GPtrArray</span></a> *array</code></em>, <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#guint" title="guint"><span class="type">guint</span></a> index_</code></em>);</pre> <p>Removes the pointer at the given index from the pointer array. The last element in the array is used to fill in the space, so this function does not preserve the order of the array. But it is faster than <a class="link" href="glib-Pointer-Arrays.html#g-ptr-array-steal-index" title="g_ptr_array_steal_index ()"><code class="function">g_ptr_array_steal_index()</code></a>. The <a class="link" href="glib-Datasets.html#GDestroyNotify" title="GDestroyNotify ()"><span class="type">GDestroyNotify</span></a> for <em class="parameter"><code>array</code></em> is *not* called on the removed element; ownership is transferred to the caller of this function.</p> <div class="refsect3"> <a name="g-ptr-array-steal-index-fast.parameters"></a><h4>Parameters</h4> <div class="informaltable"><table class="informaltable" width="100%" border="0"> <colgroup> <col width="150px" class="parameters_name"> <col class="parameters_description"> <col width="200px" class="parameters_annotations"> </colgroup> <tbody> <tr> <td class="parameter_name"><p>array</p></td> <td class="parameter_description"><p>a <a class="link" href="glib-Pointer-Arrays.html#GPtrArray" title="struct GPtrArray"><span class="type">GPtrArray</span></a></p></td> <td class="parameter_annotations"> </td> </tr> <tr> <td class="parameter_name"><p>index_</p></td> <td class="parameter_description"><p>the index of the pointer to steal</p></td> <td class="parameter_annotations"> </td> </tr> </tbody> </table></div> </div> <div class="refsect3"> <a name="g-ptr-array-steal-index-fast.returns"></a><h4>Returns</h4> <p>the pointer which was removed. </p> <p><span class="annotation">[<acronym title="Free data after the code is done."><span class="acronym">transfer full</span></acronym>][<acronym title="NULL may be passed as the value in, out, in-out; or as a return value."><span class="acronym">nullable</span></acronym>]</span></p> </div> <p class="since">Since: <a class="link" href="api-index-2-58.html#api-index-2.58">2.58</a></p> </div> <hr> <div class="refsect2"> <a name="g-ptr-array-sort"></a><h3>g_ptr_array_sort ()</h3> <pre class="programlisting"><span class="returnvalue">void</span> g_ptr_array_sort (<em class="parameter"><code><a class="link" href="glib-Pointer-Arrays.html#GPtrArray" title="struct GPtrArray"><span class="type">GPtrArray</span></a> *array</code></em>, <em class="parameter"><code><a class="link" href="glib-Doubly-Linked-Lists.html#GCompareFunc" title="GCompareFunc ()"><span class="type">GCompareFunc</span></a> compare_func</code></em>);</pre> <p>Sorts the array, using <em class="parameter"><code>compare_func</code></em> which should be a <code class="function">qsort()</code>-style comparison function (returns less than zero for first arg is less than second arg, zero for equal, greater than zero if irst arg is greater than second arg).</p> <p>Note that the comparison function for <a class="link" href="glib-Pointer-Arrays.html#g-ptr-array-sort" title="g_ptr_array_sort ()"><code class="function">g_ptr_array_sort()</code></a> doesn't take the pointers from the array as arguments, it takes pointers to the pointers in the array. Here is a full example of usage:</p> <div class="informalexample"> <table class="listing_frame" border="0" cellpadding="0" cellspacing="0"> <tbody> <tr> <td class="listing_lines" align="right"><pre>1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22</pre></td> <td class="listing_code"><pre class="programlisting"><span class="k">typedef</span> <span class="k">struct</span> <span class="p">{</span> <span class="n">gchar</span> <span class="o">*</span><span class="n">name</span><span class="p">;</span> <span class="n">gint</span> <span class="n">size</span><span class="p">;</span> <span class="p">}</span> <span class="n">FileListEntry</span><span class="p">;</span> <span class="k">static</span> <span class="n">gint</span> <span class="nf">sort_filelist</span> <span class="p">(</span><span class="n">gconstpointer</span> <span class="n">a</span><span class="p">,</span> <span class="n">gconstpointer</span> <span class="n">b</span><span class="p">)</span> <span class="p">{</span> <span class="k">const</span> <span class="n">FileListEntry</span> <span class="o">*</span><span class="n">entry1</span> <span class="o">=</span> <span class="o">*</span><span class="p">((</span><span class="n">FileListEntry</span> <span class="o">**</span><span class="p">)</span> <span class="n">a</span><span class="p">);</span> <span class="k">const</span> <span class="n">FileListEntry</span> <span class="o">*</span><span class="n">entry2</span> <span class="o">=</span> <span class="o">*</span><span class="p">((</span><span class="n">FileListEntry</span> <span class="o">**</span><span class="p">)</span> <span class="n">b</span><span class="p">);</span> <span class="k">return</span> <span class="n">g_ascii_strcasecmp</span> <span class="p">(</span><span class="n">entry1</span><span class="o">-></span><span class="n">name</span><span class="p">,</span> <span class="n">entry2</span><span class="o">-></span><span class="n">name</span><span class="p">);</span> <span class="p">}</span> <span class="err">…</span> <span class="n">g_autoptr</span> <span class="p">(</span><span class="n">GPtrArray</span><span class="p">)</span> <span class="n">file_list</span> <span class="o">=</span> <span class="nb">NULL</span><span class="p">;</span> <span class="c1">// initialize file_list array and load with many FileListEntry entries</span> <span class="p">...</span> <span class="c1">// now sort it with</span> <span class="n">g_ptr_array_sort</span> <span class="p">(</span><span class="n">file_list</span><span class="p">,</span> <span class="n">sort_filelist</span><span class="p">);</span></pre></td> </tr> </tbody> </table> </div> <p></p> <p>This is guaranteed to be a stable sort since version 2.32.</p> <div class="refsect3"> <a name="g-ptr-array-sort.parameters"></a><h4>Parameters</h4> <div class="informaltable"><table class="informaltable" width="100%" border="0"> <colgroup> <col width="150px" class="parameters_name"> <col class="parameters_description"> <col width="200px" class="parameters_annotations"> </colgroup> <tbody> <tr> <td class="parameter_name"><p>array</p></td> <td class="parameter_description"><p>a <a class="link" href="glib-Pointer-Arrays.html#GPtrArray" title="struct GPtrArray"><span class="type">GPtrArray</span></a></p></td> <td class="parameter_annotations"> </td> </tr> <tr> <td class="parameter_name"><p>compare_func</p></td> <td class="parameter_description"><p>comparison function</p></td> <td class="parameter_annotations"> </td> </tr> </tbody> </table></div> </div> </div> <hr> <div class="refsect2"> <a name="g-ptr-array-sort-with-data"></a><h3>g_ptr_array_sort_with_data ()</h3> <pre class="programlisting"><span class="returnvalue">void</span> g_ptr_array_sort_with_data (<em class="parameter"><code><a class="link" href="glib-Pointer-Arrays.html#GPtrArray" title="struct GPtrArray"><span class="type">GPtrArray</span></a> *array</code></em>, <em class="parameter"><code><a class="link" href="glib-Doubly-Linked-Lists.html#GCompareDataFunc" title="GCompareDataFunc ()"><span class="type">GCompareDataFunc</span></a> compare_func</code></em>, <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gpointer" title="gpointer"><span class="type">gpointer</span></a> user_data</code></em>);</pre> <p>Like <a class="link" href="glib-Pointer-Arrays.html#g-ptr-array-sort" title="g_ptr_array_sort ()"><code class="function">g_ptr_array_sort()</code></a>, but the comparison function has an extra user data argument.</p> <p>Note that the comparison function for <a class="link" href="glib-Pointer-Arrays.html#g-ptr-array-sort-with-data" title="g_ptr_array_sort_with_data ()"><code class="function">g_ptr_array_sort_with_data()</code></a> doesn't take the pointers from the array as arguments, it takes pointers to the pointers in the array. Here is a full example of use:</p> <div class="informalexample"> <table class="listing_frame" border="0" cellpadding="0" cellspacing="0"> <tbody> <tr> <td class="listing_lines" align="right"><pre>1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42</pre></td> <td class="listing_code"><pre class="programlisting"><span class="k">typedef</span> <span class="k">enum</span> <span class="p">{</span> <span class="n">SORT_NAME</span><span class="p">,</span> <span class="n">SORT_SIZE</span> <span class="p">}</span> <span class="n">SortMode</span><span class="p">;</span> <span class="k">typedef</span> <span class="k">struct</span> <span class="p">{</span> <span class="n">gchar</span> <span class="o">*</span><span class="n">name</span><span class="p">;</span> <span class="n">gint</span> <span class="n">size</span><span class="p">;</span> <span class="p">}</span> <span class="n">FileListEntry</span><span class="p">;</span> <span class="k">static</span> <span class="n">gint</span> <span class="nf">sort_filelist</span> <span class="p">(</span><span class="n">gconstpointer</span> <span class="n">a</span><span class="p">,</span> <span class="n">gconstpointer</span> <span class="n">b</span><span class="p">,</span> <span class="n">gpointer</span> <span class="n">user_data</span><span class="p">)</span> <span class="p">{</span> <span class="n">gint</span> <span class="n">order</span><span class="p">;</span> <span class="k">const</span> <span class="n">SortMode</span> <span class="n">sort_mode</span> <span class="o">=</span> <span class="n">GPOINTER_TO_INT</span> <span class="p">(</span><span class="n">user_data</span><span class="p">);</span> <span class="k">const</span> <span class="n">FileListEntry</span> <span class="o">*</span><span class="n">entry1</span> <span class="o">=</span> <span class="o">*</span><span class="p">((</span><span class="n">FileListEntry</span> <span class="o">**</span><span class="p">)</span> <span class="n">a</span><span class="p">);</span> <span class="k">const</span> <span class="n">FileListEntry</span> <span class="o">*</span><span class="n">entry2</span> <span class="o">=</span> <span class="o">*</span><span class="p">((</span><span class="n">FileListEntry</span> <span class="o">**</span><span class="p">)</span> <span class="n">b</span><span class="p">);</span> <span class="k">switch</span> <span class="p">(</span><span class="n">sort_mode</span><span class="p">)</span> <span class="p">{</span> <span class="k">case</span> <span class="nl">SORT_NAME</span><span class="p">:</span> <span class="n">order</span> <span class="o">=</span> <span class="n">g_ascii_strcasecmp</span> <span class="p">(</span><span class="n">entry1</span><span class="o">-></span><span class="n">name</span><span class="p">,</span> <span class="n">entry2</span><span class="o">-></span><span class="n">name</span><span class="p">);</span> <span class="k">break</span><span class="p">;</span> <span class="k">case</span> <span class="nl">SORT_SIZE</span><span class="p">:</span> <span class="n">order</span> <span class="o">=</span> <span class="n">entry1</span><span class="o">-></span><span class="n">size</span> <span class="o">-</span> <span class="n">entry2</span><span class="o">-></span><span class="n">size</span><span class="p">;</span> <span class="k">break</span><span class="p">;</span> <span class="k">default</span><span class="o">:</span> <span class="n">order</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span> <span class="k">break</span><span class="p">;</span> <span class="p">}</span> <span class="k">return</span> <span class="n">order</span><span class="p">;</span> <span class="p">}</span> <span class="p">...</span> <span class="n">g_autoptr</span> <span class="p">(</span><span class="n">GPtrArray</span><span class="p">)</span> <span class="n">file_list</span> <span class="o">=</span> <span class="nb">NULL</span><span class="p">;</span> <span class="n">SortMode</span> <span class="n">sort_mode</span><span class="p">;</span> <span class="c1">// initialize file_list array and load with many FileListEntry entries</span> <span class="p">...</span> <span class="c1">// now sort it with</span> <span class="n">sort_mode</span> <span class="o">=</span> <span class="n">SORT_NAME</span><span class="p">;</span> <span class="n">g_ptr_array_sort_with_data</span> <span class="p">(</span><span class="n">file_list</span><span class="p">,</span> <span class="n">sort_filelist</span><span class="p">,</span> <span class="n">GINT_TO_POINTER</span> <span class="p">(</span><span class="n">sort_mode</span><span class="p">));</span></pre></td> </tr> </tbody> </table> </div> <p></p> <p>This is guaranteed to be a stable sort since version 2.32.</p> <div class="refsect3"> <a name="g-ptr-array-sort-with-data.parameters"></a><h4>Parameters</h4> <div class="informaltable"><table class="informaltable" width="100%" border="0"> <colgroup> <col width="150px" class="parameters_name"> <col class="parameters_description"> <col width="200px" class="parameters_annotations"> </colgroup> <tbody> <tr> <td class="parameter_name"><p>array</p></td> <td class="parameter_description"><p>a <a class="link" href="glib-Pointer-Arrays.html#GPtrArray" title="struct GPtrArray"><span class="type">GPtrArray</span></a></p></td> <td class="parameter_annotations"> </td> </tr> <tr> <td class="parameter_name"><p>compare_func</p></td> <td class="parameter_description"><p>comparison function</p></td> <td class="parameter_annotations"> </td> </tr> <tr> <td class="parameter_name"><p>user_data</p></td> <td class="parameter_description"><p>data to pass to <em class="parameter"><code>compare_func</code></em> </p></td> <td class="parameter_annotations"> </td> </tr> </tbody> </table></div> </div> </div> <hr> <div class="refsect2"> <a name="g-ptr-array-set-size"></a><h3>g_ptr_array_set_size ()</h3> <pre class="programlisting"><span class="returnvalue">void</span> g_ptr_array_set_size (<em class="parameter"><code><a class="link" href="glib-Pointer-Arrays.html#GPtrArray" title="struct GPtrArray"><span class="type">GPtrArray</span></a> *array</code></em>, <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gint" title="gint"><span class="type">gint</span></a> length</code></em>);</pre> <p>Sets the size of the array. When making the array larger, newly-added elements will be set to <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a>. When making it smaller, if <em class="parameter"><code>array</code></em> has a non-<a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a> <a class="link" href="glib-Datasets.html#GDestroyNotify" title="GDestroyNotify ()"><span class="type">GDestroyNotify</span></a> function then it will be called for the removed elements.</p> <div class="refsect3"> <a name="g-ptr-array-set-size.parameters"></a><h4>Parameters</h4> <div class="informaltable"><table class="informaltable" width="100%" border="0"> <colgroup> <col width="150px" class="parameters_name"> <col class="parameters_description"> <col width="200px" class="parameters_annotations"> </colgroup> <tbody> <tr> <td class="parameter_name"><p>array</p></td> <td class="parameter_description"><p>a <a class="link" href="glib-Pointer-Arrays.html#GPtrArray" title="struct GPtrArray"><span class="type">GPtrArray</span></a></p></td> <td class="parameter_annotations"> </td> </tr> <tr> <td class="parameter_name"><p>length</p></td> <td class="parameter_description"><p>the new length of the pointer array</p></td> <td class="parameter_annotations"> </td> </tr> </tbody> </table></div> </div> </div> <hr> <div class="refsect2"> <a name="g-ptr-array-index"></a><h3>g_ptr_array_index()</h3> <pre class="programlisting">#define g_ptr_array_index(array,index_)</pre> <p>Returns the pointer at the given index of the pointer array.</p> <p>This does not perform bounds checking on the given <em class="parameter"><code>index_</code></em> , so you are responsible for checking it against the array length.</p> <div class="refsect3"> <a name="g-ptr-array-index.parameters"></a><h4>Parameters</h4> <div class="informaltable"><table class="informaltable" width="100%" border="0"> <colgroup> <col width="150px" class="parameters_name"> <col class="parameters_description"> <col width="200px" class="parameters_annotations"> </colgroup> <tbody> <tr> <td class="parameter_name"><p>array</p></td> <td class="parameter_description"><p>a <a class="link" href="glib-Pointer-Arrays.html#GPtrArray" title="struct GPtrArray"><span class="type">GPtrArray</span></a></p></td> <td class="parameter_annotations"> </td> </tr> <tr> <td class="parameter_name"><p>index_</p></td> <td class="parameter_description"><p>the index of the pointer to return</p></td> <td class="parameter_annotations"> </td> </tr> </tbody> </table></div> </div> <div class="refsect3"> <a name="g-ptr-array-index.returns"></a><h4>Returns</h4> <p> the pointer at the given index</p> </div> </div> <hr> <div class="refsect2"> <a name="g-ptr-array-free"></a><h3>g_ptr_array_free ()</h3> <pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gpointer" title="gpointer"><span class="returnvalue">gpointer</span></a> * g_ptr_array_free (<em class="parameter"><code><a class="link" href="glib-Pointer-Arrays.html#GPtrArray" title="struct GPtrArray"><span class="type">GPtrArray</span></a> *array</code></em>, <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gboolean" title="gboolean"><span class="type">gboolean</span></a> free_seg</code></em>);</pre> <p>Frees the memory allocated for the <a class="link" href="glib-Pointer-Arrays.html#GPtrArray" title="struct GPtrArray"><span class="type">GPtrArray</span></a>. If <em class="parameter"><code>free_seg</code></em> is <a class="link" href="glib-Standard-Macros.html#TRUE:CAPS" title="TRUE"><code class="literal">TRUE</code></a> it frees the memory block holding the elements as well. Pass <a class="link" href="glib-Standard-Macros.html#FALSE:CAPS" title="FALSE"><code class="literal">FALSE</code></a> if you want to free the <a class="link" href="glib-Pointer-Arrays.html#GPtrArray" title="struct GPtrArray"><span class="type">GPtrArray</span></a> wrapper but preserve the underlying array for use elsewhere. If the reference count of <em class="parameter"><code>array</code></em> is greater than one, the <a class="link" href="glib-Pointer-Arrays.html#GPtrArray" title="struct GPtrArray"><span class="type">GPtrArray</span></a> wrapper is preserved but the size of <em class="parameter"><code>array</code></em> will be set to zero.</p> <p>If array contents point to dynamically-allocated memory, they should be freed separately if <em class="parameter"><code>free_seg</code></em> is <a class="link" href="glib-Standard-Macros.html#TRUE:CAPS" title="TRUE"><code class="literal">TRUE</code></a> and no <a class="link" href="glib-Datasets.html#GDestroyNotify" title="GDestroyNotify ()"><span class="type">GDestroyNotify</span></a> function has been set for <em class="parameter"><code>array</code></em> .</p> <p>This function is not thread-safe. If using a <a class="link" href="glib-Pointer-Arrays.html#GPtrArray" title="struct GPtrArray"><span class="type">GPtrArray</span></a> from multiple threads, use only the atomic <a class="link" href="glib-Pointer-Arrays.html#g-ptr-array-ref" title="g_ptr_array_ref ()"><code class="function">g_ptr_array_ref()</code></a> and <a class="link" href="glib-Pointer-Arrays.html#g-ptr-array-unref" title="g_ptr_array_unref ()"><code class="function">g_ptr_array_unref()</code></a> functions.</p> <div class="refsect3"> <a name="g-ptr-array-free.parameters"></a><h4>Parameters</h4> <div class="informaltable"><table class="informaltable" width="100%" border="0"> <colgroup> <col width="150px" class="parameters_name"> <col class="parameters_description"> <col width="200px" class="parameters_annotations"> </colgroup> <tbody> <tr> <td class="parameter_name"><p>array</p></td> <td class="parameter_description"><p>a <a class="link" href="glib-Pointer-Arrays.html#GPtrArray" title="struct GPtrArray"><span class="type">GPtrArray</span></a></p></td> <td class="parameter_annotations"> </td> </tr> <tr> <td class="parameter_name"><p>free_seg</p></td> <td class="parameter_description"><p>if <a class="link" href="glib-Standard-Macros.html#TRUE:CAPS" title="TRUE"><code class="literal">TRUE</code></a> the actual pointer array is freed as well</p></td> <td class="parameter_annotations"> </td> </tr> </tbody> </table></div> </div> <div class="refsect3"> <a name="g-ptr-array-free.returns"></a><h4>Returns</h4> <p> the pointer array if <em class="parameter"><code>free_seg</code></em> is <a class="link" href="glib-Standard-Macros.html#FALSE:CAPS" title="FALSE"><code class="literal">FALSE</code></a>, otherwise <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a>. The pointer array should be freed using <a class="link" href="glib-Memory-Allocation.html#g-free" title="g_free ()"><code class="function">g_free()</code></a>.</p> </div> </div> <hr> <div class="refsect2"> <a name="g-ptr-array-foreach"></a><h3>g_ptr_array_foreach ()</h3> <pre class="programlisting"><span class="returnvalue">void</span> g_ptr_array_foreach (<em class="parameter"><code><a class="link" href="glib-Pointer-Arrays.html#GPtrArray" title="struct GPtrArray"><span class="type">GPtrArray</span></a> *array</code></em>, <em class="parameter"><code><a class="link" href="glib-Doubly-Linked-Lists.html#GFunc" title="GFunc ()"><span class="type">GFunc</span></a> func</code></em>, <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gpointer" title="gpointer"><span class="type">gpointer</span></a> user_data</code></em>);</pre> <p>Calls a function for each element of a <a class="link" href="glib-Pointer-Arrays.html#GPtrArray" title="struct GPtrArray"><span class="type">GPtrArray</span></a>. <em class="parameter"><code>func</code></em> must not add elements to or remove elements from the array.</p> <div class="refsect3"> <a name="g-ptr-array-foreach.parameters"></a><h4>Parameters</h4> <div class="informaltable"><table class="informaltable" width="100%" border="0"> <colgroup> <col width="150px" class="parameters_name"> <col class="parameters_description"> <col width="200px" class="parameters_annotations"> </colgroup> <tbody> <tr> <td class="parameter_name"><p>array</p></td> <td class="parameter_description"><p>a <a class="link" href="glib-Pointer-Arrays.html#GPtrArray" title="struct GPtrArray"><span class="type">GPtrArray</span></a></p></td> <td class="parameter_annotations"> </td> </tr> <tr> <td class="parameter_name"><p>func</p></td> <td class="parameter_description"><p>the function to call for each array element</p></td> <td class="parameter_annotations"> </td> </tr> <tr> <td class="parameter_name"><p>user_data</p></td> <td class="parameter_description"><p>user data to pass to the function</p></td> <td class="parameter_annotations"> </td> </tr> </tbody> </table></div> </div> <p class="since">Since: <a class="link" href="api-index-2-4.html#api-index-2.4">2.4</a></p> </div> <hr> <div class="refsect2"> <a name="g-ptr-array-find"></a><h3>g_ptr_array_find ()</h3> <pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gboolean" title="gboolean"><span class="returnvalue">gboolean</span></a> g_ptr_array_find (<em class="parameter"><code><a class="link" href="glib-Pointer-Arrays.html#GPtrArray" title="struct GPtrArray"><span class="type">GPtrArray</span></a> *haystack</code></em>, <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gconstpointer" title="gconstpointer"><span class="type">gconstpointer</span></a> needle</code></em>, <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#guint" title="guint"><span class="type">guint</span></a> *index_</code></em>);</pre> <p>Checks whether <em class="parameter"><code>needle</code></em> exists in <em class="parameter"><code>haystack</code></em> . If the element is found, <a class="link" href="glib-Standard-Macros.html#TRUE:CAPS" title="TRUE"><code class="literal">TRUE</code></a> is returned and the element’s index is returned in <em class="parameter"><code>index_</code></em> (if non-<a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a>). Otherwise, <a class="link" href="glib-Standard-Macros.html#FALSE:CAPS" title="FALSE"><code class="literal">FALSE</code></a> is returned and <em class="parameter"><code>index_</code></em> is undefined. If <em class="parameter"><code>needle</code></em> exists multiple times in <em class="parameter"><code>haystack</code></em> , the index of the first instance is returned.</p> <p>This does pointer comparisons only. If you want to use more complex equality checks, such as string comparisons, use <a class="link" href="glib-Pointer-Arrays.html#g-ptr-array-find-with-equal-func" title="g_ptr_array_find_with_equal_func ()"><code class="function">g_ptr_array_find_with_equal_func()</code></a>.</p> <p><span class="annotation">[<acronym title="Exposed in C code, not necessarily available in other languages."><span class="acronym">skip</span></acronym>]</span></p> <div class="refsect3"> <a name="g-ptr-array-find.parameters"></a><h4>Parameters</h4> <div class="informaltable"><table class="informaltable" width="100%" border="0"> <colgroup> <col width="150px" class="parameters_name"> <col class="parameters_description"> <col width="200px" class="parameters_annotations"> </colgroup> <tbody> <tr> <td class="parameter_name"><p>haystack</p></td> <td class="parameter_description"><p>pointer array to be searched</p></td> <td class="parameter_annotations"> </td> </tr> <tr> <td class="parameter_name"><p>needle</p></td> <td class="parameter_description"><p>pointer to look for</p></td> <td class="parameter_annotations"> </td> </tr> <tr> <td class="parameter_name"><p>index_</p></td> <td class="parameter_description"><p>return location for the index of the element, if found. </p></td> <td class="parameter_annotations"><span class="annotation">[<acronym title="NULL may be passed instead of a pointer to a location."><span class="acronym">optional</span></acronym>][<acronym title="Out parameter, where caller must allocate storage."><span class="acronym">out caller-allocates</span></acronym>]</span></td> </tr> </tbody> </table></div> </div> <div class="refsect3"> <a name="g-ptr-array-find.returns"></a><h4>Returns</h4> <p> <a class="link" href="glib-Standard-Macros.html#TRUE:CAPS" title="TRUE"><code class="literal">TRUE</code></a> if <em class="parameter"><code>needle</code></em> is one of the elements of <em class="parameter"><code>haystack</code></em> </p> </div> <p class="since">Since: <a class="link" href="api-index-2-54.html#api-index-2.54">2.54</a></p> </div> <hr> <div class="refsect2"> <a name="g-ptr-array-find-with-equal-func"></a><h3>g_ptr_array_find_with_equal_func ()</h3> <pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gboolean" title="gboolean"><span class="returnvalue">gboolean</span></a> g_ptr_array_find_with_equal_func (<em class="parameter"><code><a class="link" href="glib-Pointer-Arrays.html#GPtrArray" title="struct GPtrArray"><span class="type">GPtrArray</span></a> *haystack</code></em>, <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gconstpointer" title="gconstpointer"><span class="type">gconstpointer</span></a> needle</code></em>, <em class="parameter"><code><a class="link" href="glib-Hash-Tables.html#GEqualFunc" title="GEqualFunc ()"><span class="type">GEqualFunc</span></a> equal_func</code></em>, <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#guint" title="guint"><span class="type">guint</span></a> *index_</code></em>);</pre> <p>Checks whether <em class="parameter"><code>needle</code></em> exists in <em class="parameter"><code>haystack</code></em> , using the given <em class="parameter"><code>equal_func</code></em> . If the element is found, <a class="link" href="glib-Standard-Macros.html#TRUE:CAPS" title="TRUE"><code class="literal">TRUE</code></a> is returned and the element’s index is returned in <em class="parameter"><code>index_</code></em> (if non-<a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a>). Otherwise, <a class="link" href="glib-Standard-Macros.html#FALSE:CAPS" title="FALSE"><code class="literal">FALSE</code></a> is returned and <em class="parameter"><code>index_</code></em> is undefined. If <em class="parameter"><code>needle</code></em> exists multiple times in <em class="parameter"><code>haystack</code></em> , the index of the first instance is returned.</p> <p><em class="parameter"><code>equal_func</code></em> is called with the element from the array as its first parameter, and <em class="parameter"><code>needle</code></em> as its second parameter. If <em class="parameter"><code>equal_func</code></em> is <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a>, pointer equality is used.</p> <p><span class="annotation">[<acronym title="Exposed in C code, not necessarily available in other languages."><span class="acronym">skip</span></acronym>]</span></p> <div class="refsect3"> <a name="g-ptr-array-find-with-equal-func.parameters"></a><h4>Parameters</h4> <div class="informaltable"><table class="informaltable" width="100%" border="0"> <colgroup> <col width="150px" class="parameters_name"> <col class="parameters_description"> <col width="200px" class="parameters_annotations"> </colgroup> <tbody> <tr> <td class="parameter_name"><p>haystack</p></td> <td class="parameter_description"><p>pointer array to be searched</p></td> <td class="parameter_annotations"> </td> </tr> <tr> <td class="parameter_name"><p>needle</p></td> <td class="parameter_description"><p>pointer to look for</p></td> <td class="parameter_annotations"> </td> </tr> <tr> <td class="parameter_name"><p>equal_func</p></td> <td class="parameter_description"><p>the function to call for each element, which should return <a class="link" href="glib-Standard-Macros.html#TRUE:CAPS" title="TRUE"><code class="literal">TRUE</code></a> when the desired element is found; or <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a> to use pointer equality. </p></td> <td class="parameter_annotations"><span class="annotation">[<acronym title="NULL may be passed as the value in, out, in-out; or as a return value."><span class="acronym">nullable</span></acronym>]</span></td> </tr> <tr> <td class="parameter_name"><p>index_</p></td> <td class="parameter_description"><p>return location for the index of the element, if found. </p></td> <td class="parameter_annotations"><span class="annotation">[<acronym title="NULL may be passed instead of a pointer to a location."><span class="acronym">optional</span></acronym>][<acronym title="Out parameter, where caller must allocate storage."><span class="acronym">out caller-allocates</span></acronym>]</span></td> </tr> </tbody> </table></div> </div> <div class="refsect3"> <a name="g-ptr-array-find-with-equal-func.returns"></a><h4>Returns</h4> <p> <a class="link" href="glib-Standard-Macros.html#TRUE:CAPS" title="TRUE"><code class="literal">TRUE</code></a> if <em class="parameter"><code>needle</code></em> is one of the elements of <em class="parameter"><code>haystack</code></em> </p> </div> <p class="since">Since: <a class="link" href="api-index-2-54.html#api-index-2.54">2.54</a></p> </div> </div> <div class="refsect1"> <a name="glib-Pointer-Arrays.other_details"></a><h2>Types and Values</h2> <div class="refsect2"> <a name="GPtrArray"></a><h3>struct GPtrArray</h3> <pre class="programlisting">struct GPtrArray { gpointer *pdata; guint len; }; </pre> <p>Contains the public fields of a pointer array.</p> <div class="refsect3"> <a name="GPtrArray.members"></a><h4>Members</h4> <div class="informaltable"><table class="informaltable" width="100%" border="0"> <colgroup> <col width="300px" class="struct_members_name"> <col class="struct_members_description"> <col width="200px" class="struct_members_annotations"> </colgroup> <tbody> <tr> <td class="struct_member_name"><p><a class="link" href="glib-Basic-Types.html#gpointer" title="gpointer"><span class="type">gpointer</span></a> *<em class="structfield"><code><a name="GPtrArray.pdata"></a>pdata</code></em>;</p></td> <td class="struct_member_description"><p>points to the array of pointers, which may be moved when the array grows</p></td> <td class="struct_member_annotations"> </td> </tr> <tr> <td class="struct_member_name"><p><a class="link" href="glib-Basic-Types.html#guint" title="guint"><span class="type">guint</span></a> <em class="structfield"><code><a name="GPtrArray.len"></a>len</code></em>;</p></td> <td class="struct_member_description"><p>number of pointers in the array</p></td> <td class="struct_member_annotations"> </td> </tr> </tbody> </table></div> </div> </div> </div> </div> <div class="footer"> <hr>Generated by GTK-Doc V1.32</div> </body> </html>