001: package prefuse.data.util;
002:
003: import java.util.Comparator;
004:
005: import prefuse.util.collections.IntIterator;
006:
007: /**
008: * Represents an index over a column of data, allowing quick lookups by
009: * data value and providing iterators over sorted ranges of data. For
010: * convenience, there are index lookup methods for a variety of data
011: * types; which ones to use depend on the data type of the column
012: * being indexed and calling a lookup method for an incompatible
013: * data type could lead to an exception being thrown.
014: *
015: * @author <a href="http://jheer.org">jeffrey heer</a>
016: */
017: public interface Index {
018:
019: /** Flag for an ascending sort order. */
020: public static final int TYPE_ASCENDING = 1 << 5;
021: /** Flag for a descending sort order. */
022: public static final int TYPE_DESCENDING = 1 << 4;
023: /** Flag for including the lowest value of a range. */
024: public static final int TYPE_LEFT_INCLUSIVE = 1 << 3;
025: /** Flag for excluding the lowest value of a range. */
026: public static final int TYPE_LEFT_EXCLUSIVE = 1 << 2;
027: /** Flag for including the highest value of a range. */
028: public static final int TYPE_RIGHT_INCLUSIVE = 1 << 1;
029: /** Flag for excluding the highest value of a range. */
030: public static final int TYPE_RIGHT_EXCLUSIVE = 1;
031:
032: /** Composite flag for an ascending, left and right inclusive range. */
033: public static final int TYPE_AII = TYPE_ASCENDING
034: | TYPE_LEFT_INCLUSIVE | TYPE_RIGHT_INCLUSIVE;
035: /** Composite flag for a descending, left and right inclusive range. */
036: public static final int TYPE_DII = TYPE_DESCENDING
037: | TYPE_LEFT_INCLUSIVE | TYPE_RIGHT_INCLUSIVE;
038: /** Composite flag for an ascending, left exclusive, right inclusive
039: * range. */
040: public static final int TYPE_AEI = TYPE_ASCENDING
041: | TYPE_LEFT_EXCLUSIVE | TYPE_RIGHT_INCLUSIVE;
042: /** Composite flag for a descending, left exclusive, right inclusive
043: * range. */
044: public static final int TYPE_DEI = TYPE_DESCENDING
045: | TYPE_LEFT_EXCLUSIVE | TYPE_RIGHT_INCLUSIVE;
046: /** Composite flag for an ascending, left inclusive, right exclusive
047: * range. */
048: public static final int TYPE_AIE = TYPE_ASCENDING
049: | TYPE_LEFT_INCLUSIVE | TYPE_RIGHT_EXCLUSIVE;
050: /** Composite flag for a descending, left inclusive, right exclusive
051: * range. */
052: public static final int TYPE_DIE = TYPE_DESCENDING
053: | TYPE_LEFT_INCLUSIVE | TYPE_RIGHT_EXCLUSIVE;
054: /** Composite flag for an ascending, left and right exclusive range. */
055: public static final int TYPE_AEE = TYPE_ASCENDING
056: | TYPE_LEFT_EXCLUSIVE | TYPE_RIGHT_EXCLUSIVE;
057: /** Composite flag for a descending, left and right exclusive range. */
058: public static final int TYPE_DEE = TYPE_DESCENDING
059: | TYPE_LEFT_EXCLUSIVE | TYPE_RIGHT_EXCLUSIVE;
060:
061: /**
062: * Perform an initial indexing of a data column.
063: */
064: public void index();
065:
066: /**
067: * Dispose of an index, deregistering all listeners.
068: */
069: public void dispose();
070:
071: /**
072: * Get the comparator used to compare column data values.
073: * @return the sort comparator
074: */
075: public Comparator getComparator();
076:
077: /**
078: * Get the row (or one of the rows) with the minimum data value.
079: * @return a row with a minimum data value
080: */
081: public int minimum();
082:
083: /**
084: * Get the row (or one of the rows) with the maximum data value.
085: * @return a row with a maximum data value
086: */
087: public int maximum();
088:
089: /**
090: * Get the row (or one of the rows) with the median data value.
091: * @return a row with a median data value
092: */
093: public int median();
094:
095: /**
096: * Get the number of unique data values in the index.
097: * @return the number of unique data values
098: */
099: public int uniqueCount();
100:
101: /**
102: * Get the size of this index, the number of data value / row
103: * pairs included.
104: * @return the size of the index
105: */
106: public int size();
107:
108: /**
109: * Get an iterator over all rows in the index, in sorted order.
110: * @param type the sort type, one of {@link #TYPE_ASCENDING} or
111: * {@link #TYPE_DESCENDING}.
112: * @return an iterator over all rows in the index
113: */
114: public IntIterator allRows(int type);
115:
116: /**
117: * Get an iterator over a sorted range of rows.
118: * @param lo the minimum data value
119: * @param hi the maximum data value
120: * @param type the iteration type, one of the composite flags
121: * involving both a sort order, and whether each bound of
122: * the range should inclusive or exclusive
123: * @return an iterator over a sorted range of rows
124: */
125: public IntIterator rows(Object lo, Object hi, int type);
126:
127: /**
128: * Get an iterator over a sorted range of rows.
129: * @param lo the minimum data value
130: * @param hi the maximum data value
131: * @param type the iteration type, one of the composite flags
132: * involving both a sort order, and whether each bound of
133: * the range should inclusive or exclusive
134: * @return an iterator over a sorted range of rows
135: */
136: public IntIterator rows(int lo, int hi, int type);
137:
138: /**
139: * Get an iterator over a sorted range of rows.
140: * @param lo the minimum data value
141: * @param hi the maximum data value
142: * @param type the iteration type, one of the composite flags
143: * involving both a sort order, and whether each bound of
144: * the range should inclusive or exclusive
145: * @return an iterator over a sorted range of rows
146: */
147: public IntIterator rows(long lo, long hi, int type);
148:
149: /**
150: * Get an iterator over a sorted range of rows.
151: * @param lo the minimum data value
152: * @param hi the maximum data value
153: * @param type the iteration type, one of the composite flags
154: * involving both a sort order, and whether each bound of
155: * the range should inclusive or exclusive
156: * @return an iterator over a sorted range of rows
157: */
158: public IntIterator rows(float lo, float hi, int type);
159:
160: /**
161: * Get an iterator over a sorted range of rows.
162: * @param lo the minimum data value
163: * @param hi the maximum data value
164: * @param type the iteration type, one of the composite flags
165: * involving both a sort order, and whether each bound of
166: * the range should inclusive or exclusive
167: * @return an iterator over a sorted range of rows
168: */
169: public IntIterator rows(double lo, double hi, int type);
170:
171: /**
172: * Get an iterator over all rows with the given data value.
173: * @param val the data value
174: * @return an iterator over all rows matching the data value
175: */
176: public IntIterator rows(Object val);
177:
178: /**
179: * Get an iterator over all rows with the given data value.
180: * @param val the data value
181: * @return an iterator over all rows matching the data value
182: */
183: public IntIterator rows(int val);
184:
185: /**
186: * Get an iterator over all rows with the given data value.
187: * @param val the data value
188: * @return an iterator over all rows matching the data value
189: */
190: public IntIterator rows(long val);
191:
192: /**
193: * Get an iterator over all rows with the given data value.
194: * @param val the data value
195: * @return an iterator over all rows matching the data value
196: */
197: public IntIterator rows(float val);
198:
199: /**
200: * Get an iterator over all rows with the given data value.
201: * @param val the data value
202: * @return an iterator over all rows matching the data value
203: */
204: public IntIterator rows(double val);
205:
206: /**
207: * Get an iterator over all rows with the given data value.
208: * @param val the data value
209: * @return an iterator over all rows matching the data value
210: */
211: public IntIterator rows(boolean val);
212:
213: /**
214: * Get the first row found with the given data value.
215: * @param x the data value
216: * @return the first row matching the data value
217: */
218: public int get(Object x);
219:
220: /**
221: * Get the first row found with the given data value.
222: * @param x the data value
223: * @return the first row matching the data value
224: */
225: public int get(int x);
226:
227: /**
228: * Get the first row found with the given data value.
229: * @param x the data value
230: * @return the first row matching the data value
231: */
232: public int get(long x);
233:
234: /**
235: * Get the first row found with the given data value.
236: * @param x the data value
237: * @return the first row matching the data value
238: */
239: public int get(float x);
240:
241: /**
242: * Get the first row found with the given data value.
243: * @param x the data value
244: * @return the first row matching the data value
245: */
246: public int get(double x);
247:
248: } // end of interface Index
|