2 /*-------------------------------------------------------------------------*/
7 @version $Revision: 1.12 $
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.12 2007-11-23 21:37:00 ndevilla Exp $
19 $Date: 2007-11-23 21:37:00 $
23 #ifndef _DICTIONARY_H_
24 #define _DICTIONARY_H_
26 /*---------------------------------------------------------------------------
28 ---------------------------------------------------------------------------*/
35 /*---------------------------------------------------------------------------
37 ---------------------------------------------------------------------------*/
40 /*-------------------------------------------------------------------------*/
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)
49 /*-------------------------------------------------------------------------*/
50 typedef struct _dictionary_ {
51 int n ; /** Number of entries in dictionary */
52 int size ; /** Storage size */
53 char ** val ; /** List of string values */
54 char ** key ; /** List of string keys */
55 unsigned * hash ; /** List of hash values for keys */
59 /*---------------------------------------------------------------------------
61 ---------------------------------------------------------------------------*/
63 /*-------------------------------------------------------------------------*/
65 @brief Compute the hash key for a string.
66 @param key Character string to use for key.
67 @return 1 unsigned int on at least 32 bits.
69 This hash function has been taken from an Article in Dr Dobbs Journal.
70 This is normally a collision-free function, distributing keys evenly.
71 The key is stored anyway in the struct so that collision can be avoided
72 by comparing the key itself in last resort.
74 /*--------------------------------------------------------------------------*/
75 unsigned dictionary_hash(char * key);
77 /*-------------------------------------------------------------------------*/
79 @brief Create a new dictionary object.
80 @param size Optional initial size of the dictionary.
81 @return 1 newly allocated dictionary objet.
83 This function allocates a new dictionary object of given size and returns
84 it. If you do not know in advance (roughly) the number of entries in the
85 dictionary, give size=0.
87 /*--------------------------------------------------------------------------*/
88 dictionary * dictionary_new(int size);
90 /*-------------------------------------------------------------------------*/
92 @brief Delete a dictionary object
93 @param d dictionary object to deallocate.
96 Deallocate a dictionary object and all memory associated to it.
98 /*--------------------------------------------------------------------------*/
99 void dictionary_del(dictionary * vd);
101 /*-------------------------------------------------------------------------*/
103 @brief Get a value from a dictionary.
104 @param d dictionary object to search.
105 @param key Key to look for in the dictionary.
106 @param def Default value to return if key not found.
107 @return 1 pointer to internally allocated character string.
109 This function locates a key in a dictionary and returns a pointer to its
110 value, or the passed 'def' pointer if no such key can be found in
111 dictionary. The returned character pointer points to data internal to the
112 dictionary object, you should not try to free it or modify it.
114 /*--------------------------------------------------------------------------*/
115 char * dictionary_get(dictionary * d, char * key, char * def);
118 /*-------------------------------------------------------------------------*/
120 @brief Set a value in a dictionary.
121 @param d dictionary object to modify.
122 @param key Key to modify or add.
123 @param val Value to add.
124 @return int 0 if Ok, anything else otherwise
126 If the given key is found in the dictionary, the associated value is
127 replaced by the provided one. If the key cannot be found in the
128 dictionary, it is added to it.
130 It is Ok to provide a NULL value for val, but NULL values for the dictionary
131 or the key are considered as errors: the function will return immediately
134 Notice that if you dictionary_set a variable to NULL, a call to
135 dictionary_get will return a NULL value: the variable will be found, and
136 its value (NULL) is returned. In other words, setting the variable
137 content to NULL is equivalent to deleting the variable from the
138 dictionary. It is not possible (in this implementation) to have a key in
139 the dictionary without value.
141 This function returns non-zero in case of failure.
143 /*--------------------------------------------------------------------------*/
144 int dictionary_set(dictionary * vd, char * key, char * val);
146 /*-------------------------------------------------------------------------*/
148 @brief Delete a key in a dictionary
149 @param d dictionary object to modify.
150 @param key Key to remove.
153 This function deletes a key in a dictionary. Nothing is done if the
156 /*--------------------------------------------------------------------------*/
157 void dictionary_unset(dictionary * d, char * key);
160 /*-------------------------------------------------------------------------*/
162 @brief Dump a dictionary to an opened file pointer.
163 @param d Dictionary to dump
164 @param f Opened file pointer.
167 Dumps a dictionary onto an opened file pointer. Key pairs are printed out
168 as @c [Key]=[Value], one per line. It is Ok to provide stdout or stderr as
169 output file pointers.
171 /*--------------------------------------------------------------------------*/
172 void dictionary_dump(dictionary * d, FILE * out);