1 /* GLIB - Library of useful routines for C programming
2 * Copyright (C) 1995-1997 Peter Mattis, Spencer Kimball and Josh MacDonald
4 * GQueue: Double ended queue implementation, piggy backed on GList.
5 * Copyright (C) 1998 Tim Janik
7 * This library is free software; you can redistribute it and/or
8 * modify it under the terms of the GNU Lesser General Public
9 * License as published by the Free Software Foundation; either
10 * version 2.1 of the License, or (at your option) any later version.
12 * This library is distributed in the hope that it will be useful,
13 * but WITHOUT ANY WARRANTY; without even the implied warranty of
14 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
15 * Lesser General Public License for more details.
17 * You should have received a copy of the GNU Lesser General Public
18 * License along with this library; if not, see <http://www.gnu.org/licenses/>.
27 * @Title: Double-ended Queues
28 * @Short_description: double-ended queue data structure
30 * The #GQueue structure and its associated functions provide a standard
31 * queue data structure. Internally, GQueue uses the same data structure
32 * as #GList to store elements with the same complexity over
33 * insertion/deletion (O(1)) and access/search (O(n)) operations.
35 * The data contained in each element can be either integer values, by
36 * using one of the [Type Conversion Macros][glib-Type-Conversion-Macros],
37 * or simply pointers to any type of data.
39 * As with all other GLib data structures, #GQueue is not thread-safe.
40 * For a thread-safe queue, use #GAsyncQueue.
42 * To create a new GQueue, use g_queue_new().
44 * To initialize a statically-allocated GQueue, use %G_QUEUE_INIT or
47 * To add elements, use g_queue_push_head(), g_queue_push_head_link(),
48 * g_queue_push_tail() and g_queue_push_tail_link().
50 * To remove elements, use g_queue_pop_head() and g_queue_pop_tail().
52 * To free the entire queue, use g_queue_free().
58 #include "gtestutils.h"
64 * Creates a new #GQueue.
66 * Returns: a newly allocated #GQueue
71 return g_slice_new0 (GQueue);
78 * Frees the memory allocated for the #GQueue. Only call this function
79 * if @queue was created with g_queue_new(). If queue elements contain
80 * dynamically-allocated memory, they should be freed first.
82 * If queue elements contain dynamically-allocated memory, you should
83 * either use g_queue_free_full() or free them manually first.
86 g_queue_free (GQueue *queue)
88 g_return_if_fail (queue != NULL);
90 g_list_free (queue->head);
91 g_slice_free (GQueue, queue);
96 * @queue: a pointer to a #GQueue
97 * @free_func: the function to be called to free each element's data
99 * Convenience method, which frees all the memory used by a #GQueue,
100 * and calls the specified destroy function on every element's data.
102 * @free_func should not modify the queue (eg, by removing the freed
108 g_queue_free_full (GQueue *queue,
109 GDestroyNotify free_func)
111 g_queue_foreach (queue, (GFunc) free_func, NULL);
112 g_queue_free (queue);
117 * @queue: an uninitialized #GQueue
119 * A statically-allocated #GQueue must be initialized with this function
120 * before it can be used. Alternatively you can initialize it with
121 * %G_QUEUE_INIT. It is not necessary to initialize queues created with
127 g_queue_init (GQueue *queue)
129 g_return_if_fail (queue != NULL);
131 queue->head = queue->tail = NULL;
139 * Removes all the elements in @queue. If queue elements contain
140 * dynamically-allocated memory, they should be freed first.
145 g_queue_clear (GQueue *queue)
147 g_return_if_fail (queue != NULL);
149 g_list_free (queue->head);
150 g_queue_init (queue);
154 * g_queue_clear_full:
155 * @queue: a pointer to a #GQueue
156 * @free_func: (nullable): the function to be called to free memory allocated
158 * Convenience method, which frees all the memory used by a #GQueue,
159 * and calls the provided @free_func on each item in the #GQueue.
164 g_queue_clear_full (GQueue *queue,
165 GDestroyNotify free_func)
167 g_return_if_fail (queue != NULL);
169 if (free_func != NULL)
170 g_queue_foreach (queue, (GFunc) free_func, NULL);
172 g_queue_clear (queue);
179 * Returns %TRUE if the queue is empty.
181 * Returns: %TRUE if the queue is empty
184 g_queue_is_empty (GQueue *queue)
186 g_return_val_if_fail (queue != NULL, TRUE);
188 return queue->head == NULL;
192 * g_queue_get_length:
195 * Returns the number of items in @queue.
197 * Returns: the number of items in @queue
202 g_queue_get_length (GQueue *queue)
204 g_return_val_if_fail (queue != NULL, 0);
206 return queue->length;
213 * Reverses the order of the items in @queue.
218 g_queue_reverse (GQueue *queue)
220 g_return_if_fail (queue != NULL);
222 queue->tail = queue->head;
223 queue->head = g_list_reverse (queue->head);
230 * Copies a @queue. Note that is a shallow copy. If the elements in the
231 * queue consist of pointers to data, the pointers are copied, but the
232 * actual data is not.
234 * Returns: a copy of @queue
239 g_queue_copy (GQueue *queue)
244 g_return_val_if_fail (queue != NULL, NULL);
246 result = g_queue_new ();
248 for (list = queue->head; list != NULL; list = list->next)
249 g_queue_push_tail (result, list->data);
257 * @func: the function to call for each element's data
258 * @user_data: user data to pass to @func
260 * Calls @func for each element in the queue passing @user_data to the
263 * It is safe for @func to remove the element from @queue, but it must
264 * not modify any part of the queue after that element.
269 g_queue_foreach (GQueue *queue,
275 g_return_if_fail (queue != NULL);
276 g_return_if_fail (func != NULL);
281 GList *next = list->next;
282 func (list->data, user_data);
290 * @data: data to find
292 * Finds the first link in @queue which contains @data.
294 * Returns: the first link in @queue which contains @data
299 g_queue_find (GQueue *queue,
302 g_return_val_if_fail (queue != NULL, NULL);
304 return g_list_find (queue->head, data);
308 * g_queue_find_custom:
310 * @data: user data passed to @func
311 * @func: a #GCompareFunc to call for each element. It should return 0
312 * when the desired element is found
314 * Finds an element in a #GQueue, using a supplied function to find the
315 * desired element. It iterates over the queue, calling the given function
316 * which should return 0 when the desired element is found. The function
317 * takes two gconstpointer arguments, the #GQueue element's data as the
318 * first argument and the given user data as the second argument.
320 * Returns: the found link, or %NULL if it wasn't found
325 g_queue_find_custom (GQueue *queue,
329 g_return_val_if_fail (queue != NULL, NULL);
330 g_return_val_if_fail (func != NULL, NULL);
332 return g_list_find_custom (queue->head, data, func);
338 * @compare_func: the #GCompareDataFunc used to sort @queue. This function
339 * is passed two elements of the queue and should return 0 if they are
340 * equal, a negative value if the first comes before the second, and
341 * a positive value if the second comes before the first.
342 * @user_data: user data passed to @compare_func
344 * Sorts @queue using @compare_func.
349 g_queue_sort (GQueue *queue,
350 GCompareDataFunc compare_func,
353 g_return_if_fail (queue != NULL);
354 g_return_if_fail (compare_func != NULL);
356 queue->head = g_list_sort_with_data (queue->head, compare_func, user_data);
357 queue->tail = g_list_last (queue->head);
363 * @data: the data for the new element.
365 * Adds a new element at the head of the queue.
368 g_queue_push_head (GQueue *queue,
371 g_return_if_fail (queue != NULL);
373 queue->head = g_list_prepend (queue->head, data);
375 queue->tail = queue->head;
382 * @data: the data for the new element
383 * @n: the position to insert the new element. If @n is negative or
384 * larger than the number of elements in the @queue, the element is
385 * added to the end of the queue.
387 * Inserts a new element into @queue at the given position.
392 g_queue_push_nth (GQueue *queue,
396 g_return_if_fail (queue != NULL);
398 if (n < 0 || (guint) n >= queue->length)
400 g_queue_push_tail (queue, data);
404 g_queue_insert_before (queue, g_queue_peek_nth_link (queue, n), data);
408 * g_queue_push_head_link:
410 * @link_: a single #GList element, not a list with more than one element
412 * Adds a new element at the head of the queue.
415 g_queue_push_head_link (GQueue *queue,
418 g_return_if_fail (queue != NULL);
419 g_return_if_fail (link != NULL);
420 g_return_if_fail (link->prev == NULL);
421 g_return_if_fail (link->next == NULL);
423 link->next = queue->head;
425 queue->head->prev = link;
435 * @data: the data for the new element
437 * Adds a new element at the tail of the queue.
440 g_queue_push_tail (GQueue *queue,
443 g_return_if_fail (queue != NULL);
445 queue->tail = g_list_append (queue->tail, data);
446 if (queue->tail->next)
447 queue->tail = queue->tail->next;
449 queue->head = queue->tail;
454 * g_queue_push_tail_link:
456 * @link_: a single #GList element, not a list with more than one element
458 * Adds a new element at the tail of the queue.
461 g_queue_push_tail_link (GQueue *queue,
464 g_return_if_fail (queue != NULL);
465 g_return_if_fail (link != NULL);
466 g_return_if_fail (link->prev == NULL);
467 g_return_if_fail (link->next == NULL);
469 link->prev = queue->tail;
471 queue->tail->next = link;
479 * g_queue_push_nth_link:
481 * @n: the position to insert the link. If this is negative or larger than
482 * the number of elements in @queue, the link is added to the end of
484 * @link_: the link to add to @queue
486 * Inserts @link into @queue at the given position.
491 g_queue_push_nth_link (GQueue *queue,
498 g_return_if_fail (queue != NULL);
499 g_return_if_fail (link_ != NULL);
501 if (n < 0 || (guint) n >= queue->length)
503 g_queue_push_tail_link (queue, link_);
507 g_assert (queue->head);
508 g_assert (queue->tail);
510 next = g_queue_peek_nth_link (queue, n);
520 if (queue->head->prev)
521 queue->head = queue->head->prev;
523 /* The case where we’re pushing @link_ at the end of @queue is handled above
524 * using g_queue_push_tail_link(), so we should never have to manually adjust
526 g_assert (queue->tail->next == NULL);
535 * Removes the first element of the queue and returns its data.
537 * Returns: the data of the first element in the queue, or %NULL
538 * if the queue is empty
541 g_queue_pop_head (GQueue *queue)
543 g_return_val_if_fail (queue != NULL, NULL);
547 GList *node = queue->head;
548 gpointer data = node->data;
550 queue->head = node->next;
552 queue->head->prev = NULL;
555 g_list_free_1 (node);
565 * g_queue_pop_head_link:
568 * Removes and returns the first element of the queue.
570 * Returns: the #GList element at the head of the queue, or %NULL
571 * if the queue is empty
574 g_queue_pop_head_link (GQueue *queue)
576 g_return_val_if_fail (queue != NULL, NULL);
580 GList *node = queue->head;
582 queue->head = node->next;
585 queue->head->prev = NULL;
599 * g_queue_peek_head_link:
602 * Returns the first link in @queue.
604 * Returns: the first link in @queue, or %NULL if @queue is empty
609 g_queue_peek_head_link (GQueue *queue)
611 g_return_val_if_fail (queue != NULL, NULL);
617 * g_queue_peek_tail_link:
620 * Returns the last link in @queue.
622 * Returns: the last link in @queue, or %NULL if @queue is empty
627 g_queue_peek_tail_link (GQueue *queue)
629 g_return_val_if_fail (queue != NULL, NULL);
638 * Removes the last element of the queue and returns its data.
640 * Returns: the data of the last element in the queue, or %NULL
641 * if the queue is empty
644 g_queue_pop_tail (GQueue *queue)
646 g_return_val_if_fail (queue != NULL, NULL);
650 GList *node = queue->tail;
651 gpointer data = node->data;
653 queue->tail = node->prev;
655 queue->tail->next = NULL;
659 g_list_free_1 (node);
670 * @n: the position of the element
672 * Removes the @n'th element of @queue and returns its data.
674 * Returns: the element's data, or %NULL if @n is off the end of @queue
679 g_queue_pop_nth (GQueue *queue,
685 g_return_val_if_fail (queue != NULL, NULL);
687 if (n >= queue->length)
690 nth_link = g_queue_peek_nth_link (queue, n);
691 result = nth_link->data;
693 g_queue_delete_link (queue, nth_link);
699 * g_queue_pop_tail_link:
702 * Removes and returns the last element of the queue.
704 * Returns: the #GList element at the tail of the queue, or %NULL
705 * if the queue is empty
708 g_queue_pop_tail_link (GQueue *queue)
710 g_return_val_if_fail (queue != NULL, NULL);
714 GList *node = queue->tail;
716 queue->tail = node->prev;
719 queue->tail->next = NULL;
733 * g_queue_pop_nth_link:
735 * @n: the link's position
737 * Removes and returns the link at the given position.
739 * Returns: the @n'th link, or %NULL if @n is off the end of @queue
744 g_queue_pop_nth_link (GQueue *queue,
749 g_return_val_if_fail (queue != NULL, NULL);
751 if (n >= queue->length)
754 link = g_queue_peek_nth_link (queue, n);
755 g_queue_unlink (queue, link);
761 * g_queue_peek_nth_link:
763 * @n: the position of the link
765 * Returns the link at the given position
767 * Returns: the link at the @n'th position, or %NULL
768 * if @n is off the end of the list
773 g_queue_peek_nth_link (GQueue *queue,
779 g_return_val_if_fail (queue != NULL, NULL);
781 if (n >= queue->length)
784 if (n > queue->length / 2)
786 n = queue->length - n - 1;
789 for (i = 0; i < n; ++i)
795 for (i = 0; i < n; ++i)
803 * g_queue_link_index:
805 * @link_: a #GList link
807 * Returns the position of @link_ in @queue.
809 * Returns: the position of @link_, or -1 if the link is
815 g_queue_link_index (GQueue *queue,
818 g_return_val_if_fail (queue != NULL, -1);
820 return g_list_position (queue->head, link_);
826 * @link_: a #GList link that must be part of @queue
828 * Unlinks @link_ so that it will no longer be part of @queue.
829 * The link is not freed.
831 * @link_ must be part of @queue.
836 g_queue_unlink (GQueue *queue,
839 g_return_if_fail (queue != NULL);
840 g_return_if_fail (link_ != NULL);
842 if (link_ == queue->tail)
843 queue->tail = queue->tail->prev;
845 queue->head = g_list_remove_link (queue->head, link_);
850 * g_queue_delete_link:
852 * @link_: a #GList link that must be part of @queue
854 * Removes @link_ from @queue and frees it.
856 * @link_ must be part of @queue.
861 g_queue_delete_link (GQueue *queue,
864 g_return_if_fail (queue != NULL);
865 g_return_if_fail (link_ != NULL);
867 g_queue_unlink (queue, link_);
875 * Returns the first element of the queue.
877 * Returns: the data of the first element in the queue, or %NULL
878 * if the queue is empty
881 g_queue_peek_head (GQueue *queue)
883 g_return_val_if_fail (queue != NULL, NULL);
885 return queue->head ? queue->head->data : NULL;
892 * Returns the last element of the queue.
894 * Returns: the data of the last element in the queue, or %NULL
895 * if the queue is empty
898 g_queue_peek_tail (GQueue *queue)
900 g_return_val_if_fail (queue != NULL, NULL);
902 return queue->tail ? queue->tail->data : NULL;
908 * @n: the position of the element
910 * Returns the @n'th element of @queue.
912 * Returns: the data for the @n'th element of @queue,
913 * or %NULL if @n is off the end of @queue
918 g_queue_peek_nth (GQueue *queue,
923 g_return_val_if_fail (queue != NULL, NULL);
925 link = g_queue_peek_nth_link (queue, n);
936 * @data: the data to find
938 * Returns the position of the first element in @queue which contains @data.
940 * Returns: the position of the first element in @queue which
941 * contains @data, or -1 if no element in @queue contains @data
946 g_queue_index (GQueue *queue,
949 g_return_val_if_fail (queue != NULL, -1);
951 return g_list_index (queue->head, data);
957 * @data: the data to remove
959 * Removes the first element in @queue that contains @data.
961 * Returns: %TRUE if @data was found and removed from @queue
966 g_queue_remove (GQueue *queue,
971 g_return_val_if_fail (queue != NULL, FALSE);
973 link = g_list_find (queue->head, data);
976 g_queue_delete_link (queue, link);
978 return (link != NULL);
982 * g_queue_remove_all:
984 * @data: the data to remove
986 * Remove all elements whose data equals @data from @queue.
988 * Returns: the number of elements removed from @queue
993 g_queue_remove_all (GQueue *queue,
999 g_return_val_if_fail (queue != NULL, 0);
1001 old_length = queue->length;
1006 GList *next = list->next;
1008 if (list->data == data)
1009 g_queue_delete_link (queue, list);
1014 return (old_length - queue->length);
1018 * g_queue_insert_before:
1020 * @sibling: (nullable): a #GList link that must be part of @queue, or %NULL to
1021 * push at the tail of the queue.
1022 * @data: the data to insert
1024 * Inserts @data into @queue before @sibling.
1026 * @sibling must be part of @queue. Since GLib 2.44 a %NULL sibling pushes the
1027 * data at the tail of the queue.
1032 g_queue_insert_before (GQueue *queue,
1036 g_return_if_fail (queue != NULL);
1038 if (sibling == NULL)
1040 /* We don't use g_list_insert_before() with a NULL sibling because it
1041 * would be a O(n) operation and we would need to update manually the tail
1044 g_queue_push_tail (queue, data);
1048 queue->head = g_list_insert_before (queue->head, sibling, data);
1054 * g_queue_insert_before_link:
1056 * @sibling: (nullable): a #GList link that must be part of @queue, or %NULL to
1057 * push at the tail of the queue.
1058 * @link_: a #GList link to insert which must not be part of any other list.
1060 * Inserts @link_ into @queue before @sibling.
1062 * @sibling must be part of @queue.
1067 g_queue_insert_before_link (GQueue *queue,
1071 g_return_if_fail (queue != NULL);
1072 g_return_if_fail (link_ != NULL);
1073 g_return_if_fail (link_->prev == NULL);
1074 g_return_if_fail (link_->next == NULL);
1076 if G_UNLIKELY (sibling == NULL)
1078 /* We don't use g_list_insert_before_link() with a NULL sibling because it
1079 * would be a O(n) operation and we would need to update manually the tail
1082 g_queue_push_tail_link (queue, link_);
1086 queue->head = g_list_insert_before_link (queue->head, sibling, link_);
1092 * g_queue_insert_after:
1094 * @sibling: (nullable): a #GList link that must be part of @queue, or %NULL to
1095 * push at the head of the queue.
1096 * @data: the data to insert
1098 * Inserts @data into @queue after @sibling.
1100 * @sibling must be part of @queue. Since GLib 2.44 a %NULL sibling pushes the
1101 * data at the head of the queue.
1106 g_queue_insert_after (GQueue *queue,
1110 g_return_if_fail (queue != NULL);
1112 if (sibling == NULL)
1113 g_queue_push_head (queue, data);
1115 g_queue_insert_before (queue, sibling->next, data);
1119 * g_queue_insert_after_link:
1121 * @sibling: (nullable): a #GList link that must be part of @queue, or %NULL to
1122 * push at the head of the queue.
1123 * @link_: a #GList link to insert which must not be part of any other list.
1125 * Inserts @link_ into @queue after @sibling.
1127 * @sibling must be part of @queue.
1132 g_queue_insert_after_link (GQueue *queue,
1136 g_return_if_fail (queue != NULL);
1137 g_return_if_fail (link_ != NULL);
1138 g_return_if_fail (link_->prev == NULL);
1139 g_return_if_fail (link_->next == NULL);
1141 if G_UNLIKELY (sibling == NULL)
1142 g_queue_push_head_link (queue, link_);
1144 g_queue_insert_before_link (queue, sibling->next, link_);
1148 * g_queue_insert_sorted:
1150 * @data: the data to insert
1151 * @func: the #GCompareDataFunc used to compare elements in the queue. It is
1152 * called with two elements of the @queue and @user_data. It should
1153 * return 0 if the elements are equal, a negative value if the first
1154 * element comes before the second, and a positive value if the second
1155 * element comes before the first.
1156 * @user_data: user data passed to @func
1158 * Inserts @data into @queue using @func to determine the new position.
1163 g_queue_insert_sorted (GQueue *queue,
1165 GCompareDataFunc func,
1170 g_return_if_fail (queue != NULL);
1173 while (list && func (list->data, data, user_data) < 0)
1176 g_queue_insert_before (queue, list, data);