technical-docs: document hash API
Signed-off-by: Stephen Boyd <bebarino@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Stephen Boyd committed
Dec 17, 2009 at 16:05 UTC
afab0fe052b8a6b36c3860f7673ee1e9731c1679
1 file changed
+48
-2
Documentation/technical/api-hash.txt
+48
-2
@@ -1,6 +1,52 @@
1
hash API
2
========
3
4
-Talk about <hash.h>
4
+The hash API is a collection of simple hash table functions. Users are expected
5
+to implement their own hashing.
6
6
-(Linus)
7
+Data Structures
8
+---------------
9
+
10
+`struct hash_table`::
11
+
12
+ The hash table structure. The `array` member points to the hash table
13
+ entries. The `size` member counts the total number of valid and invalid
14
+ entries in the table. The `nr` member keeps track of the number of
15
+ valid entries.
16
+
17
+`struct hash_table_entry`::
18
+
19
+ An opaque structure representing an entry in the hash table. The `hash`
20
+ member is the entry's hash key and the `ptr` member is the entry's
21
+ value.
22
+
23
+Functions
24
+---------
25
+
26
+`init_hash`::
27
+
28
+ Initialize the hash table.
29
+
30
+`free_hash`::
31
+
32
+ Release memory associated with the hash table.
33
+
34
+`insert_hash`::
35
+
36
+ Insert a pointer into the hash table. If an entry with that hash
37
+ already exists, a pointer to the existing entry's value is returned.
38
+ Otherwise NULL is returned. This allows callers to implement
39
+ chaining, etc.
40
+
41
+`lookup_hash`::
42
+
43
+ Lookup an entry in the hash table. If an entry with that hash exists
44
+ the entry's value is returned. Otherwise NULL is returned.
45
+
46
+`for_each_hash`::
47
+
48
+ Call a function for each entry in the hash table. The function is
49
+ expected to take the entry's value as its only argument and return an
50
+ int. If the function returns a negative int the loop is aborted
51
+ immediately. Otherwise, the return value is accumulated and the sum
52
+ returned upon completion of the loop.