IntegerListInterface


1   /**
2    * com.mckoi.util.IntegerListInterface  17 Sep 2001
3    *
4    * Mckoi SQL Database ( http://www.mckoi.com/database )
5    * Copyright (C) 2000, 2001, 2002  Diehl and Associates, Inc.
6    *
7    * This program is free software; you can redistribute it and/or
8    * modify it under the terms of the GNU General Public License
9    * Version 2 as published by the Free Software Foundation.
10   *
11   * This program is distributed in the hope that it will be useful,
12   * but WITHOUT ANY WARRANTY; without even the implied warranty of
13   * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
14   * GNU General Public License Version 2 for more details.
15   *
16   * You should have received a copy of the GNU General Public License
17   * Version 2 along with this program; if not, write to the Free Software
18   * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
19   *
20   * Change Log:
21   * 
22   * 
23   */
24  
25  package com.mckoi.util;
26  
27  /**
28   * An interface for querying and accessing a list of primitive integers.  The
29   * list may or may not be sorted or may be sorted over an IndexComparator.
30   * This interface exposes general list querying/inserting/removing methods.
31   * <p>
32   * How the list is physically stored is dependant on the implementation of
33   * the interface.  An example of an implementation is 'BlockIntegerList'.
34   *
35   * @author Tobias Downer
36   */
37  
38  public interface IntegerListInterface {
39  
40    /**
41     * Makes this list immutable effectively making it read-only.  After this
42     * method, any calls to methods that modify the list will throw an error.
43     * <p>
44     * Once 'setImmutable' is called, the list can not be changed back to
45     * being mutable.
46     */
47    void setImmutable();
48  
49    /**
50     * Returns true if this interface is immutable.
51     */
52    boolean isImmutable();
53  
54    /**
55     * The number of integers that are in the list.
56     */
57    int size();
58  
59    /**
60     * Returns the int at the given position (0 first, 1 second, etc) in the
61     * list.  If the position is out of bounds an exception is thrown.
62     */
63    int get(int pos);
64  
65    /**
66     * Adds an integet to the given position in the list.  If the position is
67     * out of bounds an exception is thrown.  Any values after the given
68     * position are shifted forward.
69     */
70    void add(int val, int pos);
71  
72    /**
73     * Adds an int to the end of the list.
74     */
75    void add(int val);
76  
77    /**
78     * Removes an int from the given position in the list.  Returns the value
79     * that was removed from the removed position.  If the position is out of
80     * bounds an exception is thrown.
81     */
82    int remove(int pos);
83  
84    /**
85     * Assuming the list is sorted, this performs a binary search and returns
86     * true if the value is found, otherwise returns false.  If the list is not
87     * sorted then this may return false even if the list does contain the
88     * value.
89     */
90    boolean contains(int val);
91  
92    /**
93     * Inserts plain 'int' values into the list in sorted order.
94     */
95    void insertSort(int val);
96  
97    /**
98     * Inserts plain 'int' value into the sorted position in the list only if
99     * it isn't already in the list.  If the value is inserted it returns true,
100    * otherwise if the value wasn't inserted because it's already in the list,
101    * it returns false.
102    */
103   boolean uniqueInsertSort(int val);
104 
105   /**
106    * Removes a plain 'int' value from the sorted position in the list only if
107    * it's already in the list.  If the value is removed it returns true,
108    * otherwise if the value wasn't removed because it couldn't be found in the
109    * list, it returns false.
110    */
111   boolean removeSort(int val);
112 
113   // ---------- IndexComparator methods ----------
114   // NOTE: The IndexComparator methods offer the ability to maintain a set
115   //  of index values that reference complex objects.  This is used to manage a
116   //  sorted list of integers by their referenced object instead of the int
117   //  value itself.  This enables us to create a vaste list of indexes without
118   //  having to store the list of objects in memory.
119 
120   /**
121    * Assuming the list is sorted, this performs a binary search and returns
122    * true if the key value is found, otherwise returns false.
123    */
124   boolean contains(Object   key, IndexComparator c);
125 
126   /**
127    * Inserts the key/index pair into the list at the correct sorted position
128    * (determine by the IndexComparator).  If the list already contains
129    * identical key then the value is add to the end of the set of identical
130    * values in the list.  This way, the sort is stable (the order of identical
131    * elements does not change).
132    */
133   void insertSort(Object   key, int val, IndexComparator c);
134 
135   /**
136    * Removes the key/val pair from the list by first searching for it, and then
137    * removing it from the list.  This method uses the IndexComparator object to
138    * compare an index position in the list to an object to compare against.
139    */
140   int removeSort(Object   key, int val, IndexComparator c);
141 
142   /**
143    * Returns the index of the last value in this set that equals the given
144    * value.  This method uses the IndexComparator object to compare an
145    * index position in the list to an object to compare against.
146    */
147   int searchLast(Object   key, IndexComparator c);
148 
149   /**
150    * Returns the index of the first value in this set that equals the given
151    * value.  This method uses the IndexComparator object to compare an
152    * index position in the list to an object to compare against.
153    */
154   int searchFirst(Object   key, IndexComparator c);
155 
156   // ---------- IntegerIterator methods ----------
157 
158   /**
159    * Returns an IntegerIterator that will walk from the start offset
160    * (inclusive) to the end offset (inclusive) of this list.
161    */
162   IntegerIterator iterator(int start_offset, int end_offset);
163 
164   /**
165    * Returns an IntegerIterator that will walk from the start to the end
166    * this list.
167    */
168   IntegerIterator iterator();
169 
170 }
171
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags