1 /* -*- mode: C; c-file-style: "gnu" -*- */
2 /* dbus-list.c Generic linked list utility (internal to D-BUS implementation)
4 * Copyright (C) 2002 Red Hat, Inc.
6 * Licensed under the Academic Free License version 1.2
8 * This program is free software; you can redistribute it and/or modify
9 * it under the terms of the GNU General Public License as published by
10 * the Free Software Foundation; either version 2 of the License, or
11 * (at your option) any later version.
13 * This program is distributed in the hope that it will be useful,
14 * but WITHOUT ANY WARRANTY; without even the implied warranty of
15 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
16 * GNU General Public License for more details.
18 * You should have received a copy of the GNU General Public License
19 * along with this program; if not, write to the Free Software
20 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
24 #include "dbus-internals.h"
25 #include "dbus-list.h"
28 * @defgroup DBusList Linked list
29 * @ingroup DBusInternals
30 * @brief DBusList data structure
32 * Types and functions related to DBusList.
36 * @defgroup DBusListInternals Linked list implementation details
37 * @ingroup DBusInternals
38 * @brief DBusList implementation details
40 * The guts of DBusList.
42 * @todo should use a memory pool for the list nodes, to avoid
43 * a memory allocation for every link.
48 alloc_link (void *data)
52 link = dbus_new0 (DBusList, 1);
59 free_link (DBusList *link)
65 link_before (DBusList **list,
66 DBusList *before_this_link,
77 link->next = before_this_link;
78 link->prev = before_this_link->prev;
79 before_this_link->prev = link;
80 link->prev->next = link;
82 if (before_this_link == *list)
88 link_after (DBusList **list,
89 DBusList *after_this_link,
100 link->prev = after_this_link;
101 link->next = after_this_link->next;
102 after_this_link->next = link;
103 link->next->prev = link;
110 * @addtogroup DBusList
117 * A node in a linked list.
119 * DBusList is a circular list; that is, the tail of the list
120 * points back to the head of the list. The empty list is
121 * represented by a #NULL pointer.
125 * @def _dbus_list_get_next_link
127 * Gets the next link in the list, or #NULL if
128 * there are no more links. Used for iteration.
132 * link = _dbus_list_get_first_link (&list);
133 * while (link != NULL)
135 * printf ("value is %p\n", link->data);
136 * link = _dbus_list_get_next_link (&list);
140 * @param list address of the list head.
141 * @param link current link.
142 * @returns the next link, or %NULL if none.
147 * @def _dbus_list_get_prev_link
149 * Gets the previous link in the list, or #NULL if
150 * there are no more links. Used for iteration.
154 * link = _dbus_list_get_last_link (&list);
155 * while (link != NULL)
157 * printf ("value is %p\n", link->data);
158 * link = _dbus_list_get_prev_link (&list);
162 * @param list address of the list head.
163 * @param link current link.
164 * @returns the previous link, or %NULL if none.
169 * Appends a value to the list. May return #FALSE
170 * if insufficient memory exists to add a list link.
171 * This is a constant-time operation.
173 * @param list address of the list head.
174 * @param data the value to append.
175 * @returns #TRUE on success.
178 _dbus_list_append (DBusList **list,
181 if (!_dbus_list_prepend (list, data))
184 /* Now cycle the list forward one so the prepended node is the tail */
185 *list = (*list)->next;
191 * Prepends a value to the list. May return #FALSE
192 * if insufficient memory exists to add a list link.
193 * This is a constant-time operation.
195 * @param list address of the list head.
196 * @param data the value to prepend.
197 * @returns #TRUE on success.
200 _dbus_list_prepend (DBusList **list,
205 link = alloc_link (data);
209 link_before (list, *list, link);
215 * Inserts data into the list before the given existing link.
217 * @param list the list to modify
218 * @param before_this_link existing link to insert before, or #NULL to append
219 * @param data the value to insert
220 * @returns #TRUE on success, #FALSE if memory allocation fails
223 _dbus_list_insert_before (DBusList **list,
224 DBusList *before_this_link,
229 if (before_this_link == NULL)
230 return _dbus_list_append (list, data);
233 link = alloc_link (data);
237 link_before (list, before_this_link, link);
244 * Inserts data into the list after the given existing link.
246 * @param list the list to modify
247 * @param after_this_link existing link to insert after, or #NULL to prepend
248 * @param data the value to insert
249 * @returns #TRUE on success, #FALSE if memory allocation fails
252 _dbus_list_insert_after (DBusList **list,
253 DBusList *after_this_link,
258 if (after_this_link == NULL)
259 return _dbus_list_prepend (list, data);
262 link = alloc_link (data);
266 link_after (list, after_this_link, link);
273 * Removes a value from the list. Only removes the
274 * first value equal to the given data pointer,
275 * even if multiple values exist which match.
276 * This is a linear-time operation.
278 * @param list address of the list head.
279 * @param data the value to remove.
280 * @returns #TRUE if a value was found to remove.
283 _dbus_list_remove (DBusList **list,
291 if (link->data == data)
293 _dbus_list_remove_link (list, link);
297 link = _dbus_list_get_next_link (list, link);
304 * Removes a link from the list. This is a constant-time operation.
306 * @param list address of the list head.
307 * @param link the list link to remove.
310 _dbus_list_remove_link (DBusList **list,
313 if (link->next == link)
315 /* one-element list */
321 link->prev->next = link->next;
322 link->next->prev = link->prev;
332 * Frees all links in the list and sets the list head to #NULL. Does
333 * not free the data in each link, for obvious reasons. This is a
334 * linear-time operation.
336 * @param list address of the list head.
339 _dbus_list_clear (DBusList **list)
346 DBusList *next = _dbus_list_get_next_link (list, link);
357 * Gets the first link in the list.
358 * This is a constant-time operation.
360 * @param list address of the list head.
361 * @returns the first link, or #NULL for an empty list.
364 _dbus_list_get_first_link (DBusList **list)
370 * Gets the last link in the list.
371 * This is a constant-time operation.
373 * @param list address of the list head.
374 * @returns the last link, or #NULL for an empty list.
377 _dbus_list_get_last_link (DBusList **list)
382 return (*list)->prev;
386 * Gets the last data in the list.
387 * This is a constant-time operation.
389 * @param list address of the list head.
390 * @returns the last data in the list, or #NULL for an empty list.
393 _dbus_list_get_last (DBusList **list)
398 return (*list)->prev->data;
402 * Gets the first data in the list.
403 * This is a constant-time operation.
405 * @param list address of the list head.
406 * @returns the first data in the list, or #NULL for an empty list.
409 _dbus_list_get_first (DBusList **list)
414 return (*list)->data;
418 * Removes the first value in the list and returns it. This is a
419 * constant-time operation.
421 * @param list address of the list head.
422 * @returns the first data in the list, or #NULL for an empty list.
425 _dbus_list_pop_first (DBusList **list)
430 link = _dbus_list_get_first_link (list);
435 _dbus_list_remove_link (list, link);
441 * Removes the last value in the list and returns it. This is a
442 * constant-time operation.
444 * @param list address of the list head.
445 * @returns the last data in the list, or #NULL for an empty list.
448 _dbus_list_pop_last (DBusList **list)
453 link = _dbus_list_get_last_link (list);
458 _dbus_list_remove_link (list, link);
464 * Copies a list. This is a linear-time operation. If there isn't
465 * enough memory to copy the entire list, the destination list will be
468 * @param list address of the head of the list to copy.
469 * @param dest address where the copied list should be placed.
470 * @returns #TRUE on success, #FALSE if not enough memory.
473 _dbus_list_copy (DBusList **list,
478 _dbus_assert (list != dest);
485 if (!_dbus_list_append (dest, link->data))
487 /* free what we have so far */
488 _dbus_list_clear (dest);
492 link = _dbus_list_get_next_link (list, link);
499 * Gets the length of a list. This is a linear-time
502 * @param list address of the head of the list
503 * @returns number of elements in the list.
506 _dbus_list_get_length (DBusList **list)
518 link = _dbus_list_get_next_link (list, link);
525 * Calls the given function for each element in the list. The
526 * function is passed the list element as its first argument, and the
527 * given data as its second argument.
529 * @param list address of the head of the list.
530 * @param function function to call for each element.
531 * @param data extra data for the function.
535 _dbus_list_foreach (DBusList **list,
536 DBusForeachFunction function,
544 DBusList *next = _dbus_list_get_next_link (list, link);
546 (* function) (link->data, data);
554 #ifdef DBUS_BUILD_TESTS
555 #include "dbus-test.h"
559 verify_list (DBusList **list)
569 if (link->next == link)
571 _dbus_assert (link->prev == link);
572 _dbus_assert (*list == link);
580 _dbus_assert (link->prev->next == link);
581 _dbus_assert (link->next->prev == link);
584 while (link != *list);
586 _dbus_assert (length == _dbus_list_get_length (list));
590 is_ascending_sequence (DBusList **list)
595 prev = _DBUS_INT_MIN;
597 link = _dbus_list_get_first_link (list);
600 int v = _DBUS_POINTER_TO_INT (link->data);
607 link = _dbus_list_get_next_link (list, link);
614 is_descending_sequence (DBusList **list)
619 prev = _DBUS_INT_MAX;
621 link = _dbus_list_get_first_link (list);
624 int v = _DBUS_POINTER_TO_INT (link->data);
631 link = _dbus_list_get_next_link (list, link);
638 all_even_values (DBusList **list)
642 link = _dbus_list_get_first_link (list);
645 int v = _DBUS_POINTER_TO_INT (link->data);
650 link = _dbus_list_get_next_link (list, link);
657 all_odd_values (DBusList **list)
661 link = _dbus_list_get_first_link (list);
664 int v = _DBUS_POINTER_TO_INT (link->data);
669 link = _dbus_list_get_next_link (list, link);
676 lists_equal (DBusList **list1,
682 link1 = _dbus_list_get_first_link (list1);
683 link2 = _dbus_list_get_first_link (list2);
684 while (link1 && link2)
686 if (link1->data != link2->data)
689 link1 = _dbus_list_get_next_link (list1, link1);
690 link2 = _dbus_list_get_next_link (list2, link2);
700 * @ingroup DBusListInternals
701 * Unit test for DBusList
702 * @returns #TRUE on success.
705 _dbus_list_test (void)
718 /* Test append and prepend */
723 if (!_dbus_list_append (&list1, _DBUS_INT_TO_POINTER (i)))
724 _dbus_assert_not_reached ("could not allocate for append");
726 if (!_dbus_list_prepend (&list2, _DBUS_INT_TO_POINTER (i)))
727 _dbus_assert_not_reached ("count not allocate for prepend");
730 verify_list (&list1);
731 verify_list (&list2);
733 _dbus_assert (_dbus_list_get_length (&list1) == i);
734 _dbus_assert (_dbus_list_get_length (&list2) == i);
737 _dbus_assert (is_ascending_sequence (&list1));
738 _dbus_assert (is_descending_sequence (&list2));
740 /* Test list clear */
741 _dbus_list_clear (&list1);
742 _dbus_list_clear (&list2);
744 verify_list (&list1);
745 verify_list (&list2);
747 /* Test get_first, get_last, pop_first, pop_last */
752 _dbus_list_append (&list1, _DBUS_INT_TO_POINTER (i));
753 _dbus_list_prepend (&list2, _DBUS_INT_TO_POINTER (i));
766 got_data1 = _dbus_list_get_last (&list1);
767 got_data2 = _dbus_list_get_first (&list2);
769 data1 = _dbus_list_pop_last (&list1);
770 data2 = _dbus_list_pop_first (&list2);
772 _dbus_assert (got_data1 == data1);
773 _dbus_assert (got_data2 == data2);
775 _dbus_assert (_DBUS_POINTER_TO_INT (data1) == i);
776 _dbus_assert (_DBUS_POINTER_TO_INT (data2) == i);
778 verify_list (&list1);
779 verify_list (&list2);
781 _dbus_assert (is_ascending_sequence (&list1));
782 _dbus_assert (is_descending_sequence (&list2));
787 _dbus_assert (list1 == NULL);
788 _dbus_assert (list2 == NULL);
795 _dbus_list_append (&list1, _DBUS_INT_TO_POINTER (i));
796 _dbus_list_prepend (&list2, _DBUS_INT_TO_POINTER (i));
799 verify_list (&list1);
800 verify_list (&list2);
802 _dbus_assert (_dbus_list_get_length (&list1) == i);
803 _dbus_assert (_dbus_list_get_length (&list2) == i);
806 _dbus_assert (is_ascending_sequence (&list1));
807 _dbus_assert (is_descending_sequence (&list2));
810 link2 = _dbus_list_get_first_link (&list2);
811 while (link2 != NULL)
813 verify_list (&link2); /* pretend this link is the head */
815 _dbus_assert (_DBUS_POINTER_TO_INT (link2->data) == i);
817 link2 = _dbus_list_get_next_link (&list2, link2);
822 link1 = _dbus_list_get_first_link (&list1);
823 while (link1 != NULL)
825 verify_list (&link1); /* pretend this link is the head */
827 _dbus_assert (_DBUS_POINTER_TO_INT (link1->data) == i);
829 link1 = _dbus_list_get_next_link (&list1, link1);
833 _dbus_list_clear (&list1);
834 _dbus_list_clear (&list2);
841 _dbus_list_append (&list1, _DBUS_INT_TO_POINTER (i));
842 _dbus_list_prepend (&list2, _DBUS_INT_TO_POINTER (i));
851 if (!_dbus_list_remove (&list1, _DBUS_INT_TO_POINTER (i)))
852 _dbus_assert_not_reached ("element should have been in list");
853 if (!_dbus_list_remove (&list2, _DBUS_INT_TO_POINTER (i)))
854 _dbus_assert_not_reached ("element should have been in list");
856 verify_list (&list1);
857 verify_list (&list2);
862 _dbus_assert (all_odd_values (&list1));
863 _dbus_assert (all_odd_values (&list2));
865 _dbus_list_clear (&list1);
866 _dbus_list_clear (&list2);
868 /* test removing the other half of the elements */
873 _dbus_list_append (&list1, _DBUS_INT_TO_POINTER (i));
874 _dbus_list_prepend (&list2, _DBUS_INT_TO_POINTER (i));
883 if (!_dbus_list_remove (&list1, _DBUS_INT_TO_POINTER (i)))
884 _dbus_assert_not_reached ("element should have been in list");
885 if (!_dbus_list_remove (&list2, _DBUS_INT_TO_POINTER (i)))
886 _dbus_assert_not_reached ("element should have been in list");
888 verify_list (&list1);
889 verify_list (&list2);
894 _dbus_assert (all_even_values (&list1));
895 _dbus_assert (all_even_values (&list2));
897 /* clear list using remove_link */
898 while (list1 != NULL)
900 _dbus_list_remove_link (&list1, list1);
901 verify_list (&list1);
903 while (list2 != NULL)
905 _dbus_list_remove_link (&list2, list2);
906 verify_list (&list2);
909 /* Test remove link more generally */
913 _dbus_list_append (&list1, _DBUS_INT_TO_POINTER (i));
914 _dbus_list_prepend (&list2, _DBUS_INT_TO_POINTER (i));
919 link2 = _dbus_list_get_first_link (&list2);
920 while (link2 != NULL)
922 DBusList *next = _dbus_list_get_next_link (&list2, link2);
924 _dbus_assert (_DBUS_POINTER_TO_INT (link2->data) == i);
927 _dbus_list_remove_link (&list2, link2);
929 verify_list (&list2);
935 _dbus_assert (all_odd_values (&list2));
936 _dbus_list_clear (&list2);
939 link1 = _dbus_list_get_first_link (&list1);
940 while (link1 != NULL)
942 DBusList *next = _dbus_list_get_next_link (&list1, link1);
944 _dbus_assert (_DBUS_POINTER_TO_INT (link1->data) == i);
947 _dbus_list_remove_link (&list1, link1);
949 verify_list (&list1);
955 _dbus_assert (all_even_values (&list1));
956 _dbus_list_clear (&list1);
958 /* Test copying a list */
962 _dbus_list_append (&list1, _DBUS_INT_TO_POINTER (i));
963 _dbus_list_prepend (&list2, _DBUS_INT_TO_POINTER (i));
967 /* bad pointers, because they are allowed in the copy dest */
968 copy1 = _DBUS_INT_TO_POINTER (0x342234);
969 copy2 = _DBUS_INT_TO_POINTER (23);
971 _dbus_list_copy (&list1, ©1);
972 verify_list (&list1);
973 verify_list (©1);
974 _dbus_assert (lists_equal (&list1, ©1));
976 _dbus_list_copy (&list2, ©2);
977 verify_list (&list2);
978 verify_list (©2);
979 _dbus_assert (lists_equal (&list2, ©2));
981 /* Now test copying empty lists */
982 _dbus_list_clear (&list1);
983 _dbus_list_clear (&list2);
984 _dbus_list_clear (©1);
985 _dbus_list_clear (©2);
987 /* bad pointers, because they are allowed in the copy dest */
988 copy1 = _DBUS_INT_TO_POINTER (0x342234);
989 copy2 = _DBUS_INT_TO_POINTER (23);
991 _dbus_list_copy (&list1, ©1);
992 verify_list (&list1);
993 verify_list (©1);
994 _dbus_assert (lists_equal (&list1, ©1));
996 _dbus_list_copy (&list2, ©2);
997 verify_list (&list2);
998 verify_list (©2);
999 _dbus_assert (lists_equal (&list2, ©2));
1001 _dbus_list_clear (&list1);
1002 _dbus_list_clear (&list2);
1004 /* insert_before on empty list */
1005 _dbus_list_insert_before (&list1, NULL,
1006 _DBUS_INT_TO_POINTER (0));
1007 verify_list (&list1);
1009 /* inserting before first element */
1010 _dbus_list_insert_before (&list1, list1,
1011 _DBUS_INT_TO_POINTER (2));
1012 verify_list (&list1);
1013 _dbus_assert (is_descending_sequence (&list1));
1015 /* inserting in the middle */
1016 _dbus_list_insert_before (&list1, list1->next,
1017 _DBUS_INT_TO_POINTER (1));
1018 verify_list (&list1);
1019 _dbus_assert (is_descending_sequence (&list1));
1021 /* using insert_before to append */
1022 _dbus_list_insert_before (&list1, NULL,
1023 _DBUS_INT_TO_POINTER (-1));
1024 verify_list (&list1);
1025 _dbus_assert (is_descending_sequence (&list1));
1027 _dbus_list_clear (&list1);
1029 /* insert_after on empty list */
1030 _dbus_list_insert_after (&list1, NULL,
1031 _DBUS_INT_TO_POINTER (0));
1032 verify_list (&list1);
1034 /* inserting after first element */
1035 _dbus_list_insert_after (&list1, list1,
1036 _DBUS_INT_TO_POINTER (1));
1037 verify_list (&list1);
1038 _dbus_assert (is_ascending_sequence (&list1));
1040 /* inserting at the end */
1041 _dbus_list_insert_after (&list1, list1->next,
1042 _DBUS_INT_TO_POINTER (2));
1043 verify_list (&list1);
1044 _dbus_assert (is_ascending_sequence (&list1));
1046 /* using insert_after to prepend */
1047 _dbus_list_insert_after (&list1, NULL,
1048 _DBUS_INT_TO_POINTER (-1));
1049 verify_list (&list1);
1050 _dbus_assert (is_ascending_sequence (&list1));
1052 _dbus_list_clear (&list1);