utility/genhash.h

   1 /**********************************************************************
   2  Freeciv - Copyright (C) 1996 - A Kjeldberg, L Gregersen, P Unold
   3    This program is free software; you can redistribute it and/or modify
   4    it under the terms of the GNU General Public License as published by
   5    the Free Software Foundation; either version 2, or (at your option)
   6    any later version.
   7
   8    This program is distributed in the hope that it will be useful,
   9    but WITHOUT ANY WARRANTY; without even the implied warranty of
  10    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  11    GNU General Public License for more details.
  12 ***********************************************************************/
  13 #ifndef FC__GENHASH_H
  14 #define FC__GENHASH_H
  15
  16 #ifdef __cplusplus
  17 extern "C" {
  18 #endif /* __cplusplus */
  19
  20 /****************************************************************************
  21    A general-purpose generic hash table implementation.
  22    See comments in "genhash.c".
  23 ****************************************************************************/
  24
  25 /* utility */
  26 #include "iterator.h"
  27 #include "support.h"            /* bool type */
  28
  29 struct genhash;                 /* opaque */
  30
  31 /* Hash value type. */
  32 typedef unsigned int genhash_val_t;
  33
  34 /* Function typedefs: */
  35 typedef genhash_val_t (*genhash_val_fn_t) (const void *);
  36 typedef bool (*genhash_comp_fn_t) (const void *, const void *);
  37 typedef void * (*genhash_copy_fn_t) (const void *);
  38 typedef void (*genhash_free_fn_t) (void *);
  39
  40
  41 /* Supplied functions (matching above typedefs) appropriate for
  42  * keys being normal nul-terminated strings: */
  43 genhash_val_t genhash_str_val_func(const char *vkey);
  44 bool genhash_str_comp_func(const char *vkey1, const char *vkey2);
  45 /* and malloc'ed strings: */
  46 char *genhash_str_copy_func(const char *vkey);
  47 void genhash_str_free_func(char *vkey);
  48
  49
  50 /* General functions: */
  51 struct genhash *genhash_new(genhash_val_fn_t key_val_func,
  52                             genhash_comp_fn_t key_comp_func)
  53                 fc__warn_unused_result;
  54 struct genhash *genhash_new_full(genhash_val_fn_t key_val_func,
  55                                  genhash_comp_fn_t key_comp_func,
  56                                  genhash_copy_fn_t key_copy_func,
  57                                  genhash_free_fn_t key_free_func,
  58                                  genhash_copy_fn_t data_copy_func,
  59                                  genhash_free_fn_t data_free_func)
  60                 fc__warn_unused_result;
  61 struct genhash *genhash_new_nentries(genhash_val_fn_t key_val_func,
  62                                      genhash_comp_fn_t key_comp_func,
  63                                      size_t nentries)
  64                 fc__warn_unused_result;
  65 struct genhash *
  66 genhash_new_nentries_full(genhash_val_fn_t key_val_func,
  67                           genhash_comp_fn_t key_comp_func,
  68                           genhash_copy_fn_t key_copy_func,
  69                           genhash_free_fn_t key_free_func,
  70                           genhash_copy_fn_t data_copy_func,
  71                           genhash_free_fn_t data_free_func,
  72                           size_t nentries)
  73 fc__warn_unused_result;
  74 void genhash_destroy(struct genhash *pgenhash);
  75
  76 bool genhash_set_no_shrink(struct genhash *pgenhash, bool no_shrink);
  77 size_t genhash_size(const struct genhash *pgenhash);
  78 size_t genhash_capacity(const struct genhash *pgenhash);
  79
  80 struct genhash *genhash_copy(const struct genhash *pgenhash)
  81                 fc__warn_unused_result;
  82 void genhash_clear(struct genhash *pgenhash);
  83
  84 bool genhash_insert(struct genhash *pgenhash, const void *key,
  85                     const void *data);
  86 bool genhash_replace(struct genhash *pgenhash, const void *key,
  87                      const void *data);
  88 bool genhash_replace_full(struct genhash *pgenhash, const void *key,
  89                           const void *data, void **old_pkey,
  90                           void **old_pdata);
  91
  92 bool genhash_lookup(const struct genhash *pgenhash, const void *key,
  93                     void **pdata);
  94
  95 bool genhash_remove(struct genhash *pgenhash, const void *key);
  96 bool genhash_remove_full(struct genhash *pgenhash, const void *key,
  97                          void **deleted_pkey, void **deleted_pdata);
  98
  99 bool genhashs_are_equal(const struct genhash *pgenhash1,
 100                         const struct genhash *pgenhash2);
 101 bool genhashs_are_equal_full(const struct genhash *pgenhash1,
 102                              const struct genhash *pgenhash2,
 103                              genhash_comp_fn_t data_comp_func);
 104
 105
 106 /* Iteration. */
 107 struct genhash_iter;
 108 size_t genhash_iter_sizeof(void);
 109
 110 struct iterator *genhash_key_iter_init(struct genhash_iter *iter,
 111                                        const struct genhash *hash);
 112 #define genhash_keys_iterate(ARG_ht, NAME_key)                              \
 113   generic_iterate(struct genhash_iter, const void *, NAME_key,              \
 114                   genhash_iter_sizeof, genhash_key_iter_init, (ARG_ht))
 115 #define genhash_keys_iterate_end generic_iterate_end
 116
 117 struct iterator *genhash_value_iter_init(struct genhash_iter *iter,
 118                                          const struct genhash *hash);
 119 #define genhash_values_iterate(ARG_ht, NAME_value)                          \
 120   generic_iterate(struct genhash_iter, void *, NAME_value,                  \
 121                   genhash_iter_sizeof, genhash_value_iter_init, (ARG_ht))
 122 #define genhash_values_iterate_end generic_iterate_end
 123
 124 struct iterator *genhash_iter_init(struct genhash_iter *iter,
 125                                    const struct genhash *hash);
 126 void *genhash_iter_key(const struct iterator *genhash_iter);
 127 void *genhash_iter_value(const struct iterator *genhash_iter);
 128 #define genhash_iterate(ARG_ht, NAME_iter)                                  \
 129   generic_iterate(struct genhash_iter, struct iterator *, NAME_iter,        \
 130                   genhash_iter_sizeof, genhash_iter_init, (ARG_ht))
 131 #define genhash_iterate_end generic_iterate_end
 132
 133 #ifdef __cplusplus
 134 }
 135 #endif /* __cplusplus */
 136
 137 #endif  /* FC__GENHASH_H */