Kannel: Open Source WAP and SMS gateway  $Revision: 5037 $
dict.h
Go to the documentation of this file.
1 /* ====================================================================
2  * The Kannel Software License, Version 1.0
3  *
4  * Copyright (c) 2001-2016 Kannel Group
5  * Copyright (c) 1998-2001 WapIT Ltd.
6  * All rights reserved.
7  *
8  * Redistribution and use in source and binary forms, with or without
9  * modification, are permitted provided that the following conditions
10  * are met:
11  *
12  * 1. Redistributions of source code must retain the above copyright
13  * notice, this list of conditions and the following disclaimer.
14  *
15  * 2. Redistributions in binary form must reproduce the above copyright
16  * notice, this list of conditions and the following disclaimer in
17  * the documentation and/or other materials provided with the
18  * distribution.
19  *
20  * 3. The end-user documentation included with the redistribution,
21  * if any, must include the following acknowledgment:
22  * "This product includes software developed by the
23  * Kannel Group (http://www.kannel.org/)."
24  * Alternately, this acknowledgment may appear in the software itself,
25  * if and wherever such third-party acknowledgments normally appear.
26  *
27  * 4. The names "Kannel" and "Kannel Group" must not be used to
28  * endorse or promote products derived from this software without
29  * prior written permission. For written permission, please
30  * contact org@kannel.org.
31  *
32  * 5. Products derived from this software may not be called "Kannel",
33  * nor may "Kannel" appear in their name, without prior written
34  * permission of the Kannel Group.
35  *
36  * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
37  * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
38  * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
39  * DISCLAIMED. IN NO EVENT SHALL THE KANNEL GROUP OR ITS CONTRIBUTORS
40  * BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY,
41  * OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT
42  * OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
43  * BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
44  * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
45  * OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
46  * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
47  * ====================================================================
48  *
49  * This software consists of voluntary contributions made by many
50  * individuals on behalf of the Kannel Group. For more information on
51  * the Kannel Group, please see <http://www.kannel.org/>.
52  *
53  * Portions of this software are based upon software originally written at
54  * WapIT Ltd., Helsinki, Finland for the Kannel project.
55  */
56 
57 /*
58  * dict.h - lookup data structure using octet strings as keys
59  *
60  * A Dict is an abstract data structure that stores values, represented as
61  * void pointers, and uses octet strings (Octstr) as keys. You can think
62  * of it as an array indexed by octet strings.
63  *
64  * Lars Wirzenius
65  */
66 
67 #ifndef DICT_H
68 #define DICT_H
69 
70 typedef struct Dict Dict;
71 
72 
73 /*
74  * Create a Dict. `size_hint' gives an indication of how many different
75  * keys will be in the Dict at the same time, at most. This is used for
76  * performance optimization; things will work fine, though somewhat
77  * slower, even if it the number is exceeded. `destroy_value' is a pointer
78  * to a function that is called whenever a value stored in the Dict needs
79  * to be destroyed. If `destroy_value' is NULL, then values are not
80  * destroyed by the Dict, they are just discarded.
81  */
82 Dict *dict_create(long size_hint, void (*destroy_value)(void *));
83 
84 
85 /*
86  * Destroy a Dict and all values in it.
87  */
88 void dict_destroy(Dict *dict);
89 
90 
91 /*
92  * Put a new value into a Dict. If the same key existed already, the
93  * old value is destroyed. If `value' is NULL, the old value is destroyed
94  * and the key is removed from the Dict.
95  */
96 void dict_put(Dict *dict, Octstr *key, void *value);
97 
98 /*
99  * Put a new value into a Dict. Return error, if the same key existed all-
100  * ready.
101  */
102 
103 int dict_put_once(Dict *dict, Octstr *key, void *value);
104 
105 /*
106  * Look up a value in a Dict. If there is no value corresponding to a
107  * key, return NULL, otherwise return the value. The value will not
108  * be removed from the Dict.
109  */
110 void *dict_get(Dict *dict, Octstr *key);
111 
112 
113 /*
114  * Remove a value from a Dict without destroying it.
115  */
116 void *dict_remove(Dict *dict, Octstr *key);
117 
118 
119 /*
120  * Return the number of keys which currently exist in the Dict.
121  */
122 long dict_key_count(Dict *dict);
123 
124 
125 /*
126  * Return a list of all the currently defined keys in the Dict. The
127  * caller must destroy the list.
128  */
129 List *dict_keys(Dict *dict);
130 
131 
132 /*
133  * Return a Dict with the duplicate entries, by using the duplicate_value()
134  * function callback to duplicate the value entries.
135  */
136 Dict *dict_duplicate(Dict *dict, void *(*duplicate_value)(void *));
137 
138 
139 /*
140  * Traverse to all elements of a Dict, and execute the passed callback
141  * function with the key as first argument, a void pointer as data argument
142  * and a user defined pointer that is passed along all calls to func.
143  * Returns the number of Dict elements that have been traversed.
144  */
145 long dict_traverse(Dict *dict, void (*func)(Octstr *, void *, void *), void *data);
146 
147 
148 /*
149  * Same as dict_traverse(), but ensures that the elements are sorted before
150  * the traversal. The sorting is done via quick sort, applied via a compare
151  * callback function that compares 2 elements of the overall elements list.
152  */
153 long dict_traverse_sorted(Dict *dict, int (*cmp)(const void *, const void *),
154  void (*func)(Octstr *, void *, void *), void *data);
155 
156 
157 #endif
void dict_destroy(Dict *dict)
Definition: dict.c:215
void dict_put(Dict *dict, Octstr *key, void *value)
Definition: dict.c:240
void * dict_get(Dict *dict, Octstr *key)
Definition: dict.c:286
Dict * dict_duplicate(Dict *dict, void *(*duplicate_value)(void *))
Definition: dict.c:370
List * dict_keys(Dict *dict)
Definition: dict.c:347
int dict_put_once(Dict *dict, Octstr *key, void *value)
Definition: dict.c:271
void * dict_remove(Dict *dict, Octstr *key)
Definition: dict.c:307
long dict_key_count(Dict *dict)
Definition: dict.c:335
long dict_traverse(Dict *dict, void(*func)(Octstr *, void *, void *), void *data)
Definition: dict.c:392
Dict * dict_create(long size_hint, void(*destroy_value)(void *))
Definition: dict.c:192
Definition: dict.c:116
long dict_traverse_sorted(Dict *dict, int(*cmp)(const void *, const void *), void(*func)(Octstr *, void *, void *), void *data)
Definition: dict.c:413
Definition: octstr.c:118
Definition: list.c:102
void(* destroy_value)(void *)
Definition: dict.c:120
See file LICENSE for details about the license agreement for using, modifying, copying or deriving work from this software.