Re: [PATCHv3 1/4] cache.h: document index_name_pos
From: Junio C Hamano <hidden>
Date: 2017-01-19 20:22:03
Stefan Beller [off-list ref] writes:
quoted hunk
Signed-off-by: Stefan Beller <redacted> --- cache.h | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+)diff --git a/cache.h b/cache.h index 1b67f078dd..1469ddeafe 100644 --- a/cache.h +++ b/cache.h@@ -575,7 +575,26 @@ extern int verify_path(const char *path); extern int index_dir_exists(struct index_state *istate, const char *name, int namelen); extern void adjust_dirname_case(struct index_state *istate, char *name); extern struct cache_entry *index_file_exists(struct index_state *istate, const char *name, int namelen, int igncase); + +/* + * Searches for an entry defined by name and namelen in the given index. + * If the return value is positive (including 0) it is the position of an + * exact match. If the return value is negative, the negated value minus 1 + * is the position where the entry would be inserted.
So if the return value is -3, you negate it to get 3 and then subtract 1 to get 2. The function is telling you that "e" will sit at active_cache[2] in the following example. Which is correct.
+ * Example: The current index consists of these files and its stages: + * + * b#0, d#0, f#1, f#3 + * + * index_name_pos(&index, "a", 1) -> -1 + * index_name_pos(&index, "b", 1) -> 0 + * index_name_pos(&index, "c", 1) -> -2 + * index_name_pos(&index, "d", 1) -> 1 + * index_name_pos(&index, "e", 1) -> -3 + * index_name_pos(&index, "f", 1) -> -3 + * index_name_pos(&index, "g", 1) -> -5 + */
This time the counting seems correct. Thanks.