Tue, 05 Oct 2021 12:23:46 +0200
add documentation for list.h
1 /*
2 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
3 *
4 * Copyright 2021 Mike Becker, Olaf Wintermann All rights reserved.
5 *
6 * Redistribution and use in source and binary forms, with or without
7 * modification, are permitted provided that the following conditions are met:
8 *
9 * 1. Redistributions of source code must retain the above copyright
10 * notice, this list of conditions and the following disclaimer.
11 *
12 * 2. Redistributions in binary form must reproduce the above copyright
13 * notice, this list of conditions and the following disclaimer in the
14 * documentation and/or other materials provided with the distribution.
15 *
16 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
17 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
18 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
19 * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
20 * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
21 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
22 * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
23 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
24 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
25 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
26 * POSSIBILITY OF SUCH DAMAGE.
27 */
28 /**
29 * \file list.h
30 * \brief Interface for list implementations.
31 * \author Mike Becker
32 * \author Olaf Wintermann
33 * \version 3.0
34 * \copyright 2-Clause BSD License
35 */
37 #ifndef UCX_LIST_H
38 #define UCX_LIST_H
40 #include <stdlib.h>
41 #include "allocator.h"
43 #ifdef __cplusplus
44 extern "C" {
45 #endif
47 /**
48 * A comparator function comparing two list elements.
49 */
50 typedef int(*CxListComparator)(void const *left, void const *right);
52 /**
53 * Internal type for the list structure - use CxList instead.
54 */
55 typedef struct cx_list_s cx_list_s;
57 /**
58 * The class definition for arbitrary lists.
59 */
60 typedef struct {
61 /**
62 * Member function for adding an element.
63 */
64 int (*add)(cx_list_s *list, void *elem);
66 /**
67 * Member function for inserting an element.
68 */
69 int (*insert)(cx_list_s *list, size_t index, void *elem);
71 /**
72 * Member function for removing an element.
73 */
74 int (*remove)(cx_list_s *list, size_t index);
76 /**
77 * Member function for element lookup.
78 */
79 void *(*at)(cx_list_s *list, size_t index);
81 /**
82 * Member function for finding an element.
83 */
84 size_t (*find)(cx_list_s *list, void *elem);
86 /**
87 * Member function for retrieving the last element.
88 */
89 void *(*last)(cx_list_s *list);
90 } cx_list_class;
92 /**
93 * Structure for holding the base data of a list.
94 */
95 struct cx_list_s {
96 /**
97 * The list class definition.
98 */
99 cx_list_class *cl;
100 /**
101 * The allocator to use.
102 */
103 CxAllocator allocator;
104 /**
105 * The comparator function for the elements.
106 */
107 CxListComparator cmpfunc;
108 /**
109 * The size of each element (payload only).
110 */
111 size_t itemsize;
112 /**
113 * The size of the list (number of currently stored elements).
114 */
115 size_t size;
116 /**
117 * The capacity of the list (maximum number of elements).
118 */
119 size_t capacity;
120 };
122 /**
123 * Common type for all list implementations.
124 */
125 typedef cx_list_s *CxList;
127 /**
128 * Adds an item to the end of the list.
129 *
130 * \remark It is implementation defined whether
131 * the contents of the element are copied or the
132 * pointer is added to the list. In the latter case
133 * the \c itemsize of the list SHALL be \c sizeof(void*).
134 *
135 * @param list the list
136 * @param elem a pointer to the element to add
137 * @return zero on success, non-zero on memory allocation failure
138 */
139 int cxListAdd(CxList list, void *elem);
141 /**
142 * Inserts an item at the specified index.
143 *
144 * If \p index equals the list \c size, this is effectively cxListAdd().
145 *
146 * \remark It is implementation defined whether
147 * the contents of the element are copied or the
148 * pointer is added to the list. In the latter case
149 * the \c itemsize of the list SHALL be \c sizeof(void*).
150 *
151 * @param list the list
152 * @param index the index the element shall have
153 * @param elem a pointer to the element to add
154 * @return zero on success, non-zero on memory allocation failure
155 * or when the index is out of bounds
156 */
157 int cxListInsert(CxList list, size_t index, void *elem);
159 /**
160 * Removes the element at the specified index.
161 * @param list the list
162 * @param index the index of the element
163 * @return zero on success, non-zero if the index is out of bounds
164 */
165 int cxListRemove(CxList list, size_t index);
167 /**
168 * Returns a pointer to the element at the specified index.
169 *
170 * @param list the list
171 * @param index the index of the element
172 * @return a pointer to the element or \c NULL if the index is out of bounds
173 */
174 void *cxListAt(CxList list, size_t index);
176 /**
177 * Returns the index of the first element that equals \p elem.
178 *
179 * Determining equality is performed by the list's comparator function.
180 *
181 * @param list the list
182 * @param elem the element to find
183 * @return the index of the element or \c (size+1) if the element is not found
184 */
185 size_t cxListFind(CxList list, void *elem);
187 /**
188 * Returns a pointer to the last element of the list.
189 *
190 * This is effectively the same as cxListAt() with \c index=size-1, but
191 * this implementation may be more efficient depending on the list structure
192 * and the conrecte implementation of cxListAt().
193 *
194 * @param list the list
195 * @return a pointer to the last element or \c NULL if the list is empty
196 */
197 void *cxListLast(CxList list);
199 #ifdef __cplusplus
200 } /* extern "C" */
201 #endif
203 #endif /* UCX_LIST_H */