Make all AbstractTreeIterator implementations bi-directional
To support scanning ahead and then rewinding back to our prior
location we need to allow all tree iterators to be moved both
forward and backwards through their entries. The next(int)
API replaces the simple next() by supplying the amount that
the iterator needs to move forward. A corresponding back(int)
method supplies the opposite direction of travel.
Some iterators, like WorkingTreeIterator, can efficiently move
forward and backward any distance because they have a direct 1:1
mapping between positions of the iterator and an array index.
Others like CanonicalTreeParser must scan through their input
buffer, but can try to reduce the work needed on larger steps
as they move past the undesired entries. DirCacheIterator is
a challenge because it needs to match each entry to the
DirCacheTrees available at this level.
This API (and its implementation) is really meant for peeking at
the next entry (or two) forward to see if there is a name (but
not mode) match during a TreeWalk. This is to help TreeWalk
catch a directory/file mode conflict and report it, despite
the directory and file variants of a name appearing at two
very different positions in the trees.
Signed-off-by: Shawn O. Pearce <spearce@spearce.org>
Signed-off-by: Robin Rosenberg <robin.rosenberg@dewire.com>