1 /***************************************************************************/ 2 /* */ 3 /* ftlist.h */ 4 /* */ 5 /* Generic list support for FreeType (specification). */ 6 /* */ 7 /* Copyright 1996-2018 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 */ 22 /* data 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 */ 57 /* processing 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 :: A pointer to the parent list. */ 88 /* data :: The address of the listed object. */ 89 /* */ 90 /* <Return> */ 91 /* List node. NULL if it wasn't found. */ 92 /* */ 93 FT_EXPORT( FT_ListNode ) 94 FT_List_Find( FT_List list, 95 void* data ); 96 97 98 /*************************************************************************/ 99 /* */ 100 /* <Function> */ 101 /* FT_List_Add */ 102 /* */ 103 /* <Description> */ 104 /* Append an element to the end of a list. */ 105 /* */ 106 /* <InOut> */ 107 /* list :: A pointer to the parent list. */ 108 /* node :: The node to append. */ 109 /* */ 110 FT_EXPORT( void ) 111 FT_List_Add( FT_List list, 112 FT_ListNode node ); 113 114 115 /*************************************************************************/ 116 /* */ 117 /* <Function> */ 118 /* FT_List_Insert */ 119 /* */ 120 /* <Description> */ 121 /* Insert an element at the head of a list. */ 122 /* */ 123 /* <InOut> */ 124 /* list :: A pointer to parent list. */ 125 /* node :: The node to insert. */ 126 /* */ 127 FT_EXPORT( void ) 128 FT_List_Insert( FT_List list, 129 FT_ListNode node ); 130 131 132 /*************************************************************************/ 133 /* */ 134 /* <Function> */ 135 /* FT_List_Remove */ 136 /* */ 137 /* <Description> */ 138 /* Remove a node from a list. This function doesn't check whether */ 139 /* the node is in the list! */ 140 /* */ 141 /* <Input> */ 142 /* node :: The node to remove. */ 143 /* */ 144 /* <InOut> */ 145 /* list :: A pointer to the parent list. */ 146 /* */ 147 FT_EXPORT( void ) 148 FT_List_Remove( FT_List list, 149 FT_ListNode node ); 150 151 152 /*************************************************************************/ 153 /* */ 154 /* <Function> */ 155 /* FT_List_Up */ 156 /* */ 157 /* <Description> */ 158 /* Move a node to the head/top of a list. Used to maintain LRU */ 159 /* lists. */ 160 /* */ 161 /* <InOut> */ 162 /* list :: A pointer to the parent list. */ 163 /* node :: The node to move. */ 164 /* */ 165 FT_EXPORT( void ) 166 FT_List_Up( FT_List list, 167 FT_ListNode node ); 168 169 170 /*************************************************************************/ 171 /* */ 172 /* <FuncType> */ 173 /* FT_List_Iterator */ 174 /* */ 175 /* <Description> */ 176 /* An FT_List iterator function that is called during a list parse */ 177 /* by @FT_List_Iterate. */ 178 /* */ 179 /* <Input> */ 180 /* node :: The current iteration list node. */ 181 /* */ 182 /* user :: A typeless pointer passed to @FT_List_Iterate. */ 183 /* Can be used to point to the iteration's state. */ 184 /* */ 185 typedef FT_Error 186 (*FT_List_Iterator)( FT_ListNode node, 187 void* user ); 188 189 190 /*************************************************************************/ 191 /* */ 192 /* <Function> */ 193 /* FT_List_Iterate */ 194 /* */ 195 /* <Description> */ 196 /* 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 */ 198 /* returns a non-zero value. */ 199 /* */ 200 /* <Input> */ 201 /* list :: A handle to the list. */ 202 /* iterator :: An iterator function, called on each node of the list. */ 203 /* user :: A user-supplied field that is passed as the second */ 204 /* argument to the iterator. */ 205 /* */ 206 /* <Return> */ 207 /* The result (a FreeType error code) of the last iterator call. */ 208 /* */ 209 FT_EXPORT( FT_Error ) 210 FT_List_Iterate( FT_List list, 211 FT_List_Iterator iterator, 212 void* user ); 213 214 215 /*************************************************************************/ 216 /* */ 217 /* <FuncType> */ 218 /* FT_List_Destructor */ 219 /* */ 220 /* <Description> */ 221 /* An @FT_List iterator function that is called during a list */ 222 /* finalization by @FT_List_Finalize to destroy all elements in a */ 223 /* given list. */ 224 /* */ 225 /* <Input> */ 226 /* system :: The current system object. */ 227 /* */ 228 /* data :: The current object to destroy. */ 229 /* */ 230 /* user :: A typeless pointer passed to @FT_List_Iterate. It can */ 231 /* be used to point to the iteration's state. */ 232 /* */ 233 typedef void 234 (*FT_List_Destructor)( FT_Memory memory, 235 void* data, 236 void* user ); 237 238 239 /*************************************************************************/ 240 /* */ 241 /* <Function> */ 242 /* FT_List_Finalize */ 243 /* */ 244 /* <Description> */ 245 /* Destroy all elements in the list as well as the list itself. */ 246 /* */ 247 /* <Input> */ 248 /* list :: A handle to the list. */ 249 /* */ 250 /* destroy :: A list destructor that will be applied to each element */ 251 /* of the list. Set this to NULL if not needed. */ 252 /* */ 253 /* memory :: The current memory object that handles deallocation. */ 254 /* */ 255 /* user :: A user-supplied field that is passed as the last */ 256 /* argument to the destructor. */ 257 /* */ 258 /* <Note> */ 259 /* This function expects that all nodes added by @FT_List_Add or */ 260 /* @FT_List_Insert have been dynamically allocated. */ 261 /* */ 262 FT_EXPORT( void ) 263 FT_List_Finalize( FT_List list, 264 FT_List_Destructor destroy, 265 FT_Memory memory, 266 void* user ); 267 268 /* */ 269 270 271 FT_END_HEADER 272 273 #endif /* FTLIST_H_ */ 274 275 276 /* END */