net.markenwerk.commons.collections.sequences

Interface Sequence<Payload>

Type Parameters:

Payload - The payload type

All Superinterfaces:

BidirectionalIterable<Payload>, IndexedSource<Payload>, Iterable<Payload>, ProtectedBidirectionalIterable<Payload>, ProtectedIterable<Payload>, Source<Payload>

All Known Implementing Classes:

AbstractListSequence, AbstractSequence, ListSequence

public interface Sequence<Payload>
extends IndexedSource<Payload>

A Sequence is a linear data structure.

Since:

1.0.0

Author:

Torsten Krause (tk at markenwerk dot net)

Method Summary

Modifier and Type	Method and Description
Sequence<Payload>	append(Payload payload) Appends the given payload value.
Sequence<Payload>	appendAll(Iterable<? extends Payload> payloads) Appends the given payload values.
Sequence<Payload>	appendAll(Payload... payloads) Appends the given payload values.
Source<Payload>	clear() Removes all payload values.
boolean	equals(Object object) Compares the given object with this Sequence for equality.
int	hashCode() Returns the hash code of this Sequence.
Sequence<Payload>	insert(int index, Payload payload) Inserts the given payload value at the given index.
Sequence<Payload>	insertAll(int index, Iterable<? extends Payload> payloads) Inserts the given payload values starting at the given index.
Sequence<Payload>	insertAll(int index, Payload... payloads) Inserts the given payload values starting at the given index.
Sequence<Payload>	prepend(Payload payload) Prepends the given payload value.
Sequence<Payload>	prependAll(Iterable<? extends Payload> payloads) Prepends the given payload values.
Sequence<Payload>	prependAll(Payload... payloads) Prepends the given payload values.
Payload	remove(int index) Removes the payload value at the given index.
Source<Payload>	removeAll(Payload reference) Removes all occurrences, by equality, of the given reference payload value.
Source<Payload>	removeAllMatches(Predicate<? super Payload> predicate) Removes the payload values that satisfy the given Predicate.
Payload	removeFirst() Removes the first payload value.
Optional<Payload>	removeFirst(Payload reference) Removes the first occurrence, by equality, of the given reference payload value.
Optional<Payload>	removeFirstMatch(Predicate<? super Payload> predicate) Removes the first payload value that satisfies the given Predicate
Payload	removeLast() Removes the last payload value.
Optional<Payload>	removeLast(Payload reference) Removes the last occurrence, by equality, of the given payload value.
Optional<Payload>	removeLastMatch(Predicate<? super Payload> predicate) Removes the last payload value that satisfies the given Predicate
Payload	replace(int index, Payload replacement) Replaces the payload value at the given index with the given replacement payload value.
Source<Payload>	replaceAll(Payload reference, Provider<? extends Payload> provider) Replaces all occurrences of the the given reference payload value with payload values yielded by the given Provider.
Source<Payload>	replaceAllMatches(Predicate<? super Payload> predicate, Provider<? extends Payload> provider) Replaces all payload values that satisfy the given Predicate with payload values yielded by the given Provider.
Payload	replaceFirst(Payload replacement) Replaces the first payload value with the given replacement payload value.
Optional<Payload>	replaceFirst(Payload reference, Payload replacement) Replaces the first occurrence of the given reference payload value with the given replacement payload value.
Optional<Payload>	replaceFirstMatch(Predicate<? super Payload> predicate, Payload replacement) Replaces the first payload value that satisfy the given Predicate with the given replacement payload value.
Payload	replaceLast(Payload replacement) Replaces the last payload value with the given replacement payload value.
Optional<Payload>	replaceLast(Payload reference, Payload replacement) Replaces last occurrence of the the given reference payload value with the given replacement payload value.
Optional<Payload>	replaceLastMatch(Predicate<? super Payload> predicate, Payload replacement) Replaces the last payload value that satisfy the given Predicate with the given replacement payload value.
Source<Payload>	retainAll(Payload reference) Removes all but the given payload value.
Source<Payload>	retainAllMatches(Predicate<? super Payload> predicate) Removes all but the payload values that satisfy the given Predicate.

Methods inherited from interface net.markenwerk.commons.collections.sources.IndexedSource

firstIndexOf, firstIndexOfMatch, get, getFirst, getFirst, getFirstMatch, getLast, getLast, getLastMatch, isFirst, isLast, iterator, lastIndexOf, lastIndexOfMatch

Methods inherited from interface net.markenwerk.commons.collections.sources.Source

contains, containsAll, containsAll, containsMatch, getAll, getAllMatches, isEmpty, size

Methods inherited from interface net.markenwerk.commons.iterables.ProtectedIterable

iterator

Methods inherited from interface net.markenwerk.commons.iterables.ProtectedBidirectionalIterable

iterator

Methods inherited from interface java.lang.Iterable

forEach, spliterator

Method Detail

insert

Sequence<Payload> insert(int index,
                         Payload payload)
                  throws IllegalArgumentException,
                         IndexOutOfBoundsException

Inserts the given payload value at the given index.

Parameters:

index - The index to be used.

payload - The payload value to be inserted.

Returns:

This Sequence.

Throws:

IllegalArgumentException - If the given payload value is null and this Sequence doesn't allow a null to be added.

IndexOutOfBoundsException - If the given index is negative or larger the the size of this Sequence

insertAll

Sequence<Payload> insertAll(int index,
                            Payload... payloads)
                     throws IllegalArgumentException,
                            IndexOutOfBoundsException

Inserts the given payload values starting at the given index.

Parameters:

index - The index to be used.

payloads - The array of payload values to be inserted.

Returns:

This Sequence.

Throws:

IllegalArgumentException - If the given array of payload values is null or if any of the given payload values is null and this Sequence doesn't allow a null to be added.

IndexOutOfBoundsException - If the given index is negative or larger the the size of this Sequence

insertAll

Sequence<Payload> insertAll(int index,
                            Iterable<? extends Payload> payloads)
                     throws IllegalArgumentException,
                            IndexOutOfBoundsException

Inserts the given payload values starting at the given index.

Parameters:

index - The index to be used.

payloads - The Iterable of payload values to be inserted.

Returns:

This Sequence.

Throws:

IllegalArgumentException - If the given Iterable of payload values is null or if any of the given payload values is null and this Sequence doesn't allow a null to be added.

IndexOutOfBoundsException - If the given index is negative or larger the the size of this Sequence

prepend

Sequence<Payload> prepend(Payload payload)
                   throws IllegalArgumentException

Prepends the given payload value.

Parameters:

payload - The payload value to be prepended.

Returns:

This Sequence.

Throws:

IllegalArgumentException - If the given payload value is null and this Sequence doesn't allow a null to be added.

prependAll

Sequence<Payload> prependAll(Payload... payloads)
                      throws IllegalArgumentException

Prepends the given payload values.

Parameters:

payloads - The array of payload values to be inserted.

Returns:

This Sequence.

Throws:

IllegalArgumentException - If the given array of payload values is null or if any of the given payload values is null and this Sequence doesn't allow a null to be added.

prependAll

Sequence<Payload> prependAll(Iterable<? extends Payload> payloads)
                      throws IllegalArgumentException

Prepends the given payload values.

Parameters:

payloads - The Iterable of payload values to be inserted.

Returns:

This Sequence.

Throws:

IllegalArgumentException - If the given Iterable of payload values is null or if any of the given payload values is null and this Sequence doesn't allow a null to be added.

append

Sequence<Payload> append(Payload payload)
                  throws IllegalArgumentException

Appends the given payload value.

Parameters:

payload - The payload value to be appended.

Returns:

This Sequence.

Throws:

IllegalArgumentException - If the given payload value is null and this Sequence doesn't allow a null to be added.

appendAll

Sequence<Payload> appendAll(Payload... payloads)
                     throws IllegalArgumentException

Appends the given payload values.

Parameters:

payloads - The array of payload values to be appended.

Returns:

This Sequence.

Throws:

IllegalArgumentException - If the given array of payload values is null or if any of the given payload values is null and this Sequence doesn't allow a null to be added.

appendAll

Sequence<Payload> appendAll(Iterable<? extends Payload> payloads)
                     throws IllegalArgumentException

Appends the given payload values.

Parameters:

payloads - The Iterable of payload values to be appended.

Returns:

This Sequence.

Throws:

IllegalArgumentException - If the given Iterable of payload values is null or if any of the given payload values is null and this Sequence doesn't allow a null to be added.

remove

Payload remove(int index)
        throws IndexOutOfBoundsException

Removes the payload value at the given index.

Parameters:

index - The index to be used.

Returns:

The payload value.

Throws:

IndexOutOfBoundsException - If the given index is negative or if the given index is larger or equal to the size of this Sequence.

removeFirst

Payload removeFirst()
             throws NoSuchElementException

Removes the first payload value.

Returns:

The payload value.

Throws:

NoSuchElementException - If this Sequence is empty.

removeFirst

Optional<Payload> removeFirst(Payload reference)

Removes the first occurrence, by equality, of the given reference payload value.

Parameters:

reference - The reference payload to be removed.

Returns:

An Optional yielding the removed payload value.

removeFirstMatch

Optional<Payload> removeFirstMatch(Predicate<? super Payload> predicate)
                            throws IllegalArgumentException

Removes the first payload value that satisfies the given Predicate

Parameters:

predicate - The Predicate to be used.

Returns:

An Optional yielding the removed payload value.

Throws:

IllegalArgumentException - If the given predicate is null.

removeLast

Payload removeLast()
            throws NoSuchElementException

Removes the last payload value.

Returns:

The payload value.

Throws:

NoSuchElementException - If this Sequence is empty.

removeLast

Optional<Payload> removeLast(Payload reference)

Removes the last occurrence, by equality, of the given payload value.

Parameters:

reference - The reference payload to be removed.

Returns:

An Optional yielding the removed payload value.

removeLastMatch

Optional<Payload> removeLastMatch(Predicate<? super Payload> predicate)
                           throws IllegalArgumentException

Removes the last payload value that satisfies the given Predicate

Parameters:

predicate - The Predicate to be used.

Returns:

An Optional yielding the removed payload value.

Throws:

IllegalArgumentException - If the given predicate is null.

removeAll

Source<Payload> removeAll(Payload reference)

Removes all occurrences, by equality, of the given reference payload value.

Parameters:

reference - The reference payload to be removed.

Returns:

A Source yielding the removed payload values.

removeAllMatches

Source<Payload> removeAllMatches(Predicate<? super Payload> predicate)
                          throws IllegalArgumentException

Removes the payload values that satisfy the given Predicate.

Parameters:

predicate - The Predicate to be used.

Returns:

A Source yielding the removed payload values.

Throws:

IllegalArgumentException - If the given Predicate is null.

retainAll

Source<Payload> retainAll(Payload reference)

Removes all but the given payload value.

Parameters:

reference - The reference payload values to be retained.

Returns:

A Source yielding the removed payload values.

retainAllMatches

Source<Payload> retainAllMatches(Predicate<? super Payload> predicate)
                          throws IllegalArgumentException

Removes all but the payload values that satisfy the given Predicate.

Parameters:

predicate - The Predicate to be used.

Returns:

A Source yielding the removed payload values.

Throws:

IllegalArgumentException - If the given Predicate is null.

clear

Source<Payload> clear()

Removes all payload values.

Returns:

A Source yielding the removed payload values.

replace

Payload replace(int index,
                Payload replacement)
         throws IllegalArgumentException,
                IndexOutOfBoundsException

Replaces the payload value at the given index with the given replacement payload value.

Parameters:

index - The index to be used.

replacement - The replacement payload value to be used.

Returns:

The replaced payload value.

Throws:

IllegalArgumentException - If the given replacement payload value is null and this IndexedSource doesn't allow a null to be added.

IndexOutOfBoundsException - If the given index is negative or if the given index is larger or equal to the size of this IndexedSource.

replaceFirst

Payload replaceFirst(Payload replacement)
              throws IllegalArgumentException,
                     NoSuchElementException

Replaces the first payload value with the given replacement payload value.

Parameters:

replacement - The replacement payload value to be used.

Returns:

The replaced payload value.

Throws:

IllegalArgumentException - If the given replacement payload value is null and this IndexedSource doesn't allow a null to be added.

NoSuchElementException - If this IndexedSource is empty.

replaceFirst

Optional<Payload> replaceFirst(Payload reference,
                               Payload replacement)
                        throws IllegalArgumentException

Replaces the first occurrence of the given reference payload value with the given replacement payload value.

Parameters:

reference - The reference payload value to be used.

replacement - The replacement payload to be used.

Returns:

An Optional yielding the removed payload value, if any.

Throws:

IllegalArgumentException - If the given replacement payload value is null and this IndexedSource doesn't allow a null to be added.

replaceFirstMatch

Optional<Payload> replaceFirstMatch(Predicate<? super Payload> predicate,
                                    Payload replacement)
                             throws IllegalArgumentException

Replaces the first payload value that satisfy the given Predicate with the given replacement payload value.

Parameters:

predicate - The Predicate to be used.

replacement - The replacement payload to be used.

Returns:

An Optional yielding the removed payload value, if any.

Throws:

IllegalArgumentException - If the give Predicate is null or if the given replacement payload value is null and this IndexedSource doesn't allow a null to be added.

replaceLast

Payload replaceLast(Payload replacement)
             throws IllegalArgumentException,
                    NoSuchElementException

Replaces the last payload value with the given replacement payload value.

Parameters:

replacement - The replacement payload value to be used.

Returns:

The replaced payload value.

Throws:

IllegalArgumentException - If the given replacement payload value is null and this IndexedSource doesn't allow a null to be added.

NoSuchElementException - If this IndexedSource is empty.

replaceLast

Optional<Payload> replaceLast(Payload reference,
                              Payload replacement)
                       throws IllegalArgumentException

Replaces last occurrence of the the given reference payload value with the given replacement payload value.

Parameters:

reference - The replacement reference payload value to be used.

replacement - The payload to be used.

Returns:

An Optional yielding the removed payload value, if any.

Throws:

IllegalArgumentException - If the given replacement payload value is null and this IndexedSource doesn't allow a null to be added.

replaceLastMatch

Optional<Payload> replaceLastMatch(Predicate<? super Payload> predicate,
                                   Payload replacement)
                            throws IllegalArgumentException

Replaces the last payload value that satisfy the given Predicate with the given replacement payload value.

Parameters:

predicate - The Predicate to be used.

replacement - The replacement payload to be used.

Returns:

An Optional yielding the removed payload value, if any.

Throws:

IllegalArgumentException - If the give Predicate is null or if the given replacement payload value is null and this IndexedSource doesn't allow a null to be added.

replaceAll

Source<Payload> replaceAll(Payload reference,
                           Provider<? extends Payload> provider)
                    throws IllegalArgumentException,
                           ProvisioningException

Replaces all occurrences of the the given reference payload value with payload values yielded by the given Provider.

Parameters:

reference - The reference payload value to be used.

provider - The Provider to be used.

Returns:

A Source yielding the replaced payload values.

Throws:

IllegalArgumentException - If the given Provider is null.

ProvisioningException - If the given Provider yields null and this IndexedSource doesn't allow a null to be added.

replaceAllMatches

Source<Payload> replaceAllMatches(Predicate<? super Payload> predicate,
                                  Provider<? extends Payload> provider)
                           throws IllegalArgumentException,
                                  ProvisioningException

Replaces all payload values that satisfy the given Predicate with payload values yielded by the given Provider.

Parameters:

predicate - The Predicate to be used.

provider - The Provider to be used.

Returns:

A Source yielding the replaced payload values.

Throws:

IllegalArgumentException - If the give Predicate is null or if the given Provider is null.

ProvisioningException - If the given Provider yields null and this IndexedSource doesn't allow a null to be added.

hashCode

int hashCode()

Returns the hash code of this Sequence.

The hash code of a Sequence is defined to be the result of the following calculation:

 int hashCode = 1;
 Iterator<Payload> iterator = sequence.iterator();
 while (iterator.hasNext()) {
        Payload payload = iterator.next();
        hashCode = 31 * hashCode + (null == payload ? 0 : payload.hashCode());
 }
 

Overrides:

hashCode in class Object

Returns:

The hash code of this Sequence.

equals

boolean equals(Object object)

Compares the given object with this Sequence for equality.

Returns true if and only if the given object is also a Sequence, both Sequences have the same size, and all corresponding pairs of elements in the two Sequences are equal.

Overrides:

equals in class Object

Parameters:

object - The object to be used.

Returns:

If the given object is equal to this Sequence.