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