1. /*
  2. * $Header: /home/cvs/jakarta-commons/primitives/src/java/org/apache/commons/collections/primitives/CharList.java,v 1.3 2003/10/16 20:49:36 scolebourne Exp $
  3. * ====================================================================
  4. * The Apache Software License, Version 1.1
  5. *
  6. * Copyright (c) 2002-2003 The Apache Software Foundation. All rights
  7. * reserved.
  8. *
  9. * Redistribution and use in source and binary forms, with or without
  10. * modification, are permitted provided that the following conditions
  11. * are met:
  12. *
  13. * 1. Redistributions of source code must retain the above copyright
  14. * notice, this list of conditions and the following disclaimer.
  15. *
  16. * 2. Redistributions in binary form must reproduce the above copyright
  17. * notice, this list of conditions and the following disclaimer in
  18. * the documentation and/or other materials provided with the
  19. * distribution.
  20. *
  21. * 3. The end-user documentation included with the redistribution, if
  22. * any, must include the following acknowledgement:
  23. * "This product includes software developed by the
  24. * Apache Software Foundation (http://www.apache.org/)."
  25. * Alternately, this acknowledgement may appear in the software itself,
  26. * if and wherever such third-party acknowledgements normally appear.
  27. *
  28. * 4. The names "The Jakarta Project", "Commons", and "Apache Software
  29. * Foundation" must not be used to endorse or promote products derived
  30. * from this software without prior written permission. For written
  31. * permission, please contact apache@apache.org.
  32. *
  33. * 5. Products derived from this software may not be called "Apache"
  34. * nor may "Apache" appear in their names without prior written
  35. * permission of the Apache Software Foundation.
  36. *
  37. * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
  38. * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
  39. * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
  40. * DISCLAIMED. IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
  41. * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  42. * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  43. * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
  44. * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
  45. * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
  46. * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
  47. * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  48. * SUCH DAMAGE.
  49. * ====================================================================
  50. *
  51. * This software consists of voluntary contributions made by many
  52. * individuals on behalf of the Apache Software Foundation. For more
  53. * information on the Apache Software Foundation, please see
  54. * <http://www.apache.org/>.
  55. *
  56. */
  57. package org.apache.commons.collections.primitives;
  58. /**
  59. * An ordered collection of <code>char</code> values.
  60. *
  61. * @see org.apache.commons.collections.primitives.adapters.CharListList
  62. * @see org.apache.commons.collections.primitives.adapters.ListCharList
  63. *
  64. * @since Commons Primitives 1.0
  65. * @version $Revision: 1.3 $ $Date: 2003/10/16 20:49:36 $
  66. *
  67. * @author Rodney Waldhoff
  68. */
  69. public interface CharList extends CharCollection {
  70. /**
  71. * Appends the specified element to the end of me
  72. * (optional operation). Returns <code>true</code>
  73. * iff I changed as a result of this call.
  74. * <p/>
  75. * If a collection refuses to add the specified
  76. * element for any reason other than that it already contains
  77. * the element, it <i>must</i> throw an exception (rather than
  78. * simply returning <tt>false</tt>). This preserves the invariant
  79. * that a collection always contains the specified element after
  80. * this call returns.
  81. *
  82. * @param element the value whose presence within me is to be ensured
  83. * @return <code>true</code> iff I changed as a result of this call
  84. *
  85. * @throws UnsupportedOperationException when this operation is not
  86. * supported
  87. * @throws IllegalArgumentException may be thrown if some aspect of the
  88. * specified element prevents it from being added to me
  89. */
  90. boolean add(char element);
  91. /**
  92. * Inserts the specified element at the specified position
  93. * (optional operation). Shifts the element currently
  94. * at that position (if any) and any subsequent elements to the
  95. * right, increasing their indices.
  96. *
  97. * @param index the index at which to insert the element
  98. * @param element the value to insert
  99. *
  100. * @throws UnsupportedOperationException when this operation is not
  101. * supported
  102. * @throws IllegalArgumentException if some aspect of the specified element
  103. * prevents it from being added to me
  104. * @throws IndexOutOfBoundsException if the specified index is out of range
  105. */
  106. void add(int index, char element);
  107. /**
  108. * Inserts all of the elements in the specified collection into me,
  109. * at the specified position (optional operation). Shifts the
  110. * element currently at that position (if any) and any subsequent
  111. * elements to the right, increasing their indices. The new elements
  112. * will appear in the order that they are returned by the given
  113. * collection's {@link CharCollection#iterator iterator}.
  114. *
  115. * @param index the index at which to insert the first element from
  116. * the specified collection
  117. * @param collection the {@link CharCollection CharCollection} of elements to add
  118. * @return <code>true</code> iff I changed as a result of this call
  119. *
  120. * @throws UnsupportedOperationException when this operation is not
  121. * supported
  122. * @throws IndexOutOfBoundsException if the specified index is out of range
  123. */
  124. boolean addAll(int index, CharCollection collection);
  125. /**
  126. * Returns <code>true</code> iff <i>that</i> is an <code>CharList</code>
  127. * that contains the same elements in the same order as me.
  128. * In other words, returns <code>true</code> iff <i>that</i> is
  129. * an <code>CharList</code> that has the same {@link #size size} as me,
  130. * and for which the elements returned by its
  131. * {@link CharList#iterator iterator} are equal (<code>==</code>) to
  132. * the corresponding elements within me.
  133. * (This contract ensures that this method works properly across
  134. * different implementations of the <code>CharList</code> interface.)
  135. *
  136. * @param that the object to compare to me
  137. * @return <code>true</code> iff <i>that</i> is an <code>CharList</code>
  138. * that contains the same elements in the same order as me
  139. */
  140. boolean equals(Object that);
  141. /**
  142. * Returns the value of the element at the specified position
  143. * within me.
  144. *
  145. * @param index the index of the element to return
  146. * @return the value of the element at the specified position
  147. * @throws IndexOutOfBoundsException if the specified index is out of range
  148. */
  149. char get(int index);
  150. /**
  151. * Returns my hash code.
  152. * <p />
  153. * The hash code of an <code>CharList</code> is defined to be the
  154. * result of the following calculation:
  155. * <pre> int hash = 1;
  156. * for(CharIterator iter = iterator(); iter.hasNext(); ) {
  157. * char value = iter.next();
  158. * hash = 31*hash + (int)(value ^ (value >>> 32));
  159. * }</pre>
  160. * <p />
  161. * This contract ensures that this method is consistent with
  162. * {@link #equals equals} and with the
  163. * {@link java.util.List#hashCode hashCode}
  164. * method of a {@link java.util.List List} of {@link Character}s.
  165. *
  166. * @return my hash code
  167. */
  168. int hashCode();
  169. /**
  170. * Returns the index of the first occurrence
  171. * of the specified element within me,
  172. * or <code>-1</code> if I do not contain
  173. * the element.
  174. *
  175. * @param element the element to search for
  176. * @return the smallest index of an element matching the specified value,
  177. * or <code>-1</code> if no such matching element can be found
  178. */
  179. int indexOf(char element);
  180. /**
  181. * Returns an {@link CharIterator iterator} over all my elements,
  182. * in the appropriate sequence.
  183. * @return an {@link CharIterator iterator} over all my elements.
  184. */
  185. CharIterator iterator();
  186. /**
  187. * Returns the index of the last occurrence
  188. * of the specified element within me,
  189. * or -1 if I do not contain the element.
  190. *
  191. * @param element the element to search for
  192. * @return the largest index of an element matching the specified value,
  193. * or <code>-1</code> if no such matching element can be found
  194. */
  195. int lastIndexOf(char element);
  196. /**
  197. * Returns a
  198. * {@link CharListIterator bidirectional iterator}
  199. * over all my elements, in the appropriate sequence.
  200. */
  201. CharListIterator listIterator();
  202. /**
  203. * Returns a
  204. * {@link CharListIterator bidirectional iterator}
  205. * over all my elements, in the appropriate sequence,
  206. * starting at the specified position. The
  207. * specified <i>index</i> indicates the first
  208. * element that would be returned by an initial
  209. * call to the
  210. * {@link CharListIterator#next next}
  211. * method. An initial call to the
  212. * {@link CharListIterator#previous previous}
  213. * method would return the element with the specified
  214. * <i>index</i> minus one.
  215. *
  216. * @throws IndexOutOfBoundsException if the specified index is out of range
  217. */
  218. CharListIterator listIterator(int index);
  219. /**
  220. * Removes the element at the specified position in
  221. * (optional operation). Any subsequent elements
  222. * are shifted to the left, subtracting one from their
  223. * indices. Returns the element that was removed.
  224. *
  225. * @param index the index of the element to remove
  226. * @return the value of the element that was removed
  227. *
  228. * @throws UnsupportedOperationException when this operation is not
  229. * supported
  230. * @throws IndexOutOfBoundsException if the specified index is out of range
  231. */
  232. char removeElementAt(int index);
  233. /**
  234. * Replaces the element at the specified
  235. * position in me with the specified element
  236. * (optional operation).
  237. *
  238. * @param index the index of the element to change
  239. * @param element the value to be stored at the specified position
  240. * @return the value previously stored at the specified position
  241. *
  242. * @throws UnsupportedOperationException when this operation is not
  243. * supported
  244. * @throws IndexOutOfBoundsException if the specified index is out of range
  245. */
  246. char set(int index, char element);
  247. /**
  248. * Returns a view of the elements within me
  249. * between the specified <i>fromIndex</i>, inclusive, and
  250. * <i>toIndex</i>, exclusive. The returned <code>CharList</code>
  251. * is backed by me, so that any changes in
  252. * the returned list are reflected in me, and vice-versa.
  253. * The returned list supports all of the optional operations
  254. * that I support.
  255. * <p/>
  256. * Note that when <code><i>fromIndex</i> == <i>toIndex</i></code>,
  257. * the returned list is initially empty, and when
  258. * <code><i>fromIndex</i> == 0 && <i>toIndex</i> == {@link #size() size()}</code>
  259. * the returned list is my "improper" sublist, containing all my elements.
  260. * <p/>
  261. * The semantics of the returned list become undefined
  262. * if I am structurally modified in any way other than
  263. * via the returned list.
  264. *
  265. * @param fromIndex the smallest index (inclusive) in me that appears in
  266. * the returned list
  267. * @param toIndex the largest index (exclusive) in me that appears in the
  268. * returned list
  269. * @return a view of this list from <i>fromIndex</i> (inclusive) to
  270. * <i>toIndex</i> (exclusive)
  271. *
  272. * @throws IndexOutOfBoundsException if either specified index is out of range
  273. */
  274. CharList subList(int fromIndex, int toIndex);
  275. }