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