1 /**
2 * \file
3 *
4 * \brief List declaration.
5 *
6 * Copyright (c) 2014-2018 Microchip Technology Inc. and its subsidiaries.
7 *
8 * \asf_license_start
9 *
10 * \page License
11 *
12 * Subject to your compliance with these terms, you may use Microchip
13 * software and any derivatives exclusively with Microchip products.
14 * It is your responsibility to comply with third party license terms applicable
15 * to your use of third party software (including open source software) that
16 * may accompany Microchip software.
17 *
18 * THIS SOFTWARE IS SUPPLIED BY MICROCHIP "AS IS". NO WARRANTIES,
19 * WHETHER EXPRESS, IMPLIED OR STATUTORY, APPLY TO THIS SOFTWARE,
20 * INCLUDING ANY IMPLIED WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY,
21 * AND FITNESS FOR A PARTICULAR PURPOSE. IN NO EVENT WILL MICROCHIP BE
22 * LIABLE FOR ANY INDIRECT, SPECIAL, PUNITIVE, INCIDENTAL OR CONSEQUENTIAL
23 * LOSS, DAMAGE, COST OR EXPENSE OF ANY KIND WHATSOEVER RELATED TO THE
24 * SOFTWARE, HOWEVER CAUSED, EVEN IF MICROCHIP HAS BEEN ADVISED OF THE
25 * POSSIBILITY OR THE DAMAGES ARE FORESEEABLE. TO THE FULLEST EXTENT
26 * ALLOWED BY LAW, MICROCHIP'S TOTAL LIABILITY ON ALL CLAIMS IN ANY WAY
27 * RELATED TO THIS SOFTWARE WILL NOT EXCEED THE AMOUNT OF FEES, IF ANY,
28 * THAT YOU HAVE PAID DIRECTLY TO MICROCHIP FOR THIS SOFTWARE.
29 *
30 * \asf_license_stop
31 *
32 */
33
34 #ifndef _UTILS_LIST_H_INCLUDED
35 #define _UTILS_LIST_H_INCLUDED
36
37 #ifdef __cplusplus
38 extern "C" {
39 #endif
40
41 /**
42 * \addtogroup doc_driver_hal_utils_list
43 *
44 * @{
45 */
46
47 #include <compiler.h>
48
49 /**
50 * \brief List element type
51 */
52 struct list_element {
53 struct list_element *next;
54 };
55
56 /**
57 * \brief List head type
58 */
59 struct list_descriptor {
60 struct list_element *head;
61 };
62
63 /**
64 * \brief Reset list
65 *
66 * \param[in] list The pointer to a list descriptor
67 */
list_reset(struct list_descriptor * const list)68 static inline void list_reset(struct list_descriptor *const list)
69 {
70 list->head = NULL;
71 }
72
73 /**
74 * \brief Retrieve list head
75 *
76 * \param[in] list The pointer to a list descriptor
77 *
78 * \return A pointer to the head of the given list or NULL if the list is
79 * empty
80 */
list_get_head(const struct list_descriptor * const list)81 static inline void *list_get_head(const struct list_descriptor *const list)
82 {
83 return (void *)list->head;
84 }
85
86 /**
87 * \brief Retrieve next list head
88 *
89 * \param[in] list The pointer to a list element
90 *
91 * \return A pointer to the next list element or NULL if there is not next
92 * element
93 */
list_get_next_element(const void * const element)94 static inline void *list_get_next_element(const void *const element)
95 {
96 return element ? ((struct list_element *)element)->next : NULL;
97 }
98
99 /**
100 * \brief Insert an element as list head
101 *
102 * \param[in] list The pointer to a list element
103 * \param[in] element An element to insert to the given list
104 */
105 void list_insert_as_head(struct list_descriptor *const list, void *const element);
106
107 /**
108 * \brief Insert an element after the given list element
109 *
110 * \param[in] after An element to insert after
111 * \param[in] element Element to insert to the given list
112 */
113 void list_insert_after(void *const after, void *const element);
114
115 /**
116 * \brief Insert an element at list end
117 *
118 * \param[in] after An element to insert after
119 * \param[in] element Element to insert to the given list
120 */
121 void list_insert_at_end(struct list_descriptor *const list, void *const element);
122
123 /**
124 * \brief Check whether an element belongs to a list
125 *
126 * \param[in] list The pointer to a list
127 * \param[in] element An element to check
128 *
129 * \return The result of checking
130 * \retval true If the given element is an element of the given list
131 * \retval false Otherwise
132 */
133 bool is_list_element(const struct list_descriptor *const list, const void *const element);
134
135 /**
136 * \brief Removes list head
137 *
138 * This function removes the list head and sets the next element after the list
139 * head as a new list head.
140 *
141 * \param[in] list The pointer to a list
142 *
143 * \return The pointer to the new list head of NULL if the list head is NULL
144 */
145 void *list_remove_head(struct list_descriptor *const list);
146
147 /**
148 * \brief Removes the list element
149 *
150 * \param[in] list The pointer to a list
151 * \param[in] element An element to remove
152 *
153 * \return The result of element removing
154 * \retval true The given element is removed from the given list
155 * \retval false The given element is not an element of the given list
156 */
157 bool list_delete_element(struct list_descriptor *const list, const void *const element);
158
159 /**@}*/
160
161 #ifdef __cplusplus
162 }
163 #endif
164 #endif /* _UTILS_LIST_H_INCLUDED */
165