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