Toby Harris / iniparser

http://ndevilla.free.fr/iniparser/ Welcome to iniParser -- version 3.1 released 08 Apr 2012 This modules offers parsing of ini files from the C level. See a complete documentation in HTML format, from this directory open the file html/index.html with any HTML-capable browser. Enjoy! N.Devillard Sun Apr 8 16:38:09 CEST 2012

Dependents:   SPK-DVIMXR

dictionary.h@0:1a9f9f36242e, 2012-09-17 (annotated)

Committer:
tobyspark
Date:
Mon Sep 17 00:33:09 2012 +0000
Revision:
0:1a9f9f36242e
//#include <unistd.h> // Not required for MBED

Who changed what in which revision?

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