CharList


1   /*
2    * Licensed to the Apache Software Foundation (ASF) under one or more
3    * contributor license agreements.  See the NOTICE file distributed with
4    * this work for additional information regarding copyright ownership.
5    * The ASF licenses this file to You under the Apache License, Version 2.0
6    * (the "License"); you may not use this file except in compliance with
7    * the License.  You may obtain a copy of the License at
8    *
9    *     http://www.apache.org/licenses/LICENSE-2.0
10   *
11   * Unless required by applicable law or agreed to in writing, software
12   * distributed under the License is distributed on an "AS IS" BASIS,
13   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14   * See the License for the specific language governing permissions and
15   * limitations under the License.
16   */
17  package org.apache.commons.collections.primitives;
18  
19  /**
20   * An ordered collection of <code>char</code> values.
21   *
22   * @see org.apache.commons.collections.primitives.adapters.CharListList
23   * @see org.apache.commons.collections.primitives.adapters.ListCharList
24   *
25   * @since Commons Primitives 1.0
26   * @version $Revision: 480460 $ $Date: 2006-11-29 00:14:21 -0800 (Wed, 29 Nov 2006) $
27   * 
28   * @author Rodney Waldhoff 
29   */
30  public interface CharList extends CharCollection {
31      /** 
32       * Appends the specified element to the end of me
33       * (optional operation).  Returns <code>true</code>
34       * iff I changed as a result of this call.
35       * <p/>
36       * If a collection refuses to add the specified
37       * element for any reason other than that it already contains
38       * the element, it <i>must</i> throw an exception (rather than
39       * simply returning <tt>false</tt>).  This preserves the invariant
40       * that a collection always contains the specified element after 
41       * this call returns. 
42       * 
43       * @param element the value whose presence within me is to be ensured
44       * @return <code>true</code> iff I changed as a result of this call
45       * 
46       * @throws UnsupportedOperationException when this operation is not 
47       *         supported
48       * @throws IllegalArgumentException may be thrown if some aspect of the 
49       *         specified element prevents it from being added to me
50       */
51      boolean add(char element);
52         
53      /** 
54       * Inserts the specified element at the specified position 
55       * (optional operation). Shifts the element currently 
56       * at that position (if any) and any subsequent elements to the 
57       * right, increasing their indices.
58       * 
59       * @param index the index at which to insert the element
60       * @param element the value to insert
61       * 
62       * @throws UnsupportedOperationException when this operation is not 
63       *         supported
64       * @throws IllegalArgumentException if some aspect of the specified element 
65       *         prevents it from being added to me
66       * @throws IndexOutOfBoundsException if the specified index is out of range
67       */
68      void add(int index, char element);
69            
70      /** 
71       * Inserts all of the elements in the specified collection into me,
72       * at the specified position (optional operation).  Shifts the 
73       * element currently at that position (if any) and any subsequent 
74       * elements to the right, increasing their indices.  The new elements 
75       * will appear in the order that they are returned by the given 
76       * collection's {@link CharCollection#iterator iterator}.
77       * 
78       * @param index the index at which to insert the first element from 
79       *        the specified collection
80       * @param collection the {@link CharCollection CharCollection} of elements to add 
81       * @return <code>true</code> iff I changed as a result of this call
82       * 
83       * @throws UnsupportedOperationException when this operation is not 
84       *         supported
85       * @throws IndexOutOfBoundsException if the specified index is out of range
86       */
87      boolean addAll(int index, CharCollection collection);
88      
89      /**
90       * Returns <code>true</code> iff <i>that</i> is an <code>CharList</code>
91       * that contains the same elements in the same order as me.
92       * In other words, returns <code>true</code> iff <i>that</i> is
93       * a <code>CharList</code> that has the same {@link #size() size} as me,
94       * and for which the elements returned by its 
95       * {@link CharList#iterator iterator} are equal (<code>==</code>) to
96       * the corresponding elements within me.
97       * (This contract ensures that this method works properly across 
98       * different implementations of the <code>CharList</code> interface.)
99       * 
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 }
251
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags