technical-docs: document hash API
[git/git.git] / Documentation / technical / api-hash.txt
1 hash API
2 ========
3
4 The hash API is a collection of simple hash table functions. Users are expected
5 to implement their own hashing.
6
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.