include/freetype/ftlist.h

   1 /****************************************************************************
   2  *
   3  * ftlist.h
   4  *
   5  *   Generic list support for FreeType (specification).
   6  *
   7  * Copyright (C) 1996-2023 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 */