git.ozlabs.org Git - ccan/blob - ccan/ciniparser/dictionary.h

   1 #ifndef _DICTIONARY_H_
   2 #define _DICTIONARY_H_
   3
   4 /* Copyright (c) 2000-2007 by Nicolas Devillard.
   5  * Copyright (x) 2009 by Tim Post <tinkertim@gmail.com>
   6  * MIT License
   7  *
   8  * Permission is hereby granted, free of charge, to any person obtaining a
   9  * copy of this software and associated documentation files (the "Software"),
  10  * to deal in the Software without restriction, including without limitation
  11  * the rights to use, copy, modify, merge, publish, distribute, sublicense,
  12  * and/or sell copies of the Software, and to permit persons to whom the
  13  * Software is furnished to do so, subject to the following conditions:
  14  *
  15  * The above copyright notice and this permission notice shall be included in
  16  * all copies or substantial portions of the Software.
  17  *
  18  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
  19  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
  20  * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
  21  * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
  22  * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
  23  * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
  24  * DEALINGS IN THE SOFTWARE.
  25  */
  26
  27 #include <stdio.h>
  28 #include <stdlib.h>
  29 #include <string.h>
  30 #include <unistd.h>
  31
  32 /** @addtogroup ciniparser
  33  * @{
  34  */
  35 /**
  36  * @file    dictionary.h
  37  * @author  N. Devillard
  38  * @date    Sep 2007
  39  * @version $Revision: 1.12 $
  40  * @brief   Implements a dictionary for string variables.
  41  *
  42  * This module implements a simple dictionary object, i.e. a list
  43  * of string/string associations. This object is useful to store e.g.
  44  * information retrieved from a configuration file (ini files).
  45  */
  46
  47
  48 /**
  49  * @brief Dictionary object
  50  * @param n Number of entries in the dictionary
  51  * @param size Storage size
  52  * @param val List of string values
  53  * @param key List of string keys
  54  * @param hash List of hash values for keys
  55  *
  56  * This object contains a list of string/string associations. Each
  57  * association is identified by a unique string key. Looking up values
  58  * in the dictionary is speeded up by the use of a (hopefully collision-free)
  59  * hash function.
  60  */
  61 typedef struct _dictionary_ {
  62         int n;
  63         int size;
  64         char **val;
  65         char **key;
  66         unsigned *hash;
  67 } dictionary;
  68
  69 /**
  70  * @brief Compute the hash key for a string.
  71  * @param key Character string to use for key.
  72  * @return 1 unsigned int on at least 32 bits.
  73  *
  74  * This hash function has been taken from an Article in Dr Dobbs Journal.
  75  * This is normally a collision-free function, distributing keys evenly.
  76  * The key is stored anyway in the struct so that collision can be avoided
  77  * by comparing the key itself in last resort.
  78  */
  79 unsigned dictionary_hash(const char *key);
  80
  81 /**
  82  * @brief Create a new dictionary object.
  83  * @param size Optional initial size of the dictionary.
  84  * @return allocated dictionary object on success, NULL on failure
  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 dictionary *dictionary_new(int size);
  91
  92 /**
  93  * @brief Delete a dictionary object
  94  * @param d dictionary object to deallocate.
  95  * @return void
  96  *
  97  * Deallocate a dictionary object and all memory associated to it.
  98  */
  99 void dictionary_del(dictionary *vd);
 100
 101 /**
 102  * @brief Get a value from a dictionary.
 103  * @param d dictionary object to search.
 104  * @param key Key to look for in the dictionary.
 105  * @param def Default value to return if key not found.
 106  * @return 1 pointer to internally allocated character string.
 107  *
 108  * This function locates a key in a dictionary and returns a pointer to its
 109  * value, or the passed 'def' pointer if no such key can be found in
 110  * dictionary. The returned character pointer points to data internal to the
 111  * dictionary object, you should not try to free it or modify it.
 112  */
 113 char *dictionary_get(dictionary *d, const char *key, char *def);
 114
 115 /**
 116  * @brief Set a value in a dictionary.
 117  * @param d dictionary object to modify.
 118  * @param key Key to modify or add.
 119  * @param val Value to add.
 120  * @return int 0 if Ok, anything else otherwise
 121  *
 122  * If the given key is found in the dictionary, the associated value is
 123  * replaced by the provided one. If the key cannot be found in the
 124  * dictionary, it is added to it.
 125  *
 126  * It is Ok to provide a NULL value for val, but NULL values for the dictionary
 127  * or the key are considered as errors: the function will return immediately
 128  * in such a case.
 129  *
 130  * Notice that if you dictionary_set a variable to NULL, a call to
 131  * dictionary_get will return a NULL value: the variable will be found, and
 132  * its value (NULL) is returned. In other words, setting the variable
 133  * content to NULL is equivalent to deleting the variable from the
 134  * dictionary. It is not possible (in this implementation) to have a key in
 135  * the dictionary without value.
 136  *
 137  * This function returns non-zero in case of failure.
 138  */
 139 int dictionary_set(dictionary *vd, const char *key, char *val);
 140
 141 /**
 142  * @brief Delete a key in a dictionary
 143  * @param d dictionary object to modify.
 144  * @param key Key to remove.
 145  * @return void
 146  *
 147  * This function deletes a key in a dictionary. Nothing is done if the
 148  * key cannot be found.
 149  */
 150 void dictionary_unset(dictionary *d, const char *key);
 151
 152 /**
 153  * @brief Dump a dictionary to an opened file pointer.
 154  * @param d Dictionary to dump
 155  * @param out Opened file pointer
 156  * @return void
 157  *
 158  * Dumps a dictionary onto an opened file pointer. Key pairs are printed out
 159  * as @c [Key]=[Value], one per line. It is Ok to provide stdout or stderr as
 160  * output file pointers.
 161  */
 162 void dictionary_dump(dictionary *d, FILE *out);
 163
 164 #endif
 165 /** @}
 166  */