[LUCENE-4314] The specification of DocIdSetIterator is needlessly ambiguous.

• Type: Improvement
• Status: Closed
• Priority: Major
• Resolution: Fixed
• Affects Version/s: 3.6.1, 4.0-BETA
• Fix Version/s: 4.0, 6.0
• Component/s: core/search
• Labels: index, iterators

Environment

All

• Lucene Fields: New
• Assignee: Michael McCandless
• Reporter: Franco Callari
• Created: 20/Aug/12 02:27
• Updated: 28/Aug/22 13:24
• Resolved: 20/Aug/12 23:57

Description

Quoth Lucene at org.apache.lucene.search.DocIdSetIterator.advance:

"Advances to the first beyond (see NOTE below) the current whose document
number is greater than or equal to <i>target</i>. [...]
NOTE:</b> when <code> target ≤ current</code> implementations may opt
not to advance beyond their current

{@link #docID()}

."

However, the same specification contradictorily states that advance must behave as if written:

int advance(int target) {
int doc;
while ((doc = nextDoc()) < target) {}
return doc;
}

That is, with at least one call to nextDoc() always made, unconditionally.

This ambiguity can lead to unexpected behavior. In fact, arguably every user of this interface that does not test after every call whether the iterator has exhausted AND has advanced is incorrect.

For example, I myself had one experimental implementation (coded against a previous Lucene release) that caused an infinite loop in PhraseScorer.java because, following the above specification, it "opted" not to move the iterator when advance(target) was called with target < current.