1 /*
2 * Copyright 2001-2010 Stephen Colebourne
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 * http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16 package org.joda.primitives.list;
17
18 import org.joda.primitives.collection.CharCollection;
19 import org.joda.primitives.iterator.CharIterator;
20 import org.joda.primitives.listiterator.CharListIterator;
21
22 /**
23 * Defines a list of primitive <code>char</code> values.
24 * <p>
25 * This interface extends {@link java.util.List List} allowing seamless integration
26 * with other APIs.
27 * All List methods can be used, using the primitive wrapper class {@link Character}.
28 * However, it will be <em>much</em> more efficient to use the methods defined here.
29 *
30 * @author Stephen Colebourne
31 * @author Jason Tiscione
32 * @version CODE GENERATED
33 * @since 1.0
34 */
35 public interface CharList extends PrimitiveList<Character>, CharCollection {
36 // This file is CODE GENERATED. Do not change manually.
37
38 // Mandatory operations
39 //-----------------------------------------------------------------------
40 /**
41 * Gets an iterator over this list capable of accessing the primitive values.
42 *
43 * @return an iterator over this list, not null
44 */
45 CharIterator iterator();
46 // This method is specified here, despite being in {@code CharCollection},
47 // due to compiler bug 6487370.
48
49 /**
50 * Gets the primitive value at the specified index.
51 *
52 * @param index the index to get from
53 * @return value at the index
54 * @throws IndexOutOfBoundsException if the index is invalid
55 */
56 char getChar(int index);
57
58 /**
59 * Gets the first primitive value.
60 *
61 * @return value at index zero
62 * @throws IndexOutOfBoundsException if the size is zero
63 */
64 char firstChar();
65
66 /**
67 * Gets the last primitive value.
68 *
69 * @return value at index <code>size() - 1</code>
70 * @throws IndexOutOfBoundsException if the size is zero
71 */
72 char lastChar();
73
74 /**
75 * Gets a list iterator over this list capable of accessing the primitive values.
76 *
77 * @return an iterator over this list, not null
78 */
79 CharListIterator listIterator();
80
81 /**
82 * Gets a list iterator over this list from a start index capable of accessing the primitive values.
83 *
84 * @param index the index to start from
85 * @return an iterator over this list, not null
86 * @throws IndexOutOfBoundsException if the index is invalid
87 */
88 CharListIterator listIterator(int index);
89
90 /**
91 * Gets the first index of the specified primitive value.
92 *
93 * @param value the value to search for
94 * @return the zero-based index, or <code>-1</code> if not found
95 */
96 int indexOf(char value);
97
98 /**
99 * 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 }