|
1 |
|
2 /*-------------------------------------------------------------------------*/ |
|
3 /** |
|
4 @file dictionary.h |
|
5 @author N. Devillard |
|
6 @brief Implements a dictionary for string variables. |
|
7 |
|
8 This module implements a simple dictionary object, i.e. a list |
|
9 of string/string associations. This object is useful to store e.g. |
|
10 informations retrieved from a configuration file (ini files). |
|
11 */ |
|
12 /*--------------------------------------------------------------------------*/ |
|
13 |
|
14 #ifndef _DICTIONARY_H_ |
|
15 #define _DICTIONARY_H_ |
|
16 |
|
17 /*--------------------------------------------------------------------------- |
|
18 Includes |
|
19 ---------------------------------------------------------------------------*/ |
|
20 |
|
21 #include <stdio.h> |
|
22 #include <stdlib.h> |
|
23 #include <string.h> |
|
24 #include <unistd.h> |
|
25 |
|
26 /*--------------------------------------------------------------------------- |
|
27 New types |
|
28 ---------------------------------------------------------------------------*/ |
|
29 |
|
30 |
|
31 /*-------------------------------------------------------------------------*/ |
|
32 /** |
|
33 @brief Dictionary object |
|
34 |
|
35 This object contains a list of string/string associations. Each |
|
36 association is identified by a unique string key. Looking up values |
|
37 in the dictionary is speeded up by the use of a (hopefully collision-free) |
|
38 hash function. |
|
39 */ |
|
40 /*-------------------------------------------------------------------------*/ |
|
41 typedef struct _dictionary_ { |
|
42 int n ; /** Number of entries in dictionary */ |
|
43 int size ; /** Storage size */ |
|
44 char ** val ; /** List of string values */ |
|
45 char ** key ; /** List of string keys */ |
|
46 unsigned * hash ; /** List of hash values for keys */ |
|
47 } dictionary ; |
|
48 |
|
49 |
|
50 /*--------------------------------------------------------------------------- |
|
51 Function prototypes |
|
52 ---------------------------------------------------------------------------*/ |
|
53 |
|
54 /*-------------------------------------------------------------------------*/ |
|
55 /** |
|
56 @brief Compute the hash key for a string. |
|
57 @param key Character string to use for key. |
|
58 @return 1 unsigned int on at least 32 bits. |
|
59 |
|
60 This hash function has been taken from an Article in Dr Dobbs Journal. |
|
61 This is normally a collision-free function, distributing keys evenly. |
|
62 The key is stored anyway in the struct so that collision can be avoided |
|
63 by comparing the key itself in last resort. |
|
64 */ |
|
65 /*--------------------------------------------------------------------------*/ |
|
66 unsigned dictionary_hash(const char * key); |
|
67 |
|
68 /*-------------------------------------------------------------------------*/ |
|
69 /** |
|
70 @brief Create a new dictionary object. |
|
71 @param size Optional initial size of the dictionary. |
|
72 @return 1 newly allocated dictionary objet. |
|
73 |
|
74 This function allocates a new dictionary object of given size and returns |
|
75 it. If you do not know in advance (roughly) the number of entries in the |
|
76 dictionary, give size=0. |
|
77 */ |
|
78 /*--------------------------------------------------------------------------*/ |
|
79 dictionary * dictionary_new(int size); |
|
80 |
|
81 /*-------------------------------------------------------------------------*/ |
|
82 /** |
|
83 @brief Delete a dictionary object |
|
84 @param d dictionary object to deallocate. |
|
85 @return void |
|
86 |
|
87 Deallocate a dictionary object and all memory associated to it. |
|
88 */ |
|
89 /*--------------------------------------------------------------------------*/ |
|
90 void dictionary_del(dictionary * vd); |
|
91 |
|
92 /*-------------------------------------------------------------------------*/ |
|
93 /** |
|
94 @brief Get a value from a dictionary. |
|
95 @param d dictionary object to search. |
|
96 @param key Key to look for in the dictionary. |
|
97 @param def Default value to return if key not found. |
|
98 @return 1 pointer to internally allocated character string. |
|
99 |
|
100 This function locates a key in a dictionary and returns a pointer to its |
|
101 value, or the passed 'def' pointer if no such key can be found in |
|
102 dictionary. The returned character pointer points to data internal to the |
|
103 dictionary object, you should not try to free it or modify it. |
|
104 */ |
|
105 /*--------------------------------------------------------------------------*/ |
|
106 char * dictionary_get(dictionary * d, const char * key, char * def); |
|
107 |
|
108 |
|
109 /*-------------------------------------------------------------------------*/ |
|
110 /** |
|
111 @brief Set a value in a dictionary. |
|
112 @param d dictionary object to modify. |
|
113 @param key Key to modify or add. |
|
114 @param val Value to add. |
|
115 @return int 0 if Ok, anything else otherwise |
|
116 |
|
117 If the given key is found in the dictionary, the associated value is |
|
118 replaced by the provided one. If the key cannot be found in the |
|
119 dictionary, it is added to it. |
|
120 |
|
121 It is Ok to provide a NULL value for val, but NULL values for the dictionary |
|
122 or the key are considered as errors: the function will return immediately |
|
123 in such a case. |
|
124 |
|
125 Notice that if you dictionary_set a variable to NULL, a call to |
|
126 dictionary_get will return a NULL value: the variable will be found, and |
|
127 its value (NULL) is returned. In other words, setting the variable |
|
128 content to NULL is equivalent to deleting the variable from the |
|
129 dictionary. It is not possible (in this implementation) to have a key in |
|
130 the dictionary without value. |
|
131 |
|
132 This function returns non-zero in case of failure. |
|
133 */ |
|
134 /*--------------------------------------------------------------------------*/ |
|
135 int dictionary_set(dictionary * vd, const char * key, const char * val); |
|
136 |
|
137 /*-------------------------------------------------------------------------*/ |
|
138 /** |
|
139 @brief Delete a key in a dictionary |
|
140 @param d dictionary object to modify. |
|
141 @param key Key to remove. |
|
142 @return void |
|
143 |
|
144 This function deletes a key in a dictionary. Nothing is done if the |
|
145 key cannot be found. |
|
146 */ |
|
147 /*--------------------------------------------------------------------------*/ |
|
148 void dictionary_unset(dictionary * d, const char * key); |
|
149 |
|
150 |
|
151 /*-------------------------------------------------------------------------*/ |
|
152 /** |
|
153 @brief Dump a dictionary to an opened file pointer. |
|
154 @param d Dictionary to dump |
|
155 @param f Opened file pointer. |
|
156 @return void |
|
157 |
|
158 Dumps a dictionary onto an opened file pointer. Key pairs are printed out |
|
159 as @c [Key]=[Value], one per line. It is Ok to provide stdout or stderr as |
|
160 output file pointers. |
|
161 */ |
|
162 /*--------------------------------------------------------------------------*/ |
|
163 void dictionary_dump(dictionary * d, FILE * out); |
|
164 |
|
165 #endif |