ArrayBase


1   /*
2    * Copyright (c) 2000-2001 Sosnoski Software Solutions, Inc.
3    *
4    * Permission is hereby granted, free of charge, to any person obtaining a copy
5    * of this software and associated documentation files (the "Software"), to deal
6    * in the Software without restriction, including without limitation the rights 
7    * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 
8    * copies of the Software, and to permit persons to whom the Software is 
9    * furnished to do so, subject to the following conditions:
10   *
11   * The above copyright notice and this permission notice shall be included in 
12   * all copies or substantial portions of the Software.
13   *
14   * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 
15   * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 
16   * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 
17   * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 
18   * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING 
19   * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS 
20   * IN THE SOFTWARE.
21   */
22  
23  package com.sosnoski.util.array;
24  
25  import com.sosnoski.util.*;
26  
27  /**
28   * Base class for type-specific growable array classes with any type of values
29   * (including primitive types). This class builds on the basic structure 
30   * provided by <code>GrowableBase</code>, specializing it for usage as a 
31   * growable array. See the base class description for details of the 
32   * implementation.<p>
33   *
34   * Growable arrays based on this class are unsynchronized in order to provide
35   * the best possible performance for typical usage scenarios, so explicit
36   * synchronization must be implemented by the subclass or the application in
37   * cases where they are to be modified in a multithreaded environment.<p>
38   *
39   * Subclasses need to implement the abstract methods defined by the base class
40   * for working with the data array, as well as the actual data access methods 
41   * (at least the basic <code>add()</code>, <code>get()</code>, 
42   * <code>set()</code>, and <code>toArray()</code> methods).
43   * 
44   * @author Dennis M. Sosnoski
45   * @version 1.0
46   */
47  
48  public abstract class ArrayBase extends GrowableBase
49  {
50      /** The number of values currently present in the array. */
51      protected int m_countPresent;
52  
53      /**
54       * Constructor with full specification.
55       * 
56       * @param size number of elements initially allowed in array
57       * @param growth maximum size increment for growing array
58       * @param type array element type
59       */
60      
61      public ArrayBase(int size, int growth, Class   type) {
62          super(size, growth, type);
63      }
64  
65      /**
66       * Constructor with partial specification.
67       * 
68       * @param size number of elements initially allowed in array
69       * @param type array element type
70       */
71      
72      public ArrayBase(int size, Class   type) {
73          this(size, Integer.MAX_VALUE, type);
74      }
75  
76      /**
77       * Copy (clone) constructor.
78       * 
79       * @param base instance being copied
80       */
81      
82      public ArrayBase(ArrayBase base) {
83          super(base);
84          System.arraycopy(base.getArray(), 0, getArray(), 0,
85              base.m_countPresent);
86          m_countPresent = base.m_countPresent;
87      }
88  
89      /**
90       * Get the array for another instance of this class. This is a convenience 
91       * method to allow subclasses access to the backing array of
92       * other subclasses.
93       * 
94       * @param other subclass instance to get array from
95       * @return backing array object
96       */
97      
98      protected static Object   getArray(ArrayBase other) {
99          return other.getArray();
100     }
101 
102     /**
103      * Gets the array offset for appending a value to those in the array.
104      * If the underlying array is full, it is grown by the appropriate size
105      * increment so that the index value returned is always valid for the 
106      * array in use by the time of the return.
107      * 
108      * @return index position for added element
109      */
110     
111     protected final int getAddIndex() {
112         int index = m_countPresent++;
113         if (m_countPresent > m_countLimit) {
114             growArray(m_countPresent);
115         }
116         return index;
117     }
118 
119     /**
120      * Makes room to insert a value at a specified index in the array.
121      * 
122      * @param index index position at which to insert element
123      */
124     
125     protected void makeInsertSpace(int index) {
126         if (index >= 0 && index <= m_countPresent) {
127             if (++m_countPresent > m_countLimit) {
128                 growArray(m_countPresent);
129             }
130             if (index < m_countPresent - 1) {
131                 Object   array = getArray();
132                 System.arraycopy(array, index, array, index + 1,
133                     m_countPresent - index - 1);
134             }
135         } else {
136             throw new ArrayIndexOutOfBoundsException  ("Invalid index value");
137         }
138     }
139 
140     /**
141      * Remove a range of value from the array. The index positions for values 
142      * above the range removed are decreased by the number of values removed.
143      * 
144      * @param from index number of first value to be removed
145      * @param to index number past last value to be removed
146      */
147     
148     public void remove(int from, int to) {
149         if (from >= 0 && to <= m_countPresent && from <= to) {
150             if (to < m_countPresent){
151                 int change = from - to;
152                 Object   base = getArray();
153                 System.arraycopy(base, to, base, from, m_countPresent - to);
154                 discardValues(m_countPresent+change, m_countPresent);
155                 m_countPresent += change;
156             }
157         } else {
158             throw new ArrayIndexOutOfBoundsException  ("Invalid remove range");
159         }
160     }
161 
162     /**
163      * Remove a value from the array. All values above the index removed
164      * are moved down one index position.
165      * 
166      * @param index index number of value to be removed
167      */
168     
169     public void remove(int index) {
170         remove(index, index+1);
171     }
172 
173     /**
174      * Get the number of values currently present in the array.
175      * 
176      * @return count of values present
177      */
178     
179     public final int size() {
180         return m_countPresent;
181     }
182 
183     /**
184      * Sets the number of values currently present in the array. If the new
185      * size is greater than the current size, the added values are initialized
186      * to the default values. If the new size is less than the current size,
187      * all values dropped from the array are discarded.
188      * 
189      * @param count number of values to be set
190      */
191     
192     public void setSize(int count) {
193         if (count > m_countLimit) {
194             growArray(count);
195         } else if (count < m_countPresent) {
196             discardValues(count, m_countPresent);
197         }
198         m_countPresent = count;
199     }
200 
201     /**
202      * Set the array to the empty state.
203      */
204     
205     public final void clear() {
206         setSize(0);
207     }
208 
209     /**
210      * Constructs and returns a simple array containing the same data as held 
211      * in a portion of this growable array. This override of the base class
212      * method checks that the portion specified actually has data present
213      * before constructing the returned array.
214      * 
215      * @param type element type for constructed array
216      * @param offset start offset in array
217      * @param length number of characters to use
218      * @return array containing a copy of the data
219      */
220     
221     protected Object   buildArray(Class   type, int offset, int length) {
222         if (offset + length <= m_countPresent) {
223             return super.buildArray(type, offset, length);
224         } else {
225             throw new ArrayIndexOutOfBoundsException  ();
226         }
227     }
228 }
229
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags