src/xbt/dict.c

   1 /* $Id$ */
   2
   3 /* dict - a generic dictionnary, variation over the B-tree concept          */
   4
   5 /* Copyright (c) 2003,2004 Martin Quinson. All rights reserved.             */
   6
   7 /* This program is free software; you can redistribute it and/or modify it
   8  * under the terms of the license (GNU LGPL) which comes with this package. */
   9
  10 #include "xbt/ex.h"
  11 #include "dict_private.h"
  12
  13 XBT_LOG_NEW_DEFAULT_SUBCATEGORY(dict,xbt,
  14    "Dictionaries provide the same functionnalities than hash tables");
  15 /*####[ Private prototypes ]#################################################*/
  16
  17 /*####[ Code ]###############################################################*/
  18
  19 /**
  20  * @brief Constructor
  21  * @return pointer to the destination
  22  *
  23  * Creates and initialize a new dictionnary
  24  */
  25 xbt_dict_t
  26 xbt_dict_new(void) {
  27   xbt_dict_t res= xbt_new(s_xbt_dict_t,1);
  28   res->head=NULL;
  29   return res;
  30 }
  31 /**
  32  * @brief Destructor
  33  * @param dict the dictionnary to be freed
  34  *
  35  * Frees a cache structure with all its childs.
  36  */
  37 void
  38 xbt_dict_free(xbt_dict_t *dict)  {
  39   if (dict && *dict) {
  40     if ((*dict)->head) {
  41       xbt_dictelm_free( &( (*dict)->head ) );
  42       (*dict)->head = NULL;
  43     }
  44     free(*dict);
  45     *dict=NULL;
  46   }
  47 }
  48
  49 /**
  50  * \brief Add data to the dict (arbitrary key)
  51  * \param dict the container
  52  * \param key the key to set the new data
  53  * \param key_len the size of the \a key
  54  * \param data the data to add in the dict
  55  * \param free_ctn function to call with (\a key as argument) when
  56  *        \a key is removed from the dictionnary
  57  *
  58  * set the \a data in the structure under the \a key, which can be any kind
  59  * of data, as long as its length is provided in \a key_len.
  60  */
  61 void
  62 xbt_dict_set_ext(xbt_dict_t      dict,
  63                   const char      *key,
  64                   int              key_len,
  65                   void            *data,
  66                   void_f_pvoid_t  *free_ctn) {
  67
  68   xbt_assert(dict);
  69
  70   xbt_dictelm_set_ext(&(dict->head),
  71                        key, key_len, data, free_ctn);
  72 }
  73
  74 /**
  75  * \brief Add data to the dict (null-terminated key)
  76  *
  77  * \param dict the head of the dict
  78  * \param key the key to set the new data
  79  * \param data the data to add in the dict
  80  * \param free_ctn function to call with (\a key as argument) when
  81  *        \a key is removed from the dictionnary
  82  *
  83  * set the \a data in the structure under the \a key, which is a
  84  * null terminated string.
  85  */
  86 void
  87 xbt_dict_set(xbt_dict_t     dict,
  88               const char     *key,
  89               void           *data,
  90               void_f_pvoid_t *free_ctn) {
  91
  92   xbt_assert(dict);
  93
  94   xbt_dictelm_set(&(dict->head), key, data, free_ctn);
  95 }
  96
  97 /**
  98  * \brief Retrieve data from the dict (arbitrary key)
  99  *
 100  * \param dict the dealer of data
 101  * \param key the key to find data
 102  * \param key_len the size of the \a key
 103  * \param data the data that we are looking for
 104  * \return xbt_error
 105  *
 106  * Search the given \a key. mismatch_error when not found.
 107  */
 108 void *
 109 xbt_dict_get_ext(xbt_dict_t      dict,
 110                  const char     *key,
 111                  int             key_len) {
 112
 113   xbt_assert(dict);
 114
 115   return xbt_dictelm_get_ext(dict->head, key, key_len);
 116 }
 117
 118 /**
 119  * \brief Retrieve data from the dict (null-terminated key)
 120  *
 121  * \param dict the dealer of data
 122  * \param key the key to find data
 123  * \param data the data that we are looking for
 124  * \return xbt_error
 125  *
 126  * Search the given \a key. THROWs mismatch_error when not found.
 127  * Check xbt_dict_get_or_null() for a version returning NULL without exception when
 128  * not found.
 129  */
 130 void *
 131 xbt_dict_get(xbt_dict_t     dict,
 132              const char     *key) {
 133   xbt_assert(dict);
 134
 135   return xbt_dictelm_get(dict->head, key);
 136 }
 137
 138 /**
 139  * \brief like xbt_dict_get(), but returning NULL when not found
 140  */
 141 void *
 142 xbt_dict_get_or_null(xbt_dict_t     dict,
 143                      const char     *key) {
 144   xbt_ex_t e;
 145   void *res;
 146   TRY {
 147     res = xbt_dictelm_get(dict->head, key);
 148   } CATCH(e) {
 149     if (e.category != mismatch_error)
 150       RETHROW;
 151     xbt_ex_free(e);
 152     res=NULL;
 153   }
 154   return res;
 155 }
 156
 157
 158 /**
 159  * \brief Remove data from the dict (arbitrary key)
 160  *
 161  * \param dict the trash can
 162  * \param key the key of the data to be removed
 163  * \param key_len the size of the \a key
 164  * \return xbt_error_t
 165  *
 166  * Remove the entry associated with the given \a key
 167  */
 168 xbt_error_t
 169 xbt_dict_remove_ext(xbt_dict_t  dict,
 170                      const char  *key,
 171                      int          key_len) {
 172   xbt_assert(dict);
 173
 174   return xbt_dictelm_remove_ext(dict->head, key, key_len);
 175 }
 176
 177 /**
 178  * \brief Remove data from the dict (null-terminated key)
 179  *
 180  * \param dict the head of the dict
 181  * \param key the key of the data to be removed
 182  *
 183  * Remove the entry associated with the given \a key
 184  */
 185 xbt_error_t
 186 xbt_dict_remove(xbt_dict_t  dict,
 187                  const char  *key) {
 188   if (!dict)
 189     THROW1(arg_error,0,"Asked to remove key %s from NULL dict",key);
 190
 191   return xbt_dictelm_remove(dict->head, key);
 192 }
 193
 194
 195 /**
 196  * \brief Outputs the content of the structure (debuging purpose)
 197  *
 198  * \param dict the exibitionist
 199  * \param output a function to dump each data in the tree
 200  *
 201  * Ouputs the content of the structure. (for debuging purpose). \a ouput is a
 202  * function to output the data. If NULL, data won't be displayed, just the tree structure.
 203  */
 204
 205 void
 206 xbt_dict_dump(xbt_dict_t     dict,
 207                void_f_pvoid_t *output) {
 208
 209   printf("Dict %p:\n", (void*)dict);
 210   xbt_dictelm_dump(dict ? dict->head: NULL, output);
 211 }