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