chiark - git - mdw - mLib/blob - struct/assoc.h

   1 /* -*-c-*-
   2  *
   3  * Assocation tables
   4  *
   5  * (c) 2000 Straylight/Edgeware
   6  */
   7
   8 /*----- Licensing notice --------------------------------------------------*
   9  *
  10  * This file is part of the mLib utilities library.
  11  *
  12  * mLib is free software; you can redistribute it and/or modify
  13  * it under the terms of the GNU Library General Public License as
  14  * published by the Free Software Foundation; either version 2 of the
  15  * License, or (at your option) any later version.
  16  *
  17  * mLib is distributed in the hope that it will be useful,
  18  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  19  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  20  * GNU Library General Public License for more details.
  21  *
  22  * You should have received a copy of the GNU Library General Public
  23  * License along with mLib; if not, write to the Free
  24  * Software Foundation, Inc., 59 Temple Place - Suite 330, Boston,
  25  * MA 02111-1307, USA.
  26  */
  27
  28 #ifndef MLIB_ASSOC_H
  29 #define MLIB_ASSOC_H
  30
  31 #ifdef __cplusplus
  32   extern "C" {
  33 #endif
  34
  35 /*----- Header files ------------------------------------------------------*/
  36
  37 #ifndef MLIB_ATOM_H
  38 #  include "atom.h"
  39 #endif
  40
  41 #ifndef MLIB_HASH_H
  42 #  include "hash.h"
  43 #endif
  44
  45 /*----- Data structures ---------------------------------------------------*/
  46
  47 typedef struct assoc_table {
  48   hash_table t;
  49   size_t load;
  50 } assoc_table;
  51
  52 typedef struct assoc_base {
  53   hash_base b;
  54   atom *a;
  55 } assoc_base;
  56
  57 typedef struct { hash_iter i; } assoc_iter;
  58
  59 #define ASSOC_ATOM(p) (((assoc_base *)(p))->a + 0)
  60
  61 /*----- Functions provided ------------------------------------------------*/
  62
  63 /* --- @assoc_create@ --- *
  64  *
  65  * Arguments:   @assoc_table *t@ = pointer to an association table
  66  *
  67  * Returns:     ---
  68  *
  69  * Use:         Creates a new association table.
  70  */
  71
  72 extern void assoc_create(assoc_table */*t*/);
  73
  74 /* --- @assoc_destroy@ --- *
  75  *
  76  * Arguments:   @assoc_table *t@ = pointer to an association table
  77  *
  78  * Returns:     ---
  79  *
  80  * Use:         Destroys an association table.
  81  */
  82
  83 extern void assoc_destroy(assoc_table */*t*/);
  84
  85 /* --- @assoc_find@ --- *
  86  *
  87  * Arguments:   @assoc_table *t@ = pointer to an association table
  88  *              @atom *a@ = an atom to label the item
  89  *              @size_t sz@ = size of block to allocate
  90  *              @unsigned *f@ = pointer to `found' flag
  91  *
  92  * Returns:     A pointer to the item located or null.
  93  *
  94  * Use:         Looks up an atom in an association table.  If the atom is
  95  *              found, the association is returned.  If not, and @sz@ is
  96  *              zero, a null pointer is returned.  Otherwise, a block of size
  97  *              @sz@ is allocated, its @assoc_base@ header is filled in, and
  98  *              the pointer returned.  The flag @*f@ is cleared if the item
  99  *              couldn't be found, or set if it was.
 100  *
 101  *              All the atoms used in a particular table should come from the
 102  *              same atom table.
 103  */
 104
 105 extern void *assoc_find(assoc_table */*t*/, atom */*a*/,
 106                         size_t /*sz*/, unsigned */*f*/);
 107
 108 /* --- @assoc_remove@ --- *
 109  *
 110  * Arguments:   @assoc_table *t@ = pointer to an association table
 111  *              @void *p@ = pointer to a block to remove
 112  *
 113  * Returns:     ---
 114  *
 115  * Use:         Removes an association from a table.
 116  */
 117
 118 extern void assoc_remove(assoc_table */*t*/, void */*p*/);
 119
 120 /* --- @assoc_mkiter@, @assoc_next@ --- *
 121  *
 122  * Arguments:   @assoc_iter *i@ = pointer to an iterator
 123  *              @assoc_table *t@ = pointer to an association table
 124  *
 125  * Returns:     Next association, or null, for @assoc_next@; nothing for
 126  *              @assoc_mkiter@.
 127  *
 128  * Use:         Iterates over the associations in a table.
 129  */
 130
 131 #define ASSOC_MKITER(i_, t_) HASH_MKITER(&(i_)->i, &(t_)->t)
 132
 133 #define ASSOC_NEXT(i_, p) do {                                          \
 134   hash_base *_q;                                                        \
 135   HASH_NEXT(&(i_)->i, _q);                                              \
 136   (p) = (void *)_q;                                                     \
 137 } while (0)
 138
 139 extern void assoc_mkiter(assoc_iter */*i*/, assoc_table */*t*/);
 140 extern void *assoc_next(assoc_iter */*i*/);
 141
 142 /*----- That's all, folks -------------------------------------------------*/
 143
 144 #ifdef __cplusplus
 145   }
 146 #endif
 147
 148 #endif