Seq.java
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 &mdash; <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 }