1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
|
/* $Id: hashmap.h,v 1.4 2005-08-15 03:54:31 rjkaes Exp $
*
* A hashmap implementation. The keys are case-insensitive NULL terminated
* strings, and the data is arbitrary lumps of data. Copies of both the
* key and the data in the hashmap itself, so you must free the original
* key and data to avoid a memory leak. The hashmap returns a pointer
* to the data when a key is searched for, so take care in modifying the
* data as it's modifying the data stored in the hashmap. (In other words,
* don't try to free the data, or realloc the memory. :)
*
* Copyright (C) 2002 Robert James Kaes (rjkaes@users.sourceforge.net)
*
* This program is free software; you can redistribute it and/or modify
* it under the terms of the GNU General Public License as published by
* the Free Software Foundation; either version 2 of the License, or
* (at your option) any later version.
*
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU General Public License for more details.
*
* You should have received a copy of the GNU General Public License
* along with this program; if not, write to the Free Software
* Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
*/
#ifndef _HASHMAP_H
#define _HASHMAP_H
/* Allow the use in C++ code. */
#if defined(__cplusplus)
extern "C" {
#endif
/*
* We're using a typedef here to "hide" the implementation details of the
* hash map. Sure, it's a pointer, but the struct is hidden in the C file.
* So, just use the hashmap_t like it's a cookie. :)
*/
typedef struct hashmap_s *hashmap_t;
typedef int hashmap_iter;
/*
* hashmap_create() takes one argument, which is the number of buckets to
* use internally. hashmap_delete() is self explanatory.
*/
extern hashmap_t hashmap_create(unsigned int nbuckets);
extern int hashmap_delete(hashmap_t map);
/*
* When the you insert a key/data pair into the hashmap it will the key
* and data are duplicated, so you must free your copy if it was created
* on the heap. The key must be a NULL terminated string. "data" must be
* non-NULL and length must be greater than zero.
*
* Returns: negative on error
* 0 upon successful insert
*/
extern int hashmap_insert(hashmap_t map, const char *key,
const void *data, size_t len);
/*
* Get an iterator to the first entry.
*
* Returns: an negative value upon error.
*/
extern hashmap_iter hashmap_first(hashmap_t map);
/*
* Checks to see if the iterator is pointing at the "end" of the entries.
*
* Returns: 1 if it is the end
* 0 otherwise
*/
extern int hashmap_is_end(hashmap_t map, hashmap_iter iter);
/*
* Return a "pointer" to the first instance of the particular key. It can
* be tested against hashmap_is_end() to see if the key was not found.
*
* Returns: negative upon an error
* an "iterator" pointing at the first key
* an "end-iterator" if the key wasn't found
*/
extern hashmap_iter hashmap_find(hashmap_t map, const char *key);
/*
* Retrieve the key/data associated with a particular iterator.
* NOTE: These are pointers to the actual data, so don't mess around with them
* too much.
*
* Returns: the length of the data block upon success
* negative upon error
*/
extern ssize_t hashmap_return_entry(hashmap_t map, hashmap_iter iter,
char **key, void **data);
/*
* Get the first entry (assuming there is more than one) for a particular
* key. The data MUST be non-NULL.
*
* Returns: negative upon error
* zero if no entry is found
* length of data for the entry
*/
extern ssize_t hashmap_entry_by_key(hashmap_t map, const char *key,
void **data);
/*
* Searches for _any_ occurrances of "key" within the hashmap and returns the
* number of matching entries.
*
* Returns: negative upon an error
* zero if no key is found
* count found (positive value)
*/
extern ssize_t hashmap_search(hashmap_t map, const char *key);
/*
* Go through the hashmap and remove the particular key.
* NOTE: This will invalidate any iterators which have been created.
*
* Remove: negative upon error
* 0 if the key was not found
* positive count of entries deleted
*/
extern ssize_t hashmap_remove(hashmap_t map, const char *key);
#if defined(__cplusplus)
}
#endif /* C++ */
#endif /* _HASHMAP_H */
|
