home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: SysTools / SysTools.zip / ft-beta.zip / freetype / lib / ttlists.h < prev    next >
Encoding:
C/C++ Source or Header  |  1997-09-24  |  7.2 KB  |  164 lines
  1. /*******************************************************************
  2.  *
  3.  *  ttlists.h                                                   1.0
  4.  *
  5.  *    Generic lists routines.
  6.  *
  7.  *  Copyright 1996, 1997 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.  *  IMPORTANT NOTE :
  17.  *
  18.  *    These routines should only be used within managers. As a
  19.  *    consequence, they do not provide support for thread-safety
  20.  *    or re-entrancy.
  21.  *
  22.  ******************************************************************/
  23.  
  24. #ifndef TTLISTS_H
  25. #define TTLISTS_H
  26.  
  27. #include "ttcommon.h"
  28. #include "tttypes.h"
  29. #include "tterror.h"
  30.  
  31.   #ifdef __cplusplus
  32.   extern "C" {
  33.   #endif
  34.  
  35.   /*                                                                   */
  36.   /* A 'generic' list is made of a series of linked nodes called       */
  37.   /* 'List_Element's. Each node contains a 'data' field that is a      */
  38.   /* pointer to some listed object of any kind. The nature of the      */
  39.   /* objects of the list isn't important for now..                     */
  40.   /*                                                                   */
  41.   /*    ______      ______       ______                                */
  42.   /*   |      |    |      |     |      |                               */
  43.   /* ->| next----->| next------>| next----> NIL                        */
  44.   /*   | data |    | data |     | data |                               */
  45.   /*   |__|___|    |__|___|     |__|___|                               */
  46.   /*      |           |            |                                   */
  47.   /*      |           |            |                                   */
  48.   /*      v           v            v                                   */
  49.   /*  __________   ________    ________                                */
  50.   /* |          | |        |  |        |                               */
  51.   /* | Object A | | Obj. B |  | Obj. C |                               */
  52.   /* |__________| |        |  |________|                               */
  53.   /*              |________|                                           */
  54.   /*                                                                   */
  55.   /*                                                                   */
  56.   /* The listed objects do not necessarily contain pointers to their   */
  57.   /* own list element..                                                */
  58.   /*                                                                   */
  59.   /* Note that the structure of TList_Element may change in the        */
  60.   /* future. For example, we may decide to include the address         */
  61.   /* of a destructor for the listed object. For this reason, only      */
  62.   /* the code present in this component and in the central object      */
  63.   /* manager should access directly the fields of TList_Element..      */
  64.   /*                                                                   */
  65.   /* IMPLEMENTATION NOTE :                                             */
  66.   /*                                                                   */
  67.   /* Discarded nodes are recycled in a simple internal list called     */
  68.   /* 'Free_Elements'.                                                  */
  69.   /*                                                                   */
  70.  
  71.   struct _TList_Element;
  72.  
  73.   typedef struct _TList_Element  TList_Element;
  74.   typedef TList_Element*         PList_Element;
  75.  
  76.   struct _TList_Element
  77.   {
  78.     PList_Element  next;
  79.     void*          data;
  80.   };
  81.   /* Simple list node record. A list element is said to be 'unlinked' */
  82.   /* when it doesn't belong to any list                               */
  83.  
  84.   struct _TSingle_List
  85.   {
  86.     PList_Element  head;
  87.     PList_Element  tail;
  88.   };
  89.   typedef struct _TSingle_List  TSingle_List;
  90.   /* Simple singly-linked list record */
  91.  
  92.   #define ZERO_List( list ) \
  93.           { (list).head = NULL; (list).tail = NULL; }
  94.  
  95.   /********************************************************/
  96.   /*                                                      */
  97.   /* Two functions used to manage list elements           */
  98.   /*                                                      */
  99.   /* The elements are extracted or recycled from/into     */
  100.   /* a given engine instance..                            */
  101.   /*                                                      */
  102.  
  103.   PList_Element  Element_New();
  104.   /* Returns a new list element, either fresh or recycled */
  105.   /* Note : the returned element is unlinked              */
  106.  
  107.   void Element_Done( PList_Element      element );
  108.   /* Recycles or discards an element.                     */
  109.   /* Note : The element must be unlinked !!               */
  110.  
  111.  
  112.   /********************************************************/
  113.   /*                                                      */
  114.   /* Several functions to manage single linked list.      */
  115.   /*                                                      */
  116.   /* Note that all these functions assume that the lists  */
  117.   /* are already protected against concurrent operations  */
  118.   /* (parsing, modification..)                            */
  119.   /*                                                      */
  120.  
  121.   void List_Add( TSingle_List*  list,
  122.                  PList_Element  element );
  123.   /* Adds one element to the end of a single list         */
  124.   /* Note : The element must be unlinked !!               */
  125.   /*        Always returns True.                          */
  126.   /*                                                      */
  127.  
  128.   TT_Error List_Remove( TSingle_List*  list,
  129.                         PList_Element  element );
  130.   /* Removes one element from one list                        */
  131.   /* Note : The element must be in the argument list before   */
  132.   /*        the call. It will be unlinked after the call, and */
  133.   /*        may be discarded through 'Done_List_Element'..    */
  134.   /*                                                          */
  135.   /* returns NULL in case of failure, otherwise returns       */
  136.   /* simply 'element'..                                       */
  137.   /*                                                          */
  138.  
  139.   PList_Element  List_Find( TSingle_List*  list,
  140.                             void*          data );
  141.   /* Finds in a list the element corresponding to the object  */
  142.   /* pointed by 'data'                                        */
  143.  
  144.   PList_Element  List_Extract( TSingle_List*  list );
  145.   /* returns and extracts the first element of a list, if any. Useful */
  146.   /* for recycle lists where any element can be taken for reuse.      */
  147.  
  148.   /********************************************************/
  149.   /*                                                      */
  150.   /* The component's initializer and finalizer.           */
  151.   /*                                                      */
  152.  
  153.   TT_Error  TTLists_Init();
  154.   /* Initializes the lists component */
  155.  
  156.   TT_Error  TTLists_Done();
  157.   /* Finalizes the lists component */
  158.  
  159.   #ifdef __cplusplus
  160.   }
  161.   #endif
  162.  
  163. #endif /* TTLISTS_H */
  164.