* Lesser General Public License for more details.
*
* You should have received a copy of the GNU Lesser General Public
- * License along with this library; if not, write to the
- * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
- * Boston, MA 02111-1307, USA.
+ * License along with this library; if not, see <http://www.gnu.org/licenses/>.
*/
/*
* Each element in the list contains a piece of data, together with
* pointers which link to the previous and next elements in the list.
* Using these pointers it is possible to move through the list in both
- * directions (unlike the singly-linked <link
- * linkend="glib-Singly-Linked-Lists">#GSList</link> which
- * only allows movement through the list in the forward direction).
+ * directions (unlike the singly-linked [GSList][glib-Singly-Linked-Lists],
+ * which only allows movement through the list in the forward direction).
*
* The double linked list does not keep track of the number of items
* and does not keep track of both the start and end of the list. If
* you want fast access to both the start and the end of the list,
* and/or the number of items in the list, use a
- * <link linkend="glib-Double-ended-Queues">GQueue</link> instead.
+ * [GQueue][glib-Double-ended-Queues] instead.
*
* The data contained in each element can be either integer values, by
- * using one of the <link linkend="glib-Type-Conversion-Macros">Type
- * Conversion Macros</link>, or simply pointers to any type of data.
+ * using one of the [Type Conversion Macros][glib-Type-Conversion-Macros],
+ * or simply pointers to any type of data.
*
- * List elements are allocated from the <link
- * linkend="glib-Memory-Slices">slice allocator</link>, which is more
- * efficient than allocating elements individually.
+ * List elements are allocated from the [slice allocator][glib-Memory-Slices],
+ * which is more efficient than allocating elements individually.
*
* Note that most of the #GList functions expect to be passed a pointer
* to the first element in the list. The functions which insert
* g_list_insert() and g_list_insert_sorted().
*
* To visit all elements in the list, use a loop over the list:
- * |[
+ * |[<!-- language="C" -->
* GList *l;
* for (l = list; l != NULL; l = l->next)
* {
- * /* do something with l->data */
+ * // do something with l->data
* }
* ]|
*
*
* To loop over the list and modify it (e.g. remove a certain element)
* a while loop is more appropriate, for example:
- * |[
+ * |[<!-- language="C" -->
* GList *l = list;
* while (l != NULL)
* {
* GList *next = l->next;
* if (should_be_removed (l))
* {
- * /* possibly free l->data */
+ * // possibly free l->data
* list = g_list_delete_link (list, l);
* }
* l = next;
/**
* GList:
* @data: holds the element's data, which can be a pointer to any kind
- * of data, or any integer value using the <link
- * linkend="glib-Type-Conversion-Macros">Type Conversion
- * Macros</link>.
+ * of data, or any integer value using the
+ * [Type Conversion Macros][glib-Type-Conversion-Macros]
* @next: contains the link to the next element in the list
* @prev: contains the link to the previous element in the list
*
* @list: a #GList
*
* Frees all of the memory used by a #GList.
- * The freed elements are returned to the slice allocator
+ * The freed elements are returned to the slice allocator.
*
- * <note><para>
- * If list elements contain dynamically-allocated memory,
- * you should either use g_list_free_full() or free them manually
- * first.
- * </para></note>
+ * If list elements contain dynamically-allocated memory, you should
+ * either use g_list_free_full() or free them manually first.
*/
void
g_list_free (GList *list)
* to avoid the inefficiency is to use g_list_prepend() and reverse
* the list with g_list_reverse() when all elements have been added.
*
- * |[
- * /* Notice that these are initialized to the empty list. */
+ * |[<!-- language="C" -->
+ * // Notice that these are initialized to the empty list.
* GList *string_list = NULL, *number_list = NULL;
*
- * /* This is a list of strings. */
+ * // This is a list of strings.
* string_list = g_list_append (string_list, "first");
* string_list = g_list_append (string_list, "second");
*
- * /* This is a list of integers. */
+ * // This is a list of integers.
* number_list = g_list_append (number_list, GINT_TO_POINTER (27));
* number_list = g_list_append (number_list, GINT_TO_POINTER (14));
* ]|
* Note that the return value is the new start of the list,
* which will have changed, so make sure you store the new value.
*
- * |[
- * /* Notice that it is initialized to the empty list. */
+ * |[<!-- language="C" -->
+ * // Notice that it is initialized to the empty list.
* GList *list = NULL;
*
* list = g_list_prepend (list, "last");
* list = g_list_prepend (list, "first");
* ]|
*
- * <note><para>
- * Do not use this function to prepend a new element to a different element
- * than the start of the list. Use g_list_insert_before() instead.
- * </para></note>
+ * Do not use this function to prepend a new element to a different
+ * element than the start of the list. Use g_list_insert_before() instead.
*
* Returns: a pointer to the newly prepended element, which is the new
* start of the #GList
*
* This function is for example used to move an element in the list.
* The following example moves an element to the top of the list:
- * |[
+ * |[<!-- language="C" -->
* list = g_list_remove_link (list, llink);
* list = g_list_concat (llink, list);
* ]|
* This function is for example used to move an element in the list
* (see the example for g_list_concat()) or to remove an element in
* the list before freeing its data:
- * |[
+ * |[<!-- language="C" -->
* list = g_list_remove_link (list, llink);
* free_some_data_that_may_access_the_list_again (llink->data);
* g_list_free (llink);
*
* Copies a #GList.
*
- * <note><para>
* Note that this is a "shallow" copy. If the list elements
* consist of pointers to data, the pointers are copied but
* the actual data is not. See g_list_copy_deep() if you need
* to copy the data as well.
- * </para></note>
*
* Returns: the start of the new list that holds the same data as @list
*/
* if the copy function takes only one argument.
*
* For instance, if @list holds a list of GObjects, you can do:
- * |[
+ * |[<!-- language="C" -->
* another_list = g_list_copy_deep (list, (GCopyFunc) g_object_ref, NULL);
* ]|
*
* And, to entirely free the new list, you could do:
- * |[
+ * |[<!-- language="C" -->
* g_list_free_full (another_list, g_object_unref);
* ]|
*
*
* Gets the number of elements in a #GList.
*
- * <note><para>
* This function iterates over the whole list to count its elements.
- * Use a <link linkend="glib-Double-ended-Queues">GQueue</link> instead
- * of a GList if you regularly need the number of items.
- * </para></note>
+ * Use a #GQueue instead of a GList if you regularly need the number
+ * of items.
*
* Returns: the number of elements in the #GList
*/
* Inserts a new element into the list, using the given comparison
* function to determine its position.
*
- * <note><para>
* If you are adding many new elements to a list, and the number of
* new elements is much larger than the length of the list, use
* g_list_prepend() to add the new items and sort the list afterwards
- * with g_list_sort()
- * </para></note>
+ * with g_list_sort().
*
* Returns: the (possibly changed) start of the #GList
*/
* Inserts a new element into the list, using the given comparison
* function to determine its position.
*
- * <note><para>
* If you are adding many new elements to a list, and the number of
* new elements is much larger than the length of the list, use
* g_list_prepend() to add the new items and sort the list afterwards
- * with g_list_sort()
- * </para></note>
+ * with g_list_sort().
*
* Returns: the (possibly changed) start of the #GList
*
* value comes before the second, 0 if they are equal, or a positive
* integer if the first value comes after the second.
*
- * Returns: negative value if @a < @b; zero if @a = @b; positive
+ * Returns: negative value if @a < @b; zero if @a = @b; positive
* value if @a > @b
*/
GList *
* value comes before the second, 0 if they are equal, or a positive
* integer if the first value comes after the second.
*
- * Returns: negative value if @a < @b; zero if @a = @b; positive
+ * Returns: negative value if @a < @b; zero if @a = @b; positive
* value if @a > @b
*/
GList *
projects / platform / upstream / glib.git / blobdiff