Seq.java
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 &mdash; <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 &lt; 0 || index &gt;= 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&lt;E&gt; 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 }