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