org.jenetics.util

Interface Seq<T>

All Superinterfaces:

Iterable<T>

All Known Subinterfaces:

ISeq<T>, MSeq<T>

All Known Implementing Classes:

ArrayProxyISeq, ArrayProxySeq, CharSeq

public interface Seq<T>
extends Iterable<T>

General interface for a ordered, fixed sized, object sequence.
Use the asList() method to work together with the Java Collection Framework.

Since:

1.0

Version:

3.0 — $Date: 2014-12-28 $

Author:

Franz Wilhelmstötter

Method Summary

Modifier and Type	Method and Description
List<T>	asList() Returns a fixed-size list backed by the specified sequence.
default boolean	contains(Object element) Returns true if this sequence contains the specified element.
boolean	equals(Object object) Compares the specified object with this sequence for equality.
static boolean	equals(Seq<?> seq, Object obj) Unified method for compare to sequences for equality.
default boolean	forAll(Predicate<? super T> predicate) Tests whether a predicate holds for all elements of this sequence.
T	get(int index) Return the value at the given index.
int	hashCode() Returns the hash code value for this sequence.
static int	hashCode(Seq<?> seq) Unified method for calculating the hash code of every Seq implementation.
default int	indexOf(Object element) Returns the index of the first occurrence of the specified element in this sequence, or -1 if this sequence does not contain the element.
default int	indexOf(Object element, int start) Returns the index of the first occurrence of the specified element in this sequence, or -1 if this sequence does not contain the element.
default int	indexOf(Object element, int start, int end) Returns the index of the first occurrence of the specified element in this sequence, or -1 if this sequence does not contain the element.
default int	indexWhere(Predicate<? super T> predicate) Returns the index of the first element on which the given predicate returns true, or -1 if the predicate returns false for every sequence element.
default int	indexWhere(Predicate<? super T> predicate, int start) Returns the index of the first element on which the given predicate returns true, or -1 if the predicate returns false for every sequence element.
default int	indexWhere(Predicate<? super T> predicate, int start, int end) Returns the index of the first element on which the given predicate returns true, or -1 if the predicate returns false for every sequence element.
default boolean	isSorted() Test whether the given array is sorted in ascending order.
default boolean	isSorted(Comparator<? super T> comparator) Test whether the given array is sorted in ascending order.
default int	lastIndexOf(Object element) Returns the index of the last occurrence of the specified element in this sequence, or -1 if this sequence does not contain the element.
default int	lastIndexOf(Object element, int end) Returns the index of the last occurrence of the specified element in this sequence, or -1 if this sequence does not contain the element.
default int	lastIndexOf(Object element, int start, int end) Returns the index of the last occurrence of the specified element in this sequence, or -1 if this sequence does not contain the element.
default int	lastIndexWhere(Predicate<? super T> predicate) Returns the index of the last element on which the given predicate returns true, or -1 if the predicate returns false for every sequence element.
default int	lastIndexWhere(Predicate<? super T> predicate, int end) Returns the index of the last element on which the given predicate returns true, or -1 if the predicate returns false for every sequence element.
default int	lastIndexWhere(Predicate<? super T> predicate, int start, int end) Returns the index of the last element on which the given predicate returns true, or -1 if the predicate returns false for every sequence element.
int	length() Return the length of this sequence.
<B> Seq<B>	map(Function<? super T,? extends B> mapper) Builds a new sequence by applying a function to all elements of this sequence.
static <T> Seq<T>	of(Iterable<? extends T> values) Create a new Seq from the given values.
static <T> Seq<T>	of(T... values) Create a new Seq from the given values.
default Stream<T>	parallelStream() Returns a possibly parallel Stream with this sequence as its source.
default int	size()
default Spliterator<T>	spliterator()
default Stream<T>	stream() Returns a sequential Stream with this sequence as its source.
Seq<T>	subSeq(int start) Returns a view of the portion of this sequence between the specified start, inclusive, and end, exclusive.
Seq<T>	subSeq(int start, int end) Returns a view of the portion of this sequence between the specified start, inclusive, and end, exclusive.
default Object[]	toArray() Return an array containing all of the elements in this sequence in right order.
default T[]	toArray(T[] array) Return an array containing all of the elements in this sequence in right order; the runtime type of the returned array is that of the specified array.
static <T> Collector<T,?,Seq<T>>	toSeq() Returns a Collector that accumulates the input elements into a new Seq.
default String	toString(String separator) Create a string representation of the given sequence.
default String	toString(String prefix, String separator, String suffix) Create a string representation of the given sequence.

Methods inherited from interface java.lang.Iterable

forEach, iterator

Method Detail

get

T get(int index)

Return the value at the given index.

Parameters:

index - index of the element to return.

Returns:

the value at the given index.

Throws:

IndexOutOfBoundsException - if the index is out of range (index < 0 || index >= size()).

length

int length()

Return the length of this sequence. Once the sequence is created, the length can't be changed.

Returns:

the length of this sequence.

size

default int size()

Returns:

the size of this sequence

See Also:

length()

forAll

default boolean forAll(Predicate<? super T> predicate)

Tests whether a predicate holds for all elements of this sequence.

Parameters:

predicate - the predicate to use to test the elements.

Returns:

true if the given predicate p holds for all elements of this sequence, false otherwise.

Throws:

NullPointerException - if the given predicate is null.

stream

default Stream<T> stream()

Returns a sequential Stream with this sequence as its source.

Returns:

a sequential Stream over the elements in this sequence

Since:

3.0

parallelStream

default Stream<T> parallelStream()

Returns a possibly parallel Stream with this sequence as its source. It is allowable for this method to return a sequential stream.

Returns:

a possibly parallel Stream over the elements in this collection

Since:

3.0

spliterator

default Spliterator<T> spliterator()

Specified by:

spliterator in interface Iterable<T>

contains

default boolean contains(Object element)

Returns true if this sequence contains the specified element.

Parameters:

element - element whose presence in this sequence is to be tested. The tested element can be null.

Returns:

true if this sequence contains the specified element

indexOf

default int indexOf(Object element)

Returns the index of the first occurrence of the specified element in this sequence, or -1 if this sequence does not contain the element.

Parameters:

element - element to search for, can be null

Returns:

the index of the first occurrence of the specified element in this sequence, or -1 if this sequence does not contain the element

indexOf

default int indexOf(Object element,
                    int start)

Returns the index of the first occurrence of the specified element in this sequence, or -1 if this sequence does not contain the element.

Parameters:

element - element to search for, can be null

start - the start index (inclusively) for the element search.

Returns:

the index of the first occurrence of the specified element in this sequence, or -1 if this sequence does not contain the element

Throws:

IndexOutOfBoundsException - for an illegal end point index value (start < 0 || start > length()).

indexOf

default int indexOf(Object element,
                    int start,
                    int end)

Returns the index of the first occurrence of the specified element in this sequence, or -1 if this sequence does not contain the element.

Parameters:

element - element to search for, can be null

start - the start index (inclusively) for the element search.

end - the end index (exclusively) for the element search.

Returns:

the index of the first occurrence of the specified element in this sequence, or -1 if this sequence does not contain the element

Throws:

IndexOutOfBoundsException - for an illegal end point index value (start < 0 || end > length() || start > end).

indexWhere

default int indexWhere(Predicate<? super T> predicate)

Returns the index of the first element on which the given predicate returns true, or -1 if the predicate returns false for every sequence element.

// Finding index of first null value. final int index = seq.indexOf(o -> o == null); // Assert of no null values. assert (sequence.indexOf(o -> o == null) == -1);

Parameters:

predicate - the search predicate.

Returns:

the index of the first element on which the given predicate returns true, or -1 if the predicate returns false for every sequence element.

Throws:

NullPointerException - if the given predicate is null.

indexWhere

default int indexWhere(Predicate<? super T> predicate,
                       int start)

Returns the index of the first element on which the given predicate returns true, or -1 if the predicate returns false for every sequence element.

// Finding index of first null value. final int index = seq.indexOf(o -> o == null); // Assert of no null values. assert (sequence.indexOf(o -> o == null) == -1);

Parameters:

predicate - the search predicate.

start - the search start index

Returns:

the index of the first element on which the given predicate returns true, or -1 if the predicate returns false for every sequence element.

Throws:

NullPointerException - if the given predicate is null.

IndexOutOfBoundsException - for an illegal end point index value (start < 0 || start > length()).

indexWhere

default int indexWhere(Predicate<? super T> predicate,
                       int start,
                       int end)

Returns the index of the first element on which the given predicate returns true, or -1 if the predicate returns false for every sequence element.

// Finding index of first null value. final int index = seq.indexOf(o -> o == null); // Assert of no null values. assert (sequence.indexOf(o -> o == null) == -1);

Parameters:

predicate - the search predicate.

start - the search start index

end - the search end index

Returns:

the index of the first element on which the given predicate returns true, or -1 if the predicate returns false for every sequence element.

Throws:

NullPointerException - if the given predicate is null.

IndexOutOfBoundsException - for an illegal end point index value (start < 0 || end > length() || start > end).

lastIndexOf

default int lastIndexOf(Object element)

Returns the index of the last occurrence of the specified element in this sequence, or -1 if this sequence does not contain the element.

Parameters:

element - element to search for, can be null

Returns:

the index of the last occurrence of the specified element in this sequence, or -1 if this sequence does not contain the element

lastIndexOf

default int lastIndexOf(Object element,
                        int end)

Returns the index of the last occurrence of the specified element in this sequence, or -1 if this sequence does not contain the element.

Parameters:

element - element to search for, can be null

end - the search end index

Returns:

the index of the last occurrence of the specified element in this sequence, or -1 if this sequence does not contain the element

Throws:

IndexOutOfBoundsException - for an illegal end point index value (end < 0 || end > length()).

lastIndexOf

default int lastIndexOf(Object element,
                        int start,
                        int end)

Returns the index of the last occurrence of the specified element in this sequence, or -1 if this sequence does not contain the element.

Parameters:

element - element to search for, can be null

start - the search start index

end - the search end index

Returns:

the index of the last occurrence of the specified element in this sequence, or -1 if this sequence does not contain the element

Throws:

IndexOutOfBoundsException - for an illegal end point index value (start < 0 || end > length() || start > end).

lastIndexWhere

default int lastIndexWhere(Predicate<? super T> predicate)

Returns the index of the last element on which the given predicate returns true, or -1 if the predicate returns false for every sequence element.

Parameters:

predicate - the search predicate.

Returns:

the index of the last element on which the given predicate returns true, or -1 if the predicate returns false for every sequence element.

Throws:

NullPointerException - if the given predicate is null.

lastIndexWhere

default int lastIndexWhere(Predicate<? super T> predicate,
                           int end)

Returns the index of the last element on which the given predicate returns true, or -1 if the predicate returns false for every sequence element.

Parameters:

predicate - the search predicate.

end - the search end index

Returns:

the index of the last element on which the given predicate returns true, or -1 if the predicate returns false for every sequence element.

Throws:

NullPointerException - if the given predicate is null.

IndexOutOfBoundsException - for an illegal end point index value (end < 0 || end > length()).

lastIndexWhere

default int lastIndexWhere(Predicate<? super T> predicate,
                           int start,
                           int end)

Returns the index of the last element on which the given predicate returns true, or -1 if the predicate returns false for every sequence element.

Parameters:

predicate - the search predicate.

start - the search start index

end - the search end index

Returns:

the index of the last element on which the given predicate returns true, or -1 if the predicate returns false for every sequence element.

Throws:

NullPointerException - if the given predicate is null.

IndexOutOfBoundsException - for an illegal end point index value (start < 0 || end > length() || start > end).

asList

List<T> asList()

Returns a fixed-size list backed by the specified sequence. (Changes to the returned list "write through" to the array.) The returned list is fixed size, serializable and implements RandomAccess.

Returns:

a list view of this sequence

map

<B> Seq<B> map(Function<? super T,? extends B> mapper)

Builds a new sequence by applying a function to all elements of this sequence.

Type Parameters:

B - the element type of the returned collection.

Parameters:

mapper - the function to apply to each element.

Returns:

a new sequence of type That resulting from applying the given function f to each element of this sequence and collecting the results.

Throws:

NullPointerException - if the element mapper is null.

toArray

default Object[] toArray()

Return an array containing all of the elements in this sequence in right order. The returned array will be "safe" in that no references to it are maintained by this sequence. (In other words, this method must allocate a new array.) The caller is thus free to modify the returned array.

Returns:

an array containing all of the elements in this list in right order

See Also:

Collection.toArray()

toArray

default T[] toArray(T[] array)

Return an array containing all of the elements in this sequence in right order; the runtime type of the returned array is that of the specified array. If this sequence fits in the specified array, it is returned therein. Otherwise, a new array is allocated with the runtime type of the specified array and the length of this array.

If this sequence fits in the specified array with room to spare (i.e., the array has more elements than this array), the element in the array immediately following the end of this array is set to null. (This is useful in determining the length of the array only if the caller knows that the list does not contain any null elements.)

Parameters:

array - the array into which the elements of this array are to be stored, if it is big enough; otherwise, a new array of the same runtime type is allocated for this purpose.

Returns:

an array containing the elements of this array

Throws:

ArrayStoreException - if the runtime type of the specified array is not a super type of the runtime type of every element in this array

NullPointerException - if the given array is null.

See Also:

Collection.toArray(Object[])

subSeq

Seq<T> subSeq(int start)

Returns a view of the portion of this sequence between the specified start, inclusive, and end, exclusive. (If start and end are equal, the returned sequence has the length zero.) The returned sequence is backed by this sequence, so non-structural changes in the returned sequence are reflected in this sequence, and vice-versa.

This method eliminates the need for explicit range operations (of the populationSort that commonly exist for arrays). Any operation that expects an sequence can be used as a range operation by passing an sub sequence view instead of an whole sequence.

Parameters:

start - low end point (inclusive) of the sub array.

Returns:

a view of the specified range within this array.

Throws:

IndexOutOfBoundsException - for an illegal end point index value (start < 0 || start > length()).

subSeq

Seq<T> subSeq(int start,
              int end)

Returns a view of the portion of this sequence between the specified start, inclusive, and end, exclusive. (If start and end are equal, the returned sequence has the length zero.) The returned sequence is backed by this sequence, so non-structural changes in the returned sequence are reflected in this array, and vice-versa.

This method eliminates the need for explicit range operations (of the populationSort that commonly exist for arrays). Any operation that expects an array can be used as a range operation by passing an sub sequence view instead of an whole sequence.

Parameters:

start - low end point (inclusive) of the sub sequence.

end - high end point (exclusive) of the sub sequence.

Returns:

a view of the specified range within this sequence.

Throws:

IndexOutOfBoundsException - for an illegal end point index value (start < 0 || end > length() || start > end).

isSorted

default boolean isSorted()

Test whether the given array is sorted in ascending order.

Returns:

true if the given array is sorted in ascending order, false otherwise.

Throws:

NullPointerException - if the given array or one of it's element is null.

isSorted

default boolean isSorted(Comparator<? super T> comparator)

Test whether the given array is sorted in ascending order. The order of the array elements is defined by the given comparator.

Parameters:

comparator - the comparator which defines the order.

Returns:

true if the given array is sorted in ascending order, false otherwise.

Throws:

NullPointerException - if the given array or one of it's element or the comparator is null.

hashCode

int hashCode()

Returns the hash code value for this sequence. The hash code is defined as followed:

int hashCode = 1; final Iterator<E> it = seq.iterator(); while (it.hasNext()) { final E obj = it.next(); hashCode = 31*hashCode + (obj == null ? 0 : obj.hashCode()); }

Overrides:

hashCode in class Object

Returns:

the hash code value for this list

See Also:

List.hashCode(), hashCode(Seq)

equals

boolean equals(Object object)

Compares the specified object with this sequence for equality. Returns true if and only if the specified object is also a sequence, both sequence have the same size, and all corresponding pairs of elements in the two sequences are equal. (Two elements e1 and e2 are equal if (e1==null ? e2==null : e1.equals(e2)).) This definition ensures that the equals method works properly across different implementations of the Seq interface.

Overrides:

equals in class Object

Parameters:

object - the object to be compared for equality with this sequence.

Returns:

true if the specified object is equal to this sequence, false otherwise.

See Also:

List.equals(Object), equals(Seq, Object)

toString

default String toString(String prefix,
                        String separator,
                        String suffix)

Create a string representation of the given sequence.

Parameters:

prefix - the prefix of the string representation; e.g '['.

separator - the separator of the array elements; e.g. ','.

suffix - the suffix of the string representation; e.g. ']'.

Returns:

the string representation of this sequence.

toString

default String toString(String separator)

Create a string representation of the given sequence.

Parameters:

separator - the separator of the array elements; e.g. ','.

Returns:

the string representation of this sequence.

hashCode

static int hashCode(Seq<?> seq)

Unified method for calculating the hash code of every Seq implementation. The hash code is defined as followed:

int hashCode = 1; final Iterator<E> it = seq.iterator(); while (it.hasNext()) { final E obj = it.next(); hashCode = 31*hashCode + (obj == null ? 0 : obj.hashCode()); }

Parameters:

seq - the sequence to calculate the hash code for.

Returns:

the hash code of the given sequence.

See Also:

hashCode(), List.hashCode()

equals

static boolean equals(Seq<?> seq,
                      Object obj)

Unified method for compare to sequences for equality.

Parameters:

seq - the sequence to test for equality.

obj - the object to test for equality with the sequence.

Returns:

true if the given objects are sequences and contain the same objects in the same order, false otherwise.

See Also:

equals(Object)

toSeq

static <T> Collector<T,?,Seq<T>> toSeq()

Returns a Collector that accumulates the input elements into a new Seq.

Type Parameters:

T - the type of the input elements

Returns:

a Collector which collects all the input elements into a Seq, in encounter order

of

@SafeVarargs
static <T> Seq<T> of(T... values)

Create a new Seq from the given values.

Type Parameters:

T - the element type

Parameters:

values - the array values.

Returns:

a new Seq with the given values.

Throws:

NullPointerException - if the values array is null.

of

static <T> Seq<T> of(Iterable<? extends T> values)

Create a new Seq from the given values.

Type Parameters:

T - the element type

Parameters:

values - the array values.

Returns:

a new Seq with the given values.

Throws:

NullPointerException - if the values array is null.