index: introduce git_index_iteratorethomson/index_iterator

Provide a public git_index_iterator API that is backed by an index
snapshot.  This allows consumers to provide a stable iteration even
while manipulating the index during iteration.

2 files changed, 43 insertions, 0 deletions

diff --git a/include/git2/index.h b/include/git2/index.h
index 35af2e5bf..e43d6f857 100644
--- a/include/git2/index.h
+++ b/include/git2/index.h
@@ -492,6 +492,46 @@ GIT_EXTERN(int) git_index_entry_is_conflict(const git_index_entry *entry);
 
 /**@}*/
 
+/** @name Index Entry Iteration Functions
+ *
+ * These functions provide an iterator for index entries.
+ */
+/**@{*/
+
+/**
+ * Create an iterator that will return every entry contained in the
+ * index at the time of creation.  Entries are returned in order,
+ * sorted by path.  This iterator is backed by a snapshot that allows
+ * callers to modify the index while iterating without affecting the
+ * iterator.
+ *
+ * @param iterator_out The newly created iterator
+ * @param index The index to iterate
+ */
+GIT_EXTERN(int) git_index_iterator_new(
+	git_index_iterator **iterator_out,
+	git_index *index);
+
+/**
+ * Return the next index entry in-order from the iterator.
+ *
+ * @param out Pointer to store the index entry in
+ * @param iterator The iterator
+ * @return 0, GIT_ITEROVER on iteration completion or an error code
+ */
+GIT_EXTERN(int) git_index_iterator_next(
+	const git_index_entry **out,
+	git_index_iterator *iterator);
+
+/**
+ * Free the index iterator
+ *
+ * @param iterator The iterator to free
+ */
+GIT_EXTERN(void) git_index_iterator_free(git_index_iterator *iterator);
+
+/**@}*/
+
 /** @name Workdir Index Entry Functions
  *
  * These functions work on index entries specifically in the working
diff --git a/include/git2/types.h b/include/git2/types.h
index 607a62a5a..e77e6288d 100644
--- a/include/git2/types.h
+++ b/include/git2/types.h
@@ -137,6 +137,9 @@ typedef struct git_treebuilder git_treebuilder;
 /** Memory representation of an index file. */
 typedef struct git_index git_index;
 
+/** An iterator for entries in the index. */
+typedef struct git_index_iterator git_index_iterator;
+
 /** An iterator for conflicts in the index. */
 typedef struct git_index_conflict_iterator git_index_conflict_iterator;