* This library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Lesser General Public
* License as published by the Free Software Foundation; either
- * version 2 of the License, or (at your option) any later version.
+ * version 2.1 of the License, or (at your option) any later version.
*
* This library is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
*
* The #GQueue structure and its associated functions provide a standard
* queue data structure. Internally, GQueue uses the same data structure
- * as #GList to store elements.
+ * as #GList to store elements with the same complexity over
+ * insertion/deletion (O(1)) and access/search (O(n)) operations.
*
* The data contained in each element can be either integer values, by
* using one of the [Type Conversion Macros][glib-Type-Conversion-Macros],
* or simply pointers to any type of data.
*
+ * As with all other GLib data structures, #GQueue is not thread-safe.
+ * For a thread-safe queue, use #GAsyncQueue.
+ *
* To create a new GQueue, use g_queue_new().
*
- * To initialize a statically-allocated GQueue, use #G_QUEUE_INIT or
+ * To initialize a statically-allocated GQueue, use %G_QUEUE_INIT or
* g_queue_init().
*
* To add elements, use g_queue_push_head(), g_queue_push_head_link(),
* Convenience method, which frees all the memory used by a #GQueue,
* and calls the specified destroy function on every element's data.
*
+ * @free_func should not modify the queue (eg, by removing the freed
+ * element from it).
+ *
* Since: 2.32
*/
void
*
* A statically-allocated #GQueue must be initialized with this function
* before it can be used. Alternatively you can initialize it with
- * #G_QUEUE_INIT. It is not necessary to initialize queues created with
+ * %G_QUEUE_INIT. It is not necessary to initialize queues created with
* g_queue_new().
*
* Since: 2.14
}
/**
+ * g_queue_clear_full:
+ * @queue: a pointer to a #GQueue
+ * @free_func: (nullable): the function to be called to free memory allocated
+ *
+ * Convenience method, which frees all the memory used by a #GQueue,
+ * and calls the provided @free_func on each item in the #GQueue.
+ *
+ * Since: 2.60
+ */
+void
+g_queue_clear_full (GQueue *queue,
+ GDestroyNotify free_func)
+{
+ g_return_if_fail (queue != NULL);
+
+ if (free_func != NULL)
+ g_queue_foreach (queue, (GFunc) free_func, NULL);
+
+ g_queue_clear (queue);
+}
+
+/**
* g_queue_is_empty:
* @queue: a #GQueue.
*
* Calls @func for each element in the queue passing @user_data to the
* function.
*
+ * It is safe for @func to remove the element from @queue, but it must
+ * not modify any part of the queue after that element.
+ *
* Since: 2.4
*/
void
{
g_return_if_fail (queue != NULL);
- if (n < 0 || n >= queue->length)
+ if (n < 0 || (guint) n >= queue->length)
{
g_queue_push_tail (queue, data);
return;
g_return_if_fail (queue != NULL);
g_return_if_fail (link_ != NULL);
- if (n < 0 || n >= queue->length)
+ if (n < 0 || (guint) n >= queue->length)
{
g_queue_push_tail_link (queue, link_);
return;
if (queue->head->prev)
queue->head = queue->head->prev;
- if (queue->tail->next)
- queue->tail = queue->tail->next;
+ /* The case where we’re pushing @link_ at the end of @queue is handled above
+ * using g_queue_push_tail_link(), so we should never have to manually adjust
+ * queue->tail. */
+ g_assert (queue->tail->next == NULL);
queue->length++;
}
guint n)
{
GList *link;
- gint i;
+ guint i;
g_return_val_if_fail (queue != NULL, NULL);
/**
* g_queue_insert_before:
* @queue: a #GQueue
- * @sibling: a #GList link that must be part of @queue
+ * @sibling: (nullable): a #GList link that must be part of @queue, or %NULL to
+ * push at the tail of the queue.
* @data: the data to insert
*
* Inserts @data into @queue before @sibling.
*
- * @sibling must be part of @queue.
+ * @sibling must be part of @queue. Since GLib 2.44 a %NULL sibling pushes the
+ * data at the tail of the queue.
*
* Since: 2.4
*/
gpointer data)
{
g_return_if_fail (queue != NULL);
- g_return_if_fail (sibling != NULL);
- queue->head = g_list_insert_before (queue->head, sibling, data);
- queue->length++;
+ if (sibling == NULL)
+ {
+ /* We don't use g_list_insert_before() with a NULL sibling because it
+ * would be a O(n) operation and we would need to update manually the tail
+ * pointer.
+ */
+ g_queue_push_tail (queue, data);
+ }
+ else
+ {
+ queue->head = g_list_insert_before (queue->head, sibling, data);
+ queue->length++;
+ }
+}
+
+/**
+ * g_queue_insert_before_link:
+ * @queue: a #GQueue
+ * @sibling: (nullable): a #GList link that must be part of @queue, or %NULL to
+ * push at the tail of the queue.
+ * @link_: a #GList link to insert which must not be part of any other list.
+ *
+ * Inserts @link_ into @queue before @sibling.
+ *
+ * @sibling must be part of @queue.
+ *
+ * Since: 2.62
+ */
+void
+g_queue_insert_before_link (GQueue *queue,
+ GList *sibling,
+ GList *link_)
+{
+ g_return_if_fail (queue != NULL);
+ g_return_if_fail (link_ != NULL);
+ g_return_if_fail (link_->prev == NULL);
+ g_return_if_fail (link_->next == NULL);
+
+ if G_UNLIKELY (sibling == NULL)
+ {
+ /* We don't use g_list_insert_before_link() with a NULL sibling because it
+ * would be a O(n) operation and we would need to update manually the tail
+ * pointer.
+ */
+ g_queue_push_tail_link (queue, link_);
+ }
+ else
+ {
+ queue->head = g_list_insert_before_link (queue->head, sibling, link_);
+ queue->length++;
+ }
}
/**
* g_queue_insert_after:
* @queue: a #GQueue
- * @sibling: a #GList link that must be part of @queue
+ * @sibling: (nullable): a #GList link that must be part of @queue, or %NULL to
+ * push at the head of the queue.
* @data: the data to insert
*
- * Inserts @data into @queue after @sibling
+ * Inserts @data into @queue after @sibling.
*
- * @sibling must be part of @queue
+ * @sibling must be part of @queue. Since GLib 2.44 a %NULL sibling pushes the
+ * data at the head of the queue.
*
* Since: 2.4
*/
gpointer data)
{
g_return_if_fail (queue != NULL);
- g_return_if_fail (sibling != NULL);
- if (sibling == queue->tail)
- g_queue_push_tail (queue, data);
+ if (sibling == NULL)
+ g_queue_push_head (queue, data);
else
g_queue_insert_before (queue, sibling->next, data);
}
/**
+ * g_queue_insert_after_link:
+ * @queue: a #GQueue
+ * @sibling: (nullable): a #GList link that must be part of @queue, or %NULL to
+ * push at the head of the queue.
+ * @link_: a #GList link to insert which must not be part of any other list.
+ *
+ * Inserts @link_ into @queue after @sibling.
+ *
+ * @sibling must be part of @queue.
+ *
+ * Since: 2.62
+ */
+void
+g_queue_insert_after_link (GQueue *queue,
+ GList *sibling,
+ GList *link_)
+{
+ g_return_if_fail (queue != NULL);
+ g_return_if_fail (link_ != NULL);
+ g_return_if_fail (link_->prev == NULL);
+ g_return_if_fail (link_->next == NULL);
+
+ if G_UNLIKELY (sibling == NULL)
+ g_queue_push_head_link (queue, link_);
+ else
+ g_queue_insert_before_link (queue, sibling->next, link_);
+}
+
+/**
* g_queue_insert_sorted:
* @queue: a #GQueue
* @data: the data to insert
while (list && func (list->data, data, user_data) < 0)
list = list->next;
- if (list)
- g_queue_insert_before (queue, list, data);
- else
- g_queue_push_tail (queue, data);
+ g_queue_insert_before (queue, list, data);
}
projects / platform / upstream / glib.git / blobdiff