it.unimi.dsi.mg4j.search
Class AbstractIntersectionDocumentIterator

java.lang.Object
  extended byit.unimi.dsi.fastutil.ints.AbstractIntIterator
      extended byit.unimi.dsi.mg4j.search.AbstractIntersectionDocumentIterator
All Implemented Interfaces:
DocumentIterator, IntIterator, Iterator
Direct Known Subclasses:
AndDocumentIterator, ConsecutiveDocumentIterator

public abstract class AbstractIntersectionDocumentIterator
extends AbstractIntIterator
implements DocumentIterator

An abstract iterator on documents, generating the intersection of the documents returned by a number of document iterators.

To be usable, this class must be subclassed so to provide also an iterator on intervals. Such iterators must be instantiable using getComposedIntervalIterator(Index). The latter is an example of a non-static factory method, that is, a factory method which depends on the enclosing instance. This pattern allows to easily specialise this class to iterators that do different things, such as AndDocumentIterator and ConsecutiveDocumentIterator, but that have a similar semantics at the document level (the semantics may in fact be slightly different: for instance, not all document belonging to all components will actually appear in a consecutive iterator, as there may be documents filtered at the interval level).

The important invariant is that only after a call to nextDocument(), a call to intervalIterator(Index) will return an interval iterator over the document just returned, and that for at least one index in indices() the iterator will not be empty or TRUE.


Field Summary
protected  DocumentIterator[] it
          The component document iterators.
 
Constructor Summary
AbstractIntersectionDocumentIterator(DocumentIterator[] it)
          Creates a new intersection iterator using a given array of iterators.
 
Method Summary
 int document()
          Returns the last document returned by IntIterator.nextInt().
protected abstract  IntervalIterator getComposedIntervalIterator(Index index)
           
 boolean hasNext()
           
 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.
protected  void invalidate()
          Invalidates the current document, and forces hasNext() to find whether there is another one.
 int nextDocument()
          A synonym for IntIterator.nextInt().
 int nextInt()
           
 int skipTo(int n)
          Skips all documents smaller than n.
 String toString()
           
 
Methods inherited from class it.unimi.dsi.fastutil.ints.AbstractIntIterator
next, remove, skip
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 
Methods inherited from interface it.unimi.dsi.fastutil.ints.IntIterator
skip
 
Methods inherited from interface java.util.Iterator
next, remove
 

Field Detail

it

protected final DocumentIterator[] it
The component document iterators.

Constructor Detail

AbstractIntersectionDocumentIterator

public AbstractIntersectionDocumentIterator(DocumentIterator[] it)
Creates a new intersection iterator using a given array of iterators.

Parameters:
it - the iterators to be insersected.
Method Detail

indices

public Set indices()
Description copied from interface: DocumentIterator
Returns the set of indices over which this iterator is built.

Specified by:
indices in interface DocumentIterator
Returns:
the set of indices over which this iterator is built.

skipTo

public int skipTo(int n)
Description copied from interface: DocumentIterator
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().

Specified by:
skipTo in interface DocumentIterator
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.

invalidate

protected void invalidate()
Invalidates the current document, and forces hasNext() to find whether there is another one.

This method call may be used by subclasses to skip documents on the base of some further analysis (e.g., on the interval iterators, as it happens for ConsecutiveDocumentIterator).


nextInt

public int nextInt()
Specified by:
nextInt in interface IntIterator

document

public int document()
Description copied from interface: DocumentIterator
Returns the last document returned by IntIterator.nextInt().

Specified by:
document in interface DocumentIterator
Returns:
the last document returned by IntIterator.nextInt(), or -1 if no document has been returned yet.

nextDocument

public int nextDocument()
Description copied from interface: DocumentIterator
A synonym for IntIterator.nextInt().

Specified by:
nextDocument in interface DocumentIterator
Returns:
the next document.

hasNext

public boolean hasNext()
Specified by:
hasNext in interface Iterator

intervalIterators

public Map intervalIterators()
Description copied from interface: DocumentIterator
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).

Specified by:
intervalIterators in interface DocumentIterator
Returns:
a map from indices to interval iterators over the current document.
See Also:
DocumentIterator.intervalIterator(Index)

intervalIterator

public IntervalIterator intervalIterator()
Description copied from interface: DocumentIterator
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.

Specified by:
intervalIterator in interface DocumentIterator
Returns:
an interval iterator.
See Also:
DocumentIterator.intervalIterator(Index)

intervalIterator

public IntervalIterator intervalIterator(Index index)
Description copied from interface: DocumentIterator
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.

Specified by:
intervalIterator in interface DocumentIterator
Parameters:
index - an index (must be one over which the query was built).
Returns:
an interval iterator over the current document in index.

getComposedIntervalIterator

protected abstract IntervalIterator getComposedIntervalIterator(Index index)

toString

public String toString()