001 /*
002 * Copyright 2001-2010 Stephen Colebourne
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 *
008 * http://www.apache.org/licenses/LICENSE-2.0
009 *
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS,
012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 * See the License for the specific language governing permissions and
014 * limitations under the License.
015 */
016 package org.joda.primitives.list;
017
018 import org.joda.primitives.collection.CharCollection;
019 import org.joda.primitives.iterator.CharIterator;
020 import org.joda.primitives.listiterator.CharListIterator;
021
022 /**
023 * Defines a list of primitive <code>char</code> values.
024 * <p>
025 * This interface extends {@link java.util.List List} allowing seamless integration
026 * with other APIs.
027 * All List methods can be used, using the primitive wrapper class {@link Character}.
028 * However, it will be <em>much</em> more efficient to use the methods defined here.
029 *
030 * @author Stephen Colebourne
031 * @author Jason Tiscione
032 * @version CODE GENERATED
033 * @since 1.0
034 */
035 public interface CharList extends PrimitiveList<Character>, CharCollection {
036 // This file is CODE GENERATED. Do not change manually.
037
038 // Mandatory operations
039 //-----------------------------------------------------------------------
040 /**
041 * Gets an iterator over this list capable of accessing the primitive values.
042 *
043 * @return an iterator over this list, not null
044 */
045 CharIterator iterator();
046 // This method is specified here, despite being in {@code CharCollection},
047 // due to compiler bug 6487370.
048
049 /**
050 * Gets the primitive value at the specified index.
051 *
052 * @param index the index to get from
053 * @return value at the index
054 * @throws IndexOutOfBoundsException if the index is invalid
055 */
056 char getChar(int index);
057
058 /**
059 * Gets the first primitive value.
060 *
061 * @return value at index zero
062 * @throws IndexOutOfBoundsException if the size is zero
063 */
064 char firstChar();
065
066 /**
067 * Gets the last primitive value.
068 *
069 * @return value at index <code>size() - 1</code>
070 * @throws IndexOutOfBoundsException if the size is zero
071 */
072 char lastChar();
073
074 /**
075 * Gets a list iterator over this list capable of accessing the primitive values.
076 *
077 * @return an iterator over this list, not null
078 */
079 CharListIterator listIterator();
080
081 /**
082 * Gets a list iterator over this list from a start index capable of accessing the primitive values.
083 *
084 * @param index the index to start from
085 * @return an iterator over this list, not null
086 * @throws IndexOutOfBoundsException if the index is invalid
087 */
088 CharListIterator listIterator(int index);
089
090 /**
091 * Gets the first index of the specified primitive value.
092 *
093 * @param value the value to search for
094 * @return the zero-based index, or <code>-1</code> if not found
095 */
096 int indexOf(char value);
097
098 /**
099 * Gets the first index of the specified primitive value from an index.
100 * <p>
101 * This method follows the conventions of <code>String</code> in that a
102 * negative index is treated as zero, and an index greater than the list
103 * size will simply return <code>-1</code>.
104 *
105 * @param value the value to search for
106 * @param fromIndexInclusive the index to start searching from, inclusive
107 * @return the zero-based index, or <code>-1</code> if not found
108 */
109 int indexOf(char value, int fromIndexInclusive);
110
111 /**
112 * Gets the last index of the specified primitive value.
113 *
114 * @param value the value to search for
115 * @return the zero-based index, or <code>-1</code> if not found
116 */
117 int lastIndexOf(char value);
118
119 /**
120 * Gets the first index of the specified primitive value from an index.
121 * <p>
122 * This method follows the conventions of <code>String</code> in that an
123 * index greater than the list size will start searching at the list size,
124 * and a negative index simply returns <code>-1</code>.
125 *
126 * @param value the value to search for
127 * @param fromIndexInclusive the index to start searching from, inclusive
128 * @return the zero-based index, or <code>-1</code> if not found
129 */
130 int lastIndexOf(char value, int fromIndexInclusive);
131
132 /**
133 * Gets the contents of the list as a String.
134 *
135 * @return the list contents
136 */
137 String toStringContents();
138
139 /**
140 * Gets a range of elements as an array.
141 *
142 * @param fromIndexInclusive the index to start from, inclusive
143 * @param toIndexExclusive the index to end at, exclusive
144 * @return a new array containing a copy of the range of elements, not null
145 * @throws IndexOutOfBoundsException if either index is invalid
146 */
147 char[] toCharArray(int fromIndexInclusive, int toIndexExclusive);
148
149 /**
150 * Gets a range view of part of this list.
151 * <p>
152 * This method allows operations to work on a range within the greater list.
153 * Changes made to the either object will affect the other.
154 *
155 * @param fromIndexInclusive the index to start from, inclusive
156 * @param toIndexExclusive the index to end at, exclusive
157 * @return a new CharList for the subList, not null
158 * @throws IndexOutOfBoundsException if either index is invalid
159 */
160 CharList subList(int fromIndexInclusive, int toIndexExclusive);
161
162 // Optional operations
163 //-----------------------------------------------------------------------
164 /**
165 * Adds a primitive value to this list at an index (optional operation).
166 * <p>
167 * This method is optional, throwing an UnsupportedOperationException if the
168 * collection cannot be added to.
169 *
170 * @param index the index to add at
171 * @param value the value to add to this collection
172 * @return <code>true</code> if this list was modified by this method call
173 * @throws IndexOutOfBoundsException if the index is invalid
174 * @throws IllegalArgumentException if value is rejected by this collection
175 * @throws UnsupportedOperationException if not supported by this collection
176 */
177 boolean add(int index, char value);
178
179 /**
180 * Adds an array of primitive values to this list at an index (optional operation).
181 * <p>
182 * This method is optional, throwing an UnsupportedOperationException if the
183 * collection cannot be added to.
184 *
185 * @param index the index to add at
186 * @param values the values to add to this collection, null treated as empty array
187 * @return <code>true</code> if this list was modified by this method call
188 * @throws IndexOutOfBoundsException if the index is invalid
189 * @throws IllegalArgumentException if value is rejected by this collection
190 * @throws UnsupportedOperationException if not supported by this collection
191 */
192 boolean addAll(int index, char[] values);
193
194 /**
195 * Removes a primitive value by index from the list (optional operation).
196 * <p>
197 * This method is optional, throwing an UnsupportedOperationException if the
198 * collection cannot be added to.
199 * <p>
200 * This method is deprecated to serve as a warning to developers.
201 * Using it can be confusing as it removes by index rather than by primitive.
202 * The method will still function correctly as the method is defined in the List interface.
203 * Use {@link #removeCharAt} instead.
204 *
205 * @deprecated use char removeCharAt(int)
206 * @param index the index to remove from
207 * @return the primitive value previously at this index
208 * @throws IndexOutOfBoundsException if the index is invalid
209 * @throws UnsupportedOperationException if not supported by this collection
210 */
211 @Deprecated
212 Character remove(int index);
213
214 /**
215 * Removes a primitive value by index from the list (optional operation).
216 * <p>
217 * This method is optional, throwing an UnsupportedOperationException if the
218 * collection cannot be added to.
219 *
220 * @param index the index to remove from
221 * @return the primitive value previously at this index
222 * @throws IndexOutOfBoundsException if the index is invalid
223 * @throws UnsupportedOperationException if not supported by this collection
224 */
225 char removeCharAt(int index);
226
227 /**
228 * Sets the primitive value at a specified index (optional operation).
229 * <p>
230 * This method is optional, throwing an UnsupportedOperationException if the
231 * collection cannot be changed.
232 *
233 * @param index the index to set
234 * @param value the value to store
235 * @return the previous value at the index
236 * @throws IndexOutOfBoundsException if the index is invalid
237 * @throws IllegalArgumentException if value is rejected by this collection
238 * @throws UnsupportedOperationException if not supported by this collection
239 */
240 char set(int index, char value);
241
242 }