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 "dict_private.h"
  11
  12 #include <stdlib.h> /* malloc() */
  13 #include <string.h> /* strlen() */
  14
  15 #include <stdio.h>
  16
  17 /** \defgroup XBT_dict A generic dictionnary
  18  *  \brief This section describes the API to a dictionnary structure
  19  *  that associates as string to a void* key. It is not a hash table
  20  *  and the internal data-structure rather looks like a tree.
  21  */
  22
  23 XBT_LOG_NEW_DEFAULT_SUBCATEGORY(dict,xbt,
  24    "Dictionaries provide the same functionnalities than hash tables");
  25 /*####[ Private prototypes ]#################################################*/
  26
  27 /*####[ Code ]###############################################################*/
  28
  29 /**
  30  * \ingroup XBT_dict
  31  *
  32  * \return pointer to the destination
  33  *
  34  * Creates and initialize a new dictionnary
  35  */
  36 xbt_dict_t
  37 xbt_dict_new(void) {
  38   xbt_dict_t res= xbt_new(s_xbt_dict_t,1);
  39   res->head=NULL;
  40   return res;
  41 }
  42 /**
  43  * \ingroup XBT_dict
  44  * \param dict the dictionnary to be freed
  45  *
  46  * Frees a cache structure with all its childs.
  47  */
  48 void
  49 xbt_dict_free(xbt_dict_t *dict)  {
  50   if (dict && *dict) {
  51     if ((*dict)->head) {
  52       xbt_dictelm_free( &( (*dict)->head ) );
  53       (*dict)->head = NULL;
  54     }
  55     xbt_free(*dict);
  56     *dict=NULL;
  57   }
  58 }
  59
  60 /**
  61  * \ingroup XBT_dict
  62  *
  63  * \param dict the container
  64  * \param key the key to set the new data
  65  * \param key_len the size of the #key
  66  * \param data the data to add in the dict
  67  * \param free_ctn function to call with (#key as argument) when
  68  *        #key is removed from the dictionnary
  69  *
  70  * set the #data in the structure under the #key, which can be any kind
  71  * of data, as long as its length is provided in #key_len.
  72  */
  73 void
  74 xbt_dict_set_ext(xbt_dict_t      dict,
  75                   const char      *key,
  76                   int              key_len,
  77                   void            *data,
  78                   void_f_pvoid_t  *free_ctn) {
  79
  80   xbt_assert(dict);
  81
  82   xbt_dictelm_set_ext(&(dict->head),
  83                        key, key_len, data, free_ctn);
  84 }
  85
  86 /**
  87  * \ingroup XBT_dict
  88  *
  89  * \param dict the head of the dict
  90  * \param key the key to set the new data
  91  * \param data the data to add in the dict
  92  * \param free_ctn function to call with (#key as argument) when
  93  *        #key is removed from the dictionnary
  94  *
  95  * set the #data in the structure under the #key, which is a
  96  * null terminated string.
  97  */
  98 void
  99 xbt_dict_set(xbt_dict_t     dict,
 100               const char     *key,
 101               void           *data,
 102               void_f_pvoid_t *free_ctn) {
 103
 104   xbt_assert(dict);
 105
 106   xbt_dictelm_set(&(dict->head), key, data, free_ctn);
 107 }
 108
 109 /**
 110  * \ingroup XBT_dict
 111  *
 112  * \param dict the dealer of data
 113  * \param key the key to find data
 114  * \param key_len the size of the #key
 115  * \param data the data that we are looking for
 116  * \return xbt_error
 117  *
 118  * Search the given #key. mismatch_error when not found.
 119  */
 120 xbt_error_t
 121 xbt_dict_get_ext(xbt_dict_t     dict,
 122                   const char     *key,
 123                   int             key_len,
 124                   /* OUT */void **data) {
 125
 126   xbt_assert(dict);
 127
 128   return xbt_dictelm_get_ext(dict->head, key, key_len, data);
 129 }
 130
 131 /**
 132  * \ingroup XBT_dict
 133  *
 134  * \param dict the dealer of data
 135  * \param key the key to find data
 136  * \param data the data that we are looking for
 137  * \return xbt_error
 138  *
 139  * Search the given #key. mismatch_error when not found.
 140  */
 141 xbt_error_t
 142 xbt_dict_get(xbt_dict_t     dict,
 143               const char     *key,
 144               /* OUT */void **data) {
 145   xbt_assert(dict);
 146
 147   return xbt_dictelm_get(dict->head, key, data);
 148 }
 149
 150
 151 /**
 152  * \ingroup XBT_dict
 153  *
 154  * \param dict the trash can
 155  * \param key the key of the data to be removed
 156  * \param key_len the size of the #key
 157  * \return xbt_error_t
 158  *
 159  * Remove the entry associated with the given #key
 160  */
 161 xbt_error_t
 162 xbt_dict_remove_ext(xbt_dict_t  dict,
 163                      const char  *key,
 164                      int          key_len) {
 165   xbt_assert(dict);
 166
 167   return xbt_dictelm_remove_ext(dict->head, key, key_len);
 168 }
 169
 170 /**
 171  * \ingroup XBT_dict
 172  *
 173  * \param dict the head of the dict
 174  * \param key the key of the data to be removed
 175  * \return xbt_error_t
 176  *
 177  * Remove the entry associated with the given #key
 178  */
 179 xbt_error_t
 180 xbt_dict_remove(xbt_dict_t  dict,
 181                  const char  *key) {
 182   if (!dict)
 183      RAISE1(mismatch_error,"Asked to remove key %s from NULL dict",key);
 184
 185   return xbt_dictelm_remove(dict->head, key);
 186 }
 187
 188
 189 /**
 190  * \ingroup XBT_dict
 191  *
 192  * \param dict the exibitionist
 193  * \param output a function to dump each data in the tree
 194  * \return xbt_error_t
 195  *
 196  * Ouputs the content of the structure. (for debuging purpose). #ouput is a
 197  * function to output the data. If NULL, data won't be displayed.
 198  */
 199
 200 void
 201 xbt_dict_dump(xbt_dict_t     dict,
 202                void_f_pvoid_t *output) {
 203
 204   printf("Dict %p:\n", (void*)dict);
 205   xbt_dictelm_dump(dict ? dict->head: NULL, output);
 206 }