1 /*
2  * Copyright (C) the libgit2 contributors. All rights reserved.
3  *
4  * This file is part of libgit2, distributed under the GNU GPL v2 with
5  * a Linking Exception. For full terms see the included COPYING file.
6  */
7 #ifndef INCLUDE_idxmap_h__
8 #define INCLUDE_idxmap_h__
9 
10 #include "common.h"
11 
12 #include "git2/index.h"
13 
14 /** A map with `git_index_entry`s as key. */
15 typedef struct kh_idx_s git_idxmap;
16 /** A map with case-insensitive `git_index_entry`s as key */
17 typedef struct kh_idxicase_s git_idxmap_icase;
18 
19 /**
20  * Allocate a new index entry map.
21  *
22  * @param out Pointer to the map that shall be allocated.
23  * @return 0 on success, an error code if allocation has failed.
24  */
25 int git_idxmap_new(git_idxmap **out);
26 
27 /**
28  * Allocate a new case-insensitive index entry map.
29  *
30  * @param out Pointer to the map that shall be allocated.
31  * @return 0 on success, an error code if allocation has failed.
32  */
33 int git_idxmap_icase_new(git_idxmap_icase **out);
34 
35 /**
36  * Free memory associated with the map.
37  *
38  * Note that this function will _not_ free values added to this
39  * map.
40  *
41  * @param map Pointer to the map that is to be free'd. May be
42  *            `NULL`.
43  */
44 void git_idxmap_free(git_idxmap *map);
45 
46 /**
47  * Free memory associated with the map.
48  *
49  * Note that this function will _not_ free values added to this
50  * map.
51  *
52  * @param map Pointer to the map that is to be free'd. May be
53  *            `NULL`.
54  */
55 void git_idxmap_icase_free(git_idxmap_icase *map);
56 
57 /**
58  * Clear all entries from the map.
59  *
60  * This function will remove all entries from the associated map.
61  * Memory associated with it will not be released, though.
62  *
63  * @param map Pointer to the map that shall be cleared. May be
64  *            `NULL`.
65  */
66 void git_idxmap_clear(git_idxmap *map);
67 
68 /**
69  * Clear all entries from the map.
70  *
71  * This function will remove all entries from the associated map.
72  * Memory associated with it will not be released, though.
73  *
74  * @param map Pointer to the map that shall be cleared. May be
75  *            `NULL`.
76  */
77 void git_idxmap_icase_clear(git_idxmap_icase *map);
78 
79 /**
80  * Resize the map by allocating more memory.
81  *
82  * @param map map that shall be resized
83  * @param size count of entries that the map shall hold
84  * @return `0` if the map was successfully resized, a negative
85  *         error code otherwise
86  */
87 int git_idxmap_resize(git_idxmap *map, size_t size);
88 
89 /**
90  * Resize the map by allocating more memory.
91  *
92  * @param map map that shall be resized
93  * @param size count of entries that the map shall hold
94  * @return `0` if the map was successfully resized, a negative
95  *         error code otherwise
96  */
97 int git_idxmap_icase_resize(git_idxmap_icase *map, size_t size);
98 
99 /**
100  * Return value associated with the given key.
101  *
102  * @param map map to search key in
103  * @param key key to search for; the index entry will be searched
104  *            for by its case-sensitive path
105  * @return value associated with the given key or NULL if the key was not found
106  */
107 void *git_idxmap_get(git_idxmap *map, const git_index_entry *key);
108 
109 /**
110  * Return value associated with the given key.
111  *
112  * @param map map to search key in
113  * @param key key to search for; the index entry will be searched
114  *            for by its case-insensitive path
115  * @return value associated with the given key or NULL if the key was not found
116  */
117 void *git_idxmap_icase_get(git_idxmap_icase *map, const git_index_entry *key);
118 
119 /**
120  * Set the entry for key to value.
121  *
122  * If the map has no corresponding entry for the given key, a new
123  * entry will be created with the given value. If an entry exists
124  * already, its value will be updated to match the given value.
125  *
126  * @param map map to create new entry in
127  * @param key key to set
128  * @param value value to associate the key with; may be NULL
129  * @return zero if the key was successfully set, a negative error
130  *         code otherwise
131  */
132 int git_idxmap_set(git_idxmap *map, const git_index_entry *key, void *value);
133 
134 /**
135  * Set the entry for key to value.
136  *
137  * If the map has no corresponding entry for the given key, a new
138  * entry will be created with the given value. If an entry exists
139  * already, its value will be updated to match the given value.
140  *
141  * @param map map to create new entry in
142  * @param key key to set
143  * @param value value to associate the key with; may be NULL
144  * @return zero if the key was successfully set, a negative error
145  *         code otherwise
146  */
147 int git_idxmap_icase_set(git_idxmap_icase *map, const git_index_entry *key, void *value);
148 
149 /**
150  * Delete an entry from the map.
151  *
152  * Delete the given key and its value from the map. If no such
153  * key exists, this will do nothing.
154  *
155  * @param map map to delete key in
156  * @param key key to delete
157  * @return `0` if the key has been deleted, GIT_ENOTFOUND if no
158  *         such key was found, a negative code in case of an
159  *         error
160  */
161 int git_idxmap_delete(git_idxmap *map, const git_index_entry *key);
162 
163 /**
164  * Delete an entry from the map.
165  *
166  * Delete the given key and its value from the map. If no such
167  * key exists, this will do nothing.
168  *
169  * @param map map to delete key in
170  * @param key key to delete
171  * @return `0` if the key has been deleted, GIT_ENOTFOUND if no
172  *         such key was found, a negative code in case of an
173  *         error
174  */
175 int git_idxmap_icase_delete(git_idxmap_icase *map, const git_index_entry *key);
176 
177 #endif
178