it.unimi.dsi.mg4j.search
Class AbstractIntersectionDocumentIterator

java.lang.Object
  it.unimi.dsi.fastutil.ints.AbstractIntIterator
      it.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()