Tracing for tdb operations.
[ccan] / ccan / ciniparser / dictionary.h
1 #ifndef _DICTIONARY_H_
2 #define _DICTIONARY_H_
3
4 /* Copyright (c) 2000-2007 by Nicolas Devillard.
5  * Copyright (x) 2009 by Tim Post <tinkertim@gmail.com>
6  * MIT License
7  *
8  * Permission is hereby granted, free of charge, to any person obtaining a
9  * copy of this software and associated documentation files (the "Software"),
10  * to deal in the Software without restriction, including without limitation
11  * the rights to use, copy, modify, merge, publish, distribute, sublicense,
12  * and/or sell copies of the Software, and to permit persons to whom the
13  * Software is furnished to do so, subject to the following conditions:
14  *
15  * The above copyright notice and this permission notice shall be included in
16  * all copies or substantial portions of the Software.
17  *
18  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
19  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
20  * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
21  * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
22  * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
23  * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
24  * DEALINGS IN THE SOFTWARE.
25  */
26
27 #include <stdio.h>
28 #include <stdlib.h>
29 #include <string.h>
30 #include <unistd.h>
31
32 /** @addtogroup ciniparser
33  * @{
34  */
35 /**
36  * @file    dictionary.h
37  * @author  N. Devillard
38  * @date    Sep 2007
39  * @version $Revision: 1.12 $
40  * @brief   Implements a dictionary for string variables.
41  *
42  * This module implements a simple dictionary object, i.e. a list
43  * of string/string associations. This object is useful to store e.g.
44  * informations retrieved from a configuration file (ini files).
45  */
46
47
48 /**
49  * @brief Dictionary object
50  * @param n Number of entries in the dictionary
51  * @param size Storage size
52  * @param val List of string values
53  * @param key List of string keys
54  * @param hash List of hash values for keys
55  *
56  * This object contains a list of string/string associations. Each
57  * association is identified by a unique string key. Looking up values
58  * in the dictionary is speeded up by the use of a (hopefully collision-free)
59  * hash function.
60  */
61 typedef struct _dictionary_ {
62         int n;
63         int size;
64         char **val;
65         char **key;
66         unsigned *hash;
67 } dictionary;
68
69 /**
70  * @brief Compute the hash key for a string.
71  * @param key Character string to use for key.
72  * @return 1 unsigned int on at least 32 bits.
73  *
74  * This hash function has been taken from an Article in Dr Dobbs Journal.
75  * This is normally a collision-free function, distributing keys evenly.
76  * The key is stored anyway in the struct so that collision can be avoided
77  * by comparing the key itself in last resort.
78  */
79 unsigned dictionary_hash(char *key);
80
81 /**
82  * @brief Create a new dictionary object.
83  * @param size Optional initial size of the dictionary.
84  * @return allocated dictionary object on success, NULL on failure
85  *
86  * This function allocates a new dictionary object of given size and returns
87  * it. If you do not know in advance (roughly) the number of entries in the
88  * dictionary, give size=0.
89  */
90 dictionary *dictionary_new(int size);
91
92 /**
93  * @brief Delete a dictionary object
94  * @param d dictionary object to deallocate.
95  * @return void
96  *
97  * Deallocate a dictionary object and all memory associated to it.
98  */
99 void dictionary_del(dictionary *vd);
100
101 /**
102  * @brief Get a value from a dictionary.
103  * @param d dictionary object to search.
104  * @param key Key to look for in the dictionary.
105  * @param def Default value to return if key not found.
106  * @return 1 pointer to internally allocated character string.
107  *
108  * This function locates a key in a dictionary and returns a pointer to its
109  * value, or the passed 'def' pointer if no such key can be found in
110  * dictionary. The returned character pointer points to data internal to the
111  * dictionary object, you should not try to free it or modify it.
112  */
113 char *dictionary_get(dictionary *d, char *key, char *def);
114
115 /**
116  * @brief Set a value in a dictionary.
117  * @param d dictionary object to modify.
118  * @param key Key to modify or add.
119  * @param val Value to add.
120  * @return int 0 if Ok, anything else otherwise
121  *
122  * If the given key is found in the dictionary, the associated value is
123  * replaced by the provided one. If the key cannot be found in the
124  * dictionary, it is added to it.
125  *
126  * It is Ok to provide a NULL value for val, but NULL values for the dictionary
127  * or the key are considered as errors: the function will return immediately
128  * in such a case.
129  *
130  * Notice that if you dictionary_set a variable to NULL, a call to
131  * dictionary_get will return a NULL value: the variable will be found, and
132  * its value (NULL) is returned. In other words, setting the variable
133  * content to NULL is equivalent to deleting the variable from the
134  * dictionary. It is not possible (in this implementation) to have a key in
135  * the dictionary without value.
136  *
137  * This function returns non-zero in case of failure.
138  */
139 int dictionary_set(dictionary *vd, char *key, char *val);
140
141 /**
142  * @brief Delete a key in a dictionary
143  * @param d dictionary object to modify.
144  * @param key Key to remove.
145  * @return void
146  *
147  * This function deletes a key in a dictionary. Nothing is done if the
148  * key cannot be found.
149  */
150 void dictionary_unset(dictionary *d, char *key);
151
152 /**
153  * @brief Dump a dictionary to an opened file pointer.
154  * @param d Dictionary to dump
155  * @param out 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 void dictionary_dump(dictionary *d, FILE *out);
163
164 #endif
165 /** @}
166  */