libraries/freetype-2.0.5/include/freetype/ftlist.h

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