StringArray


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 java.util.Iterator  ;
26  
27  import com.sosnoski.util.ArrayRangeIterator;
28  
29  /**
30   * Growable <code>String</code> array with type specific access methods. This
31   * implementation is unsynchronized in order to provide the best possible
32   * performance for typical usage scenarios, so explicit synchronization must
33   * be implemented by a wrapper class or directly by the application in cases
34   * where instances are modified in a multithreaded environment. See the base
35   * classes for other details of the implementation.
36   *
37   * @author Dennis M. Sosnoski
38   * @version 1.1
39   */
40  
41  public class StringArray extends ArrayBase
42  {
43      /** The underlying array used for storing the data. */
44      protected String  [] m_baseArray;
45  
46      /**
47       * Constructor with full specification.
48       *
49       * @param size number of <code>String</code> values initially allowed in
50       * array
51       * @param growth maximum size increment for growing array
52       */
53  
54      public StringArray(int size, int growth) {
55          super(size, growth, String  .class);
56      }
57  
58      /**
59       * Constructor with initial size specified.
60       *
61       * @param size number of chars to size array for initially
62       */
63  
64      public StringArray(int size) {
65          super(size, String  .class);
66      }
67  
68      /**
69       * Default constructor.
70       */
71  
72      public StringArray() {
73          this(DEFAULT_SIZE);
74      }
75  
76      /**
77       * Copy (clone) constructor.
78       *
79       * @param base instance being copied
80       */
81  
82      public StringArray(StringArray base) {
83          super(base);
84      }
85  
86      /**
87       * Get the backing array. This method is used by the type-agnostic base
88       * class code to access the array used for type-specific storage.
89       *
90       * @return backing array object
91       */
92  
93      protected final Object   getArray() {
94          return m_baseArray;
95      }
96  
97      /**
98       * Set the backing array. This method is used by the type-agnostic base
99       * class code to set the array used for type-specific storage.
100      *
101      * @param backing array object
102      */
103 
104     protected final void setArray(Object   array) {
105         m_baseArray = (String  [])array;
106     }
107 
108     /**
109      * Add a value to the array, appending it after the current values.
110      *
111      * @param value value to be added
112      * @return index number of added element
113      */
114 
115     public final int add(String   value) {
116         int index = getAddIndex();
117         m_baseArray[index] = value;
118         return index;
119     }
120 
121     /**
122      * Add a value at a specified index in the array.
123      *
124      * @param index index position at which to insert element
125      * @param value value to be inserted into array
126      */
127 
128     public void add(int index, String   value) {
129         makeInsertSpace(index);
130         m_baseArray[index] = (String  )value;
131     }
132 
133     /**
134      * Retrieve the value present at an index position in the array.
135      *
136      * @param index index position for value to be retrieved
137      * @return value from position in the array
138      */
139 
140     public final String   get(int index) {
141         if (index < m_countPresent) {
142             return m_baseArray[index];
143         } else {
144             throw new ArrayIndexOutOfBoundsException  ("Invalid index value");
145         }
146     }
147 
148     /**
149      * Set the value at an index position in the array. Note that this
150      * method can only be used for modifying an existing value in the
151      * array, not for appending to the end of the array.
152      *
153      * @param index index position to be set
154      * @param value value to be set
155      * @see #add
156      */
157 
158     public final void set(int index, String   value) {
159         if (index < m_countPresent) {
160             m_baseArray[index] = value;
161         } else {
162             throw new ArrayIndexOutOfBoundsException  ("Invalid index value");
163         }
164     }
165 
166     /**
167      * Return an iterator for the <code>String</code>s in this array. The
168      * iterator returns all values in order, but is not "live". Values
169      * added to the array during iteration will not be returned by the
170      * iteration, and any other changes to the array while the iteration is
171      * in progress will give indeterminant results.
172      *
173      * @return iterator for values in array
174      */
175 
176     public final Iterator   iterator() {
177         return ArrayRangeIterator.buildIterator(m_baseArray, 0, m_countPresent);
178     }
179 
180     /**
181      * Constructs and returns a simple array containing the same data as held
182      * in this growable array.
183      *
184      * @return array containing a copy of the data
185      */
186 
187     public String  [] toArray() {
188         return (String  [])buildArray(String  .class, 0, m_countPresent);
189     }
190 
191     /**
192      * Constructs and returns a simple array containing the same data as held
193      * in a portion of this growable array.
194      *
195      * @param offset start offset in array
196      * @param length number of characters to use
197      * @return array containing a copy of the data
198      */
199 
200     public String  [] toArray(int offset, int length) {
201         return (String  [])buildArray(String  .class, offset, length);
202     }
203 
204     /**
205      * Duplicates the object with the generic call.
206      *
207      * @return a copy of the object
208      */
209 
210     public Object   clone() {
211         return new StringArray(this);
212     }
213 }
214
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags