dictionary.h

00001 
00002 /*-------------------------------------------------------------------------*/
00003 /**
00004    @file    dictionary.h
00005    @author  N. Devillard
00006    @date    Sep 2007
00007    @version $Revision: 1.12 $
00008    @brief   Implements a dictionary for string variables.
00009 
00010    This module implements a simple dictionary object, i.e. a list
00011    of string/string associations. This object is useful to store e.g.
00012    informations retrieved from a configuration file (ini files).
00013 */
00014 /*--------------------------------------------------------------------------*/
00015 
00016 /*
00017     $Id: dictionary.h,v 1.12 2007-11-23 21:37:00 ndevilla Exp $
00018     $Author: ndevilla $
00019     $Date: 2007-11-23 21:37:00 $
00020     $Revision: 1.12 $
00021 */
00022 
00023 #ifndef _DICTIONARY_H_
00024 #define _DICTIONARY_H_
00025 
00026 /*---------------------------------------------------------------------------
00027                                    Includes
00028  ---------------------------------------------------------------------------*/
00029 
00030 #include <stdio.h>
00031 #include <stdlib.h>
00032 #include <string.h>
00033 //#include <unistd.h>
00034 
00035 /*---------------------------------------------------------------------------
00036                                    New types
00037  ---------------------------------------------------------------------------*/
00038 
00039 
00040 /*-------------------------------------------------------------------------*/
00041 /**
00042   @brief    Dictionary object
00043 
00044   This object contains a list of string/string associations. Each
00045   association is identified by a unique string key. Looking up values
00046   in the dictionary is speeded up by the use of a (hopefully collision-free)
00047   hash function.
00048  */
00049 /*-------------------------------------------------------------------------*/
00050 typedef struct _dictionary_ {
00051     int                n ;        /** Number of entries in dictionary */
00052     int                size ;    /** Storage size */
00053     char         **    val ;    /** List of string values */
00054     char         **  key ;    /** List of string keys */
00055     unsigned     *    hash ;    /** List of hash values for keys */
00056 } dictionary ;
00057 
00058 
00059 /*---------------------------------------------------------------------------
00060                               Function prototypes
00061  ---------------------------------------------------------------------------*/
00062 
00063 /*-------------------------------------------------------------------------*/
00064 /**
00065   @brief    Compute the hash key for a string.
00066   @param    key     Character string to use for key.
00067   @return   1 unsigned int on at least 32 bits.
00068 
00069   This hash function has been taken from an Article in Dr Dobbs Journal.
00070   This is normally a collision-free function, distributing keys evenly.
00071   The key is stored anyway in the struct so that collision can be avoided
00072   by comparing the key itself in last resort.
00073  */
00074 /*--------------------------------------------------------------------------*/
00075 unsigned dictionary_hash(char * key);
00076 
00077 /*-------------------------------------------------------------------------*/
00078 /**
00079   @brief    Create a new dictionary object.
00080   @param    size    Optional initial size of the dictionary.
00081   @return   1 newly allocated dictionary objet.
00082 
00083   This function allocates a new dictionary object of given size and returns
00084   it. If you do not know in advance (roughly) the number of entries in the
00085   dictionary, give size=0.
00086  */
00087 /*--------------------------------------------------------------------------*/
00088 dictionary * dictionary_new(int size);
00089 
00090 /*-------------------------------------------------------------------------*/
00091 /**
00092   @brief    Delete a dictionary object
00093   @param    d   dictionary object to deallocate.
00094   @return   void
00095 
00096   Deallocate a dictionary object and all memory associated to it.
00097  */
00098 /*--------------------------------------------------------------------------*/
00099 void dictionary_del(dictionary * vd);
00100 
00101 /*-------------------------------------------------------------------------*/
00102 /**
00103   @brief    Get a value from a dictionary.
00104   @param    d       dictionary object to search.
00105   @param    key     Key to look for in the dictionary.
00106   @param    def     Default value to return if key not found.
00107   @return   1 pointer to internally allocated character string.
00108 
00109   This function locates a key in a dictionary and returns a pointer to its
00110   value, or the passed 'def' pointer if no such key can be found in
00111   dictionary. The returned character pointer points to data internal to the
00112   dictionary object, you should not try to free it or modify it.
00113  */
00114 /*--------------------------------------------------------------------------*/
00115 char * dictionary_get(dictionary * d, char * key, char * def);
00116 
00117 
00118 /*-------------------------------------------------------------------------*/
00119 /**
00120   @brief    Set a value in a dictionary.
00121   @param    d       dictionary object to modify.
00122   @param    key     Key to modify or add.
00123   @param    val     Value to add.
00124   @return   int     0 if Ok, anything else otherwise
00125 
00126   If the given key is found in the dictionary, the associated value is
00127   replaced by the provided one. If the key cannot be found in the
00128   dictionary, it is added to it.
00129 
00130   It is Ok to provide a NULL value for val, but NULL values for the dictionary
00131   or the key are considered as errors: the function will return immediately
00132   in such a case.
00133 
00134   Notice that if you dictionary_set a variable to NULL, a call to
00135   dictionary_get will return a NULL value: the variable will be found, and
00136   its value (NULL) is returned. In other words, setting the variable
00137   content to NULL is equivalent to deleting the variable from the
00138   dictionary. It is not possible (in this implementation) to have a key in
00139   the dictionary without value.
00140 
00141   This function returns non-zero in case of failure.
00142  */
00143 /*--------------------------------------------------------------------------*/
00144 int dictionary_set(dictionary * vd, char * key, char * val);
00145 
00146 /*-------------------------------------------------------------------------*/
00147 /**
00148   @brief    Delete a key in a dictionary
00149   @param    d       dictionary object to modify.
00150   @param    key     Key to remove.
00151   @return   void
00152 
00153   This function deletes a key in a dictionary. Nothing is done if the
00154   key cannot be found.
00155  */
00156 /*--------------------------------------------------------------------------*/
00157 void dictionary_unset(dictionary * d, char * key);
00158 
00159 
00160 /*-------------------------------------------------------------------------*/
00161 /**
00162   @brief    Dump a dictionary to an opened file pointer.
00163   @param    d   Dictionary to dump
00164   @param    f   Opened file pointer.
00165   @return   void
00166 
00167   Dumps a dictionary onto an opened file pointer. Key pairs are printed out
00168   as @c [Key]=[Value], one per line. It is Ok to provide stdout or stderr as
00169   output file pointers.
00170  */
00171 /*--------------------------------------------------------------------------*/
00172 void dictionary_dump(dictionary * d, FILE * out);
00173 
00174 #endif