testing/mozbase/mozprocess/tests/iniparser/dictionary.h@6474c204b198
testing/mozbase/mozprocess/tests/iniparser/dictionary.h
Wed, 31 Dec 2014 06:09:35 +0100
- author
- Michael Schloh von Bennewitz <michael@schloh.com>
- date
- Wed, 31 Dec 2014 06:09:35 +0100
- changeset 0
- 6474c204b198
- permissions
- -rw-r--r--
Cloned upstream origin tor-browser at tor-browser-31.3.0esr-4.5-1-build1
revision ID fc1c9ff7c1b2defdbc039f12214767608f46423f for hacking purpose.
2 /*-------------------------------------------------------------------------*/
3 /**
4 @file dictionary.h
5 @author N. Devillard
6 @date Sep 2007
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).
13 */
14 /*--------------------------------------------------------------------------*/
16 /*
17 $Id: dictionary.h,v 1.12 2007-11-23 21:37:00 ndevilla Exp $
18 $Author: ndevilla $
19 $Date: 2007-11-23 21:37:00 $
20 $Revision: 1.12 $
21 */
23 #ifndef _DICTIONARY_H_
24 #define _DICTIONARY_H_
26 /*---------------------------------------------------------------------------
27 Includes
28 ---------------------------------------------------------------------------*/
30 #include <stdio.h>
31 #include <stdlib.h>
32 #include <string.h>
33 #ifndef _WIN32
34 #include <unistd.h>
35 #endif
37 /*---------------------------------------------------------------------------
38 New types
39 ---------------------------------------------------------------------------*/
42 /*-------------------------------------------------------------------------*/
43 /**
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)
49 hash function.
50 */
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 */
58 } dictionary ;
61 /*---------------------------------------------------------------------------
62 Function prototypes
63 ---------------------------------------------------------------------------*/
65 /*-------------------------------------------------------------------------*/
66 /**
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.
75 */
76 /*--------------------------------------------------------------------------*/
77 unsigned dictionary_hash(char * key);
79 /*-------------------------------------------------------------------------*/
80 /**
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.
88 */
89 /*--------------------------------------------------------------------------*/
90 dictionary * dictionary_new(int size);
92 /*-------------------------------------------------------------------------*/
93 /**
94 @brief Delete a dictionary object
95 @param d dictionary object to deallocate.
96 @return void
98 Deallocate a dictionary object and all memory associated to it.
99 */
100 /*--------------------------------------------------------------------------*/
101 void dictionary_del(dictionary * vd);
103 /*-------------------------------------------------------------------------*/
104 /**
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.
115 */
116 /*--------------------------------------------------------------------------*/
117 char * dictionary_get(dictionary * d, char * key, char * def);
120 /*-------------------------------------------------------------------------*/
121 /**
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
134 in such a case.
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.
144 */
145 /*--------------------------------------------------------------------------*/
146 int dictionary_set(dictionary * vd, char * key, char * val);
148 /*-------------------------------------------------------------------------*/
149 /**
150 @brief Delete a key in a dictionary
151 @param d dictionary object to modify.
152 @param key Key to remove.
153 @return void
155 This function deletes a key in a dictionary. Nothing is done if the
156 key cannot be found.
157 */
158 /*--------------------------------------------------------------------------*/
159 void dictionary_unset(dictionary * d, char * key);
162 /*-------------------------------------------------------------------------*/
163 /**
164 @brief Dump a dictionary to an opened file pointer.
165 @param d Dictionary to dump
166 @param f Opened file pointer.
167 @return void
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.
172 */
173 /*--------------------------------------------------------------------------*/
174 void dictionary_dump(dictionary * d, FILE * out);
176 #endif
