linked_lists_double.sgml

GLib是GTK+和GNOME工程的基础底层核心程序库

<title><anchor id="g-list-insert">g_list_insert ()</title>
<programlisting><link linkend="GList">GList</link>*      g_list_insert                   (<link linkend="GList">GList</link> *list,
                                             <link linkend="gpointer">gpointer</link> data,
                                             <link linkend="gint">gint</link> position);</programlisting>
<para>
Inserts a new element into the list at the given position.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>list</parameter>&nbsp;:</entry>
<entry>a pointer to a <link linkend="GList">GList</link>.
</entry></row>
<row><entry align="right"><parameter>data</parameter>&nbsp;:</entry>
<entry>the data for the new element.
</entry></row>
<row><entry align="right"><parameter>position</parameter>&nbsp;:</entry>
<entry>the position to insert the element. If this is negative, or is
larger than the number of elements in the list, the new element is added on
to the end of the list.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry>the new start of the <link linkend="GList">GList</link>.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-list-insert-before">g_list_insert_before ()</title>
<programlisting><link linkend="GList">GList</link>*      g_list_insert_before            (<link linkend="GList">GList</link> *list,
                                             <link linkend="GList">GList</link> *sibling,
                                             <link linkend="gpointer">gpointer</link> data);</programlisting>
<para>
Inserts a new element into the list before the given position.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>list</parameter>&nbsp;:</entry>
<entry>a pointer to a <link linkend="GList">GList</link>.
</entry></row>
<row><entry align="right"><parameter>sibling</parameter>&nbsp;:</entry>
<entry>the list element before which the new element is inserted
  or <literal>NULL</literal> to insert at the end of the list.
</entry></row>
<row><entry align="right"><parameter>data</parameter>&nbsp;:</entry>
<entry>the data for the new element.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry>the new start of the <link linkend="GList">GList</link>.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-list-insert-sorted">g_list_insert_sorted ()</title>
<programlisting><link linkend="GList">GList</link>*      g_list_insert_sorted            (<link linkend="GList">GList</link> *list,
                                             <link linkend="gpointer">gpointer</link> data,
                                             <link linkend="GCompareFunc">GCompareFunc</link> func);</programlisting>
<para>
Inserts a new element into the list, using the given comparison function
to determine its position.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>list</parameter>&nbsp;:</entry>
<entry>a pointer to a <link linkend="GList">GList</link>.
</entry></row>
<row><entry align="right"><parameter>data</parameter>&nbsp;:</entry>
<entry>the data for the new element.
</entry></row>
<row><entry align="right"><parameter>func</parameter>&nbsp;:</entry>
<entry>the function to compare elements in the list. It should return a
number > 0 if the first parameter comes after the second parameter in
the sort order.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry>the new start of the <link linkend="GList">GList</link>.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-list-remove">g_list_remove ()</title>
<programlisting><link linkend="GList">GList</link>*      g_list_remove                   (<link linkend="GList">GList</link> *list,
                                             <link linkend="gconstpointer">gconstpointer</link> data);</programlisting>
<para>
Removes an element from a <link linkend="GList">GList</link>.
If two elements contain the same data, only the first is removed.
If none of the elements contain the data, the <link linkend="GList">GList</link> is unchanged.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>list</parameter>&nbsp;:</entry>
<entry>a <link linkend="GList">GList</link>.
</entry></row>
<row><entry align="right"><parameter>data</parameter>&nbsp;:</entry>
<entry>the data of the element to remove.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry>the new start of the <link linkend="GList">GList</link>.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-list-remove-link">g_list_remove_link ()</title>
<programlisting><link linkend="GList">GList</link>*      g_list_remove_link              (<link linkend="GList">GList</link> *list,
                                             <link linkend="GList">GList</link> *llink);</programlisting>
<para>
Removes an element from a <link linkend="GList">GList</link>, without freeing the element.
The removed element's prev and next links are set to <literal>NULL</literal>, so that it becomes a
self-contained list with one element.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>list</parameter>&nbsp;:</entry>
<entry>a <link linkend="GList">GList</link>.
</entry></row>
<row><entry align="right"><parameter>llink</parameter>&nbsp;:</entry>
<entry>an element in the <link linkend="GList">GList</link>.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry>the new start of the <link linkend="GList">GList</link>, without the element.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-list-delete-link">g_list_delete_link ()</title>
<programlisting><link linkend="GList">GList</link>*      g_list_delete_link              (<link linkend="GList">GList</link> *list,
                                             <link linkend="GList">GList</link> *link);</programlisting>
<para>
Deletes the node <parameter>link</parameter> from <parameter>list</parameter>.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>list</parameter>&nbsp;:</entry>
<entry>a <link linkend="GList">GList</link>.
</entry></row>
<row><entry align="right"><parameter>link</parameter>&nbsp;:</entry>
<entry>node to delete from <parameter>list</parameter>.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry>the new head of <parameter>list</parameter>.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-list-remove-all">g_list_remove_all ()</title>
<programlisting><link linkend="GList">GList</link>*      g_list_remove_all               (<link linkend="GList">GList</link> *list,
                                             <link linkend="gconstpointer">gconstpointer</link> data);</programlisting>
<para>
Removes all list nodes with data equal to <parameter>data</parameter>. Returns the new
head of the list. Contrast with <link linkend="g-list-remove">g_list_remove</link>() which removes only 
the first node matching the given data.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>list</parameter>&nbsp;:</entry>
<entry>a <link linkend="GList">GList</link>.
</entry></row>
<row><entry align="right"><parameter>data</parameter>&nbsp;:</entry>
<entry>data to remove.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry>new head of <parameter>list</parameter>.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-list-free">g_list_free ()</title>
<programlisting>void        g_list_free                     (<link linkend="GList">GList</link> *list);</programlisting>
<para>
Frees all of the memory used by a <link linkend="GList">GList</link>.
The freed elements are added to the <link linkend="GListAllocator">GListAllocator</link> free list.
</para>
<note>
<para>
If list elements contain dynamically-allocated memory, they should be freed
first.
</para>
</note><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>list</parameter>&nbsp;:</entry>
<entry>a <link linkend="GList">GList</link>.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-list-alloc">g_list_alloc ()</title>
<programlisting><link linkend="GList">GList</link>*      g_list_alloc                    (void);</programlisting>
<para>
Allocates space for one <link linkend="GList">GList</link> element.
It is called by <link linkend="g-list-append">g_list_append</link>(), <link linkend="g-list-prepend">g_list_prepend</link>(), <link linkend="g-list-insert">g_list_insert</link>() and
<link linkend="g-list-insert-sorted">g_list_insert_sorted</link>() and so is rarely used on its own.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry>a pointer to the newly-allocated <link linkend="GList">GList</link> element.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-list-free-1">g_list_free_1 ()</title>
<programlisting>void        g_list_free_1                   (<link linkend="GList">GList</link> *list);</programlisting>
<para>
Frees one <link linkend="GList">GList</link> element.
It is usually used after <link linkend="g-list-remove-link">g_list_remove_link</link>().
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>list</parameter>&nbsp;:</entry>
<entry>a <link linkend="GList">GList</link> element.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-list-length">g_list_length ()</title>
<programlisting><link linkend="guint">guint</link>       g_list_length                   (<link linkend="GList">GList</link> *list);</programlisting>
<para>
Gets the number of elements in a <link linkend="GList">GList</link>.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>list</parameter>&nbsp;:</entry>
<entry>a <link linkend="GList">GList</link>.
</entry></row>