1 /**
2 * \file
3 *
4 * \brief List declaration.
5 *
6 * Copyright (C) 2014 Atmel Corporation. All rights reserved.
7 *
8 * \asf_license_start
9 *
10 * \page License
11 *
12 * Redistribution and use in source and binary forms, with or without
13 * modification, are permitted provided that the following conditions are met:
14 *
15 * 1. Redistributions of source code must retain the above copyright notice,
16 * this list of conditions and the following disclaimer.
17 *
18 * 2. Redistributions in binary form must reproduce the above copyright notice,
19 * this list of conditions and the following disclaimer in the documentation
20 * and/or other materials provided with the distribution.
21 *
22 * 3. The name of Atmel may not be used to endorse or promote products derived
23 * from this software without specific prior written permission.
24 *
25 * 4. This software may only be redistributed and used in connection with an
26 * Atmel microcontroller product.
27 *
28 * THIS SOFTWARE IS PROVIDED BY ATMEL "AS IS" AND ANY EXPRESS OR IMPLIED
29 * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
30 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT ARE
31 * EXPRESSLY AND SPECIFICALLY DISCLAIMED. IN NO EVENT SHALL ATMEL BE LIABLE FOR
32 * ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
33 * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
34 * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
35 * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
36 * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
37 * ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
38 * POSSIBILITY OF SUCH DAMAGE.
39 *
40 * \asf_license_stop
41 *
42 */
43
44 #ifndef _UTILS_LIST_H_INCLUDED
45 #define _UTILS_LIST_H_INCLUDED
46
47 #ifdef __cplusplus
48 extern "C" {
49 #endif
50
51 /**
52 * \addtogroup doc_driver_hal_utils_list
53 *
54 * @{
55 */
56
57 #include <compiler.h>
58
59 /**
60 * \brief List element type
61 */
62 struct list_element {
63 struct list_element *next;
64 };
65
66 /**
67 * \brief List head type
68 */
69 struct list_descriptor {
70 struct list_element *head;
71 };
72
73 /**
74 * \brief Reset list
75 *
76 * \param[in] list The pointer to a list descriptor
77 */
list_reset(struct list_descriptor * const list)78 static inline void list_reset(struct list_descriptor *const list)
79 {
80 list->head = NULL;
81 }
82
83 /**
84 * \brief Retrieve list head
85 *
86 * \param[in] list The pointer to a list descriptor
87 *
88 * \return A pointer to the head of the given list or NULL if the list is
89 * empty
90 */
list_get_head(const struct list_descriptor * const list)91 static inline void *list_get_head(const struct list_descriptor *const list)
92 {
93 return (void *)list->head;
94 }
95
96 /**
97 * \brief Retrieve next list head
98 *
99 * \param[in] list The pointer to a list element
100 *
101 * \return A pointer to the next list element or NULL if there is not next
102 * element
103 */
list_get_next_element(const void * const element)104 static inline void *list_get_next_element(const void *const element)
105 {
106 return element ? ((struct list_element *)element)->next : NULL;
107 }
108
109 /**
110 * \brief Insert an element as list head
111 *
112 * \param[in] list The pointer to a list element
113 * \param[in] element An element to insert to the given list
114 */
115 void list_insert_as_head(struct list_descriptor *const list, void *const element);
116
117 /**
118 * \brief Insert an element after the given list element
119 *
120 * \param[in] after An element to insert after
121 * \param[in] element Element to insert to the given list
122 */
123 void list_insert_after(void *const after, void *const element);
124
125 /**
126 * \brief Insert an element at list end
127 *
128 * \param[in] after An element to insert after
129 * \param[in] element Element to insert to the given list
130 */
131 void list_insert_at_end(struct list_descriptor *const list, void *const element);
132
133 /**
134 * \brief Check whether an element belongs to a list
135 *
136 * \param[in] list The pointer to a list
137 * \param[in] element An element to check
138 *
139 * \return The result of checking
140 * \retval true If the given element is an element of the given list
141 * \retval false Otherwise
142 */
143 bool is_list_element(const struct list_descriptor *const list, const void *const element);
144
145 /**
146 * \brief Removes list head
147 *
148 * This function removes the list head and sets the next element after the list
149 * head as a new list head.
150 *
151 * \param[in] list The pointer to a list
152 *
153 * \return The pointer to the new list head of NULL if the list head is NULL
154 */
155 void *list_remove_head(struct list_descriptor *const list);
156
157 /**
158 * \brief Removes the list element
159 *
160 * \param[in] list The pointer to a list
161 * \param[in] element An element to remove
162 *
163 * \return The result of element removing
164 * \retval true The given element is removed from the given list
165 * \retval false The given element is not an element of the given list
166 */
167 bool list_delete_element(struct list_descriptor *const list, const void *const element);
168
169 /**@}*/
170
171 #ifdef __cplusplus
172 }
173 #endif
174 #endif /* _UTILS_LIST_H_INCLUDED */
175
