Coverage Report - org.apache.commons.collections.primitives.ShortList
 
Classes in this File Line Coverage Branch Coverage Complexity
ShortList
N/A
N/A
1
 
 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>short</code> values.
 21  
  *
 22  
  * @see org.apache.commons.collections.primitives.adapters.ShortListList
 23  
  * @see org.apache.commons.collections.primitives.adapters.ListShortList
 24  
  *
 25  
  * @since Commons Primitives 1.0
 26  
  * @version $Revision: 480460 $ $Date: 2006-11-29 03:14:21 -0500 (Wed, 29 Nov 2006) $
 27  
  * 
 28  
  * @author Rodney Waldhoff 
 29  
  */
 30  
 public interface ShortList extends ShortCollection {
 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(short 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, short 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 ShortCollection#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 ShortCollection ShortCollection} 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, ShortCollection collection);
 88  
     
 89  
     /**
 90  
      * Returns <code>true</code> iff <i>that</i> is an <code>ShortList</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>ShortList</code> that has the same {@link #size() size} as me,
 94  
      * and for which the elements returned by its 
 95  
      * {@link ShortList#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>ShortList</code> interface.)
 99  
      * 
 100  
      * @param that the object to compare to me
 101  
      * @return <code>true</code> iff <i>that</i> is an <code>ShortList</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  
     short get(int index);
 115  
         
 116  
     /**
 117  
      * Returns my hash code.
 118  
      * <p />
 119  
      * The hash code of an <code>ShortList</code> is defined to be the
 120  
      * result of the following calculation:
 121  
      * <pre> int hash = 1;
 122  
      * for(ShortIterator iter = iterator(); iter.hasNext(); ) {
 123  
      *   short 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 Short}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(short element);
 147  
      
 148  
     /** 
 149  
      * Returns an {@link ShortIterator iterator} over all my elements,
 150  
      * in the appropriate sequence.
 151  
      * @return an {@link ShortIterator iterator} over all my elements.
 152  
      */
 153  
     ShortIterator 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(short element);
 165  
     
 166  
     /** 
 167  
      * Returns a 
 168  
      * {@link ShortListIterator bidirectional iterator}
 169  
      * over all my elements, in the appropriate sequence.
 170  
      */
 171  
     ShortListIterator listIterator();
 172  
     
 173  
     /** 
 174  
      * Returns a 
 175  
      * {@link ShortListIterator 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 ShortListIterator#next next} 
 182  
      * method. An initial call to the 
 183  
      * {@link ShortListIterator#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  
     ShortListIterator 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  
     short 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  
     short set(int index, short 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>ShortList</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  
     ShortList subList(int fromIndex, int toIndex);
 249  
 
 250  
 }