Make iterator APIs consistent with standards

The iterator APIs are not currently consistent with the parameter
ordering of the rest of the codebase.  This rearranges the order
of parameters, simplifies the naming of a number of functions, and
makes somewhat better use of macros internally to clean up the
iterator code.

This also expands the test coverage of iterator functionality,
making sure that case sensitive range-limited iteration works
correctly.

1 files changed, 43 insertions, 54 deletions

diff --git a/src/iterator.h b/src/iterator.h
index a9bccfca8..feb0c2271 100644
--- a/src/iterator.h
+++ b/src/iterator.h
@@ -12,11 +12,6 @@
 #include "vector.h"
 #include "buffer.h"
 
-#define ITERATOR_PREFIXCMP(ITER, STR, PREFIX)	\
-	(((ITER).flags & GIT_ITERATOR_IGNORE_CASE) != 0 ? \
-	git__prefixcmp_icase((STR), (PREFIX)) : \
-	git__prefixcmp((STR), (PREFIX)))
-
 typedef struct git_iterator git_iterator;
 
 typedef enum {
@@ -28,16 +23,18 @@ typedef enum {
 } git_iterator_type_t;
 
 typedef enum {
-	GIT_ITERATOR_IGNORE_CASE = (1 << 0), /* ignore_case */
-	GIT_ITERATOR_DONT_IGNORE_CASE = (1 << 1), /* force ignore_case off */
+	/** ignore case for entry sort order */
+	GIT_ITERATOR_IGNORE_CASE = (1 << 0),
+	/** force case sensitivity for entry sort order */
+	GIT_ITERATOR_DONT_IGNORE_CASE = (1 << 1),
 } git_iterator_flag_t;
 
 typedef struct {
-	int (*current)(git_iterator *, const git_index_entry **);
-	int (*at_end)(git_iterator *);
-	int (*advance)(git_iterator *, const git_index_entry **);
+	int (*current)(const git_index_entry **, git_iterator *);
+	int (*advance)(const git_index_entry **, git_iterator *);
 	int (*seek)(git_iterator *, const char *prefix);
 	int (*reset)(git_iterator *, const char *start, const char *end);
+	int (*at_end)(git_iterator *);
 	void (*free)(git_iterator *);
 } git_iterator_callbacks;
 
@@ -52,53 +49,41 @@ struct git_iterator {
 };
 
 extern int git_iterator_for_nothing(
-	git_iterator **out, git_iterator_flag_t flags);
+	git_iterator **out,
+	git_iterator_flag_t flags,
+	const char *start,
+	const char *end);
 
 /* tree iterators will match the ignore_case value from the index of the
  * repository, unless you override with a non-zero flag value
  */
-extern int git_iterator_for_tree_range(
+extern int git_iterator_for_tree(
 	git_iterator **out,
 	git_tree *tree,
 	git_iterator_flag_t flags,
 	const char *start,
 	const char *end);
 
-GIT_INLINE(int) git_iterator_for_tree(git_iterator **out, git_tree *tree)
-{
-	return git_iterator_for_tree_range(out, tree, 0, NULL, NULL);
-}
-
 /* index iterators will take the ignore_case value from the index; the
  * ignore_case flags are not used
  */
-extern int git_iterator_for_index_range(
+extern int git_iterator_for_index(
 	git_iterator **out,
 	git_index *index,
 	git_iterator_flag_t flags,
 	const char *start,
 	const char *end);
 
-GIT_INLINE(int) git_iterator_for_index(git_iterator **out, git_index *index)
-{
-	return git_iterator_for_index_range(out, index, 0, NULL, NULL);
-}
-
 /* workdir iterators will match the ignore_case value from the index of the
  * repository, unless you override with a non-zero flag value
  */
-extern int git_iterator_for_workdir_range(
+extern int git_iterator_for_workdir(
 	git_iterator **out,
 	git_repository *repo,
 	git_iterator_flag_t flags,
 	const char *start,
 	const char *end);
 
-GIT_INLINE(int) git_iterator_for_workdir(git_iterator **out, git_repository *repo)
-{
-	return git_iterator_for_workdir_range(out, repo, 0, NULL, NULL);
-}
-
 extern void git_iterator_free(git_iterator *iter);
 
 /* Spool all iterator values, resort with alternative ignore_case value
@@ -109,29 +94,27 @@ extern int git_iterator_spoolandsort_push(git_iterator *iter, bool ignore_case);
 /* Restore original callbacks - not required in most circumstances */
 extern void git_iterator_spoolandsort_pop(git_iterator *iter);
 
-/* Entry is not guaranteed to be fully populated.  For a tree iterator,
- * we will only populate the mode, oid and path, for example.  For a workdir
- * iterator, we will not populate the oid.
+/* Return a git_index_entry structure for the current value the iterator
+ * is looking at or NULL if the iterator is at the end.
+ *
+ * The entry may noy be fully populated.  Tree iterators will only have a
+ * value mode, OID, and path.  Workdir iterators will not have an OID (but
+ * you can use `git_iterator_current_oid()` to calculate it on demand).
  *
  * You do not need to free the entry.  It is still "owned" by the iterator.
- * Once you call `git_iterator_advance`, then content of the old entry is
- * no longer guaranteed to be valid.
+ * Once you call `git_iterator_advance()` then the old entry is no longer
+ * guaranteed to be valid - it may be freed or just overwritten in place.
  */
 GIT_INLINE(int) git_iterator_current(
-	git_iterator *iter, const git_index_entry **entry)
-{
-	return iter->cb->current(iter, entry);
-}
-
-GIT_INLINE(int) git_iterator_at_end(git_iterator *iter)
+	const git_index_entry **entry, git_iterator *iter)
 {
-	return iter->cb->at_end(iter);
+	return iter->cb->current(entry, iter);
 }
 
 GIT_INLINE(int) git_iterator_advance(
-	git_iterator *iter, const git_index_entry **entry)
+	const git_index_entry **entry, git_iterator *iter)
 {
-	return iter->cb->advance(iter, entry);
+	return iter->cb->advance(entry, iter);
 }
 
 GIT_INLINE(int) git_iterator_seek(
@@ -146,6 +129,11 @@ GIT_INLINE(int) git_iterator_reset(
 	return iter->cb->reset(iter, start, end);
 }
 
+GIT_INLINE(int) git_iterator_at_end(git_iterator *iter)
+{
+	return iter->cb->at_end(iter);
+}
+
 GIT_INLINE(git_iterator_type_t) git_iterator_type(git_iterator *iter)
 {
 	return iter->type;
@@ -167,15 +155,15 @@ GIT_INLINE(bool) git_iterator_ignore_case(git_iterator *iter)
 }
 
 extern int git_iterator_current_tree_entry(
-	git_iterator *iter, const git_tree_entry **tree_entry);
+	const git_tree_entry **tree_entry, git_iterator *iter);
 
 extern int git_iterator_current_parent_tree(
-	git_iterator *iter, const char *parent_path, const git_tree **tree_ptr);
+	const git_tree **tree_ptr, git_iterator *iter, const char *parent_path);
 
-extern int git_iterator_current_is_ignored(git_iterator *iter);
+extern bool git_iterator_current_is_ignored(git_iterator *iter);
 
 /**
- * Iterate into a workdir directory.
+ * Iterate into a directory.
  *
  * Workdir iterators do not automatically descend into directories (so that
  * when comparing two iterator entries you can detect a newly created
@@ -191,21 +179,22 @@ extern int git_iterator_current_is_ignored(git_iterator *iter);
  * On non-workdir iterators or if not pointing at a directory, this is a
  * no-op and will not advance the iterator.
  */
-extern int git_iterator_advance_into_directory(
-	git_iterator *iter, const git_index_entry **entry);
+extern int git_iterator_advance_into(
+	const git_index_entry **entry, git_iterator *iter);
 
 extern int git_iterator_cmp(
 	git_iterator *iter, const char *path_prefix);
 
 /**
- * Get the full path of the current item from a workdir iterator.
- * This will return NULL for a non-workdir iterator.
+ * Get full path of the current item from a workdir iterator.  This will
+ * return NULL for a non-workdir iterator.  The git_buf is still owned by
+ * the iterator; this is exposed just for efficiency.
  */
 extern int git_iterator_current_workdir_path(
-	git_iterator *iter, git_buf **path);
-
+	git_buf **path, git_iterator *iter);
 
-extern git_index *git_iterator_index_get_index(git_iterator *iter);
+/* Return index pointer if index iterator, else NULL */
+extern git_index *git_iterator_get_index(git_iterator *iter);
 
 extern git_iterator_type_t git_iterator_inner_type(git_iterator *iter);