001: package it.unimi.dsi.mg4j.search;
002:
003: /*
004: * MG4J: Managing Gigabytes for Java
005: *
006: * Copyright (C) 2003-2007 Paolo Boldi and Sebastiano Vigna
007: *
008: * This library is free software; you can redistribute it and/or modify it
009: * under the terms of the GNU Lesser General Public License as published by the Free
010: * Software Foundation; either version 2.1 of the License, or (at your option)
011: * any later version.
012: *
013: * This library is distributed in the hope that it will be useful, but
014: * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
015: * or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License
016: * for more details.
017: *
018: * You should have received a copy of the GNU Lesser General Public License
019: * along with this program; if not, write to the Free Software
020: * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
021: *
022: */
023:
024: import it.unimi.dsi.fastutil.ints.IntSet;
025: import it.unimi.dsi.fastutil.objects.AbstractObjectIterator;
026: import it.unimi.dsi.mg4j.index.IndexIterator;
027: import it.unimi.dsi.util.Interval;
028: import it.unimi.dsi.util.Intervals;
029:
030: import java.util.Collections;
031: import java.util.NoSuchElementException;
032:
033: /** A class providing static methods and objects that do useful things with interval iterators.
034: *
035: */
036:
037: public class IntervalIterators {
038: private IntervalIterators() {
039: }
040:
041: /** An iterator that throws an exception on all advancing method calls, except for {@link #hasNext()},
042: * which has a settable value. The extent is 0.
043: *
044: * <P>The only purpose of this class is to instantiate singleton iterators
045: * such as {@link #TRUE} and {@link #FALSE}.
046: */
047:
048: protected static class FakeIterator extends
049: AbstractObjectIterator<Interval> implements
050: IntervalIterator {
051: final boolean hasNext;
052:
053: private FakeIterator(final boolean hasNext) {
054: this .hasNext = hasNext;
055: }
056:
057: public boolean hasNext() {
058: return hasNext;
059: }
060:
061: public void reset() {
062: }
063:
064: public Interval next() {
065: throw hasNext ? new UnsupportedOperationException()
066: : new NoSuchElementException();
067: }
068:
069: public Interval nextInterval() {
070: if (!hasNext)
071: new UnsupportedOperationException();
072: return null;
073: }
074:
075: public int extent() {
076: return 0;
077: } // TODO: this is not correct for FALSE (but it is unlikely to be a problem)
078:
079: public String toString() {
080: return this .getClass().getName() + "."
081: + (hasNext ? "TRUE" : "FALSE");
082: }
083:
084: public void intervalTerms(IntSet terms) {
085: }
086: }
087:
088: /** A singleton iterator representing maximum truth.
089: *
090: * <p>This iterator is a placeholder for an iterator returning just {@link Intervals#EMPTY_INTERVAL}.
091: * The antichain formed by the empty interval is the top element of the lattice of antichains, and
092: * thus represents the highest truth. Since, however, <code>EMPTY_INTERVAL</code>
093: * is a singleton that slightly violates the {@link Interval} invariants, an iterator actually
094: * returning <code>EMPTY_INTERVAL</code> would cause severe problems in all algorithms manipulating
095: * intervals. Rather, {@link #TRUE} is treated separately and is never actually used in
096: * an algorithm on interval antichains (also because, albeit it claims to have elements,
097: * it will return <code>null</code> on {@link IntervalIterator#nextInterval()}).
098: *
099: * <P>A most natural appearance of {@link #TRUE} is due to negation: all documents satisfying
100: * a negative query return {@link #TRUE} as interval iterator.
101: *
102: * <P>Finally, an {@link IndexIterator} by convention returns {@link #TRUE}
103: * when {@link DocumentIterator#intervalIterator(it.unimi.dsi.mg4j.index.Index)}
104: * is called with an argument that is not the {@linkplain IndexIterator#index() key index}.
105: * The idea is that there is no witness to be returned, but the query is nonetheless true.
106: */
107:
108: public final static IntervalIterator TRUE = new FakeIterator(true);
109:
110: /** A singleton empty interval iterator.
111: *
112: * <P>The main usefulness of this iterator is as a singleton: in some circumstances you have
113: * to return an empty iterator, and since it is by definition stateless, it is a pity
114: * to create a new object (the same considerations led to {@link Collections#emptySet()}).
115: */
116: public final static IntervalIterator FALSE = new FakeIterator(false);
117:
118: }
|