001: /**
002: * com.mckoi.util.IntegerListInterface 17 Sep 2001
003: *
004: * Mckoi SQL Database ( http://www.mckoi.com/database )
005: * Copyright (C) 2000, 2001, 2002 Diehl and Associates, Inc.
006: *
007: * This program is free software; you can redistribute it and/or
008: * modify it under the terms of the GNU General Public License
009: * Version 2 as published by the Free Software Foundation.
010: *
011: * This program is distributed in the hope that it will be useful,
012: * but WITHOUT ANY WARRANTY; without even the implied warranty of
013: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
014: * GNU General Public License Version 2 for more details.
015: *
016: * You should have received a copy of the GNU General Public License
017: * Version 2 along with this program; if not, write to the Free Software
018: * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
019: *
020: * Change Log:
021: *
022: *
023: */package com.mckoi.util;
024:
025: /**
026: * An interface for querying and accessing a list of primitive integers. The
027: * list may or may not be sorted or may be sorted over an IndexComparator.
028: * This interface exposes general list querying/inserting/removing methods.
029: * <p>
030: * How the list is physically stored is dependant on the implementation of
031: * the interface. An example of an implementation is 'BlockIntegerList'.
032: *
033: * @author Tobias Downer
034: */
035:
036: public interface IntegerListInterface {
037:
038: /**
039: * Makes this list immutable effectively making it read-only. After this
040: * method, any calls to methods that modify the list will throw an error.
041: * <p>
042: * Once 'setImmutable' is called, the list can not be changed back to
043: * being mutable.
044: */
045: void setImmutable();
046:
047: /**
048: * Returns true if this interface is immutable.
049: */
050: boolean isImmutable();
051:
052: /**
053: * The number of integers that are in the list.
054: */
055: int size();
056:
057: /**
058: * Returns the int at the given position (0 first, 1 second, etc) in the
059: * list. If the position is out of bounds an exception is thrown.
060: */
061: int get(int pos);
062:
063: /**
064: * Adds an integet to the given position in the list. If the position is
065: * out of bounds an exception is thrown. Any values after the given
066: * position are shifted forward.
067: */
068: void add(int val, int pos);
069:
070: /**
071: * Adds an int to the end of the list.
072: */
073: void add(int val);
074:
075: /**
076: * Removes an int from the given position in the list. Returns the value
077: * that was removed from the removed position. If the position is out of
078: * bounds an exception is thrown.
079: */
080: int remove(int pos);
081:
082: /**
083: * Assuming the list is sorted, this performs a binary search and returns
084: * true if the value is found, otherwise returns false. If the list is not
085: * sorted then this may return false even if the list does contain the
086: * value.
087: */
088: boolean contains(int val);
089:
090: /**
091: * Inserts plain 'int' values into the list in sorted order.
092: */
093: void insertSort(int val);
094:
095: /**
096: * Inserts plain 'int' value into the sorted position in the list only if
097: * it isn't already in the list. If the value is inserted it returns true,
098: * otherwise if the value wasn't inserted because it's already in the list,
099: * it returns false.
100: */
101: boolean uniqueInsertSort(int val);
102:
103: /**
104: * Removes a plain 'int' value from the sorted position in the list only if
105: * it's already in the list. If the value is removed it returns true,
106: * otherwise if the value wasn't removed because it couldn't be found in the
107: * list, it returns false.
108: */
109: boolean removeSort(int val);
110:
111: // ---------- IndexComparator methods ----------
112: // NOTE: The IndexComparator methods offer the ability to maintain a set
113: // of index values that reference complex objects. This is used to manage a
114: // sorted list of integers by their referenced object instead of the int
115: // value itself. This enables us to create a vaste list of indexes without
116: // having to store the list of objects in memory.
117:
118: /**
119: * Assuming the list is sorted, this performs a binary search and returns
120: * true if the key value is found, otherwise returns false.
121: */
122: boolean contains(Object key, IndexComparator c);
123:
124: /**
125: * Inserts the key/index pair into the list at the correct sorted position
126: * (determine by the IndexComparator). If the list already contains
127: * identical key then the value is add to the end of the set of identical
128: * values in the list. This way, the sort is stable (the order of identical
129: * elements does not change).
130: */
131: void insertSort(Object key, int val, IndexComparator c);
132:
133: /**
134: * Removes the key/val pair from the list by first searching for it, and then
135: * removing it from the list. This method uses the IndexComparator object to
136: * compare an index position in the list to an object to compare against.
137: */
138: int removeSort(Object key, int val, IndexComparator c);
139:
140: /**
141: * Returns the index of the last value in this set that equals the given
142: * value. This method uses the IndexComparator object to compare an
143: * index position in the list to an object to compare against.
144: */
145: int searchLast(Object key, IndexComparator c);
146:
147: /**
148: * Returns the index of the first value in this set that equals the given
149: * value. This method uses the IndexComparator object to compare an
150: * index position in the list to an object to compare against.
151: */
152: int searchFirst(Object key, IndexComparator c);
153:
154: // ---------- IntegerIterator methods ----------
155:
156: /**
157: * Returns an IntegerIterator that will walk from the start offset
158: * (inclusive) to the end offset (inclusive) of this list.
159: */
160: IntegerIterator iterator(int start_offset, int end_offset);
161:
162: /**
163: * Returns an IntegerIterator that will walk from the start to the end
164: * this list.
165: */
166: IntegerIterator iterator();
167:
168: }
|