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