1 /*
2 * Copyright 2001-2010 Stephen Colebourne
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 * http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16 package org.joda.primitives.list;
17
18 import org.joda.primitives.collection.ByteCollection;
19 import org.joda.primitives.iterator.ByteIterator;
20 import org.joda.primitives.listiterator.ByteListIterator;
21
22 /**
23 * Defines a list of primitive <code>byte</code> values.
24 * <p>
25 * This interface extends {@link java.util.List List} allowing seamless integration
26 * with other APIs.
27 * All List methods can be used, using the primitive wrapper class {@link Byte}.
28 * However, it will be <em>much</em> more efficient to use the methods defined here.
29 *
30 * @author Stephen Colebourne
31 * @author Jason Tiscione
32 * @version CODE GENERATED
33 * @since 1.0
34 */
35 public interface ByteList extends PrimitiveList<Byte>, ByteCollection {
36 // This file is CODE GENERATED. Do not change manually.
37
38 // Mandatory operations
39 //-----------------------------------------------------------------------
40 /**
41 * Gets an iterator over this list capable of accessing the primitive values.
42 *
43 * @return an iterator over this list, not null
44 */
45 ByteIterator iterator();
46 // This method is specified here, despite being in {@code ByteCollection},
47 // due to compiler bug 6487370.
48
49 /**
50 * Gets the primitive value at the specified index.
51 *
52 * @param index the index to get from
53 * @return value at the index
54 * @throws IndexOutOfBoundsException if the index is invalid
55 */
56 byte getByte(int index);
57
58 /**
59 * Gets the first primitive value.
60 *
61 * @return value at index zero
62 * @throws IndexOutOfBoundsException if the size is zero
63 */
64 byte firstByte();
65
66 /**
67 * Gets the last primitive value.
68 *
69 * @return value at index <code>size() - 1</code>
70 * @throws IndexOutOfBoundsException if the size is zero
71 */
72 byte lastByte();
73
74 /**
75 * Gets a list iterator over this list capable of accessing the primitive values.
76 *
77 * @return an iterator over this list, not null
78 */
79 ByteListIterator listIterator();
80
81 /**
82 * Gets a list iterator over this list from a start index capable of accessing the primitive values.
83 *
84 * @param index the index to start from
85 * @return an iterator over this list, not null
86 * @throws IndexOutOfBoundsException if the index is invalid
87 */
88 ByteListIterator listIterator(int index);
89
90 /**
91 * Gets the first index of the specified primitive value.
92 *
93 * @param value the value to search for
94 * @return the zero-based index, or <code>-1</code> if not found
95 */
96 int indexOf(byte value);
97
98 /**
99 * 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(byte 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(byte 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(byte 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 byte[] toByteArray(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 ByteList for the subList, not null
151 * @throws IndexOutOfBoundsException if either index is invalid
152 */
153 ByteList 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, byte 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, byte[] 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 #removeByteAt} instead.
197 *
198 * @deprecated use byte removeByteAt(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 Byte 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 byte removeByteAt(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 byte set(int index, byte value);
234
235 }