include/freetype/ftlist.h

   1 /***************************************************************************/
   2 /*                                                                         */
   3 /*  ftlist.h                                                               */
   4 /*                                                                         */
   5 /*    Generic list support for FreeType (specification).                   */
   6 /*                                                                         */
   7 /*  Copyright 1996-2001, 2003, 2007, 2010 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 which 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 which 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 which 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.                                            */
 252   /*                                                                       */
 253   /*    memory  :: The current memory object which handles deallocation.   */
 254   /*                                                                       */
 255   /*    user    :: A user-supplied field which 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
 272 FT_END_HEADER
 273
 274 #endif /* __FTLIST_H__ */
 275
 276
 277 /* END */