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.
34 * The data contained in each element can be either integer values, by
35 * using one of the [Type Conversion Macros][glib-Type-Conversion-Macros],
36 * or simply pointers to any type of data.
38 * To create a new GQueue, use g_queue_new().
40 * To initialize a statically-allocated GQueue, use #G_QUEUE_INIT or
43 * To add elements, use g_queue_push_head(), g_queue_push_head_link(),
44 * g_queue_push_tail() and g_queue_push_tail_link().
46 * To remove elements, use g_queue_pop_head() and g_queue_pop_tail().
48 * To free the entire queue, use g_queue_free().
54 #include "gtestutils.h"
60 * Creates a new #GQueue.
62 * Returns: a newly allocated #GQueue
67 return g_slice_new0 (GQueue);
74 * Frees the memory allocated for the #GQueue. Only call this function
75 * if @queue was created with g_queue_new(). If queue elements contain
76 * dynamically-allocated memory, they should be freed first.
78 * If queue elements contain dynamically-allocated memory, you should
79 * either use g_queue_free_full() or free them manually first.
82 g_queue_free (GQueue *queue)
84 g_return_if_fail (queue != NULL);
86 g_list_free (queue->head);
87 g_slice_free (GQueue, queue);
92 * @queue: a pointer to a #GQueue
93 * @free_func: the function to be called to free each element's data
95 * Convenience method, which frees all the memory used by a #GQueue,
96 * and calls the specified destroy function on every element's data.
98 * @free_func should not modify the queue (eg, by removing the freed
104 g_queue_free_full (GQueue *queue,
105 GDestroyNotify free_func)
107 g_queue_foreach (queue, (GFunc) free_func, NULL);
108 g_queue_free (queue);
113 * @queue: an uninitialized #GQueue
115 * A statically-allocated #GQueue must be initialized with this function
116 * before it can be used. Alternatively you can initialize it with
117 * #G_QUEUE_INIT. It is not necessary to initialize queues created with
123 g_queue_init (GQueue *queue)
125 g_return_if_fail (queue != NULL);
127 queue->head = queue->tail = NULL;
135 * Removes all the elements in @queue. If queue elements contain
136 * dynamically-allocated memory, they should be freed first.
141 g_queue_clear (GQueue *queue)
143 g_return_if_fail (queue != NULL);
145 g_list_free (queue->head);
146 g_queue_init (queue);
153 * Returns %TRUE if the queue is empty.
155 * Returns: %TRUE if the queue is empty
158 g_queue_is_empty (GQueue *queue)
160 g_return_val_if_fail (queue != NULL, TRUE);
162 return queue->head == NULL;
166 * g_queue_get_length:
169 * Returns the number of items in @queue.
171 * Returns: the number of items in @queue
176 g_queue_get_length (GQueue *queue)
178 g_return_val_if_fail (queue != NULL, 0);
180 return queue->length;
187 * Reverses the order of the items in @queue.
192 g_queue_reverse (GQueue *queue)
194 g_return_if_fail (queue != NULL);
196 queue->tail = queue->head;
197 queue->head = g_list_reverse (queue->head);
204 * Copies a @queue. Note that is a shallow copy. If the elements in the
205 * queue consist of pointers to data, the pointers are copied, but the
206 * actual data is not.
208 * Returns: a copy of @queue
213 g_queue_copy (GQueue *queue)
218 g_return_val_if_fail (queue != NULL, NULL);
220 result = g_queue_new ();
222 for (list = queue->head; list != NULL; list = list->next)
223 g_queue_push_tail (result, list->data);
231 * @func: the function to call for each element's data
232 * @user_data: user data to pass to @func
234 * Calls @func for each element in the queue passing @user_data to the
237 * It is safe for @func to remove the element from @queue, but it must
238 * not modify any part of the queue after that element.
243 g_queue_foreach (GQueue *queue,
249 g_return_if_fail (queue != NULL);
250 g_return_if_fail (func != NULL);
255 GList *next = list->next;
256 func (list->data, user_data);
264 * @data: data to find
266 * Finds the first link in @queue which contains @data.
268 * Returns: the first link in @queue which contains @data
273 g_queue_find (GQueue *queue,
276 g_return_val_if_fail (queue != NULL, NULL);
278 return g_list_find (queue->head, data);
282 * g_queue_find_custom:
284 * @data: user data passed to @func
285 * @func: a #GCompareFunc to call for each element. It should return 0
286 * when the desired element is found
288 * Finds an element in a #GQueue, using a supplied function to find the
289 * desired element. It iterates over the queue, calling the given function
290 * which should return 0 when the desired element is found. The function
291 * takes two gconstpointer arguments, the #GQueue element's data as the
292 * first argument and the given user data as the second argument.
294 * Returns: the found link, or %NULL if it wasn't found
299 g_queue_find_custom (GQueue *queue,
303 g_return_val_if_fail (queue != NULL, NULL);
304 g_return_val_if_fail (func != NULL, NULL);
306 return g_list_find_custom (queue->head, data, func);
312 * @compare_func: the #GCompareDataFunc used to sort @queue. This function
313 * is passed two elements of the queue and should return 0 if they are
314 * equal, a negative value if the first comes before the second, and
315 * a positive value if the second comes before the first.
316 * @user_data: user data passed to @compare_func
318 * Sorts @queue using @compare_func.
323 g_queue_sort (GQueue *queue,
324 GCompareDataFunc compare_func,
327 g_return_if_fail (queue != NULL);
328 g_return_if_fail (compare_func != NULL);
330 queue->head = g_list_sort_with_data (queue->head, compare_func, user_data);
331 queue->tail = g_list_last (queue->head);
337 * @data: the data for the new element.
339 * Adds a new element at the head of the queue.
342 g_queue_push_head (GQueue *queue,
345 g_return_if_fail (queue != NULL);
347 queue->head = g_list_prepend (queue->head, data);
349 queue->tail = queue->head;
356 * @data: the data for the new element
357 * @n: the position to insert the new element. If @n is negative or
358 * larger than the number of elements in the @queue, the element is
359 * added to the end of the queue.
361 * Inserts a new element into @queue at the given position.
366 g_queue_push_nth (GQueue *queue,
370 g_return_if_fail (queue != NULL);
372 if (n < 0 || n >= queue->length)
374 g_queue_push_tail (queue, data);
378 g_queue_insert_before (queue, g_queue_peek_nth_link (queue, n), data);
382 * g_queue_push_head_link:
384 * @link_: a single #GList element, not a list with more than one element
386 * Adds a new element at the head of the queue.
389 g_queue_push_head_link (GQueue *queue,
392 g_return_if_fail (queue != NULL);
393 g_return_if_fail (link != NULL);
394 g_return_if_fail (link->prev == NULL);
395 g_return_if_fail (link->next == NULL);
397 link->next = queue->head;
399 queue->head->prev = link;
409 * @data: the data for the new element
411 * Adds a new element at the tail of the queue.
414 g_queue_push_tail (GQueue *queue,
417 g_return_if_fail (queue != NULL);
419 queue->tail = g_list_append (queue->tail, data);
420 if (queue->tail->next)
421 queue->tail = queue->tail->next;
423 queue->head = queue->tail;
428 * g_queue_push_tail_link:
430 * @link_: a single #GList element, not a list with more than one element
432 * Adds a new element at the tail of the queue.
435 g_queue_push_tail_link (GQueue *queue,
438 g_return_if_fail (queue != NULL);
439 g_return_if_fail (link != NULL);
440 g_return_if_fail (link->prev == NULL);
441 g_return_if_fail (link->next == NULL);
443 link->prev = queue->tail;
445 queue->tail->next = link;
453 * g_queue_push_nth_link:
455 * @n: the position to insert the link. If this is negative or larger than
456 * the number of elements in @queue, the link is added to the end of
458 * @link_: the link to add to @queue
460 * Inserts @link into @queue at the given position.
465 g_queue_push_nth_link (GQueue *queue,
472 g_return_if_fail (queue != NULL);
473 g_return_if_fail (link_ != NULL);
475 if (n < 0 || n >= queue->length)
477 g_queue_push_tail_link (queue, link_);
481 g_assert (queue->head);
482 g_assert (queue->tail);
484 next = g_queue_peek_nth_link (queue, n);
494 if (queue->head->prev)
495 queue->head = queue->head->prev;
497 if (queue->tail->next)
498 queue->tail = queue->tail->next;
507 * Removes the first element of the queue and returns its data.
509 * Returns: the data of the first element in the queue, or %NULL
510 * if the queue is empty
513 g_queue_pop_head (GQueue *queue)
515 g_return_val_if_fail (queue != NULL, NULL);
519 GList *node = queue->head;
520 gpointer data = node->data;
522 queue->head = node->next;
524 queue->head->prev = NULL;
527 g_list_free_1 (node);
537 * g_queue_pop_head_link:
540 * Removes and returns the first element of the queue.
542 * Returns: the #GList element at the head of the queue, or %NULL
543 * if the queue is empty
546 g_queue_pop_head_link (GQueue *queue)
548 g_return_val_if_fail (queue != NULL, NULL);
552 GList *node = queue->head;
554 queue->head = node->next;
557 queue->head->prev = NULL;
571 * g_queue_peek_head_link:
574 * Returns the first link in @queue.
576 * Returns: the first link in @queue, or %NULL if @queue is empty
581 g_queue_peek_head_link (GQueue *queue)
583 g_return_val_if_fail (queue != NULL, NULL);
589 * g_queue_peek_tail_link:
592 * Returns the last link in @queue.
594 * Returns: the last link in @queue, or %NULL if @queue is empty
599 g_queue_peek_tail_link (GQueue *queue)
601 g_return_val_if_fail (queue != NULL, NULL);
610 * Removes the last element of the queue and returns its data.
612 * Returns: the data of the last element in the queue, or %NULL
613 * if the queue is empty
616 g_queue_pop_tail (GQueue *queue)
618 g_return_val_if_fail (queue != NULL, NULL);
622 GList *node = queue->tail;
623 gpointer data = node->data;
625 queue->tail = node->prev;
627 queue->tail->next = NULL;
631 g_list_free_1 (node);
642 * @n: the position of the element
644 * Removes the @n'th element of @queue and returns its data.
646 * Returns: the element's data, or %NULL if @n is off the end of @queue
651 g_queue_pop_nth (GQueue *queue,
657 g_return_val_if_fail (queue != NULL, NULL);
659 if (n >= queue->length)
662 nth_link = g_queue_peek_nth_link (queue, n);
663 result = nth_link->data;
665 g_queue_delete_link (queue, nth_link);
671 * g_queue_pop_tail_link:
674 * Removes and returns the last element of the queue.
676 * Returns: the #GList element at the tail of the queue, or %NULL
677 * if the queue is empty
680 g_queue_pop_tail_link (GQueue *queue)
682 g_return_val_if_fail (queue != NULL, NULL);
686 GList *node = queue->tail;
688 queue->tail = node->prev;
691 queue->tail->next = NULL;
705 * g_queue_pop_nth_link:
707 * @n: the link's position
709 * Removes and returns the link at the given position.
711 * Returns: the @n'th link, or %NULL if @n is off the end of @queue
716 g_queue_pop_nth_link (GQueue *queue,
721 g_return_val_if_fail (queue != NULL, NULL);
723 if (n >= queue->length)
726 link = g_queue_peek_nth_link (queue, n);
727 g_queue_unlink (queue, link);
733 * g_queue_peek_nth_link:
735 * @n: the position of the link
737 * Returns the link at the given position
739 * Returns: the link at the @n'th position, or %NULL
740 * if @n is off the end of the list
745 g_queue_peek_nth_link (GQueue *queue,
751 g_return_val_if_fail (queue != NULL, NULL);
753 if (n >= queue->length)
756 if (n > queue->length / 2)
758 n = queue->length - n - 1;
761 for (i = 0; i < n; ++i)
767 for (i = 0; i < n; ++i)
775 * g_queue_link_index:
777 * @link_: a #GList link
779 * Returns the position of @link_ in @queue.
781 * Returns: the position of @link_, or -1 if the link is
787 g_queue_link_index (GQueue *queue,
790 g_return_val_if_fail (queue != NULL, -1);
792 return g_list_position (queue->head, link_);
798 * @link_: a #GList link that must be part of @queue
800 * Unlinks @link_ so that it will no longer be part of @queue.
801 * The link is not freed.
803 * @link_ must be part of @queue.
808 g_queue_unlink (GQueue *queue,
811 g_return_if_fail (queue != NULL);
812 g_return_if_fail (link_ != NULL);
814 if (link_ == queue->tail)
815 queue->tail = queue->tail->prev;
817 queue->head = g_list_remove_link (queue->head, link_);
822 * g_queue_delete_link:
824 * @link_: a #GList link that must be part of @queue
826 * Removes @link_ from @queue and frees it.
828 * @link_ must be part of @queue.
833 g_queue_delete_link (GQueue *queue,
836 g_return_if_fail (queue != NULL);
837 g_return_if_fail (link_ != NULL);
839 g_queue_unlink (queue, link_);
847 * Returns the first element of the queue.
849 * Returns: the data of the first element in the queue, or %NULL
850 * if the queue is empty
853 g_queue_peek_head (GQueue *queue)
855 g_return_val_if_fail (queue != NULL, NULL);
857 return queue->head ? queue->head->data : NULL;
864 * Returns the last element of the queue.
866 * Returns: the data of the last element in the queue, or %NULL
867 * if the queue is empty
870 g_queue_peek_tail (GQueue *queue)
872 g_return_val_if_fail (queue != NULL, NULL);
874 return queue->tail ? queue->tail->data : NULL;
880 * @n: the position of the element
882 * Returns the @n'th element of @queue.
884 * Returns: the data for the @n'th element of @queue,
885 * or %NULL if @n is off the end of @queue
890 g_queue_peek_nth (GQueue *queue,
895 g_return_val_if_fail (queue != NULL, NULL);
897 link = g_queue_peek_nth_link (queue, n);
908 * @data: the data to find
910 * Returns the position of the first element in @queue which contains @data.
912 * Returns: the position of the first element in @queue which
913 * contains @data, or -1 if no element in @queue contains @data
918 g_queue_index (GQueue *queue,
921 g_return_val_if_fail (queue != NULL, -1);
923 return g_list_index (queue->head, data);
929 * @data: the data to remove
931 * Removes the first element in @queue that contains @data.
933 * Returns: %TRUE if @data was found and removed from @queue
938 g_queue_remove (GQueue *queue,
943 g_return_val_if_fail (queue != NULL, FALSE);
945 link = g_list_find (queue->head, data);
948 g_queue_delete_link (queue, link);
950 return (link != NULL);
954 * g_queue_remove_all:
956 * @data: the data to remove
958 * Remove all elements whose data equals @data from @queue.
960 * Returns: the number of elements removed from @queue
965 g_queue_remove_all (GQueue *queue,
971 g_return_val_if_fail (queue != NULL, 0);
973 old_length = queue->length;
978 GList *next = list->next;
980 if (list->data == data)
981 g_queue_delete_link (queue, list);
986 return (old_length - queue->length);
990 * g_queue_insert_before:
992 * @sibling: (nullable): a #GList link that must be part of @queue, or %NULL to
993 * push at the tail of the queue.
994 * @data: the data to insert
996 * Inserts @data into @queue before @sibling.
998 * @sibling must be part of @queue. Since GLib 2.44 a %NULL sibling pushes the
999 * data at the tail of the queue.
1004 g_queue_insert_before (GQueue *queue,
1008 g_return_if_fail (queue != NULL);
1010 if (sibling == NULL)
1012 /* We don't use g_list_insert_before() with a NULL sibling because it
1013 * would be a O(n) operation and we would need to update manually the tail
1016 g_queue_push_tail (queue, data);
1020 queue->head = g_list_insert_before (queue->head, sibling, data);
1026 * g_queue_insert_after:
1028 * @sibling: (nullable): a #GList link that must be part of @queue, or %NULL to
1029 * push at the head of the queue.
1030 * @data: the data to insert
1032 * Inserts @data into @queue after @sibling.
1034 * @sibling must be part of @queue. Since GLib 2.44 a %NULL sibling pushes the
1035 * data at the head of the queue.
1040 g_queue_insert_after (GQueue *queue,
1044 g_return_if_fail (queue != NULL);
1046 if (sibling == NULL)
1047 g_queue_push_head (queue, data);
1049 g_queue_insert_before (queue, sibling->next, data);
1053 * g_queue_insert_sorted:
1055 * @data: the data to insert
1056 * @func: the #GCompareDataFunc used to compare elements in the queue. It is
1057 * called with two elements of the @queue and @user_data. It should
1058 * return 0 if the elements are equal, a negative value if the first
1059 * element comes before the second, and a positive value if the second
1060 * element comes before the first.
1061 * @user_data: user data passed to @func
1063 * Inserts @data into @queue using @func to determine the new position.
1068 g_queue_insert_sorted (GQueue *queue,
1070 GCompareDataFunc func,
1075 g_return_if_fail (queue != NULL);
1078 while (list && func (list->data, data, user_data) < 0)
1081 g_queue_insert_before (queue, list, data);