zephyr/zwgc/dictionary.h

   1 /* This file is part of the Project Athena Zephyr Notification System.
   2  * It is one of the source files comprising zwgc, the Zephyr WindowGram
   3  * client.
   4  *
   5  *      Created by:     Marc Horowitz <marc@athena.mit.edu>
   6  *
   7  *      $Id$
   8  *
   9  *      Copyright (c) 1989 by the Massachusetts Institute of Technology.
  10  *      For copying and distribution information, see the file
  11  *      "mit-copyright.h".
  12  */
  13
  14 #ifndef TYPE_T_dictionary_TYPE
  15 #define TYPE_T_dictionary_TYPE
  16
  17 typedef struct _TYPE_T_dictionary_binding {
  18     struct _TYPE_T_dictionary_binding *next;       /* PRIVATE */
  19     char *key;                                     /* READ-ONLY */
  20     TYPE_T value;
  21 } TYPE_T_dictionary_binding;
  22
  23 typedef struct _TYPE_T_dictionary {                /* PRIVATE */
  24     int size;
  25     TYPE_T_dictionary_binding **slots;
  26 } *TYPE_T_dictionary;
  27
  28 /*
  29  *    TYPE_T_dictionary TYPE_T_dictionary_Create(int size):
  30  *        Requires: size > 0
  31  *        Effects: Returns a new empty dictionary containing no bindings.
  32  *                 The returned dictionary must be destroyed using
  33  *                 TYPE_T_dictionary_Destroy.  Size is a time vs space
  34  *                 parameter.  For this implementation, space used is
  35  *                 proportional to size and time used is proportional
  36  *                 to number of bindings divided by size.  It is preferable
  37  *                 that size is a prime number.
  38  */
  39
  40 extern TYPE_T_dictionary TYPE_T_dictionary_Create(int);
  41
  42 /*
  43  *    void TYPE_T_dictionary_Destroy(TYPE_T_dictionary d):
  44  *        Requires: d is a non-destroyed TYPE_T_dictionary
  45  *        Modifies: d
  46  *        Effects: Destroys dictionary d freeing up the space it consumes.
  47  *                 Dictionary d should never be referenced again.  Note that
  48  *                 free is NOT called on the values of the bindings.  If
  49  *                 this is needed, the client must do this first using
  50  *                 TYPE_T_dictionary_Enumerate.
  51  */
  52
  53 extern void TYPE_T_dictionary_Destroy(TYPE_T_dictionary);
  54
  55 /*
  56  *    void TYPE_T_dictionary_Enumerate(TYPE_T_dictionary d;
  57  *                                     void (*proc)(TYPE_T_dictionary_binding *b)):
  58  *        Requires: proc is a void procedure taking 1 argument, a
  59  *                  TYPE_T_dictionary_binding pointer, which does not
  60  *                  make any calls using dictionary d.
  61  *        Effects: Calls proc once with each binding in dictionary d.
  62  *                 Order of bindings passed is undefined.  Note that
  63  *                 only the value field of the binding should be considered
  64  *                 writable by proc.
  65  */
  66
  67 extern void TYPE_T_dictionary_Enumerate(TYPE_T_dictionary, void (*)(TYPE_T_dictionary_binding *));
  68
  69 /*
  70  *    TYPE_T_dictionary_binding *TYPE_T_dictionary_Lookup(TYPE_T_dictionary d,
  71  *                                                        char *key):
  72  *        Effects: If key is not bound in d, returns 0.  Othersize,
  73  *                 returns a pointer to the binding that binds key.
  74  *                 Note the access restrictions on bindings...
  75  */
  76
  77 extern TYPE_T_dictionary_binding *TYPE_T_dictionary_Lookup(TYPE_T_dictionary,
  78                                                            char *);
  79
  80 /*
  81  *    TYPE_T_dictionary_binding *TYPE_T_dictionary_Define(TYPE_T_dictionary d,
  82  *                                            char *key,
  83  *                                            int *already_existed):
  84  *        Modifies: d
  85  *        Effects: If key is bound in d, returns a pointer to the binding
  86  *                 that binds key.  Otherwise, adds a binding of key to
  87  *                 d and returns its address.  If already_existed is non-zero
  88  *                 then *already_existed is set to 0 if key was not
  89  *                 previously bound in d and 1 otherwise.
  90  *                 Note the access restrictions on bindings...  Note also
  91  *                 that the value that key is bounded to if a binding is
  92  *                 created is undefined.  The caller should set the value
  93  *                 in this case.
  94  */
  95
  96 extern TYPE_T_dictionary_binding *TYPE_T_dictionary_Define(TYPE_T_dictionary,
  97                                                            char *, int *);
  98
  99 /*
 100  *    void TYPE_T_dictionary_Delete(TYPE_T_dictionary d,
 101  *                                  TYPE_T_dictionary_binding *b):
 102  *        Requires: *b is a binding in d.
 103  *        Modifies: d
 104  *        Effects: Removes the binding *b from d.  Note that if
 105  *                 b->value needs to be freed, it should be freed
 106  *                 before making this call.
 107  */
 108
 109 extern void TYPE_T_dictionary_Delete(TYPE_T_dictionary,
 110                                      TYPE_T_dictionary_binding *);
 111
 112 #endif