modified: makefile
[GalaxyCodeBases.git] / BGI / soap_src / soap_builder / dictionary.h
blob8e23879506ace9d0c21ab5314843d59a276e77e2
2 /*-------------------------------------------------------------------------*/
3 /**
4 @file dictionary.h
5 @author N. Devillard
6 @date Aug 2000
7 @version $Revision: 1.11 $
8 @brief Implements a dictionary for string variables.
10 This module implements a simple dictionary object, i.e. a list
11 of string/string associations. This object is useful to store e.g.
12 informations retrieved from a configuration file (ini files).
14 /*--------------------------------------------------------------------------*/
17 $Id: dictionary.h,v 1.11 2002/06/17 09:30:46 ndevilla Exp $
18 $Author: ndevilla $
19 $Date: 2002/06/17 09:30:46 $
20 $Revision: 1.11 $
23 #ifndef _DICTIONARY_H_
24 #define _DICTIONARY_H_
26 /*---------------------------------------------------------------------------
27 Includes
28 ---------------------------------------------------------------------------*/
30 #include <stdio.h>
31 #include <stdlib.h>
32 #include <string.h>
33 //#include <unistd.h>
35 /*---------------------------------------------------------------------------
36 New types
37 ---------------------------------------------------------------------------*/
40 /*-------------------------------------------------------------------------*/
41 /**
42 @brief Dictionary object
44 This object contains a list of string/string associations. Each
45 association is identified by a unique string key. Looking up values
46 in the dictionary is speeded up by the use of a (hopefully collision-free)
47 hash function.
49 /*-------------------------------------------------------------------------*/
50 typedef struct _dictionary_ {
51 int n ; /** Number of entries in dictionary */
52 int size ; /** Storage size */
53 int caseSensitive ; /** Case sensitive or not */
54 char ** val ; /** List of string values */
55 char ** key ; /** List of string keys */
56 unsigned * hash ; /** List of hash values for keys */
57 } dictionary ;
60 /*---------------------------------------------------------------------------
61 Function prototypes
62 ---------------------------------------------------------------------------*/
64 /*-------------------------------------------------------------------------*/
65 /**
66 @brief Compute the hash key for a string.
67 @param key Character string to use for key.
68 @return 1 unsigned int on at least 32 bits.
70 This hash function has been taken from an Article in Dr Dobbs Journal.
71 This is normally a collision-free function, distributing keys evenly.
72 The key is stored anyway in the struct so that collision can be avoided
73 by comparing the key itself in last resort.
75 /*--------------------------------------------------------------------------*/
76 unsigned dictionary_hash(char * key);
78 /*-------------------------------------------------------------------------*/
79 /**
80 @brief Create a new dictionary object.
81 @param size Optional initial size of the dictionary.
82 @return 1 newly allocated dictionary objet.
84 This function allocates a new dictionary object of given size and returns
85 it. If you do not know in advance (roughly) the number of entries in the
86 dictionary, give size=0.
88 /*--------------------------------------------------------------------------*/
89 dictionary * dictionary_new(int size, int caseSensitive);
91 /*-------------------------------------------------------------------------*/
92 /**
93 @brief Delete a dictionary object
94 @param d dictionary object to deallocate.
95 @return void
97 Deallocate a dictionary object and all memory associated to it.
99 /*--------------------------------------------------------------------------*/
100 void dictionary_del(dictionary * vd);
102 /*-------------------------------------------------------------------------*/
104 @brief Get a value from a dictionary.
105 @param d dictionary object to search.
106 @param key Key to look for in the dictionary.
107 @param def Default value to return if key not found.
108 @return 1 pointer to internally allocated character string.
110 This function locates a key in a dictionary and returns a pointer to its
111 value, or the passed 'def' pointer if no such key can be found in
112 dictionary. The returned character pointer points to data internal to the
113 dictionary object, you should not try to free it or modify it.
115 /*--------------------------------------------------------------------------*/
116 char * dictionary_get(dictionary * d, char * key, char * def);
119 /*-------------------------------------------------------------------------*/
121 @brief Get a value from a dictionary, as a char.
122 @param d dictionary object to search.
123 @param key Key to look for in the dictionary.
124 @param def Default value for the key if not found.
125 @return char
127 This function locates a key in a dictionary using dictionary_get,
128 and returns the first char of the found string.
130 /*--------------------------------------------------------------------------*/
131 char dictionary_getchar(dictionary * d, char * key, char def) ;
133 /*-------------------------------------------------------------------------*/
135 @brief Get a value from a dictionary, as an int.
136 @param d dictionary object to search.
137 @param key Key to look for in the dictionary.
138 @param def Default value for the key if not found.
139 @return int
141 This function locates a key in a dictionary using dictionary_get,
142 and applies atoi on it to return an int. If the value cannot be found
143 in the dictionary, the default is returned.
145 /*--------------------------------------------------------------------------*/
146 int dictionary_getint(dictionary * d, char * key, int def);
148 /*-------------------------------------------------------------------------*/
150 @brief Get a value from a dictionary, as a double.
151 @param d dictionary object to search.
152 @param key Key to look for in the dictionary.
153 @param def Default value for the key if not found.
154 @return double
156 This function locates a key in a dictionary using dictionary_get,
157 and applies atof on it to return a double. If the value cannot be found
158 in the dictionary, the default is returned.
160 /*--------------------------------------------------------------------------*/
161 double dictionary_getdouble(dictionary * d, char * key, double def);
163 /*-------------------------------------------------------------------------*/
165 @brief Set a value in a dictionary.
166 @param d dictionary object to modify.
167 @param key Key to modify or add.
168 @param val Value to add.
169 @return void
171 If the given key is found in the dictionary, the associated value is
172 replaced by the provided one. If the key cannot be found in the
173 dictionary, it is added to it.
175 It is Ok to provide a NULL value for val, but NULL values for the dictionary
176 or the key are considered as errors: the function will return immediately
177 in such a case.
179 Notice that if you dictionary_set a variable to NULL, a call to
180 dictionary_get will return a NULL value: the variable will be found, and
181 its value (NULL) is returned. In other words, setting the variable
182 content to NULL is equivalent to deleting the variable from the
183 dictionary. It is not possible (in this implementation) to have a key in
184 the dictionary without value.
186 /*--------------------------------------------------------------------------*/
187 void dictionary_set(dictionary * vd, char * key, char * val);
189 /*-------------------------------------------------------------------------*/
191 @brief Delete a key in a dictionary
192 @param d dictionary object to modify.
193 @param key Key to remove.
194 @return void
196 This function deletes a key in a dictionary. Nothing is done if the
197 key cannot be found.
199 /*--------------------------------------------------------------------------*/
200 void dictionary_unset(dictionary * d, char * key);
203 /*-------------------------------------------------------------------------*/
205 @brief Set a key in a dictionary, providing an int.
206 @param d Dictionary to update.
207 @param key Key to modify or add
208 @param val Integer value to store (will be stored as a string).
209 @return void
211 This helper function calls dictionary_set() with the provided integer
212 converted to a string using %d.
214 /*--------------------------------------------------------------------------*/
215 void dictionary_setint(dictionary * d, char * key, int val);
217 /*-------------------------------------------------------------------------*/
219 @brief Set a key in a dictionary, providing a double.
220 @param d Dictionary to update.
221 @param key Key to modify or add
222 @param val Double value to store (will be stored as a string).
223 @return void
225 This helper function calls dictionary_set() with the provided double
226 converted to a string using %g.
228 /*--------------------------------------------------------------------------*/
229 void dictionary_setdouble(dictionary * d, char * key, double val);
231 /*-------------------------------------------------------------------------*/
233 @brief Dump a dictionary to an opened file pointer.
234 @param d Dictionary to dump
235 @param f Opened file pointer.
236 @return void
238 Dumps a dictionary onto an opened file pointer. Key pairs are printed out
239 as @c [Key]=[Value], one per line. It is Ok to provide stdout or stderr as
240 output file pointers.
242 /*--------------------------------------------------------------------------*/
243 void dictionary_dump(dictionary * d, FILE * out);
245 #endif