Logo AND Algorithmique Numérique Distribuée

Public GIT Repository
Make sure that the code still compiles with the freaking paranoid gcc warning options...
[simgrid.git] / 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  * \returns the data that we are looking for
104  *
105  * Search the given \a key. throws not_found_error when not found.
106  */
107 void *
108 xbt_dict_get_ext(xbt_dict_t      dict,
109                  const char     *key,
110                  int             key_len) {
111
112   xbt_assert(dict);
113
114   return xbt_dictelm_get_ext(dict->head, key, key_len);
115 }
116
117 /**
118  * \brief Retrieve data from the dict (null-terminated key) 
119  *
120  * \param dict the dealer of data
121  * \param key the key to find data
122  * \returns the data that we are looking for
123  *
124  * Search the given \a key. THROWs mismatch_error when not found. 
125  * Check xbt_dict_get_or_null() for a version returning NULL without exception when 
126  * not found.
127  */
128 void *
129 xbt_dict_get(xbt_dict_t     dict,
130              const char     *key) {
131   xbt_assert(dict);
132
133   return xbt_dictelm_get(dict->head, key);
134 }
135
136 /**
137  * \brief like xbt_dict_get(), but returning NULL when not found
138  */
139 void *
140 xbt_dict_get_or_null(xbt_dict_t     dict,
141                      const char     *key) {
142   xbt_ex_t e;
143   void *res=NULL;
144   TRY {
145     res = xbt_dictelm_get(dict->head, key);
146   } CATCH(e) {
147     if (e.category != not_found_error) 
148       RETHROW;
149     xbt_ex_free(e);
150     res=NULL;
151   }
152   return res;
153 }
154
155
156 /**
157  * \brief Remove data from the dict (arbitrary key)
158  *
159  * \param dict the trash can
160  * \param key the key of the data to be removed
161  * \param key_len the size of the \a key
162  * 
163  *
164  * Remove the entry associated with the given \a key (throws not_found)
165  */
166 void
167 xbt_dict_remove_ext(xbt_dict_t  dict,
168                      const char  *key,
169                      int          key_len) {
170   xbt_assert(dict);
171   
172   xbt_dictelm_remove_ext(dict->head, key, key_len);
173 }
174
175 /**
176  * \brief Remove data from the dict (null-terminated key)
177  *
178  * \param dict the head of the dict
179  * \param key the key of the data to be removed
180  *
181  * Remove the entry associated with the given \a key
182  */
183 void
184 xbt_dict_remove(xbt_dict_t  dict,
185                  const char  *key) {
186   if (!dict)
187     THROW1(arg_error,0,"Asked to remove key %s from NULL dict",key);
188
189   xbt_dictelm_remove(dict->head, key);
190 }
191
192
193 /**
194  * \brief Outputs the content of the structure (debuging purpose) 
195  *
196  * \param dict the exibitionist
197  * \param output a function to dump each data in the tree
198  *
199  * Ouputs the content of the structure. (for debuging purpose). \a ouput is a
200  * function to output the data. If NULL, data won't be displayed, just the tree structure.
201  */
202
203 void
204 xbt_dict_dump(xbt_dict_t     dict,
205                void_f_pvoid_t *output) {
206
207   printf("Dict %p:\n", (void*)dict);
208   xbt_dictelm_dump(dict ? dict->head: NULL, output);
209 }