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 */
016package org.joda.primitives.list;
017
018import org.joda.primitives.collection.CharCollection;
019import org.joda.primitives.iterator.CharIterator;
020import 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 */
035public 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}