001 /*
002 * Java Genetic Algorithm Library (jenetics-1.5.0).
003 * Copyright (c) 2007-2013 Franz Wilhelmstötter
004 *
005 * Licensed under the Apache License, Version 2.0 (the "License");
006 * you may not use this file except in compliance with the License.
007 * You may obtain a copy of the License at
008 *
009 * http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 *
017 * Author:
018 * Franz Wilhelmstötter (franz.wilhelmstoetter@gmx.at)
019 */
020 package org.jenetics.util;
021
022 import java.util.Iterator;
023 import java.util.List;
024 import java.util.RandomAccess;
025
026
027 /**
028 * General interface for a ordered, fixed sized, object sequence.
029 * <br/>
030 * Use the {@link #asList()} method to work together with the
031 * <a href="http://download.oracle.com/javase/6/docs/technotes/guides/collections/index.html">
032 * Java Collection Framework</a>.
033 *
034 * @author <a href="mailto:franz.wilhelmstoetter@gmx.at">Franz Wilhelmstötter</a>
035 * @since 1.0
036 * @version 1.3 — <em>$Date: 2013-08-30 $</em>
037 */
038 public interface Seq<T> extends Iterable<T> {
039
040 /**
041 * Return the value at the given {@code index}.
042 *
043 * @param index index of the element to return.
044 * @return the value at the given {@code index}.
045 * @throws IndexOutOfBoundsException if the index is out of range
046 * {@code (index < 0 || index >= size())}.
047 */
048 public T get(final int index);
049
050 /**
051 * Return the length of this sequence. Once the sequence is created, the
052 * length can't be changed.
053 *
054 * @return the length of this sequence.
055 */
056 public int length();
057
058 /**
059 * Return an iterator with the new type {@code B}.
060 *
061 * @param <B> the component type of the returned type.
062 * @param mapper the converter for converting from {@code T} to {@code B}.
063 * @return the iterator of the converted type.
064 * @throws NullPointerException if the given {@code converter} is {@code null}.
065 */
066 public <B> Iterator<B> iterator(
067 final Function<? super T, ? extends B> mapper
068 );
069
070 /**
071 * @deprecated Align the naming with the upcomming JDK 1.8 release. Use
072 * {@link #forEach(Function)} instead.
073 */
074 @Deprecated
075 public <R> void foreach(final Function<? super T, ? extends R> function);
076
077 /**
078 * Applies a {@code function} to all elements of this sequence.
079 *
080 * @param function the function to apply to the elements.
081 * @throws NullPointerException if the given {@code function} is
082 * {@code null}.
083 */
084 public <R> void forEach(final Function<? super T, ? extends R> function);
085
086 /**
087 * @deprecated Align the naming with the upcomming JDK 1.8 release. Use
088 * {@link #forAll(Function)} instead.
089 */
090 @Deprecated
091 public boolean forall(final Function<? super T, Boolean> predicate);
092
093 /**
094 * Tests whether a predicate holds for all elements of this sequence.
095 *
096 * @param predicate the predicate to use to test the elements.
097 * @return {@code true} if the given predicate p holds for all elements of
098 * this sequence, {@code false} otherwise.
099 * @throws NullPointerException if the given {@code predicate} is
100 * {@code null}.
101 */
102 public boolean forAll(final Function<? super T, Boolean> predicate);
103
104 /**
105 * Returns {@code true} if this sequence contains the specified element.
106 *
107 * @param element element whose presence in this sequence is to be tested.
108 * The tested element can be {@code null}.
109 * @return {@code true} if this sequence contains the specified element
110 */
111 public boolean contains(final Object element);
112
113 /**
114 * Returns the index of the first occurrence of the specified element
115 * in this sequence, or -1 if this sequence does not contain the element.
116 *
117 * @param element element to search for, can be {@code null}
118 * @return the index of the first occurrence of the specified element in
119 * this sequence, or -1 if this sequence does not contain the element
120 */
121 public int indexOf(final Object element);
122
123 /**
124 * Returns the index of the first occurrence of the specified element
125 * in this sequence, or -1 if this sequence does not contain the element.
126 *
127 * @param element element to search for, can be {@code null}
128 * @param start the start index (inclusively) for the element search.
129 * @return the index of the first occurrence of the specified element in
130 * this sequence, or -1 if this sequence does not contain the element
131 * @throws IndexOutOfBoundsException for an illegal end point index value
132 * ({@code start < 0 || start > length()}).
133 */
134 public int indexOf(final Object element, final int start);
135
136 /**
137 * Returns the index of the first occurrence of the specified element
138 * in this sequence, or -1 if this sequence does not contain the element.
139 *
140 * @param element element to search for, can be {@code null}
141 * @param start the start index (inclusively) for the element search.
142 * @param end the end index (exclusively) for the element search.
143 * @return the index of the first occurrence of the specified element in
144 * this sequence, or -1 if this sequence does not contain the element
145 * @throws IndexOutOfBoundsException for an illegal end point index value
146 * ({@code start < 0 || end > length() || start > end}).
147 */
148 public int indexOf(final Object element, final int start, final int end);
149
150 /**
151 * <p>
152 * Returns the index of the first element on which the given predicate
153 * returns {@code true}, or -1 if the predicate returns false for every
154 * sequence element.
155 * </p>
156 * [code]
157 * // Finding index of first null value.
158 * final int index = seq.indexOf(new Predicates.Nil());
159 *
160 * // Assert of no null values.
161 * assert (sequence.indexOf(new Predicates.Nil()) == -1);
162 * [/code]
163 *
164 * @param predicate the search predicate.
165 * @return the index of the first element on which the given predicate
166 * returns {@code true}, or -1 if the predicate returns {@code false}
167 * for every sequence element.
168 * @throws NullPointerException if the given {@code predicate} is {@code null}.
169 */
170 public int indexWhere(final Function<? super T, Boolean> predicate);
171
172 /**
173 * <p>
174 * Returns the index of the first element on which the given predicate
175 * returns {@code true}, or -1 if the predicate returns false for every
176 * sequence element.
177 * </p>
178 * [code]
179 * // Finding index of first null value.
180 * final int index = seq.indexOf(new Predicates.Nil());
181 *
182 * // Assert of no null values.
183 * assert (sequence.indexOf(new Predicates.Nil()) == -1);
184 * [/code]
185 *
186 * @param predicate the search predicate.
187 * @return the index of the first element on which the given predicate
188 * returns {@code true}, or -1 if the predicate returns {@code false}
189 * for every sequence element.
190 * @throws NullPointerException if the given {@code predicate} is {@code null}.
191 * @throws IndexOutOfBoundsException for an illegal end point index value
192 * ({@code start < 0 || start > length()}).
193 */
194 public int indexWhere(
195 final Function<? super T, Boolean> predicate,
196 final int start
197 );
198
199 /**
200 * <p>
201 * Returns the index of the first element on which the given predicate
202 * returns {@code true}, or -1 if the predicate returns false for every
203 * sequence element.
204 * </p>
205 * [code]
206 * // Finding index of first null value.
207 * final int index = seq.indexOf(new Predicates.Nil());
208 *
209 * // Assert of no null values.
210 * assert (sequence.indexOf(new Predicates.Nil()) == -1);
211 * [/code]
212 *
213 * @param predicate the search predicate.
214 * @return the index of the first element on which the given predicate
215 * returns {@code true}, or -1 if the predicate returns {@code false}
216 * for every sequence element.
217 * @throws NullPointerException if the given {@code predicate} is {@code null}.
218 * @throws IndexOutOfBoundsException for an illegal end point index value
219 * ({@code start < 0 || end > length() || start > end}).
220 */
221 public int indexWhere(
222 final Function<? super T, Boolean> predicate,
223 final int start,
224 final int end
225 );
226
227 /**
228 * Returns the index of the last occurrence of the specified element
229 * in this sequence, or -1 if this sequence does not contain the element.
230 *
231 * @param element element to search for, can be {@code null}
232 * @return the index of the last occurrence of the specified element in
233 * this sequence, or -1 if this sequence does not contain the element
234 */
235 public int lastIndexOf(final Object element);
236
237 /**
238 * Returns the index of the last occurrence of the specified element
239 * in this sequence, or -1 if this sequence does not contain the element.
240 *
241 * @param element element to search for, can be {@code null}
242 * @return the index of the last occurrence of the specified element in
243 * this sequence, or -1 if this sequence does not contain the element
244 * @throws IndexOutOfBoundsException for an illegal end point index value
245 * ({@code end < 0 || end > length()}).
246 */
247 public int lastIndexOf(final Object element, final int end);
248
249 /**
250 * Returns the index of the last occurrence of the specified element
251 * in this sequence, or -1 if this sequence does not contain the element.
252 *
253 * @param element element to search for, can be {@code null}
254 * @return the index of the last occurrence of the specified element in
255 * this sequence, or -1 if this sequence does not contain the element
256 * @throws IndexOutOfBoundsException for an illegal end point index value
257 * ({@code start < 0 || end > length() || start > end}).
258 */
259 public int lastIndexOf(final Object element, final int start, final int end);
260
261 /**
262 * Returns the index of the last element on which the given predicate
263 * returns {@code true}, or -1 if the predicate returns false for every
264 * sequence element.
265 *
266 * @param predicate the search predicate.
267 * @return the index of the last element on which the given predicate
268 * returns {@code true}, or -1 if the predicate returns false for
269 * every sequence element.
270 * @throws NullPointerException if the given {@code predicate} is {@code null}.
271 */
272 public int lastIndexWhere(final Function<? super T, Boolean> predicate);
273
274 /**
275 * Returns the index of the last element on which the given predicate
276 * returns {@code true}, or -1 if the predicate returns false for every
277 * sequence element.
278 *
279 * @param predicate the search predicate.
280 * @return the index of the last element on which the given predicate
281 * returns {@code true}, or -1 if the predicate returns false for
282 * every sequence element.
283 * @throws NullPointerException if the given {@code predicate} is {@code null}.
284 * @throws IndexOutOfBoundsException for an illegal end point index value
285 * ({@code end < 0 || end > length()}).
286 */
287 public int lastIndexWhere(
288 final Function<? super T, Boolean> predicate,
289 final int end
290 );
291
292 /**
293 * Returns the index of the last element on which the given predicate
294 * returns {@code true}, or -1 if the predicate returns false for every
295 * sequence element.
296 *
297 * @param predicate the search predicate.
298 * @return the index of the last element on which the given predicate
299 * returns {@code true}, or -1 if the predicate returns false for
300 * every sequence element.
301 * @throws NullPointerException if the given {@code predicate} is {@code null}.
302 * @throws IndexOutOfBoundsException for an illegal end point index value
303 * ({@code start < 0 || end > length() || start > end}).
304 */
305 public int lastIndexWhere(
306 final Function<? super T, Boolean> predicate,
307 final int start,
308 final int end
309 );
310
311 /**
312 * Returns a fixed-size list backed by the specified sequence. (Changes to
313 * the returned list "write through" to the array.) The returned list is
314 * fixed size, serializable and implements {@link RandomAccess}.
315 *
316 * @return a list view of this sequence
317 */
318 public List<T> asList();
319
320 /**
321 * Builds a new sequence by applying a function to all elements of this
322 * sequence.
323 *
324 * @param <B> the element type of the returned collection.
325 * @param mapper the function to apply to each element.
326 * @return a new sequence of type That resulting from applying the given
327 * function f to each element of this sequence and collecting the
328 * results.
329 * @throws NullPointerException if the element {@code mapper} is
330 * {@code null}.
331 */
332 public <B> Seq<B> map(final Function<? super T, ? extends B> mapper);
333
334 /**
335 * Return an array containing all of the elements in this sequence in right
336 * order. The returned array will be "safe" in that no references to it
337 * are maintained by this sequence. (In other words, this method must allocate
338 * a new array.) The caller is thus free to modify the returned array.
339 *
340 * @see java.util.Collection#toArray()
341 *
342 * @return an array containing all of the elements in this list in right
343 * order
344 */
345 public Object[] toArray();
346
347 /**
348 * Return an array containing all of the elements in this sequence in right
349 * order; the runtime type of the returned array is that of the specified
350 * array. If this sequence fits in the specified array, it is returned therein.
351 * Otherwise, a new array is allocated with the runtime type of the specified
352 * array and the length of this array.
353 * <p/>
354 * If this sequence fits in the specified array with room to spare (i.e., the
355 * array has more elements than this array), the element in the array
356 * immediately following the end of this array is set to null. (This is
357 * useful in determining the length of the array only if the caller knows
358 * that the list does not contain any null elements.)
359 *
360 * @see java.util.Collection#toArray(Object[])
361 *
362 * @param array the array into which the elements of this array are to be
363 * stored, if it is big enough; otherwise, a new array of the same
364 * runtime type is allocated for this purpose.
365 * @return an array containing the elements of this array
366 * @throws ArrayStoreException if the runtime type of the specified array is
367 * not a super type of the runtime type of every element in this array
368 * @throws NullPointerException if the given array is {@code null}.
369 */
370 public T[] toArray(final T[] array);
371
372 /**
373 * Returns a view of the portion of this sequence between the specified
374 * {@code start}, inclusive, and {@code end}, exclusive. (If {@code start}
375 * and {@code end} are equal, the returned sequence has the length zero.) The
376 * returned sequence is backed by this sequence, so non-structural changes
377 * in the returned sequence are reflected in this sequence, and vice-versa.
378 * <p/>
379 * This method eliminates the need for explicit range operations (of the
380 * sort that commonly exist for arrays). Any operation that expects an sequence
381 * can be used as a range operation by passing an sub sequence view instead of
382 * an whole sequence.
383 *
384 * @param start low end point (inclusive) of the sub array.
385 * @return a view of the specified range within this array.
386 * @throws IndexOutOfBoundsException for an illegal end point index value
387 * ({@code start < 0 || start > length()}).
388 */
389 public Seq<T> subSeq(final int start);
390
391 /**
392 * Returns a view of the portion of this sequence between the specified
393 * {@code start}, inclusive, and {@code end}, exclusive. (If {@code start}
394 * and {@code end} are equal, the returned sequence has the length zero.) The
395 * returned sequence is backed by this sequence, so non-structural changes in the
396 * returned sequence are reflected in this array, and vice-versa.
397 * <p/>
398 * This method eliminates the need for explicit range operations (of the
399 * sort that commonly exist for arrays). Any operation that expects an array
400 * can be used as a range operation by passing an sub sequence view instead of
401 * an whole sequence.
402 *
403 * @param start low end point (inclusive) of the sub sequence.
404 * @param end high end point (exclusive) of the sub sequence.
405 * @return a view of the specified range within this sequence.
406 * @throws IndexOutOfBoundsException for an illegal end point index value
407 * ({@code start < 0 || end > length() || start > end}).
408 */
409 public Seq<T> subSeq(final int start, final int end);
410
411 /**
412 * Returns the hash code value for this sequence. The hash code is defined
413 * as followed:
414 *
415 * [code]
416 * int hashCode = 1;
417 * final Iterator<E> it = seq.iterator();
418 * while (it.hasNext()) {
419 * final E obj = it.next();
420 * hashCode = 31*hashCode + (obj == null ? 0 : obj.hashCode());
421 * }
422 * [/code]
423 *
424 * @see List#hashCode()
425 *
426 * @return the hash code value for this list
427 */
428 @Override
429 public int hashCode();
430
431 /**
432 * Compares the specified object with this sequence for equality. Returns
433 * true if and only if the specified object is also a sequence, both
434 * sequence have the same size, and all corresponding pairs of elements in
435 * the two sequences are equal. (Two elements e1 and e2 are equal if
436 * (e1==null ? e2==null : e1.equals(e2)).) This definition ensures that the
437 * equals method works properly across different implementations of the Seq
438 * interface.
439 *
440 * @see List#equals(Object)
441 *
442 * @param object the object to be compared for equality with this sequence.
443 * @return {@code true} if the specified object is equal to this sequence,
444 * {@code false} otherwise.
445 */
446 @Override
447 public boolean equals(final Object object);
448
449 /**
450 * Create a string representation of the given sequence.
451 *
452 * @param prefix the prefix of the string representation; e.g {@code '['}.
453 * @param separator the separator of the array elements; e.g. {@code ','}.
454 * @param suffix the suffix of the string representation; e.g. {@code ']'}.
455 * @return the string representation of this sequence.
456 */
457 public String toString(
458 final String prefix, final String separator, final String suffix
459 );
460
461 /**
462 * Create a string representation of the given sequence.
463 *
464 * @param separator the separator of the array elements; e.g. {@code ','}.
465 * @return the string representation of this sequence.
466 */
467 public String toString(final String separator);
468
469 }
470
471
472
473
474
|