Type Parameters:: T - the entity type of the sequence

All Superinterfaces:: Collection<T>, Foldable<T>, java.lang.Iterable<T>, List<T>, java.io.Serializable, Streamable<T>, Traversable<T>, Value<T>

public interface Sequence<T>
extends List<T>

Sequences are ordered collections of elements. These collections allow for appending duplicate entries, but all entries will always be returned in the order that they were added or inserted.

Creating a new sequence can be achieved by using the on of the following operations:

**Single change operations**
Operation	Description
append(Object)	Add element to end of the sequence
prepend(Object)	Add elements to start of the sequence
insert(int, Object)	Add an element to the indicated place
remove(Object)	Remove the element
remove(int)	Remove the element at the indicated place

**Collection operations**
Operation	Description
union(Iterable)	Combine this sequence of elements with the provided iterable
reject(Predicate)	Create a new sequence without the rejected values matching the predicate
filter(Predicate)	Create a new sequence with values matching the predicate
map(Function)	Create a new sequence with the mapped values
distinct()	Create a set with only unique elements

Note: all operation that alter the contents of the sequence will return a new instance.

Method Summary

All Methods Instance Methods Abstract Methods Default Methods
Modifier and Type	Method	Description
`default Sequence<T>`	`append(T value)`	Create a new list containing all elements in this instance and appending the provided `value` to the end of the new list.
`Set<T>`	`distinct()`	Generate a new set containing only unique elements from this collection.
`Set<T>`	`distinctBy(java.util.Comparator<T> comparator)`	Creates a distinct list based upon the provided comparator.
`Sequence<T>`	`filter(java.util.function.Predicate<T> predicate)`	Filter out an element if it does not match the supplied `predicate`.
`<K> Map<K,? extends Sequence<T>>`	`groupBy(java.util.function.Function<? super T,? extends K> keyGenerator)`	Generate a new sequence using the `keyGenerator`.
`default T`	`head()`	Fetch the head of the collection and return it.
`Sequence<T>`	`insert(int index, T value)`	Add an element to the list at the provided index, shifting all elements after the index one.
`<U> Sequence<U>`	`map(java.util.function.Function<T,U> mapper)`	Perform a mapping operation on the elements in the stream.
`default Sequence<T>`	`orElse(java.lang.Iterable<? extends T> other)`	Returns either `this` if it is non empty, otherwise will return the provided `other`.
`default Sequence<T>`	`orElse(java.util.function.Supplier<? extends java.lang.Iterable<? extends T>> supplier)`	Returns either `this` if it is non empty, otherwise the provided supplier is evaluated and returned.
`default Sequence<T>`	`prepend(T value)`	Create a new sequence with the provided `value` at position 0 and the remainder of this sequence from position 1 to Collection.size() + 1.
`default Sequence<T>`	`reject(java.util.function.Predicate<T> predicate)`	Return a list that removes all elements that match the `predicate` provided.
`Sequence<T>`	`remove(int index)`	Removes an element from the list and returns a new instance of the list.
`default Sequence<T>`	`remove(T value)`	Removes the first element found matching the provided value.
`Sequence<T>`	`reverse()`	Reverse the order of the elements in the sequence.
`Sequence<T>`	`sorted()`	Sorts the specified array of objects into ascending order, according to the natural ordering of its elements.
`default Pair<? extends Sequence<T>,? extends Sequence<T>>`	`split(java.util.function.Predicate<T> predicate)`	The split operation is an execution that combines the `Collection.reject(Predicate)` and the `Collection.filter(Predicate)` methods into one.
`Sequence<T>`	`tail()`	Build a new collection with all elements except for the head.
`java.util.List<T>`	`toJava()`	Transform this collection into one supported natively in Java.
`Sequence<T>`	`union(java.lang.Iterable<T> iterable)`	Create a new sequence with all elements of this sequence combined with the elements of the provided iterable.

Methods inherited from interface com.jongsoft.lang.collection.Collection
containsAll, count, first, foldLeft, foldRight, get, isEmpty, isSingleValued, last, reduceLeft, size, summing

Methods inherited from interface com.jongsoft.lang.collection.Foldable
fold, reduce

Methods inherited from interface java.lang.Iterable
forEach, spliterator

Methods inherited from interface com.jongsoft.lang.collection.List
firstIndexWhere, get, indexOf, median, pipeline

Methods inherited from interface com.jongsoft.lang.collection.Traversable
average, iterator, sum

Methods inherited from interface com.jongsoft.lang.Value
all, contains, exists, none, stream

- Method Detail
  - append
```
default Sequence<T> append(T value)
```
    Description copied from interface: List
    Create a new list containing all elements in this instance and appending the provided value to the end of the new list.
    Example:
    
    // will result in a list with 2, 3, 4, 1 List(2, 3, 4).append(1)
    Specified by:
    
    append in interface List<T>
    
    Parameters:
    
    value - the value to append to the list
    
    Returns:
    
    the new list with the value appended
  - prepend
```
default Sequence<T> prepend(T value)
```
    Create a new sequence with the provided value at position 0 and the remainder of this sequence from position 1 to Collection.size() + 1.
    Example:
    
    // will result in a sequence with 1, 2, 3, 4 Sequence(2, 3, 4).prepend(1)
    Parameters:
    
    value - the value to be added
    
    Returns:
    
    the new list with the value appended
  - insert
```
Sequence<T> insert(int index,
                   T value)
```
    Add an element to the list at the provided index, shifting all elements after the index one.
    
    Parameters:
    
    index - the index at which to insert the element
    
    value - the element to insert
    
    Returns:
    
    the updated list with the inserted element
  - remove
```
Sequence<T> remove(int index)
```
    Description copied from interface: List
    
    Removes an element from the list and returns a new instance of the list.
    
    Specified by:
    
    remove in interface List<T>
    
    Parameters:
    
    index - the index of the element to be removed
    
    Returns:
    
    the new instance of the list without the element at the provided index
  - remove
```
default Sequence<T> remove(T value)
```
    Removes the first element found matching the provided value. The match is done based upon the Objects.equals(Object, Object) call.
    
    Parameters:
    
    value - the element to be removed
    
    Returns:
    
    the current list if the element is not present, otherwise a new list instance without the element in it.
  - head
```
default T head()
```
    Description copied from interface: Collection
    Fetch the head of the collection and return it. The following operations will all return the same value for a non empty collection.
    Collection(0, 1).get(); Collection(0, 1).head();
    The caller must verify the collection is not empty using either Collection.size() or Collection.isEmpty() to prevent a NoSuchElementException to be thrown.
    Specified by:
    
    head in interface Collection<T>
    
    Returns:
    
    the first element in the collection
  - tail
```
Sequence<T> tail()
```
    Description copied from interface: Collection
    
    Build a new collection with all elements except for the head. If there is only one element present then an empty collection will be returned. If the operation is called on an empty collection an NoSuchElementException will be thrown.
    
    Specified by:
    
    tail in interface Collection<T>
    
    Specified by:
    
    tail in interface List<T>
    
    Returns:
    
    a collection containing the tail
  - reverse
```
Sequence<T> reverse()
```
    Reverse the order of the elements in the sequence.
    
    Returns:
    
    the reversed sequence
  - filter
```
Sequence<T> filter(java.util.function.Predicate<T> predicate)
```
    Description copied from interface: Streamable
    
    Filter out an element if it does not match the supplied predicate. This operation will iterate over all elements and return a new set containing only the elements where the predicate returns true for.
    
    Specified by:
    
    filter in interface Collection<T>
    
    Specified by:
    
    filter in interface List<T>
    
    Specified by:
    
    filter in interface Streamable<T>
    
    Specified by:
    
    filter in interface Traversable<T>
    
    Parameters:
    
    predicate - the predicate to apply to the contents of this
    
    Returns:
    
    the filtered value
  - groupBy
```
<K> Map<K,? extends Sequence<T>> groupBy(java.util.function.Function<? super T,? extends K> keyGenerator)
```
    Description copied from interface: List
    Generate a new sequence using the keyGenerator. Calling this operation will create a new map grouping the elements by the generator provided.
    Example:
    
    // This will result in Map(1 -> List(1, 11, 21), 2 -> List(2, 12, 22)) Sequence(1, 2, 11, 12, 21, 22) .groupBy(x -> x % 10);
    Specified by:
    
    groupBy in interface List<T>
    
    Type Parameters:
    
    K - the type of the key
    
    Parameters:
    
    keyGenerator - the generator to use for creating keys
    
    Returns:
    
    the new map created using the generator
  - reject
```
default Sequence<T> reject(java.util.function.Predicate<T> predicate)
```
    Description copied from interface: Traversable
    
    Return a list that removes all elements that match the predicate provided.
    
    Specified by:
    
    reject in interface Collection<T>
    
    Specified by:
    
    reject in interface List<T>
    
    Specified by:
    
    reject in interface Traversable<T>
    
    Parameters:
    
    predicate - the predicate to use
    
    Returns:
    
    the elements that do not match the predicate
  - split
```
default Pair<? extends Sequence<T>,? extends Sequence<T>> split(java.util.function.Predicate<T> predicate)
```
    Description copied from interface: Collection
    
    The split operation is an execution that combines the Collection.reject(Predicate) and the Collection.filter(Predicate) methods into one. Separating the values into 2 separate buckets. The first bucket will contain the same as the Collection.filter(Predicate) operation. The second bucket will contain the result of the Collection.reject(Predicate) operation.
    
    Specified by:
    
    split in interface Collection<T>
    
    Parameters:
    
    predicate - the predicate to use
    
    Returns:
    
    the two buckets of this operation
  - distinct
```
Set<T> distinct()
```
    Generate a new set containing only unique elements from this collection. As identified by their Object.hashCode().
    
    Returns:
    
    a set with unique elements
  - distinctBy
```
Set<T> distinctBy(java.util.Comparator<T> comparator)
```
    Description copied from interface: List
    
    Creates a distinct list based upon the provided comparator. If a duplicate is found only the first match will be included in the returned list.
    
    Specified by:
    
    distinctBy in interface List<T>
    
    Parameters:
    
    comparator - the comparator to use for distinct check
    
    Returns:
    
    the distinct list
  - map
```
<U> Sequence<U> map(java.util.function.Function<T,U> mapper)
```
    Description copied from interface: Streamable
    
    Perform a mapping operation on the elements in the stream.
    This operation will loop over all elements in the stream and apply the mapper method. The mapped values will be returned in as a new stream of elements.
    
    Specified by:
    
    map in interface Collection<T>
    
    Specified by:
    
    map in interface List<T>
    
    Specified by:
    
    map in interface Streamable<T>
    
    Specified by:
    
    map in interface Traversable<T>
    
    Type Parameters:
    
    U - the type of object expected as a result
    
    Parameters:
    
    mapper - the mapping functionality
    
    Returns:
    
    the mapped object
  - orElse
```
default Sequence<T> orElse(java.lang.Iterable<? extends T> other)
```
    Description copied from interface: Traversable
    
    Returns either this if it is non empty, otherwise will return the provided other.
    
    Specified by:
    
    orElse in interface Collection<T>
    
    Specified by:
    
    orElse in interface List<T>
    
    Specified by:
    
    orElse in interface Traversable<T>
    
    Parameters:
    
    other - the alternative
    
    Returns:
    
    this Traversable if non empty, or other
  - orElse
```
default Sequence<T> orElse(java.util.function.Supplier<? extends java.lang.Iterable<? extends T>> supplier)
```
    Description copied from interface: Traversable
    
    Returns either this if it is non empty, otherwise the provided supplier is evaluated and returned.
    
    Specified by:
    
    orElse in interface Collection<T>
    
    Specified by:
    
    orElse in interface List<T>
    
    Specified by:
    
    orElse in interface Traversable<T>
    
    Parameters:
    
    supplier - the supplier to generate the other
    
    Returns:
    
    this (@code Traversable} if non empty, otherwise other
  - toJava
```
java.util.List<T> toJava()
```
    Transform this collection into one supported natively in Java.
    
    Returns:
    
    the native java collection
  - sorted
```
Sequence<T> sorted()
```
    Description copied from interface: List
    
    Sorts the specified array of objects into ascending order, according to the natural ordering of its elements. All elements in the array must implement the Comparable interface. Furthermore, all elements in the array must be mutually comparable (that is, e1.compareTo(e2) must not throw a ClassCastException for any elements e1 and e2 in the array).
    This sort is guaranteed to be stable: equal elements will not be reordered as a result of the sort. Implementation note: This implementation is a stable, adaptive, iterative mergesort that requires far fewer than n lg(n) comparisons when the input array is partially sorted, while offering the performance of a traditional mergesort when the input array is randomly ordered. If the input array is nearly sorted, the implementation requires approximately n comparisons. Temporary storage requirements vary from a small constant for nearly sorted input arrays to n/2 object references for randomly ordered input arrays.
    The implementation takes equal advantage of ascending and descending order in its input array, and can take advantage of ascending and descending order in different parts of the same input array. It is well-suited to merging two or more sorted arrays: simply concatenate the arrays and sort the resulting array.
    
    Specified by:
    
    sorted in interface List<T>
    
    Returns:
    
    the sorted set
  - union
```
Sequence<T> union(java.lang.Iterable<T> iterable)
```
    Description copied from interface: List
    Create a new sequence with all elements of this sequence combined with the elements of the provided iterable. The elements in this sequence will be added before the provided iterable in the returned sequence.
    Example:
    
    // the example would be a List(1, 2, 3, 4) List<Integer> result = List(1, 2).union(List(3, 4));
    Specified by:
    
    union in interface List<T>
    
    Parameters:
    
    iterable - the elements to be added
    
    Returns:
    
    the new list containing a union between this and the iterable

Interface Sequence<T>

Method Summary

Methods inherited from interface com.jongsoft.lang.collection.Collection

Methods inherited from interface com.jongsoft.lang.collection.Foldable

Methods inherited from interface java.lang.Iterable

Methods inherited from interface com.jongsoft.lang.collection.List

Methods inherited from interface com.jongsoft.lang.collection.Traversable

Methods inherited from interface com.jongsoft.lang.Value

Method Detail

append

prepend

insert

remove

remove

head

tail

reverse

filter

groupBy

reject

split

distinct

distinctBy

map

orElse

orElse

toJava

sorted

union