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.ShortCollection;
019import org.joda.primitives.iterator.ShortIterator;
020import org.joda.primitives.listiterator.ShortListIterator;
021
022/**
023 * Defines a list of primitive <code>short</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 Short}.
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 ShortList extends PrimitiveList<Short>, ShortCollection {
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    ShortIterator iterator();
046    // This method is specified here, despite being in {@code ShortCollection},
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    short getShort(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    short firstShort();
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    short lastShort();
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    ShortListIterator 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    ShortListIterator 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(short 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(short 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(short 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(short value, int fromIndexInclusive);
131
132    /**
133     * Gets a range of elements as an array.
134     *
135     * @param fromIndexInclusive  the index to start from, inclusive
136     * @param toIndexExclusive  the index to end at, exclusive
137     * @return a new array containing a copy of the range of elements, not null
138     * @throws IndexOutOfBoundsException if either index is invalid
139     */
140    short[] toShortArray(int fromIndexInclusive, int toIndexExclusive);
141
142    /**
143     * Gets a range view of part of this list.
144     * <p>
145     * This method allows operations to work on a range within the greater list.
146     * Changes made to the either object will affect the other.
147     *
148     * @param fromIndexInclusive  the index to start from, inclusive
149     * @param toIndexExclusive  the index to end at, exclusive
150     * @return a new ShortList for the subList, not null
151     * @throws IndexOutOfBoundsException if either index is invalid
152     */
153    ShortList subList(int fromIndexInclusive, int toIndexExclusive);
154
155    // Optional operations
156    //-----------------------------------------------------------------------
157    /**
158     * Adds a primitive value to this list at an index (optional operation).
159     * <p>
160     * This method is optional, throwing an UnsupportedOperationException if the
161     * collection cannot be added to.
162     *
163     * @param index  the index to add at
164     * @param value  the value to add to this collection
165     * @return <code>true</code> if this list was modified by this method call
166     * @throws IndexOutOfBoundsException if the index is invalid
167     * @throws IllegalArgumentException if value is rejected by this collection
168     * @throws UnsupportedOperationException if not supported by this collection
169     */
170    boolean add(int index, short value);
171
172    /**
173     * Adds an array of primitive values to this list at an index (optional operation).
174     * <p>
175     * This method is optional, throwing an UnsupportedOperationException if the
176     * collection cannot be added to.
177     *
178     * @param index  the index to add at
179     * @param values  the values to add to this collection, null treated as empty array
180     * @return <code>true</code> if this list was modified by this method call
181     * @throws IndexOutOfBoundsException if the index is invalid
182     * @throws IllegalArgumentException if value is rejected by this collection
183     * @throws UnsupportedOperationException if not supported by this collection
184     */
185    boolean addAll(int index, short[] values);
186
187    /**
188     * Removes a primitive value by index from the list (optional operation).
189     * <p>
190     * This method is optional, throwing an UnsupportedOperationException if the
191     * collection cannot be added to.
192     * <p>
193     * This method is deprecated to serve as a warning to developers.
194     * Using it can be confusing as it removes by index rather than by primitive.
195     * The method will still function correctly as the method is defined in the List interface.
196     * Use {@link #removeShortAt} instead.
197     *
198     * @deprecated use short removeShortAt(int)
199     * @param index  the index to remove from
200     * @return the primitive value previously at this index
201     * @throws IndexOutOfBoundsException if the index is invalid
202     * @throws UnsupportedOperationException if not supported by this collection
203     */
204    @Deprecated
205    Short remove(int index);
206
207    /**
208     * Removes a primitive value by index from the list (optional operation).
209     * <p>
210     * This method is optional, throwing an UnsupportedOperationException if the
211     * collection cannot be added to.
212     *
213     * @param index  the index to remove from
214     * @return the primitive value previously at this index
215     * @throws IndexOutOfBoundsException if the index is invalid
216     * @throws UnsupportedOperationException if not supported by this collection
217     */
218    short removeShortAt(int index);
219
220    /**
221     * Sets the primitive value at a specified index (optional operation).
222     * <p>
223     * This method is optional, throwing an UnsupportedOperationException if the
224     * collection cannot be changed.
225     *
226     * @param index  the index to set
227     * @param value  the value to store
228     * @return the previous value at the index
229     * @throws IndexOutOfBoundsException if the index is invalid
230     * @throws IllegalArgumentException if value is rejected by this collection
231     * @throws UnsupportedOperationException if not supported by this collection
232     */
233    short set(int index, short value);
234
235}