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
---------------------------------------------------------------------------*/
37
/*---------------------------------------------------------------------------
39
---------------------------------------------------------------------------*/
42
/*-------------------------------------------------------------------------*/
44
@brief Dictionary object
46
This object contains a list of string/string associations. Each
47
association is identified by a unique string key. Looking up values
48
in the dictionary is speeded up by the use of a (hopefully collision-free)
51
/*-------------------------------------------------------------------------*/
52
typedef struct _dictionary_ {
53
int n ; /** Number of entries in dictionary */
54
int size ; /** Storage size */
55
char ** val ; /** List of string values */
56
char ** key ; /** List of string keys */
57
unsigned * hash ; /** List of hash values for keys */
61
/*---------------------------------------------------------------------------
63
---------------------------------------------------------------------------*/
65
/*-------------------------------------------------------------------------*/
67
@brief Compute the hash key for a string.
68
@param key Character string to use for key.
69
@return 1 unsigned int on at least 32 bits.
71
This hash function has been taken from an Article in Dr Dobbs Journal.
72
This is normally a collision-free function, distributing keys evenly.
73
The key is stored anyway in the struct so that collision can be avoided
74
by comparing the key itself in last resort.
76
/*--------------------------------------------------------------------------*/
77
unsigned dictionary_hash(char * key);
79
/*-------------------------------------------------------------------------*/
81
@brief Create a new dictionary object.
82
@param size Optional initial size of the dictionary.
83
@return 1 newly allocated dictionary objet.
85
This function allocates a new dictionary object of given size and returns
86
it. If you do not know in advance (roughly) the number of entries in the
87
dictionary, give size=0.
89
/*--------------------------------------------------------------------------*/
90
dictionary * dictionary_new(int size);
92
/*-------------------------------------------------------------------------*/
94
@brief Delete a dictionary object
95
@param d dictionary object to deallocate.
98
Deallocate a dictionary object and all memory associated to it.
100
/*--------------------------------------------------------------------------*/
101
void dictionary_del(dictionary * vd);
103
/*-------------------------------------------------------------------------*/
105
@brief Get a value from a dictionary.
106
@param d dictionary object to search.
107
@param key Key to look for in the dictionary.
108
@param def Default value to return if key not found.
109
@return 1 pointer to internally allocated character string.
111
This function locates a key in a dictionary and returns a pointer to its
112
value, or the passed 'def' pointer if no such key can be found in
113
dictionary. The returned character pointer points to data internal to the
114
dictionary object, you should not try to free it or modify it.
116
/*--------------------------------------------------------------------------*/
117
char * dictionary_get(dictionary * d, char * key, char * def);
120
/*-------------------------------------------------------------------------*/
122
@brief Set a value in a dictionary.
123
@param d dictionary object to modify.
124
@param key Key to modify or add.
125
@param val Value to add.
126
@return int 0 if Ok, anything else otherwise
128
If the given key is found in the dictionary, the associated value is
129
replaced by the provided one. If the key cannot be found in the
130
dictionary, it is added to it.
132
It is Ok to provide a NULL value for val, but NULL values for the dictionary
133
or the key are considered as errors: the function will return immediately
136
Notice that if you dictionary_set a variable to NULL, a call to
137
dictionary_get will return a NULL value: the variable will be found, and
138
its value (NULL) is returned. In other words, setting the variable
139
content to NULL is equivalent to deleting the variable from the
140
dictionary. It is not possible (in this implementation) to have a key in
141
the dictionary without value.
143
This function returns non-zero in case of failure.
145
/*--------------------------------------------------------------------------*/
146
int dictionary_set(dictionary * vd, char * key, char * val);
148
/*-------------------------------------------------------------------------*/
150
@brief Delete a key in a dictionary
151
@param d dictionary object to modify.
152
@param key Key to remove.
155
This function deletes a key in a dictionary. Nothing is done if the
158
/*--------------------------------------------------------------------------*/
159
void dictionary_unset(dictionary * d, char * key);
162
/*-------------------------------------------------------------------------*/
164
@brief Dump a dictionary to an opened file pointer.
165
@param d Dictionary to dump
166
@param f Opened file pointer.
169
Dumps a dictionary onto an opened file pointer. Key pairs are printed out
170
as @c [Key]=[Value], one per line. It is Ok to provide stdout or stderr as
171
output file pointers.
173
/*--------------------------------------------------------------------------*/
174
void dictionary_dump(dictionary * d, FILE * out);