1 /* Copyright (C) 2010-2020 The RetroArch team
3 * ---------------------------------------------------------------------------------------
4 * The following license statement only applies to this file (linked_list.h).
5 * ---------------------------------------------------------------------------------------
7 * Permission is hereby granted, free of charge,
8 * to any person obtaining a copy of this software and associated documentation files (the "Software"),
9 * to deal in the Software without restriction, including without limitation the rights to
10 * use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software,
11 * and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
13 * The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
15 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
16 * INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
18 * IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
19 * WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
23 #ifndef __LIBRETRO_SDK_LINKED_LIST_H
24 #define __LIBRETRO_SDK_LINKED_LIST_H
26 #include <retro_common_api.h>
34 * Represents a linked list. Contains any number of elements.
36 typedef struct linked_list linked_list_t;
39 * Represents an iterator for iterating over a linked list. The iterator can
40 * go through the linked list forwards or backwards.
42 typedef struct linked_list_iterator linked_list_iterator_t;
45 * Creates a new linked list with no elements.
47 * @return New linked list
49 linked_list_t *linked_list_new(void);
52 * @brief frees the memory used by the linked list
54 * Frees all of the memory used by this linked list. The values of all
55 * remaining elements are freed using the "free_value" function. Does
56 * nothing if "list" is NULL.
58 * @param list linked list to free
59 * @param free_value function to use to free remaining values
61 void linked_list_free(linked_list_t *list, void (*free_value)(void *value));
64 * @brief adds an element to the linked list
66 * Add a new element to the end of this linked list. Does nothing if
69 * @param list list to add the element to
70 * @param value new value to add to the linked list
72 void linked_list_add(linked_list_t *list, void *value);
75 * @brief inserts a value into the linked list
77 * Inserts a value into the linked list at the specified index. Does
78 * nothing if "list" is NULL.
80 * @param list list to insert the value into
81 * @param index index where the value should be inserted at (can be equal to list size)
82 * @param value value to insert into the linked list
84 void linked_list_insert(linked_list_t *list, size_t index, void *value);
87 * @brief Get the value in the linked list at the provided index.
89 * Return the value vstored in the linked list at the provided index. Does
90 * nothing if "list" is NULL.
92 * @param list list to get the value from
93 * @param index index of the value to return
94 * @return value in the list at the provided index
96 void *linked_list_get(linked_list_t *list, size_t index);
99 * @brief Get the first value that is matched by the provided function
101 * Return the first value that the function matches. The matches function
102 * parameters are value from the linked list and the provided state.
104 * @param list list to get the value from
105 * @param matches function to test the values with
106 * @param usrptr user data to pass to the matches function
107 * @return first value that matches otherwise NULL
109 void *linked_list_get_first_matching(linked_list_t *list, bool (*matches)(void *item, void *usrptr), void *usrptr);
112 * @brief Get the last value that is matched by the provided function
114 * Return the last value that the function matches. The matches function
115 * parameters are value from the linked list and the provided state.
117 * @param list list to get the value from
118 * @param matches function to test the values with
119 * @param usrptr user data to pass to the matches function
120 * @return last value that matches otherwise NULL
122 void *linked_list_get_last_matching(linked_list_t *list, bool (*matches)(void *item, void *usrptr), void *usrptr);
125 * @brief Remove the element at the provided index
127 * Removes the element of the linked list at the provided index.
129 * @param list linked list to remove the element from
130 * @param index index of the element to remove
131 * @return value of the element that was removed, NULL if list is NULL or
134 void *linked_list_remove_at(linked_list_t *list, size_t index);
137 * @brief Remove the first element with the provided value
139 * Removes the first element with a value equal to the provided value.
140 * Does nothing if "list" is NULL.
142 * @param list linked list to remove the element from
143 * @param value value of the element to remove
144 * @return value if a matching element was removed
146 void *linked_list_remove_first(linked_list_t *list, void *value);
149 * @brief Remove the last element with the provided value
151 * Removes the last element with a value equal to the provided value.
152 * Does nothing if "list" is NULL.
154 * @param list linked list to remove the element from
155 * @param value value of the element to remove
156 * @return value if a matching element was removed
158 void *linked_list_remove_last(linked_list_t *list, void *value);
161 * @brief Remove all elements with the provided value
163 * Removes all elements with a value equal to the provided value.
164 * Does nothing if "list" is NULL.
166 * @param list linked list to remove the elements from
167 * @param value value of the elements to remove
168 * @return value if any matching element(s) where removed
170 void *linked_list_remove_all(linked_list_t *list, void *value);
173 * @brief Remove the first matching element
175 * Removes the first matching element from the linked list. The "matches" function
176 * is used to test for matching element values. Does nothing if "list" is NULL.
178 * @param list linked list to remove the element from
179 * @param matches function to use for testing element values for a match
180 * @return value if a matching element was removed
182 void *linked_list_remove_first_matching(linked_list_t *list, bool (*matches)(void *value));
185 * @brief Remove the last matching element
187 * Removes the last matching element from the linked list. The "matches" function
188 * is used to test for matching element values.
190 * @param list linked list to remove the element from
191 * @param matches function to use for testing element value for a match
192 * @return value if a matching element was removed
194 void *linked_list_remove_last_matching(linked_list_t *list, bool (*matches)(void *value));
197 * @brief Remove all matching elements
199 * Removes all matching elements from the linked list. The "matches" function
200 * is used to test for matching element values. Does nothing if "list" is NULL.
202 * @param list linked list to remove the elements from
203 * @param matches function to use for testing element values for a match
205 void linked_list_remove_all_matching(linked_list_t *list, bool (*matches)(void *value));
208 * @brief Replace the value of the element at the provided index
210 * Replaces the value of the element at the provided index. The linked list must
211 * contain an element at the index.
213 * @param list linked list to replace the value in
214 * @param index index of the element to replace the value of
215 * @param value new value for the selected element
216 * @return whether an element was updated
218 bool linked_list_set_at(linked_list_t *list, size_t index, void *value);
221 * @brief Get the size of the linked list
223 * Returns the number of elements in the linked list.
225 * @param linked list to get the size of
226 * @return number of elements in the linked list, 0 if linked list is NULL
228 size_t linked_list_size(linked_list_t *list);
231 * @brief Get an iterator for the linked list
233 * Returns a new iterator for the linked list. Can be either a forward or backward
236 * @param list linked list to iterate over
237 * @param forward true for a forward iterator, false for backwards
238 * @return new iterator for the linked list in the specified direction, NULL if
241 linked_list_iterator_t *linked_list_iterator(linked_list_t *list, bool forward);
244 * @brief Move to the next element in the linked list
246 * Moves the iterator to the next element in the linked list. The direction is
247 * specified when retrieving a new iterator.
249 * @param iterator iterator for the current element
250 * @return iterator for the next element, NULL if iterator is NULL or "iterator"
251 * is at the last element
253 linked_list_iterator_t *linked_list_iterator_next(linked_list_iterator_t *iterator);
256 * @brief Get the value of the element for the iterator
258 * Returns the value of the element that the iterator is at.
260 * @param iterator iterator for the current element
261 * @return value of the element for the iterator
263 void *linked_list_iterator_value(linked_list_iterator_t *iterator);
266 * @brief Remove the element that the iterator is at
268 * Removes the element that the iterator is at. The iterator is updated to the
271 * @param iterator iterator for the current element
272 * @return updated iterator or NULL if the last element was removed
274 linked_list_iterator_t *linked_list_iterator_remove(linked_list_iterator_t *iterator);
277 * @brief Release the memory for the iterator
279 * Frees the memory for the provided iterator. Does nothing if "iterator" is NULL.
281 * @param iterator iterator to free
283 void linked_list_iterator_free(linked_list_iterator_t *iterator);
286 * @brief Apply the provided function to all values in the linked list
288 * Apply the provied function to all values in the linked list. The values are applied
289 * in the forward direction. Does nothing if "list" is NULL.
291 * @param list linked list to apply the function to
292 * @param fn function to apply to all elements
294 void linked_list_foreach(linked_list_t *list, void (*fn)(size_t index, void *value));