2 Copyright (c) 2000-2011 by Nicolas Devillard.
5 Permission is hereby granted, free of charge, to any person obtaining a
6 copy of this software and associated documentation files (the "Software"),
7 to deal in the Software without restriction, including without limitation
8 the rights to use, copy, modify, merge, publish, distribute, sublicense,
9 and/or sell copies of the Software, and to permit persons to whom the
10 Software is furnished to do so, subject to the following conditions:
12 The above copyright notice and this permission notice shall be included in
13 all copies or substantial portions of the Software.
15 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
20 FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
21 DEALINGS IN THE SOFTWARE.
30 /*-------------------------------------------------------------------------*/
34 @brief Implements a dictionary for string variables.
36 This module implements a simple dictionary object, i.e. a list
37 of string/string associations. This object is useful to store e.g.
38 informations retrieved from a configuration file (ini files).
40 /*--------------------------------------------------------------------------*/
42 /*---------------------------------------------------------------------------
44 ---------------------------------------------------------------------------*/
51 /*---------------------------------------------------------------------------
53 ---------------------------------------------------------------------------*/
56 /*-------------------------------------------------------------------------*/
58 @brief Dictionary object
60 This object contains a list of string/string associations. Each
61 association is identified by a unique string key. Looking up values
62 in the dictionary is speeded up by the use of a (hopefully collision-free)
65 /*-------------------------------------------------------------------------*/
66 typedef struct _dictionary_ {
67 int n ; /** Number of entries in dictionary */
68 size_t size ; /** Storage size */
69 char ** val ; /** List of string values */
70 char ** key ; /** List of string keys */
71 unsigned * hash ; /** List of hash values for keys */
75 /*---------------------------------------------------------------------------
77 ---------------------------------------------------------------------------*/
79 /*-------------------------------------------------------------------------*/
81 @brief Compute the hash key for a string.
82 @param key Character string to use for key.
83 @return 1 unsigned int on at least 32 bits.
85 This hash function has been taken from an Article in Dr Dobbs Journal.
86 This is normally a collision-free function, distributing keys evenly.
87 The key is stored anyway in the struct so that collision can be avoided
88 by comparing the key itself in last resort.
90 /*--------------------------------------------------------------------------*/
91 unsigned dictionary_hash(const char * key);
93 /*-------------------------------------------------------------------------*/
95 @brief Create a new dictionary object.
96 @param size Optional initial size of the dictionary.
97 @return 1 newly allocated dictionary objet.
99 This function allocates a new dictionary object of given size and returns
100 it. If you do not know in advance (roughly) the number of entries in the
101 dictionary, give size=0.
103 /*--------------------------------------------------------------------------*/
104 dictionary * dictionary_new(size_t size);
106 /*-------------------------------------------------------------------------*/
108 @brief Delete a dictionary object
109 @param d dictionary object to deallocate.
112 Deallocate a dictionary object and all memory associated to it.
114 /*--------------------------------------------------------------------------*/
115 void dictionary_del(dictionary * vd);
117 /*-------------------------------------------------------------------------*/
119 @brief Get a value from a dictionary.
120 @param d dictionary object to search.
121 @param key Key to look for in the dictionary.
122 @param def Default value to return if key not found.
123 @return 1 pointer to internally allocated character string.
125 This function locates a key in a dictionary and returns a pointer to its
126 value, or the passed 'def' pointer if no such key can be found in
127 dictionary. The returned character pointer points to data internal to the
128 dictionary object, you should not try to free it or modify it.
130 /*--------------------------------------------------------------------------*/
131 char * dictionary_get(dictionary * d, const char * key, char * def);
134 /*-------------------------------------------------------------------------*/
136 @brief Set a value in a dictionary.
137 @param d dictionary object to modify.
138 @param key Key to modify or add.
139 @param val Value to add.
140 @return int 0 if Ok, anything else otherwise
142 If the given key is found in the dictionary, the associated value is
143 replaced by the provided one. If the key cannot be found in the
144 dictionary, it is added to it.
146 It is Ok to provide a NULL value for val, but NULL values for the dictionary
147 or the key are considered as errors: the function will return immediately
150 Notice that if you dictionary_set a variable to NULL, a call to
151 dictionary_get will return a NULL value: the variable will be found, and
152 its value (NULL) is returned. In other words, setting the variable
153 content to NULL is equivalent to deleting the variable from the
154 dictionary. It is not possible (in this implementation) to have a key in
155 the dictionary without value.
157 This function returns non-zero in case of failure.
159 /*--------------------------------------------------------------------------*/
160 int dictionary_set(dictionary * vd, const char * key, const char * val);
162 /*-------------------------------------------------------------------------*/
164 @brief Delete a key in a dictionary
165 @param d dictionary object to modify.
166 @param key Key to remove.
169 This function deletes a key in a dictionary. Nothing is done if the
172 /*--------------------------------------------------------------------------*/
173 void dictionary_unset(dictionary * d, const char * key);
176 /*-------------------------------------------------------------------------*/
178 @brief Dump a dictionary to an opened file pointer.
179 @param d Dictionary to dump
180 @param f Opened file pointer.
183 Dumps a dictionary onto an opened file pointer. Key pairs are printed out
184 as @c [Key]=[Value], one per line. It is Ok to provide stdout or stderr as
185 output file pointers.
187 /*--------------------------------------------------------------------------*/
188 void dictionary_dump(dictionary * d, FILE * out);