dictionary.h   dictionary.h 
/*------------------------------------------------------------------------- */ /*------------------------------------------------------------------------- */
/** /**
@file dictionary.h @file dictionary.h
@author N. Devillard @author N. Devillard
@date Sep 2007
@version $Revision: 1.12 $
@brief Implements a dictionary for string variables. @brief Implements a dictionary for string variables.
This module implements a simple dictionary object, i.e. a list This module implements a simple dictionary object, i.e. a list
of string/string associations. This object is useful to store e.g. of string/string associations. This object is useful to store e.g.
informations retrieved from a configuration file (ini files). informations retrieved from a configuration file (ini files).
*/ */
/*------------------------------------------------------------------------- -*/ /*------------------------------------------------------------------------- -*/
/*
$Id: dictionary.h,v 1.12 2007-11-23 21:37:00 ndevilla Exp $
$Author: ndevilla $
$Date: 2007-11-23 21:37:00 $
$Revision: 1.12 $
*/
#ifndef _DICTIONARY_H_ #ifndef _DICTIONARY_H_
#define _DICTIONARY_H_ #define _DICTIONARY_H_
/*------------------------------------------------------------------------- -- /*------------------------------------------------------------------------- --
Includes Includes
-------------------------------------------------------------------------- -*/ -------------------------------------------------------------------------- -*/
#include <stdio.h> #include <stdio.h>
#include <stdlib.h> #include <stdlib.h>
#include <string.h> #include <string.h>
#include <unistd.h> #include <unistd.h>
/*------------------------------------------------------------------------- -- /*------------------------------------------------------------------------- --
New types New types
-------------------------------------------------------------------------- -*/ -------------------------------------------------------------------------- -*/
/*------------------------------------------------------------------------- */ /*------------------------------------------------------------------------- */
/** /**
@brief Dictionary object @brief Dictionary object
This object contains a list of string/string associations. Each This object contains a list of string/string associations. Each
association is identified by a unique string key. Looking up values association is identified by a unique string key. Looking up values
in the dictionary is speeded up by the use of a (hopefully collision-free ) in the dictionary is speeded up by the use of a (hopefully collision-free )
hash function. hash function.
*/ */
/*------------------------------------------------------------------------- */ /*------------------------------------------------------------------------- */
typedef struct _dictionary_ { typedef struct _dictionary_ {
int n ; /** Number of entrie int n ; /** Number of entries in dictionary */
s in dictionary */ int size ; /** Storage size */
int size ; /** Storage size */ char ** val ; /** List of string values */
char ** val ; /** List of string values */ char ** key ; /** List of string keys */
char ** key ; /** List of string keys */ unsigned * hash ; /** List of hash values for keys */
unsigned * hash ; /** List of hash values for keys */
} dictionary ; } dictionary ;
/*------------------------------------------------------------------------- -- /*------------------------------------------------------------------------- --
Function prototypes Function prototypes
-------------------------------------------------------------------------- -*/ -------------------------------------------------------------------------- -*/
/*------------------------------------------------------------------------- */ /*------------------------------------------------------------------------- */
/** /**
@brief Compute the hash key for a string. @brief Compute the hash key for a string.
@param key Character string to use for key. @param key Character string to use for key.
@return 1 unsigned int on at least 32 bits. @return 1 unsigned int on at least 32 bits.
This hash function has been taken from an Article in Dr Dobbs Journal. This hash function has been taken from an Article in Dr Dobbs Journal.
This is normally a collision-free function, distributing keys evenly. This is normally a collision-free function, distributing keys evenly.
The key is stored anyway in the struct so that collision can be avoided The key is stored anyway in the struct so that collision can be avoided
by comparing the key itself in last resort. by comparing the key itself in last resort.
*/ */
/*------------------------------------------------------------------------- -*/ /*------------------------------------------------------------------------- -*/
unsigned dictionary_hash(char * key); unsigned dictionary_hash(const char * key);
/*------------------------------------------------------------------------- */ /*------------------------------------------------------------------------- */
/** /**
@brief Create a new dictionary object. @brief Create a new dictionary object.
@param size Optional initial size of the dictionary. @param size Optional initial size of the dictionary.
@return 1 newly allocated dictionary objet. @return 1 newly allocated dictionary objet.
This function allocates a new dictionary object of given size and returns This function allocates a new dictionary object of given size and returns
it. If you do not know in advance (roughly) the number of entries in the it. If you do not know in advance (roughly) the number of entries in the
dictionary, give size=0. dictionary, give size=0.
skipping to change at line 113 skipping to change at line 104
@param key Key to look for in the dictionary. @param key Key to look for in the dictionary.
@param def Default value to return if key not found. @param def Default value to return if key not found.
@return 1 pointer to internally allocated character string. @return 1 pointer to internally allocated character string.
This function locates a key in a dictionary and returns a pointer to its This function locates a key in a dictionary and returns a pointer to its
value, or the passed 'def' pointer if no such key can be found in value, or the passed 'def' pointer if no such key can be found in
dictionary. The returned character pointer points to data internal to the dictionary. The returned character pointer points to data internal to the
dictionary object, you should not try to free it or modify it. dictionary object, you should not try to free it or modify it.
*/ */
/*------------------------------------------------------------------------- -*/ /*------------------------------------------------------------------------- -*/
char * dictionary_get(dictionary * d, char * key, char * def); char * dictionary_get(dictionary * d, const char * key, char * def);
/*------------------------------------------------------------------------- */ /*------------------------------------------------------------------------- */
/** /**
@brief Set a value in a dictionary. @brief Set a value in a dictionary.
@param d dictionary object to modify. @param d dictionary object to modify.
@param key Key to modify or add. @param key Key to modify or add.
@param val Value to add. @param val Value to add.
@return int 0 if Ok, anything else otherwise @return int 0 if Ok, anything else otherwise
If the given key is found in the dictionary, the associated value is If the given key is found in the dictionary, the associated value is
skipping to change at line 141 skipping to change at line 132
Notice that if you dictionary_set a variable to NULL, a call to Notice that if you dictionary_set a variable to NULL, a call to
dictionary_get will return a NULL value: the variable will be found, and dictionary_get will return a NULL value: the variable will be found, and
its value (NULL) is returned. In other words, setting the variable its value (NULL) is returned. In other words, setting the variable
content to NULL is equivalent to deleting the variable from the content to NULL is equivalent to deleting the variable from the
dictionary. It is not possible (in this implementation) to have a key in dictionary. It is not possible (in this implementation) to have a key in
the dictionary without value. the dictionary without value.
This function returns non-zero in case of failure. This function returns non-zero in case of failure.
*/ */
/*------------------------------------------------------------------------- -*/ /*------------------------------------------------------------------------- -*/
int dictionary_set(dictionary * vd, char * key, char * val); int dictionary_set(dictionary * vd, const char * key, const char * val);
/*------------------------------------------------------------------------- */ /*------------------------------------------------------------------------- */
/** /**
@brief Delete a key in a dictionary @brief Delete a key in a dictionary
@param d dictionary object to modify. @param d dictionary object to modify.
@param key Key to remove. @param key Key to remove.
@return void @return void
This function deletes a key in a dictionary. Nothing is done if the This function deletes a key in a dictionary. Nothing is done if the
key cannot be found. key cannot be found.
*/ */
/*------------------------------------------------------------------------- -*/ /*------------------------------------------------------------------------- -*/
void dictionary_unset(dictionary * d, char * key); void dictionary_unset(dictionary * d, const char * key);
/*------------------------------------------------------------------------- */ /*------------------------------------------------------------------------- */
/** /**
@brief Dump a dictionary to an opened file pointer. @brief Dump a dictionary to an opened file pointer.
@param d Dictionary to dump @param d Dictionary to dump
@param f Opened file pointer. @param f Opened file pointer.
@return void @return void
Dumps a dictionary onto an opened file pointer. Key pairs are printed out Dumps a dictionary onto an opened file pointer. Key pairs are printed out
as @c [Key]=[Value], one per line. It is Ok to provide stdout or stderr a s as @c [Key]=[Value], one per line. It is Ok to provide stdout or stderr a s
 End of changes. 11 change blocks. 
23 lines changed or deleted 13 lines changed or added


 iniparser.h   iniparser.h 
/*------------------------------------------------------------------------- */ /*------------------------------------------------------------------------- */
/** /**
@file iniparser.h @file iniparser.h
@author N. Devillard @author N. Devillard
@date Sep 2007
@version 3.0
@brief Parser for ini files. @brief Parser for ini files.
*/ */
/*------------------------------------------------------------------------- -*/ /*------------------------------------------------------------------------- -*/
/*
$Id: iniparser.h,v 1.26 2011-03-02 20:15:13 ndevilla Exp $
$Revision: 1.26 $
*/
#ifndef _INIPARSER_H_ #ifndef _INIPARSER_H_
#define _INIPARSER_H_ #define _INIPARSER_H_
/*------------------------------------------------------------------------- -- /*------------------------------------------------------------------------- --
Includes Includes
-------------------------------------------------------------------------- -*/ -------------------------------------------------------------------------- -*/
#include <stdio.h> #include <stdio.h>
#include <stdlib.h> #include <stdlib.h>
#include <string.h> #include <string.h>
/* /*
* The following #include is necessary on many Unixes but not Linux. * The following #include is necessary on many Unixes but not Linux.
* It is not needed for Windows platforms. * It is not needed for Windows platforms.
* Uncomment it if needed. * Uncomment it if needed.
skipping to change at line 91 skipping to change at line 84
This function dumps a given dictionary into a loadable ini file. This function dumps a given dictionary into a loadable ini file.
It is Ok to specify @c stderr or @c stdout as output files. It is Ok to specify @c stderr or @c stdout as output files.
*/ */
/*------------------------------------------------------------------------- -*/ /*------------------------------------------------------------------------- -*/
void iniparser_dump_ini(dictionary * d, FILE * f); void iniparser_dump_ini(dictionary * d, FILE * f);
/*------------------------------------------------------------------------- */ /*------------------------------------------------------------------------- */
/** /**
@brief Save a dictionary section to a loadable ini file
@param d Dictionary to dump
@param s Section name of dictionary to dump
@param f Opened file pointer to dump to
@return void
This function dumps a given section of a given dictionary into a loadable
ini
file. It is Ok to specify @c stderr or @c stdout as output files.
*/
/*-------------------------------------------------------------------------
-*/
void iniparser_dumpsection_ini(dictionary * d, char * s, FILE * f);
/*-------------------------------------------------------------------------
*/
/**
@brief Dump a dictionary to an opened file pointer. @brief Dump a dictionary to an opened file pointer.
@param d Dictionary to dump. @param d Dictionary to dump.
@param f Opened file pointer to dump to. @param f Opened file pointer to dump to.
@return void @return void
This function prints out the contents of a dictionary, one element by This function prints out the contents of a dictionary, one element by
line, onto the provided file pointer. It is OK to specify @c stderr line, onto the provided file pointer. It is OK to specify @c stderr
or @c stdout as output files. This function is meant for debugging or @c stdout as output files. This function is meant for debugging
purposes mostly. purposes mostly.
*/ */
/*------------------------------------------------------------------------- -*/ /*------------------------------------------------------------------------- -*/
void iniparser_dump(dictionary * d, FILE * f); void iniparser_dump(dictionary * d, FILE * f);
/*------------------------------------------------------------------------- */ /*------------------------------------------------------------------------- */
/** /**
@brief Get the number of keys in a section of a dictionary.
@param d Dictionary to examine
@param s Section name of dictionary to examine
@return Number of keys in section
*/
/*-------------------------------------------------------------------------
-*/
int iniparser_getsecnkeys(dictionary * d, char * s);
/*-------------------------------------------------------------------------
*/
/**
@brief Get the number of keys in a section of a dictionary.
@param d Dictionary to examine
@param s Section name of dictionary to examine
@return pointer to statically allocated character strings
This function queries a dictionary and finds all keys in a given section.
Each pointer in the returned char pointer-to-pointer is pointing to
a string allocated in the dictionary; do not free or modify them.
This function returns NULL in case of error.
*/
/*-------------------------------------------------------------------------
-*/
char ** iniparser_getseckeys(dictionary * d, char * s);
/*-------------------------------------------------------------------------
*/
/**
@brief Get the string associated to a key @brief Get the string associated to a key
@param d Dictionary to search @param d Dictionary to search
@param key Key string to look for @param key Key string to look for
@param def Default value to return if key not found. @param def Default value to return if key not found.
@return pointer to statically allocated character string @return pointer to statically allocated character string
This function queries a dictionary for a key. A key as read from an This function queries a dictionary for a key. A key as read from an
ini file is given as "section:key". If the key cannot be found, ini file is given as "section:key". If the key cannot be found,
the pointer passed as 'def' is returned. the pointer passed as 'def' is returned.
The returned char pointer is pointing to a string allocated in The returned char pointer is pointing to a string allocated in
the dictionary, do not free or modify it. the dictionary, do not free or modify it.
*/ */
/*------------------------------------------------------------------------- -*/ /*------------------------------------------------------------------------- -*/
char * iniparser_getstring(dictionary * d, char * key, char * def); char * iniparser_getstring(dictionary * d, const char * key, char * def);
/*------------------------------------------------------------------------- */ /*------------------------------------------------------------------------- */
/** /**
@brief Get the string associated to a key, convert to an int @brief Get the string associated to a key, convert to an int
@param d Dictionary to search @param d Dictionary to search
@param key Key string to look for @param key Key string to look for
@param notfound Value to return in case of error @param notfound Value to return in case of error
@return integer @return integer
This function queries a dictionary for a key. A key as read from an This function queries a dictionary for a key. A key as read from an
skipping to change at line 148 skipping to change at line 182
- "042" -> 34 (octal -> decimal) - "042" -> 34 (octal -> decimal)
- "0x42" -> 66 (hexa -> decimal) - "0x42" -> 66 (hexa -> decimal)
Warning: the conversion may overflow in various ways. Conversion is Warning: the conversion may overflow in various ways. Conversion is
totally outsourced to strtol(), see the associated man page for overflow totally outsourced to strtol(), see the associated man page for overflow
handling. handling.
Credits: Thanks to A. Becker for suggesting strtol() Credits: Thanks to A. Becker for suggesting strtol()
*/ */
/*------------------------------------------------------------------------- -*/ /*------------------------------------------------------------------------- -*/
int iniparser_getint(dictionary * d, char * key, int notfound); int iniparser_getint(dictionary * d, const char * key, int notfound);
/*------------------------------------------------------------------------- */ /*------------------------------------------------------------------------- */
/** /**
@brief Get the string associated to a key, convert to a double @brief Get the string associated to a key, convert to a double
@param d Dictionary to search @param d Dictionary to search
@param key Key string to look for @param key Key string to look for
@param notfound Value to return in case of error @param notfound Value to return in case of error
@return double @return double
This function queries a dictionary for a key. A key as read from an This function queries a dictionary for a key. A key as read from an
ini file is given as "section:key". If the key cannot be found, ini file is given as "section:key". If the key cannot be found,
the notfound value is returned. the notfound value is returned.
*/ */
/*------------------------------------------------------------------------- -*/ /*------------------------------------------------------------------------- -*/
double iniparser_getdouble(dictionary * d, char * key, double notfound); double iniparser_getdouble(dictionary * d, const char * key, double notfoun d);
/*------------------------------------------------------------------------- */ /*------------------------------------------------------------------------- */
/** /**
@brief Get the string associated to a key, convert to a boolean @brief Get the string associated to a key, convert to a boolean
@param d Dictionary to search @param d Dictionary to search
@param key Key string to look for @param key Key string to look for
@param notfound Value to return in case of error @param notfound Value to return in case of error
@return integer @return integer
This function queries a dictionary for a key. A key as read from an This function queries a dictionary for a key. A key as read from an
skipping to change at line 197 skipping to change at line 231
- A string starting with 'n' - A string starting with 'n'
- A string starting with 'N' - A string starting with 'N'
- A string starting with 'f' - A string starting with 'f'
- A string starting with 'F' - A string starting with 'F'
- A string starting with '0' - A string starting with '0'
The notfound value returned if no boolean is identified, does not The notfound value returned if no boolean is identified, does not
necessarily have to be 0 or 1. necessarily have to be 0 or 1.
*/ */
/*------------------------------------------------------------------------- -*/ /*------------------------------------------------------------------------- -*/
int iniparser_getboolean(dictionary * d, char * key, int notfound); int iniparser_getboolean(dictionary * d, const char * key, int notfound);
/*------------------------------------------------------------------------- */ /*------------------------------------------------------------------------- */
/** /**
@brief Set an entry in a dictionary. @brief Set an entry in a dictionary.
@param ini Dictionary to modify. @param ini Dictionary to modify.
@param entry Entry to modify (entry name) @param entry Entry to modify (entry name)
@param val New value to associate to the entry. @param val New value to associate to the entry.
@return int 0 if Ok, -1 otherwise. @return int 0 if Ok, -1 otherwise.
If the given entry can be found in the dictionary, it is modified to If the given entry can be found in the dictionary, it is modified to
contain the provided value. If it cannot be found, -1 is returned. contain the provided value. If it cannot be found, -1 is returned.
It is Ok to set val to NULL. It is Ok to set val to NULL.
*/ */
/*------------------------------------------------------------------------- -*/ /*------------------------------------------------------------------------- -*/
int iniparser_set(dictionary * ini, char * entry, char * val); int iniparser_set(dictionary * ini, const char * entry, const char * val);
/*------------------------------------------------------------------------- */ /*------------------------------------------------------------------------- */
/** /**
@brief Delete an entry in a dictionary @brief Delete an entry in a dictionary
@param ini Dictionary to modify @param ini Dictionary to modify
@param entry Entry to delete (entry name) @param entry Entry to delete (entry name)
@return void @return void
If the given entry can be found, it is deleted from the dictionary. If the given entry can be found, it is deleted from the dictionary.
*/ */
/*------------------------------------------------------------------------- -*/ /*------------------------------------------------------------------------- -*/
void iniparser_unset(dictionary * ini, char * entry); void iniparser_unset(dictionary * ini, const char * entry);
/*------------------------------------------------------------------------- */ /*------------------------------------------------------------------------- */
/** /**
@brief Finds out if a given entry exists in a dictionary @brief Finds out if a given entry exists in a dictionary
@param ini Dictionary to search @param ini Dictionary to search
@param entry Name of the entry to look for @param entry Name of the entry to look for
@return integer 1 if entry exists, 0 otherwise @return integer 1 if entry exists, 0 otherwise
Finds out if a given entry exists in the dictionary. Since sections Finds out if a given entry exists in the dictionary. Since sections
are stored as keys with NULL associated values, this is the only way are stored as keys with NULL associated values, this is the only way
of querying for the presence of sections in a dictionary. of querying for the presence of sections in a dictionary.
*/ */
/*------------------------------------------------------------------------- -*/ /*------------------------------------------------------------------------- -*/
int iniparser_find_entry(dictionary * ini, char * entry) ; int iniparser_find_entry(dictionary * ini, const char * entry) ;
/*------------------------------------------------------------------------- */ /*------------------------------------------------------------------------- */
/** /**
@brief Parse an ini file and return an allocated dictionary object @brief Parse an ini file and return an allocated dictionary object
@param ininame Name of the ini file to read. @param ininame Name of the ini file to read.
@return Pointer to newly allocated dictionary @return Pointer to newly allocated dictionary
This is the parser for ini files. This function is called, providing This is the parser for ini files. This function is called, providing
the name of the file to be read. It returns a dictionary object that the name of the file to be read. It returns a dictionary object that
should not be accessed directly, but through accessor functions should not be accessed directly, but through accessor functions
instead. instead.
The returned dictionary must be freed using iniparser_freedict(). The returned dictionary must be freed using iniparser_freedict().
*/ */
/*------------------------------------------------------------------------- -*/ /*------------------------------------------------------------------------- -*/
dictionary * iniparser_load(char * ininame); dictionary * iniparser_load(const char * ininame);
/*------------------------------------------------------------------------- */ /*------------------------------------------------------------------------- */
/** /**
@brief Free all memory associated to an ini dictionary @brief Free all memory associated to an ini dictionary
@param d Dictionary to free @param d Dictionary to free
@return void @return void
Free all memory associated to an ini dictionary. Free all memory associated to an ini dictionary.
It is mandatory to call this function before the dictionary object It is mandatory to call this function before the dictionary object
gets out of the current context. gets out of the current context.
 End of changes. 13 change blocks. 
16 lines changed or deleted 57 lines changed or added

This html diff was produced by rfcdiff 1.41. The latest version is available from http://tools.ietf.org/tools/rfcdiff/