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
|
/* tinyproxy - A fast light-weight HTTP proxy
* 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.,
* 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
*/
/* See 'hashmap.c' for detailed information. */
#ifndef _HASHMAP_H
#define _HASHMAP_H
#include "common.h"
/*
* 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);
#endif /* _HASHMAP_H */
|
