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