1 /***************************************************************************/ |
1 /**************************************************************************** |
2 /* */ |
2 * |
3 /* ftlist.h */ |
3 * ftlist.h |
4 /* */ |
4 * |
5 /* Generic list support for FreeType (specification). */ |
5 * Generic list support for FreeType (specification). |
6 /* */ |
6 * |
7 /* Copyright 1996-2018 by */ |
7 * Copyright (C) 1996-2019 by |
8 /* David Turner, Robert Wilhelm, and Werner Lemberg. */ |
8 * David Turner, Robert Wilhelm, and Werner Lemberg. |
9 /* */ |
9 * |
10 /* This file is part of the FreeType project, and may only be used, */ |
10 * This file is part of the FreeType project, and may only be used, |
11 /* modified, and distributed under the terms of the FreeType project */ |
11 * modified, and distributed under the terms of the FreeType project |
12 /* license, LICENSE.TXT. By continuing to use, modify, or distribute */ |
12 * license, LICENSE.TXT. By continuing to use, modify, or distribute |
13 /* this file you indicate that you have read the license and */ |
13 * this file you indicate that you have read the license and |
14 /* understand and accept it fully. */ |
14 * understand and accept it fully. |
15 /* */ |
15 * |
16 /***************************************************************************/ |
16 */ |
17 |
17 |
18 |
18 |
19 /*************************************************************************/ |
19 /************************************************************************** |
20 /* */ |
20 * |
21 /* This file implements functions relative to list processing. Its */ |
21 * This file implements functions relative to list processing. Its data |
22 /* data structures are defined in `freetype.h'. */ |
22 * structures are defined in `freetype.h`. |
23 /* */ |
23 * |
24 /*************************************************************************/ |
24 */ |
25 |
25 |
26 |
26 |
27 #ifndef FTLIST_H_ |
27 #ifndef FTLIST_H_ |
28 #define FTLIST_H_ |
28 #define FTLIST_H_ |
29 |
29 |
39 |
39 |
40 |
40 |
41 FT_BEGIN_HEADER |
41 FT_BEGIN_HEADER |
42 |
42 |
43 |
43 |
44 /*************************************************************************/ |
44 /************************************************************************** |
45 /* */ |
45 * |
46 /* <Section> */ |
46 * @section: |
47 /* list_processing */ |
47 * list_processing |
48 /* */ |
48 * |
49 /* <Title> */ |
49 * @title: |
50 /* List Processing */ |
50 * List Processing |
51 /* */ |
51 * |
52 /* <Abstract> */ |
52 * @abstract: |
53 /* Simple management of lists. */ |
53 * Simple management of lists. |
54 /* */ |
54 * |
55 /* <Description> */ |
55 * @description: |
56 /* This section contains various definitions related to list */ |
56 * This section contains various definitions related to list processing |
57 /* processing using doubly-linked nodes. */ |
57 * using doubly-linked nodes. |
58 /* */ |
58 * |
59 /* <Order> */ |
59 * @order: |
60 /* FT_List */ |
60 * FT_List |
61 /* FT_ListNode */ |
61 * FT_ListNode |
62 /* FT_ListRec */ |
62 * FT_ListRec |
63 /* FT_ListNodeRec */ |
63 * FT_ListNodeRec |
64 /* */ |
64 * |
65 /* FT_List_Add */ |
65 * FT_List_Add |
66 /* FT_List_Insert */ |
66 * FT_List_Insert |
67 /* FT_List_Find */ |
67 * FT_List_Find |
68 /* FT_List_Remove */ |
68 * FT_List_Remove |
69 /* FT_List_Up */ |
69 * FT_List_Up |
70 /* FT_List_Iterate */ |
70 * FT_List_Iterate |
71 /* FT_List_Iterator */ |
71 * FT_List_Iterator |
72 /* FT_List_Finalize */ |
72 * FT_List_Finalize |
73 /* FT_List_Destructor */ |
73 * FT_List_Destructor |
74 /* */ |
74 * |
75 /*************************************************************************/ |
75 */ |
76 |
76 |
77 |
77 |
78 /*************************************************************************/ |
78 /************************************************************************** |
79 /* */ |
79 * |
80 /* <Function> */ |
80 * @function: |
81 /* FT_List_Find */ |
81 * FT_List_Find |
82 /* */ |
82 * |
83 /* <Description> */ |
83 * @description: |
84 /* Find the list node for a given listed object. */ |
84 * Find the list node for a given listed object. |
85 /* */ |
85 * |
86 /* <Input> */ |
86 * @input: |
87 /* list :: A pointer to the parent list. */ |
87 * list :: |
88 /* data :: The address of the listed object. */ |
88 * A pointer to the parent list. |
89 /* */ |
89 * data :: |
90 /* <Return> */ |
90 * The address of the listed object. |
91 /* List node. NULL if it wasn't found. */ |
91 * |
92 /* */ |
92 * @return: |
|
93 * List node. `NULL` if it wasn't found. |
|
94 */ |
93 FT_EXPORT( FT_ListNode ) |
95 FT_EXPORT( FT_ListNode ) |
94 FT_List_Find( FT_List list, |
96 FT_List_Find( FT_List list, |
95 void* data ); |
97 void* data ); |
96 |
98 |
97 |
99 |
98 /*************************************************************************/ |
100 /************************************************************************** |
99 /* */ |
101 * |
100 /* <Function> */ |
102 * @function: |
101 /* FT_List_Add */ |
103 * FT_List_Add |
102 /* */ |
104 * |
103 /* <Description> */ |
105 * @description: |
104 /* Append an element to the end of a list. */ |
106 * Append an element to the end of a list. |
105 /* */ |
107 * |
106 /* <InOut> */ |
108 * @inout: |
107 /* list :: A pointer to the parent list. */ |
109 * list :: |
108 /* node :: The node to append. */ |
110 * A pointer to the parent list. |
109 /* */ |
111 * node :: |
|
112 * The node to append. |
|
113 */ |
110 FT_EXPORT( void ) |
114 FT_EXPORT( void ) |
111 FT_List_Add( FT_List list, |
115 FT_List_Add( FT_List list, |
112 FT_ListNode node ); |
116 FT_ListNode node ); |
113 |
117 |
114 |
118 |
115 /*************************************************************************/ |
119 /************************************************************************** |
116 /* */ |
120 * |
117 /* <Function> */ |
121 * @function: |
118 /* FT_List_Insert */ |
122 * FT_List_Insert |
119 /* */ |
123 * |
120 /* <Description> */ |
124 * @description: |
121 /* Insert an element at the head of a list. */ |
125 * Insert an element at the head of a list. |
122 /* */ |
126 * |
123 /* <InOut> */ |
127 * @inout: |
124 /* list :: A pointer to parent list. */ |
128 * list :: |
125 /* node :: The node to insert. */ |
129 * A pointer to parent list. |
126 /* */ |
130 * node :: |
|
131 * The node to insert. |
|
132 */ |
127 FT_EXPORT( void ) |
133 FT_EXPORT( void ) |
128 FT_List_Insert( FT_List list, |
134 FT_List_Insert( FT_List list, |
129 FT_ListNode node ); |
135 FT_ListNode node ); |
130 |
136 |
131 |
137 |
132 /*************************************************************************/ |
138 /************************************************************************** |
133 /* */ |
139 * |
134 /* <Function> */ |
140 * @function: |
135 /* FT_List_Remove */ |
141 * FT_List_Remove |
136 /* */ |
142 * |
137 /* <Description> */ |
143 * @description: |
138 /* Remove a node from a list. This function doesn't check whether */ |
144 * Remove a node from a list. This function doesn't check whether the |
139 /* the node is in the list! */ |
145 * node is in the list! |
140 /* */ |
146 * |
141 /* <Input> */ |
147 * @input: |
142 /* node :: The node to remove. */ |
148 * node :: |
143 /* */ |
149 * The node to remove. |
144 /* <InOut> */ |
150 * |
145 /* list :: A pointer to the parent list. */ |
151 * @inout: |
146 /* */ |
152 * list :: |
|
153 * A pointer to the parent list. |
|
154 */ |
147 FT_EXPORT( void ) |
155 FT_EXPORT( void ) |
148 FT_List_Remove( FT_List list, |
156 FT_List_Remove( FT_List list, |
149 FT_ListNode node ); |
157 FT_ListNode node ); |
150 |
158 |
151 |
159 |
152 /*************************************************************************/ |
160 /************************************************************************** |
153 /* */ |
161 * |
154 /* <Function> */ |
162 * @function: |
155 /* FT_List_Up */ |
163 * FT_List_Up |
156 /* */ |
164 * |
157 /* <Description> */ |
165 * @description: |
158 /* Move a node to the head/top of a list. Used to maintain LRU */ |
166 * Move a node to the head/top of a list. Used to maintain LRU lists. |
159 /* lists. */ |
167 * |
160 /* */ |
168 * @inout: |
161 /* <InOut> */ |
169 * list :: |
162 /* list :: A pointer to the parent list. */ |
170 * A pointer to the parent list. |
163 /* node :: The node to move. */ |
171 * node :: |
164 /* */ |
172 * The node to move. |
|
173 */ |
165 FT_EXPORT( void ) |
174 FT_EXPORT( void ) |
166 FT_List_Up( FT_List list, |
175 FT_List_Up( FT_List list, |
167 FT_ListNode node ); |
176 FT_ListNode node ); |
168 |
177 |
169 |
178 |
170 /*************************************************************************/ |
179 /************************************************************************** |
171 /* */ |
180 * |
172 /* <FuncType> */ |
181 * @functype: |
173 /* FT_List_Iterator */ |
182 * FT_List_Iterator |
174 /* */ |
183 * |
175 /* <Description> */ |
184 * @description: |
176 /* An FT_List iterator function that is called during a list parse */ |
185 * An FT_List iterator function that is called during a list parse by |
177 /* by @FT_List_Iterate. */ |
186 * @FT_List_Iterate. |
178 /* */ |
187 * |
179 /* <Input> */ |
188 * @input: |
180 /* node :: The current iteration list node. */ |
189 * node :: |
181 /* */ |
190 * The current iteration list node. |
182 /* user :: A typeless pointer passed to @FT_List_Iterate. */ |
191 * |
183 /* Can be used to point to the iteration's state. */ |
192 * user :: |
184 /* */ |
193 * A typeless pointer passed to @FT_List_Iterate. Can be used to point |
|
194 * to the iteration's state. |
|
195 */ |
185 typedef FT_Error |
196 typedef FT_Error |
186 (*FT_List_Iterator)( FT_ListNode node, |
197 (*FT_List_Iterator)( FT_ListNode node, |
187 void* user ); |
198 void* user ); |
188 |
199 |
189 |
200 |
190 /*************************************************************************/ |
201 /************************************************************************** |
191 /* */ |
202 * |
192 /* <Function> */ |
203 * @function: |
193 /* FT_List_Iterate */ |
204 * FT_List_Iterate |
194 /* */ |
205 * |
195 /* <Description> */ |
206 * @description: |
196 /* Parse a list and calls a given iterator function on each element. */ |
207 * Parse a list and calls a given iterator function on each element. |
197 /* Note that parsing is stopped as soon as one of the iterator calls */ |
208 * Note that parsing is stopped as soon as one of the iterator calls |
198 /* returns a non-zero value. */ |
209 * returns a non-zero value. |
199 /* */ |
210 * |
200 /* <Input> */ |
211 * @input: |
201 /* list :: A handle to the list. */ |
212 * list :: |
202 /* iterator :: An iterator function, called on each node of the list. */ |
213 * A handle to the list. |
203 /* user :: A user-supplied field that is passed as the second */ |
214 * iterator :: |
204 /* argument to the iterator. */ |
215 * An iterator function, called on each node of the list. |
205 /* */ |
216 * user :: |
206 /* <Return> */ |
217 * A user-supplied field that is passed as the second argument to the |
207 /* The result (a FreeType error code) of the last iterator call. */ |
218 * iterator. |
208 /* */ |
219 * |
|
220 * @return: |
|
221 * The result (a FreeType error code) of the last iterator call. |
|
222 */ |
209 FT_EXPORT( FT_Error ) |
223 FT_EXPORT( FT_Error ) |
210 FT_List_Iterate( FT_List list, |
224 FT_List_Iterate( FT_List list, |
211 FT_List_Iterator iterator, |
225 FT_List_Iterator iterator, |
212 void* user ); |
226 void* user ); |
213 |
227 |
214 |
228 |
215 /*************************************************************************/ |
229 /************************************************************************** |
216 /* */ |
230 * |
217 /* <FuncType> */ |
231 * @functype: |
218 /* FT_List_Destructor */ |
232 * FT_List_Destructor |
219 /* */ |
233 * |
220 /* <Description> */ |
234 * @description: |
221 /* An @FT_List iterator function that is called during a list */ |
235 * An @FT_List iterator function that is called during a list |
222 /* finalization by @FT_List_Finalize to destroy all elements in a */ |
236 * finalization by @FT_List_Finalize to destroy all elements in a given |
223 /* given list. */ |
237 * list. |
224 /* */ |
238 * |
225 /* <Input> */ |
239 * @input: |
226 /* system :: The current system object. */ |
240 * system :: |
227 /* */ |
241 * The current system object. |
228 /* data :: The current object to destroy. */ |
242 * |
229 /* */ |
243 * data :: |
230 /* user :: A typeless pointer passed to @FT_List_Iterate. It can */ |
244 * The current object to destroy. |
231 /* be used to point to the iteration's state. */ |
245 * |
232 /* */ |
246 * user :: |
|
247 * A typeless pointer passed to @FT_List_Iterate. It can be used to |
|
248 * point to the iteration's state. |
|
249 */ |
233 typedef void |
250 typedef void |
234 (*FT_List_Destructor)( FT_Memory memory, |
251 (*FT_List_Destructor)( FT_Memory memory, |
235 void* data, |
252 void* data, |
236 void* user ); |
253 void* user ); |
237 |
254 |
238 |
255 |
239 /*************************************************************************/ |
256 /************************************************************************** |
240 /* */ |
257 * |
241 /* <Function> */ |
258 * @function: |
242 /* FT_List_Finalize */ |
259 * FT_List_Finalize |
243 /* */ |
260 * |
244 /* <Description> */ |
261 * @description: |
245 /* Destroy all elements in the list as well as the list itself. */ |
262 * Destroy all elements in the list as well as the list itself. |
246 /* */ |
263 * |
247 /* <Input> */ |
264 * @input: |
248 /* list :: A handle to the list. */ |
265 * list :: |
249 /* */ |
266 * A handle to the list. |
250 /* destroy :: A list destructor that will be applied to each element */ |
267 * |
251 /* of the list. Set this to NULL if not needed. */ |
268 * destroy :: |
252 /* */ |
269 * A list destructor that will be applied to each element of the list. |
253 /* memory :: The current memory object that handles deallocation. */ |
270 * Set this to `NULL` if not needed. |
254 /* */ |
271 * |
255 /* user :: A user-supplied field that is passed as the last */ |
272 * memory :: |
256 /* argument to the destructor. */ |
273 * The current memory object that handles deallocation. |
257 /* */ |
274 * |
258 /* <Note> */ |
275 * user :: |
259 /* This function expects that all nodes added by @FT_List_Add or */ |
276 * A user-supplied field that is passed as the last argument to the |
260 /* @FT_List_Insert have been dynamically allocated. */ |
277 * destructor. |
261 /* */ |
278 * |
|
279 * @note: |
|
280 * This function expects that all nodes added by @FT_List_Add or |
|
281 * @FT_List_Insert have been dynamically allocated. |
|
282 */ |
262 FT_EXPORT( void ) |
283 FT_EXPORT( void ) |
263 FT_List_Finalize( FT_List list, |
284 FT_List_Finalize( FT_List list, |
264 FT_List_Destructor destroy, |
285 FT_List_Destructor destroy, |
265 FT_Memory memory, |
286 FT_Memory memory, |
266 void* user ); |
287 void* user ); |