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