it.unimi.dsi.mg4j.search
Interface DocumentIterator

All Superinterfaces:

IntIterator, Iterator

All Known Subinterfaces:

IndexIterator, ScoredDocumentIterator

All Known Implementing Classes:

AbstractIntersectionDocumentIterator, LowPassDocumentIterator, NotDocumentIterator, OrDocumentIterator

public interface DocumentIterator

extends IntIterator

An iterator over documents and their intervals.

This class extends IntIterator to a full-fledged document iterator. Each call to nextDocument() (a synonym for IntIterator.nextInt()) will return a document pointer. Just after the call to nextDocument(), intervalIterator(Index) will return an interval iterator enumerating intervals in the last returned document for the specified index. The latter method may return, as a special result, a special TRUE value: this means that even you should never care about the intervals this document iterator returns (see TRUE for some elaboration).

Warning: the interval enumeration can be carried out only just after a call to nextDocument(). Subsequent calls to nextDocument() or even Iterator.hasNext() will reset the internal state of the iterator. In particular, trying to enumerate intervals after a call to Iterator.hasNext() will throw an IllegalStateException.

Method Summary

int	document() Returns the last document returned by IntIterator.nextInt().
Set	indices() Returns the set of indices over which this iterator is built.
IntervalIterator	intervalIterator() Returns the interval iterator of this document iterator for single-index queries.
IntervalIterator	intervalIterator(Index index) Returns the interval iterator of this document iterator for the given index.
Map	intervalIterators() Returns an unmodifiable map from indices to interval iterators.
int	nextDocument() A synonym for IntIterator.nextInt().
int	skipTo(int n) Skips all documents smaller than n.

Methods inherited from interface it.unimi.dsi.fastutil.ints.IntIterator

nextInt, skip

Methods inherited from interface java.util.Iterator

hasNext, next, remove

Method Detail

intervalIterator

public IntervalIterator intervalIterator()

Returns the interval iterator of this document iterator for single-index queries.

This is a commodity method that can be used only for queries built over a single index.

Returns:

an interval iterator.

Throws:

IllegalStateException - if this document iterator is not built on a single index.

See Also:

intervalIterator(Index)

intervalIterator

public IntervalIterator intervalIterator(Index index)

Returns the interval iterator of this document iterator for the given index.

After a call to IntIterator.nextInt(), this iterator can be used to retrieve the intervals in the current document (the one returned by IntIterator.nextInt()) for the index index.

Note that it is guaranteed that at least one index will return an interval. However, for disjunctive queries it cannot be guaranteed that all indices will return an interval.

Parameters:

index - an index (must be one over which the query was built).

Returns:

an interval iterator over the current document in index.

Throws:

UnsupportedOperationException - if this index does not contain positions.

intervalIterators

public Map intervalIterators()

Returns an unmodifiable map from indices to interval iterators.

After a call to IntIterator.nextInt(), this map can be used to retrieve the intervals in the current document. An invocation of Map.get(java.lang.Object) on this map with argument index yields the same result as intervalIterator(index).

Returns:

a map from indices to interval iterators over the current document.

Throws:

UnsupportedOperationException - if this index does not contain positions.

See Also:

intervalIterator(Index)

indices

public Set indices()

Returns the set of indices over which this iterator is built.

Returns:

the set of indices over which this iterator is built.

nextDocument

public int nextDocument()

A synonym for IntIterator.nextInt().

Returns:

the next document.

document

public int document()

Returns the last document returned by IntIterator.nextInt().

Returns:

the last document returned by IntIterator.nextInt(), or -1 if no document has been returned yet.

skipTo

public int skipTo(int n)

Skips all documents smaller than n.

Let k be the last document returned by IntIterator.nextInt(). If k is larger than or equal to n, then this method does nothing and returns k. Otherwise, a call to this method is equivalent to

 while( hasNext() && ( k = nextInt() ) < n );
 return hasNext() ? k : -1;
 

Beware that the first document larger than or equal to n (which is returned by this method) will not be returned by the next call to IntIterator.nextInt().

Parameters:

n - a document index.

Returns:

-1, if all documents produced by this iterator are smaller than n; otherwise, an document larger than or equal to n as described above.