1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/testing/mozbase/mozprocess/tests/iniparser/dictionary.h Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,176 @@
1.4 +
1.5 +/*-------------------------------------------------------------------------*/
1.6 +/**
1.7 + @file dictionary.h
1.8 + @author N. Devillard
1.9 + @date Sep 2007
1.10 + @version $Revision: 1.12 $
1.11 + @brief Implements a dictionary for string variables.
1.12 +
1.13 + This module implements a simple dictionary object, i.e. a list
1.14 + of string/string associations. This object is useful to store e.g.
1.15 + informations retrieved from a configuration file (ini files).
1.16 +*/
1.17 +/*--------------------------------------------------------------------------*/
1.18 +
1.19 +/*
1.20 + $Id: dictionary.h,v 1.12 2007-11-23 21:37:00 ndevilla Exp $
1.21 + $Author: ndevilla $
1.22 + $Date: 2007-11-23 21:37:00 $
1.23 + $Revision: 1.12 $
1.24 +*/
1.25 +
1.26 +#ifndef _DICTIONARY_H_
1.27 +#define _DICTIONARY_H_
1.28 +
1.29 +/*---------------------------------------------------------------------------
1.30 + Includes
1.31 + ---------------------------------------------------------------------------*/
1.32 +
1.33 +#include <stdio.h>
1.34 +#include <stdlib.h>
1.35 +#include <string.h>
1.36 +#ifndef _WIN32
1.37 +#include <unistd.h>
1.38 +#endif
1.39 +
1.40 +/*---------------------------------------------------------------------------
1.41 + New types
1.42 + ---------------------------------------------------------------------------*/
1.43 +
1.44 +
1.45 +/*-------------------------------------------------------------------------*/
1.46 +/**
1.47 + @brief Dictionary object
1.48 +
1.49 + This object contains a list of string/string associations. Each
1.50 + association is identified by a unique string key. Looking up values
1.51 + in the dictionary is speeded up by the use of a (hopefully collision-free)
1.52 + hash function.
1.53 + */
1.54 +/*-------------------------------------------------------------------------*/
1.55 +typedef struct _dictionary_ {
1.56 + int n ; /** Number of entries in dictionary */
1.57 + int size ; /** Storage size */
1.58 + char ** val ; /** List of string values */
1.59 + char ** key ; /** List of string keys */
1.60 + unsigned * hash ; /** List of hash values for keys */
1.61 +} dictionary ;
1.62 +
1.63 +
1.64 +/*---------------------------------------------------------------------------
1.65 + Function prototypes
1.66 + ---------------------------------------------------------------------------*/
1.67 +
1.68 +/*-------------------------------------------------------------------------*/
1.69 +/**
1.70 + @brief Compute the hash key for a string.
1.71 + @param key Character string to use for key.
1.72 + @return 1 unsigned int on at least 32 bits.
1.73 +
1.74 + This hash function has been taken from an Article in Dr Dobbs Journal.
1.75 + This is normally a collision-free function, distributing keys evenly.
1.76 + The key is stored anyway in the struct so that collision can be avoided
1.77 + by comparing the key itself in last resort.
1.78 + */
1.79 +/*--------------------------------------------------------------------------*/
1.80 +unsigned dictionary_hash(char * key);
1.81 +
1.82 +/*-------------------------------------------------------------------------*/
1.83 +/**
1.84 + @brief Create a new dictionary object.
1.85 + @param size Optional initial size of the dictionary.
1.86 + @return 1 newly allocated dictionary objet.
1.87 +
1.88 + This function allocates a new dictionary object of given size and returns
1.89 + it. If you do not know in advance (roughly) the number of entries in the
1.90 + dictionary, give size=0.
1.91 + */
1.92 +/*--------------------------------------------------------------------------*/
1.93 +dictionary * dictionary_new(int size);
1.94 +
1.95 +/*-------------------------------------------------------------------------*/
1.96 +/**
1.97 + @brief Delete a dictionary object
1.98 + @param d dictionary object to deallocate.
1.99 + @return void
1.100 +
1.101 + Deallocate a dictionary object and all memory associated to it.
1.102 + */
1.103 +/*--------------------------------------------------------------------------*/
1.104 +void dictionary_del(dictionary * vd);
1.105 +
1.106 +/*-------------------------------------------------------------------------*/
1.107 +/**
1.108 + @brief Get a value from a dictionary.
1.109 + @param d dictionary object to search.
1.110 + @param key Key to look for in the dictionary.
1.111 + @param def Default value to return if key not found.
1.112 + @return 1 pointer to internally allocated character string.
1.113 +
1.114 + This function locates a key in a dictionary and returns a pointer to its
1.115 + value, or the passed 'def' pointer if no such key can be found in
1.116 + dictionary. The returned character pointer points to data internal to the
1.117 + dictionary object, you should not try to free it or modify it.
1.118 + */
1.119 +/*--------------------------------------------------------------------------*/
1.120 +char * dictionary_get(dictionary * d, char * key, char * def);
1.121 +
1.122 +
1.123 +/*-------------------------------------------------------------------------*/
1.124 +/**
1.125 + @brief Set a value in a dictionary.
1.126 + @param d dictionary object to modify.
1.127 + @param key Key to modify or add.
1.128 + @param val Value to add.
1.129 + @return int 0 if Ok, anything else otherwise
1.130 +
1.131 + If the given key is found in the dictionary, the associated value is
1.132 + replaced by the provided one. If the key cannot be found in the
1.133 + dictionary, it is added to it.
1.134 +
1.135 + It is Ok to provide a NULL value for val, but NULL values for the dictionary
1.136 + or the key are considered as errors: the function will return immediately
1.137 + in such a case.
1.138 +
1.139 + Notice that if you dictionary_set a variable to NULL, a call to
1.140 + dictionary_get will return a NULL value: the variable will be found, and
1.141 + its value (NULL) is returned. In other words, setting the variable
1.142 + content to NULL is equivalent to deleting the variable from the
1.143 + dictionary. It is not possible (in this implementation) to have a key in
1.144 + the dictionary without value.
1.145 +
1.146 + This function returns non-zero in case of failure.
1.147 + */
1.148 +/*--------------------------------------------------------------------------*/
1.149 +int dictionary_set(dictionary * vd, char * key, char * val);
1.150 +
1.151 +/*-------------------------------------------------------------------------*/
1.152 +/**
1.153 + @brief Delete a key in a dictionary
1.154 + @param d dictionary object to modify.
1.155 + @param key Key to remove.
1.156 + @return void
1.157 +
1.158 + This function deletes a key in a dictionary. Nothing is done if the
1.159 + key cannot be found.
1.160 + */
1.161 +/*--------------------------------------------------------------------------*/
1.162 +void dictionary_unset(dictionary * d, char * key);
1.163 +
1.164 +
1.165 +/*-------------------------------------------------------------------------*/
1.166 +/**
1.167 + @brief Dump a dictionary to an opened file pointer.
1.168 + @param d Dictionary to dump
1.169 + @param f Opened file pointer.
1.170 + @return void
1.171 +
1.172 + Dumps a dictionary onto an opened file pointer. Key pairs are printed out
1.173 + as @c [Key]=[Value], one per line. It is Ok to provide stdout or stderr as
1.174 + output file pointers.
1.175 + */
1.176 +/*--------------------------------------------------------------------------*/
1.177 +void dictionary_dump(dictionary * d, FILE * out);
1.178 +
1.179 +#endif
