001/*
002 * Licensed to the Apache Software Foundation (ASF) under one or more
003 * contributor license agreements.  See the NOTICE file distributed with
004 * this work for additional information regarding copyright ownership.
005 * The ASF licenses this file to You under the Apache License, Version 2.0
006 * (the "License"); you may not use this file except in compliance with
007 * the License.  You may obtain a copy of the License at
008 *
009 *     http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017package org.apache.commons.collections.primitives;
018
019/**
020 * An ordered collection of <code>char</code> values.
021 *
022 * @see org.apache.commons.collections.primitives.adapters.CharListList
023 * @see org.apache.commons.collections.primitives.adapters.ListCharList
024 *
025 * @since Commons Primitives 1.0
026 * @version $Revision: 480460 $ $Date: 2006-11-29 03:14:21 -0500 (Wed, 29 Nov 2006) $
027 * 
028 * @author Rodney Waldhoff 
029 */
030public interface CharList extends CharCollection {
031    /** 
032     * Appends the specified element to the end of me
033     * (optional operation).  Returns <code>true</code>
034     * iff I changed as a result of this call.
035     * <p/>
036     * If a collection refuses to add the specified
037     * element for any reason other than that it already contains
038     * the element, it <i>must</i> throw an exception (rather than
039     * simply returning <tt>false</tt>).  This preserves the invariant
040     * that a collection always contains the specified element after 
041     * this call returns. 
042     * 
043     * @param element the value whose presence within me is to be ensured
044     * @return <code>true</code> iff I changed as a result of this call
045     * 
046     * @throws UnsupportedOperationException when this operation is not 
047     *         supported
048     * @throws IllegalArgumentException may be thrown if some aspect of the 
049     *         specified element prevents it from being added to me
050     */
051    boolean add(char element);
052       
053    /** 
054     * Inserts the specified element at the specified position 
055     * (optional operation). Shifts the element currently 
056     * at that position (if any) and any subsequent elements to the 
057     * right, increasing their indices.
058     * 
059     * @param index the index at which to insert the element
060     * @param element the value to insert
061     * 
062     * @throws UnsupportedOperationException when this operation is not 
063     *         supported
064     * @throws IllegalArgumentException if some aspect of the specified element 
065     *         prevents it from being added to me
066     * @throws IndexOutOfBoundsException if the specified index is out of range
067     */
068    void add(int index, char element);
069          
070    /** 
071     * Inserts all of the elements in the specified collection into me,
072     * at the specified position (optional operation).  Shifts the 
073     * element currently at that position (if any) and any subsequent 
074     * elements to the right, increasing their indices.  The new elements 
075     * will appear in the order that they are returned by the given 
076     * collection's {@link CharCollection#iterator iterator}.
077     * 
078     * @param index the index at which to insert the first element from 
079     *        the specified collection
080     * @param collection the {@link CharCollection CharCollection} of elements to add 
081     * @return <code>true</code> iff I changed as a result of this call
082     * 
083     * @throws UnsupportedOperationException when this operation is not 
084     *         supported
085     * @throws IndexOutOfBoundsException if the specified index is out of range
086     */
087    boolean addAll(int index, CharCollection collection);
088    
089    /**
090     * Returns <code>true</code> iff <i>that</i> is an <code>CharList</code>
091     * that contains the same elements in the same order as me.
092     * In other words, returns <code>true</code> iff <i>that</i> is
093     * a <code>CharList</code> that has the same {@link #size() size} as me,
094     * and for which the elements returned by its 
095     * {@link CharList#iterator iterator} are equal (<code>==</code>) to
096     * the corresponding elements within me.
097     * (This contract ensures that this method works properly across 
098     * different implementations of the <code>CharList</code> interface.)
099     * 
100     * @param that the object to compare to me
101     * @return <code>true</code> iff <i>that</i> is an <code>CharList</code>
102     *         that contains the same elements in the same order as me
103     */
104    boolean equals(Object that);
105    
106    /** 
107     * Returns the value of the element at the specified position 
108     * within me. 
109     * 
110     * @param index the index of the element to return
111     * @return the value of the element at the specified position
112     * @throws IndexOutOfBoundsException if the specified index is out of range
113     */
114    char get(int index);
115        
116    /**
117     * Returns my hash code.
118     * <p />
119     * The hash code of an <code>CharList</code> is defined to be the
120     * result of the following calculation:
121     * <pre> int hash = 1;
122     * for(CharIterator iter = iterator(); iter.hasNext(); ) {
123     *   char value = iter.next();
124     *   hash = 31*hash + (int)(value ^ (value >>> 32));
125     * }</pre>
126     * <p />
127     * This contract ensures that this method is consistent with 
128     * {@link #equals equals} and with the 
129     * {@link java.util.List#hashCode hashCode}
130     * method of a {@link java.util.List List} of {@link Character}s. 
131     * 
132     * @return my hash code
133     */
134    int hashCode();
135
136    /** 
137     * Returns the index of the first occurrence 
138     * of the specified element within me, 
139     * or <code>-1</code> if I do not contain 
140     * the element. 
141     * 
142     * @param element the element to search for
143     * @return the smallest index of an element matching the specified value,
144     *         or <code>-1</code> if no such matching element can be found 
145     */
146    int indexOf(char element);
147     
148    /** 
149     * Returns an {@link CharIterator iterator} over all my elements,
150     * in the appropriate sequence.
151     * @return an {@link CharIterator iterator} over all my elements.
152     */
153    CharIterator iterator();
154
155    /** 
156     * Returns the index of the last occurrence 
157     * of the specified element within me, 
158     * or -1 if I do not contain the element. 
159     * 
160     * @param element the element to search for
161     * @return the largest index of an element matching the specified value,
162     *         or <code>-1</code> if no such matching element can be found 
163     */
164    int lastIndexOf(char element);
165    
166    /** 
167     * Returns a 
168     * {@link CharListIterator bidirectional iterator}
169     * over all my elements, in the appropriate sequence.
170     */
171    CharListIterator listIterator();
172    
173    /** 
174     * Returns a 
175     * {@link CharListIterator bidirectional iterator}
176     * over all my elements, in the appropriate sequence, 
177     * starting at the specified position. The 
178     * specified <i>index</i> indicates the first 
179     * element that would be returned by an initial 
180     * call to the 
181     * {@link CharListIterator#next next} 
182     * method. An initial call to the 
183     * {@link CharListIterator#previous previous}
184     * method would return the element with the specified 
185     * <i>index</i> minus one.
186     * 
187     * @throws IndexOutOfBoundsException if the specified index is out of range
188     */
189    CharListIterator listIterator(int index);
190    
191    /** 
192     * Removes the element at the specified position in 
193     * (optional operation).  Any subsequent elements 
194     * are shifted to the left, subtracting one from their 
195     * indices.  Returns the element that was removed.
196     * 
197     * @param index the index of the element to remove
198     * @return the value of the element that was removed
199     * 
200     * @throws UnsupportedOperationException when this operation is not 
201     *         supported
202     * @throws IndexOutOfBoundsException if the specified index is out of range
203     */
204    char removeElementAt(int index);
205   
206    /** 
207     * Replaces the element at the specified 
208     * position in me with the specified element
209     * (optional operation). 
210     * 
211     * @param index the index of the element to change
212     * @param element the value to be stored at the specified position
213     * @return the value previously stored at the specified position
214     * 
215     * @throws UnsupportedOperationException when this operation is not 
216     *         supported
217     * @throws IndexOutOfBoundsException if the specified index is out of range
218     */
219    char set(int index, char element);
220    
221    /** 
222     * Returns a view of the elements within me 
223     * between the specified <i>fromIndex</i>, inclusive, and 
224     * <i>toIndex</i>, exclusive.  The returned <code>CharList</code>
225     * is backed by me, so that any changes in 
226     * the returned list are reflected in me, and vice-versa.
227     * The returned list supports all of the optional operations
228     * that I support.
229     * <p/>
230     * Note that when <code><i>fromIndex</i> == <i>toIndex</i></code>,
231     * the returned list is initially empty, and when 
232     * <code><i>fromIndex</i> == 0 && <i>toIndex</i> == {@link #size() size()}</code>
233     * the returned list is my "improper" sublist, containing all my elements.
234     * <p/>
235     * The semantics of the returned list become undefined
236     * if I am structurally modified in any way other than 
237     * via the returned list.
238     * 
239     * @param fromIndex the smallest index (inclusive) in me that appears in 
240     *        the returned list
241     * @param toIndex the largest index (exclusive) in me that appears in the 
242     *        returned list
243     * @return a view of this list from <i>fromIndex</i> (inclusive) to 
244     *         <i>toIndex</i> (exclusive)
245     * 
246     * @throws IndexOutOfBoundsException if either specified index is out of range
247     */
248    CharList subList(int fromIndex, int toIndex);
249
250}