Merge branch 'cs/pretty-formats-doc-typofix'
[git/git.git] / oidmap.h
1 #ifndef OIDMAP_H
2 #define OIDMAP_H
3
4 #include "cache.h"
5 #include "hashmap.h"
6
7 /*
8 * struct oidmap_entry is a structure representing an entry in the hash table,
9 * which must be used as first member of user data structures.
10 *
11 * Users should set the oid field. oidmap_put() will populate the
12 * internal_entry field.
13 */
14 struct oidmap_entry {
15 /* For internal use only */
16 struct hashmap_entry internal_entry;
17
18 struct object_id oid;
19 };
20
21 struct oidmap {
22 struct hashmap map;
23 };
24
25 #define OIDMAP_INIT { { NULL } }
26
27 /*
28 * Initializes an oidmap structure.
29 *
30 * `map` is the oidmap to initialize.
31 *
32 * If the total number of entries is known in advance, the `initial_size`
33 * parameter may be used to preallocate a sufficiently large table and thus
34 * prevent expensive resizing. If 0, the table is dynamically resized.
35 */
36 void oidmap_init(struct oidmap *map, size_t initial_size);
37
38 /*
39 * Frees an oidmap structure and allocated memory.
40 *
41 * If `free_entries` is true, each oidmap_entry in the map is freed as well
42 * using stdlibs free().
43 */
44 void oidmap_free(struct oidmap *map, int free_entries);
45
46 /*
47 * Returns the oidmap entry for the specified oid, or NULL if not found.
48 */
49 void *oidmap_get(const struct oidmap *map,
50 const struct object_id *key);
51
52 /*
53 * Adds or replaces an oidmap entry.
54 *
55 * ((struct oidmap_entry *) entry)->internal_entry will be populated by this
56 * function.
57 *
58 * Returns the replaced entry, or NULL if not found (i.e. the entry was added).
59 */
60 void *oidmap_put(struct oidmap *map, void *entry);
61
62 /*
63 * Removes an oidmap entry matching the specified oid.
64 *
65 * Returns the removed entry, or NULL if not found.
66 */
67 void *oidmap_remove(struct oidmap *map, const struct object_id *key);
68
69
70 struct oidmap_iter {
71 struct hashmap_iter h_iter;
72 };
73
74 static inline void oidmap_iter_init(struct oidmap *map, struct oidmap_iter *iter)
75 {
76 hashmap_iter_init(&map->map, &iter->h_iter);
77 }
78
79 static inline void *oidmap_iter_next(struct oidmap_iter *iter)
80 {
81 return hashmap_iter_next(&iter->h_iter);
82 }
83
84 static inline void *oidmap_iter_first(struct oidmap *map,
85 struct oidmap_iter *iter)
86 {
87 oidmap_iter_init(map, iter);
88 return oidmap_iter_next(iter);
89 }
90
91 #endif