net.markenwerk.commons.collections.sources

Interface IndexedSource<Payload>

Type Parameters:

Payload - The payload type

All Superinterfaces:

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

All Known Subinterfaces:

Sequence<Payload>

All Known Implementing Classes:

AbstractIndexedSource, AbstractListSequence, AbstractSequence, ArraySource, ListSequence, ListSource

public interface IndexedSource<Payload>
extends Source<Payload>, ProtectedBidirectionalIterable<Payload>

A Source is a linear read-only data structure.

A Source is intended to be used in APIs that want to expose read-only access to a collection of payload values.

It is, amongst other things, intended as a more expressive replacement for Collections.unmodifiableList(java.util.List) that prevents unnecessary runtime exceptions.

Since:

1.0.0

Author:

Torsten Krause (tk at markenwerk dot net)

Method Summary

Modifier and Type	Method and Description
Optional<Integer>	firstIndexOf(Payload payload) Returns index, of the first occurrence, by Object#equals(Object) equality, of the given reference payload value.
Optional<Integer>	firstIndexOfMatch(Predicate<? super Payload> predicate) Returns index, of the first occurrence of a payload value that satisfies the given Predicate.
Payload	get(int index) Returns the payload value at the given index.
Payload	getFirst() Returns the first payload value.
Optional<Payload>	getFirst(Payload reference) Returns the first occurrences, by equality, of the given reference payload value.
Optional<Payload>	getFirstMatch(Predicate<? super Payload> predicate) Returns the first payload value that satisfies the given Predicate .
Payload	getLast() Returns the last payload value.
Optional<Payload>	getLast(Payload reference) Returns the first occurrences, by equality, of the given reference payload value.
Optional<Payload>	getLastMatch(Predicate<? super Payload> predicate) Returns the last payload value that satisfies the given Predicate .
boolean	isFirst(Payload payload) Returns whether the given payload value is the first payload value.
boolean	isLast(Payload payload) Returns whether the given payload value is the last payload value.
ProtectedBidirectionalIterator<Payload>	iterator(boolean reverse) Returns a ProtectedBidirectionalIterator.
Optional<Integer>	lastIndexOf(Payload payload) Returns index, of the last occurrence, by Object#equals(Object) equality, of the given reference payload value.
Optional<Integer>	lastIndexOfMatch(Predicate<? super Payload> predicate) Returns index, of the last occurrence of a payload value that satisfies the given Predicate.

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

get

Payload get(int index)
     throws IndexOutOfBoundsException

Returns 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 IndexedSource.

isFirst

boolean isFirst(Payload payload)
         throws NoSuchElementException

Returns whether the given payload value is the first payload value.

Parameters:

payload - The payload value to be used.

Returns:

Whether the given payload value is the first payload value.

Throws:

NoSuchElementException - If the given payload value is not contained in this IndexedSource.

getFirst

Payload getFirst()
          throws NoSuchElementException

Returns the first payload value.

Specified by:

getFirst in interface Source<Payload>

Returns:

The payload value.

Throws:

NoSuchElementException - If this IndexedSource is empty.

getFirst

Optional<Payload> getFirst(Payload reference)

Returns the first occurrences, by equality, of the given reference payload value.

Specified by:

getFirst in interface Source<Payload>

Parameters:

reference - The reference payload to be used.

Returns:

An Optional yielding the payload value.

getFirstMatch

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

Returns the first payload value that satisfies the given Predicate .

Specified by:

getFirstMatch in interface Source<Payload>

Parameters:

predicate - The Predicate to be used.

Returns:

An Optional yielding the payload value.

Throws:

IllegalArgumentException - If the given Predicate is null.

isLast

boolean isLast(Payload payload)
        throws NoSuchElementException

Returns whether the given payload value is the last payload value.

Parameters:

payload - The payload value to be used.

Returns:

Whether the given payload value is the first payload value.

Throws:

NoSuchElementException - If the given payload value is not contained in this IndexedSource.

getLast

Payload getLast()
         throws NoSuchElementException

Returns the last payload value.

Returns:

The payload value.

Throws:

NoSuchElementException - If this IndexedSource is empty.

getLast

Optional<Payload> getLast(Payload reference)

Returns the first occurrences, by equality, of the given reference payload value.

Parameters:

reference - The reference payload to be used.

Returns:

An Optional yielding the payload value.

getLastMatch

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

Returns the last payload value that satisfies the given Predicate .

Parameters:

predicate - The Predicate to be used.

Returns:

An Optional yielding the payload value.

Throws:

IllegalArgumentException - If the given Predicate is null.

firstIndexOf

Optional<Integer> firstIndexOf(Payload payload)

Returns index, of the first occurrence, by Object#equals(Object) equality, of the given reference payload value.

Parameters:

payload - The payload value to be used.

Returns:

An Optional yielding the index.

firstIndexOfMatch

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

Returns index, of the first occurrence of a payload value that satisfies the given Predicate.

Parameters:

predicate - The Predicate value to be used.

Returns:

An Optional yielding the index.

Throws:

IllegalArgumentException - If the given Predicate is null.

lastIndexOf

Optional<Integer> lastIndexOf(Payload payload)

Returns index, of the last occurrence, by Object#equals(Object) equality, of the given reference payload value.

Parameters:

payload - The payload value to be used.

Returns:

An Optional yielding the index.

lastIndexOfMatch

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

Returns index, of the last occurrence of a payload value that satisfies the given Predicate.

Parameters:

predicate - The Predicate value to be used.

Returns:

An Optional yielding the index.

Throws:

IllegalArgumentException - If the given Predicate is null.

iterator

ProtectedBidirectionalIterator<Payload> iterator(boolean reverse)

Returns a ProtectedBidirectionalIterator.

Parameters:

reverse - Whether to return a ProtectedBidirectionalIterator that iterates this indexed source in reverse.

Returns:

A ProtectedBidirectionalIterator.