T
- type parameterpublic interface Indexable<T> extends Countable<T>
This interface describes something which is iterable, has a defined size and allows direct indexed access to its elements.
Although this behaves similar to an unmodifiable List
its advantage is greater clearness because there are no methods to
modify this indexable, while List
provides such methods but
will throw an exception when one of these method is called on an unmodifiable
list. Whenever you see a List
in code you cannot be sure whether
it's meant to be modified or not. With an Indexable
this is perfectly
clear. But note that in general you cannot be sure whether the underlying class
which implements this interface is immutable or not, so it might change,
although this is considered bad style.
The Java collection framework is built around Collection
,
which is already modifiable by design. The method asCollection()
allows to use an indexable in cases where a Collection
is expected,
and the asList()
method where a List
is expected.
The other way round (get an indexable from a standard class or a standard array)
is given by viewList(List)
and viewArray(Object[])
. As the
returned Indeable is read-only, the former allows transparent conversion of the
element type to one of its super classes. The following code compiles without any
compiler warning:
List<Integer> integers = Arrays.asList(1, 2, 3);
Indexable<Number> numbers = Indexable.viewList(integers);
The same is not possible with standard collection classes as their interface is basically
modifiable (even when wrapped in an unmodifiable wrapper). So a List<Number>
is different from a ListInteger>
because to the former you could add
a double value, but to the latter not.
The above factory methods view their content, and they even have counterparts which
expect a Function
which is mapping the incoming element type to a different
type which the Indexable
exhibits. But viewing means that changes of the underlying
list or array will be reflected by the viewing indexable. To decouple the indexable
call its Countable.frozen()
method which will return an indexable which will not
change. Its elements itself might still change, though, if they are mutable.
Another way to get a frozen indexable is by using Countable.sorted(Comparator)
,
which will return a frozen copy which is also sorted according to the given order
There are also factory methods which do a copy on creation, and which are also useful
to create an Indexable
from non-indexable collections:
fromCollection(Collection)
:
convert a collection into an indexable, can be called with a List
if you want to make a copy on creation
fromCollection(Collection, Function)
:
convert a collection into an indexable while changing the elements,
can be called with a List
if you want to make a copy on creation
fromCountable(Countable)
:
convert a countable into an indexable
fromCountable(Countable, Function)
:
convert a countable into an indexable while changing the elements
fromIterable(Iterable)
:
convert any iterable into an indexable
fromIterable(Iterable, int)
:
convert any iterable into an indexable, with expected size
fromIterable(Iterable, Function)
:
convert any iterable into an indexable, while changing the element type
fromIterable(Iterable, int, Function)
:
convert any iterable into an indexable, while changing the element type, with expected size
init(int, Supplier)
:
creates an indexable with a given number of elements, provided by a supplier.
viewByIndex(int, IntFunction)
:
creates an indexable which will create the elements only when requested,
but each time the same index is requested.
initByIndex(int, IntFunction)
:
creates an indexable with a given number of elements, created by an index-based initializer,
where the elements are cached during creation.
The emptyIndexable()
method provides a useful return value to indicate
emptiness.
FastSequenceSearch
Modifier and Type | Interface and Description |
---|---|
static class |
Indexable.Base<TT>
Abstract base class which provides useful implementations
for
Object.equals(Object) , Object.hashCode() ,
Object.toString() . |
static class |
Indexable.IndexableSpliterator<TElem>
A spliterator for indexables.
|
static class |
Indexable.ListView<T>
Helper class for viewing a mutable indexable as a standard list.
|
Modifier and Type | Field and Description |
---|---|
static Indexable<?> |
EMPTY
An empty indexable.
|
static java.lang.String |
EMPTY_INDEXABLE_STRING
String representation of an empty indexable.
|
Modifier and Type | Method and Description |
---|---|
default int |
addToArray(T[] array,
int arrayPos)
Add the complete content of this indexable to the gien array.
|
default int |
addToArray(T[] array,
int arrayPos,
int index,
int length)
Add a part of the content of this indexable to the given array.
|
default void |
addToCollection(java.util.Collection<? super T> collection)
Deprecated.
use
Countable.addAllTo(Collection) instead |
default Indexable.Base<T> |
asBase()
Convert this into a base indexable.
|
default java.util.Collection<T> |
asCollection()
Get a view on this indexable as an unmodifiable collection.
|
default java.util.List<T> |
asList()
Get a view of this indexable as an unmodifiable list.
|
default int |
binarySearch(T value,
Ordering<? super T> order)
Do a binary search in an ordered indexable.
|
static void |
checkIndex(int idx,
int size)
Check the index if it is between 0 (included) and the given size (excluded).
|
static <E> Indexable<E> |
combine(Indexable<? extends E>... parts) |
static <E> int |
compare(Indexable<? extends E> indexable1,
Indexable<? extends E> indexable2,
java.util.Comparator<E> comparator)
Deprecated.
|
static <E> Indexable<E> |
downCast(Indexable<? extends E> indexable)
Downcast an indexable of a given type so that it appears at an indexable of a super type.
|
static <E> Indexable.Base<E> |
emptyIndexable()
Get an empty indexable set.
|
static <E> boolean |
equal(Indexable<? extends E> indexable1,
Indexable<? extends E> indexable2,
java.util.function.BiPredicate<E,E> equalityChecker)
Deprecated.
|
default Indexable<T> |
findAll(java.util.function.Predicate<? super T> filter)
Find all elements that fulfill a given condition.
|
default <X extends java.lang.Exception> |
findAllX(FragilePredicate1<X,? super T> filter)
Find all elements that fulfill a given condition that might throw a checked exception.
|
default int |
findFirst(java.util.function.Predicate<? super T> matcher)
Do a linear forward search from the beginning.
|
default int |
findFirst(T element)
Do a linear forward search from the beginning.
|
default <U> int |
findFirst(U object,
Matcher<? super U,? super T> equality)
Do a linear forward search from an element (or a substitute)
from the beginning.
|
default <X extends java.lang.Exception> |
findFirstX(FragilePredicate1<X,? super T> matcher)
Do a linear forward search from the beginning.
|
default int |
findLast(java.util.function.Predicate<? super T> matcher)
Do a linear backward search from the beginning.
|
default int |
findLast(T element)
Do a linear backward search from the end.
|
default <U> int |
findLast(U object,
Matcher<? super U,? super T> equality)
Do a linear backward search from an element (or a substitute)
from the beginning.
|
default int |
findNext(java.util.function.Predicate<? super T> matcher,
int start)
Do a linear forward search from the beginning.
|
default int |
findNext(T element,
int start)
Do a linear forward search from a given index and look for an
element which is the same as the given element.
|
default <U> int |
findNext(U object,
Matcher<? super U,? super T> equality,
int start)
Do a linear forward search from a given index and look for an
element which is the same as the given object.
|
default <X extends java.lang.Exception> |
findNextX(FragilePredicate1<X,? super T> matcher,
int start)
Do a linear forward search from the beginning.
|
default int |
findPrevious(java.util.function.Predicate<? super T> matcher,
int start)
Do a linear backward search from a given index and look for an
element which is the same as the given object.
|
default int |
findPrevious(T element,
int start)
Do a linear backward search from a given index and look for an
element which is the same as the given element.
|
default <U> int |
findPrevious(U object,
Matcher<? super U,? super T> equality,
int start)
Do a linear backward search from a given index and look for an
element which is the same as the given object.
|
default T |
first()
Get the first element.
|
default T |
firstMatch(java.util.function.Predicate<? super T> condition)
Get the first element which matches a given condition.
|
default <R> R |
firstMatch(java.util.function.Predicate<? super T> condition,
java.util.function.Function<? super T,? extends R> adaptor)
Get an adapted value from the first element which matches a given condition.
|
default <X extends java.lang.Exception> |
firstMatchX(FragilePredicate1<X,? super T> condition)
Get the first element which matches a given fragile condition.
|
default void |
forEachEntry(java.util.function.BiConsumer<java.lang.Integer,? super T> action)
Call an action for each entry.
|
default <E extends java.lang.Exception> |
forEachEntryFragile(FragileProcedure2<E,java.lang.Integer,? super T> action)
Call a fragile action for each entry.
|
static <E> Indexable<E> |
fromArray(E... array)
Deprecated.
this was inconsistently named, use
viewArray(Object[]) instead |
static <E> Indexable<E> |
fromCollection(java.util.Collection<? extends E> collection)
Convert a collection into an indexable.
|
static <E,V> Indexable<E> |
fromCollection(java.util.Collection<V> collection,
java.util.function.Function<? super V,? extends E> mapper)
Convert a collection into an indexable.
|
static <E> Indexable<E> |
fromCountable(Countable<? extends E> countable)
Convert a countable into an indexable.
|
static <E,V> Indexable<E> |
fromCountable(Countable<V> countable,
java.util.function.Function<? super V,? extends E> mapper)
Convert a countable into an indexable.
|
static <E> Indexable<E> |
fromEnumeration(java.util.Enumeration<? extends E> enumeration,
int size)
Convert an enumeration into an indexable.
|
static <E,V> Indexable<E> |
fromEnumeration(java.util.Enumeration<V> enumeration,
int size,
java.util.function.Function<? super V,? extends E> mapper)
Convert an enumeration into an indexable.
|
static <E> Indexable<E> |
fromIterable(java.lang.Iterable<? extends E> iterable)
Convert an iterable into an indexable.
|
static <E> Indexable<E> |
fromIterable(java.lang.Iterable<? extends E> iterable,
int size)
Convert an iterable into an indexable.
|
static <E,V> Indexable<E> |
fromIterable(java.lang.Iterable<V> iterable,
java.util.function.Function<? super V,? extends E> mapper)
Convert an iterable into an indexable.
|
static <E,V> Indexable<E> |
fromIterable(java.lang.Iterable<V> iterable,
int size,
java.util.function.Function<? super V,? extends E> mapper)
Convert an iterable into an indexable.
|
static <E> Indexable<E> |
fromIterator(java.util.Iterator<? extends E> iterator)
Convert an iterator to an indexable.
|
static <E> Indexable<E> |
fromList(java.util.List<? extends E> list)
Deprecated.
this was inconsistently named, use
viewList(List) instead |
static <E> Indexable<E> |
fromOptional(java.util.Optional<E> optional)
Convert a standard Optional to an Indexable with either one or no element.
|
default java.util.Spliterator<T> |
frozenSpliterator()
Get an immutable spliterator on a frozen copy of this indexable.
|
T |
get(int index)
Get the element at the given index.
|
default T |
getMod(int index)
Get an element modulo size.
|
default T |
gyt(int index)
Pythonesque get.
|
static int |
hash(Indexable<?> indexable)
Deprecated.
use
Types.hash(Iterable) instead |
default Indexable<T> |
headSet(int toIndex)
Create an indexable subset from the last elements of this indexable set.
|
default <E> Indexable<E> |
indexedView(java.util.function.BiFunction<? super java.lang.Integer,? super T,? extends E> mapper)
View this indexable as if it has another type.
|
default java.lang.Iterable<java.lang.Integer> |
indexes()
Get the indexes of this indexable as an iterable range.
|
static <V> Indexable<V> |
init(int size,
java.util.function.Supplier<? extends V> producer)
Create an indexable with a given size, and initialize its elements.
|
static <V> Indexable<V> |
initByIndex(int size,
java.util.function.IntFunction<? extends V> producer)
Create an indexable with a given size, and initialize its elements by index.
|
default IntIndexable |
intIndexes()
Get the valid set of indexes as in integer indexable.
|
default boolean |
isEmpty()
Is this indexable empty?
|
default boolean |
isOrdered(Ordering<? super T> order)
Is this indexable sorted according to the given ordering?
|
default boolean |
isStrictlyOrdered(Ordering<? super T> order)
Is this indexable strictly sorted according to the given ordering?
|
default java.util.Iterator<T> |
iterator()
Returns an iterator over elements of type
T . |
default java.util.Iterator<T> |
iterator(int fromIndex,
int toIndex)
Get a sub set iterator.
|
default T |
last()
Get the last element.
|
default java.util.ListIterator<T> |
listIterator()
Returns a list iterator over elements of type
T . |
static <E,V> Indexable<E> |
mapArray(java.util.function.Function<? super V,? extends E> mapper,
V... array)
View an array as an indexable of another type.
|
static <E> Indexable<E> |
optional(E optionalElement)
Get an indexable with a single or no element.
|
default MutableIndexable<T> |
ordered(Ordering<? super T> order)
Create a (mutable) double indexable from the values of this indexable
which is ordered as defined by the given ordering.
|
default Indexable<T> |
reverse()
Get this indexable but with inverted order.
|
default Indexable<T> |
rotated(int steps)
Get a rotated view of this indexable.
|
static <E> Indexable<E> |
singleton(E singleElement)
Create an indexable with only one element.
|
default java.util.Spliterator<T> |
spliterator()
Get a spliterator on this indexable.
|
default Indexable<T> |
subSet(int fromIndex,
int toIndex)
Get an indexable subset.
|
default Indexable<T> |
sybSet(int fromIndex,
int toIndex)
Get an indexable subset.
|
default Indexable<T> |
tailSet(int fromIndex)
Create an indexable subset from the last elements of this indexable set.
|
static java.lang.String |
toString(Indexable<?> indexable)
Deprecated.
|
default <E> Indexable<E> |
view(java.util.function.Function<? super T,? extends E> mapper)
View this indexable as if it has another type.
|
static <V> Indexable<V> |
view(Indexable<? extends V> indexable)
View an indexable as if it has entries belonging to a super class.
|
static <E> Indexable<E> |
viewArray(E... array)
View an array as an Indexable.
|
static <E> Indexable<E> |
viewArray(E[] array,
int start,
int len)
View a slice of an array.
|
default BooleanIndexable |
viewAsBooleanIndexable(java.util.function.Predicate<? super T> extractor)
View this indexable as a boolean indexable.
|
default ByteIndexable |
viewAsByteIndexable(ToByteFunction<? super T> extractor)
View this indexable as a byte indexable.
|
default CharIndexable |
viewAsCharIndexable(ToCharFunction<? super T> extractor)
View this indexable as a char indexable.
|
default DoubleIndexable |
viewAsDoubleIndexable(java.util.function.ToDoubleFunction<? super T> extractor)
View this indexable as a double indexable.
|
default FloatIndexable |
viewAsFloatIndexable(ToFloatFunction<? super T> extractor)
View this indexable as a float indexable.
|
default IntIndexable |
viewAsIntIndexable(java.util.function.ToIntFunction<? super T> extractor)
View this indexable as an integer indexable.
|
default LongIndexable |
viewAsLongIndexable(java.util.function.ToLongFunction<? super T> extractor)
View this indexable as a long indexable.
|
default ShortIndexable |
viewAsShortIndexable(ToShortFunction<? super T> extractor)
View this indexable as a short indexable.
|
static <V> Indexable<V> |
viewByIndex(int size,
java.util.function.IntFunction<? extends V> producer)
Create an indexable with a given size which returns its elements by calling a producer.
|
default <R,E extends java.lang.Exception> |
viewFragile(FragileFunction1<? extends R,E,? super T> mapper)
View this indexable as if it has another type using a fragile mapping which might
throw a checked exception.
|
static <E> Indexable<E> |
viewList(java.util.List<? extends E> list)
View a list as an Indexable.
|
static <E,V> Indexable<E> |
viewList(java.util.List<V> list,
java.util.function.Function<? super V,? extends E> mapper)
View a list as an indexable of another type.
|
static <E> Indexable<E> |
viewListN(java.util.List<? extends E> list)
View a list which is possibly
null as an indexable. |
static <E,V> Indexable<E> |
viewListN(java.util.List<V> list,
java.util.function.Function<? super V,? extends E> mapper)
View a list as an indexable of another type.
|
static <C> Indexable<C> |
viewTuple(ITuple2<? extends C,? extends C> tuple)
View a 2-element tuple as an indexable.
|
static <C> Indexable<C> |
viewTuple(ITuple3<? extends C,? extends C,? extends C> tuple)
View a 3-element tuple as an indexable.
|
static <C> Indexable<C> |
viewTuple(ITuple4<? extends C,? extends C,? extends C,? extends C> tuple)
View a 4-element tuple as an indexable.
|
static <C> Indexable<C> |
viewTuple(ITuple5<? extends C,? extends C,? extends C,? extends C,? extends C> tuple)
View a 5-element tuple as an indexable.
|
static <C> Indexable<C> |
viewTuple(ITuple6<? extends C,? extends C,? extends C,? extends C,? extends C,? extends C> tuple)
View a 6-element tuple as an indexable.
|
static <C> Indexable<C> |
viewTuple(ITuple7<? extends C,? extends C,? extends C,? extends C,? extends C,? extends C,? extends C> tuple)
View a 7-element tuple as an indexable.
|
static <C> Indexable<C> |
viewTuple(ITuple8<? extends C,? extends C,? extends C,? extends C,? extends C,? extends C,? extends C,? extends C> tuple)
View a 8-element tuple as an indexable.
|
static <C> Indexable<C> |
viewTuple(ITuple9<? extends C,? extends C,? extends C,? extends C,? extends C,? extends C,? extends C,? extends C,? extends C> tuple)
View a 9-element tuple as an indexable.
|
default Indexable<T> |
withAppendedItem(T item)
Create a view with of this indexable with another item added at the end.
|
static <E> Indexable<E> |
withCachedHash(Indexable<E> indexable)
Wrap an indexable with one which caches the hash value.
|
default Indexable<T> |
withExchangedItemAt(int index,
T value)
Create a view of this indexable with an exchanged element.
|
default Indexable<T> |
withInsertedItemAt(int index,
T item)
Create a view of this indexable with an inserted element.
|
default Indexable<T> |
withRemovedItemAt(int index)
Create a view of this indexable with one item removed.
|
default Indexable<T> |
withSwappedItemsAt(int index1,
int index2)
Create a view of this indexable with two items swapped.
|
addAllTo, combined, combined, containsEq, containsRef, downCast, empty, equal, equals, filtered, filteredToIndexable, filterToCountable, firstOrNull, foldLeft, forEachFragile, freeze, frozen, frozen, groupingBy, groupingBy, hasAll, hasAny, isSorted, isStrictlySorted, lastOrNull, mappingBy, mappingBy, optFirst, optLast, orderedCombination, sorted, toArray, toArray, toList, toString, uniform, viewCollection, viewCollection, viewCollectionN, viewCollectionN
static final java.lang.String EMPTY_INDEXABLE_STRING
@NotNull static final Indexable<?> EMPTY
emptyIndexable()
instead for compiler-safe access.T get(int index)
index
- index between 0
and size() - 1
static void checkIndex(int idx, int size)
idx
- index to checksize
- size of indexablejava.lang.IndexOutOfBoundsException
- if idx
is outside rangedefault T gyt(int index)
-1
references the last element, -2
its predecessor, and so on.index
- index between -size()
and size() - 1
default T getMod(int index)
This maps the given index
into the range of this indexable
by applying a modulo Sizeable.size()
operation. For empty indexable
this will throw an IndexOutOfBoundsException
as there is no
possible index to get.
index
- index, possibly out of range, possibly even negative
for Pythonesque access@NotNull default Indexable<T> reverse()
default boolean isEmpty()
@NotNull default java.util.Iterator<T> iterator()
T
.iterator
in interface java.lang.Iterable<T>
@NotNull default java.util.Iterator<T> iterator(int fromIndex, int toIndex)
fromIndex
- start indextoIndex
- end index@NotNull default java.util.ListIterator<T> listIterator()
T
.default T first()
Countable
first
in interface Countable<T>
Countable.firstOrNull()
,
Countable.optFirst()
default T last()
Countable
last
in interface Countable<T>
Countable.lastOrNull()
,
Countable.optLast()
@NotNull default Indexable<T> subSet(int fromIndex, int toIndex)
fromIndex
to toIndex - 1
.fromIndex
- start index of sub settoIndex
- index after last index@NotNull default Indexable<T> sybSet(int fromIndex, int toIndex)
fromIndex
- start index of sub settoIndex
- end index of sub set@NotNull default Indexable<T> tailSet(int fromIndex)
fromIndex
- index to start with, negative counts from the back@NotNull default Indexable<T> headSet(int toIndex)
toIndex
- index one after the end (equal to the length of the returned set),
negative counts from the back@NotNull default java.util.Collection<T> asCollection()
Collection.addAll(Collection)
.asCollection
in interface Countable<T>
@NotNull default java.util.List<T> asList()
Collection.addAll(Collection)
(but have a look at
Countable.addAllTo(Collection)
).Countable.toList()
@NotNull default java.lang.Iterable<java.lang.Integer> indexes()
intIndexes()
,
Range.indexes(int)
@NotNull default IntIndexable intIndexes()
indexes()
,
IntIndexable.rangeFromSize(int)
@NotNull default <E> Indexable<E> view(@NotNull java.util.function.Function<? super T,? extends E> mapper)
view
in interface Countable<T>
E
- element type of returned viewmapper
- mapper used to convert the element type of this indexable to the expected type,
will be applied on each accessCountable.frozen()
on the resulting indexable to change this.@NotNull default <R,E extends java.lang.Exception> Indexable<R> viewFragile(@NotNull FragileFunction1<? extends R,E,? super T> mapper)
The returned indexable is evaluated lazily, so the exception might be triggered much later, of even never if the element where the converted does throw an exception is never used.
If mapper
is throwing an exception this exception is wrapped into a WrappedFragileException
which is thrown instead.
If the resulting indexable is only temporarily used, you can wrap its usage with a
try-catch construction (see below). If it is returned from your code the only way
to make the exception appear early is freezing
with the price
of an internal copy.
Example of wrapping the usage (assuming that method Foo foo(Bar)
converts Foo
objects
to Bar
objects with the occasional CheckedException
exception):
try {
Indexable<Bar> bars = // ...
try {
Indexable<Foo> foos = bars.viewFragile(bar -> foo(bar));
// use foos only inside this block or
// return foos.frozen();
// to trigger possible exceptions inside this block.
} catch(WrappedFragileException x) {
x.rethrow(CheckedException.class); // this will throw the caught exception
// throw new RuntimeException("Never will reach here!");
}
}
viewFragile
in interface Countable<T>
R
- target type of the elements of the returned indexableE
- possible exception thrown by mapper
mapper
- mapper from incoming to outgoing objects which might throw an exception@NotNull default <E> Indexable<E> indexedView(@NotNull java.util.function.BiFunction<? super java.lang.Integer,? super T,? extends E> mapper)
view(Function)
this calls the mapper with an additional index argument.E
- element type of returned viewmapper
- mapper which gets the index as first and the associated element as second argument,
and will be applied on each access to return the element of the resulting indexableCountable.frozen()
on the resulting indexable to change this.default int addToArray(@NotNull T[] array, int arrayPos, int index, int length)
array
- array where the content is addedarrayPos
- start position in the array where the content is addedindex
- start index of this indexable which is added firstlength
- number of entries of this indexable added to the arraydefault int addToArray(@NotNull T[] array, int arrayPos)
addToArray
in interface Countable<T>
array
- array where the content is addedarrayPos
- start position in hte array where the content is added@Deprecated default void addToCollection(@NotNull java.util.Collection<? super T> collection)
Countable.addAllTo(Collection)
insteadcollection
- collection for collecting this indexabledefault void forEachEntry(@NotNull java.util.function.BiConsumer<java.lang.Integer,? super T> action)
Iterable.forEach(Consumer)
, but also provides the index.action
- action which will be called for each entry with index and element at that indexforEachEntryFragile(FragileProcedure2)
,
Iterable.forEach(Consumer)
default <E extends java.lang.Exception> void forEachEntryFragile(@NotNull FragileProcedure2<E,java.lang.Integer,? super T> action) throws E extends java.lang.Exception
forEachEntry(BiConsumer)
but allows an action which might throw an exception.E
- exception typeaction
- action which will be called for each entry with index and associated element, might throw an exceptionE
- if action
throwsE extends java.lang.Exception
@NotNull default java.util.Spliterator<T> spliterator()
Spliterator.IMMUTABLE
flag set,
see frozenSpliterator()
for an alternative.spliterator
in interface java.lang.Iterable<T>
@NotNull default java.util.Spliterator<T> frozenSpliterator()
Countable.frozen()
returns this
)
then this is the same as spliterator()
with the difference that the spliterator
returned here will have its Spliterator.IMMUTABLE
flag set. If this is not immutable
a frozen copy will be created, and the spliterator will be operating on that. Please refer to
Countable.frozen()
to understand what level of immutabiliy it will provide.default boolean isOrdered(@NotNull Ordering<? super T> order)
order
- expected orderingtrue
if this indexable is sorted as defined by order
false
if notdefault boolean isStrictlyOrdered(@NotNull Ordering<? super T> order)
order
- expected orderingtrue
if this indexable is sorted as defined by order
false
if notdefault int binarySearch(T value, @NotNull Ordering<? super T> order)
order
,
i.e. isOrdered(Ordering) has to return true
for this order.
For efficiency this prerequisite is not checked, but not fulfilling
it will make this method return bogus results. If this indexable is only ordered,
but not strictly ordered
it is not defined
which index is returned when the looked up value appears in a sequence of equal values.value
- value to look uporder
- sort order-(insertIndex + 1)
.@NotNull default MutableIndexable<T> ordered(@NotNull Ordering<? super T> order)
order
- sort order@NotNull default Indexable.Base<T> asBase()
Object.equals(Object)
, Object.hashCode()
,
and Object.toString()
.default int findFirst(T element)
Objects.deepEquals(Object, Object)
for
checking if a given element is the same as the searched one.element
- element to look for-1
if nothing was founddefault int findNext(T element, int start)
Objects.deepEquals(Object, Object)
for
checking if a given element is the same as the searched one.element
- element to look forstart
- start index to look from, pythonesque-1
if nothing was founddefault <U> int findFirst(U object, @NotNull Matcher<? super U,? super T> equality)
U
- type of search elementobject
- element to look forequality
- equality check used-1
if nothing was founddefault <U> int findNext(U object, @NotNull Matcher<? super U,? super T> equality, int start)
U
- pattern object type, depending on the matcher this may differ
from the element typeobject
- element to look forequality
- equality check usedstart
- start index to look from, pythonesque-1
if nothing was founddefault int findFirst(@NotNull java.util.function.Predicate<? super T> matcher)
matcher
- test which returns true
when a matching element is found-1
if nothing was founddefault <X extends java.lang.Exception> int findFirstX(@NotNull FragilePredicate1<X,? super T> matcher) throws X extends java.lang.Exception
X
- exception type thrown by matchermatcher
- test which returns true
when a matching element is found-1
if nothing was foundX
- if matcher
throwsX extends java.lang.Exception
default int findNext(@NotNull java.util.function.Predicate<? super T> matcher, int start)
matcher
- test which returns true
when a matching element is foundstart
- start index where the search begins-1
if nothing was founddefault <X extends java.lang.Exception> int findNextX(@NotNull FragilePredicate1<X,? super T> matcher, int start) throws X extends java.lang.Exception
X
- exception type thrown by matchermatcher
- test which returns true
when a matching element is foundstart
- start index where the search begins-1
if nothing was foundX
- if matcher
throwsX extends java.lang.Exception
@Nullable default T firstMatch(@NotNull java.util.function.Predicate<? super T> condition)
condition
- matching conditiontrue
,
or null
if no element fulfills the conditionTypes.findFirst(Iterable, Predicate)
@Nullable default <X extends java.lang.Exception> T firstMatchX(@NotNull FragilePredicate1<X,? super T> condition) throws X extends java.lang.Exception
X
- exception typecondition
- matching condition which might throw an exceptiontrue
,
or null
if no element fulfills the conditionX
- if the condition throwsX extends java.lang.Exception
@Nullable default <R> R firstMatch(@NotNull java.util.function.Predicate<? super T> condition, @NotNull java.util.function.Function<? super T,? extends R> adaptor)
null
check in your code.
Indexables which may contain null
values which the
condition
considers a match should not use this method.R
- result typecondition
- matching conditionadaptor
- adaptor which adapts a possible match to your needs, only
called with non-null valuesnull
if no match was founddefault int findLast(T element)
Objects.deepEquals(Object, Object)
for
checking if a given element is the same as the searched one.element
- element to look for-1
if nothing was founddefault int findPrevious(T element, int start)
Objects.deepEquals(Object, Object)
for
checking if a given element is the same as the searched one.element
- element to look forstart
- start index to look from, pythonesque,
use -1
to start with the last element-1
if nothing was founddefault <U> int findLast(U object, @NotNull Matcher<? super U,? super T> equality)
U
- type of search elementobject
- element to look forequality
- equality check used-1
if nothing was founddefault <U> int findPrevious(U object, @NotNull Matcher<? super U,? super T> equality, int start)
U
- pattern object type, depending on the matcher this may differ
from the element typeobject
- element to look forequality
- equality check usedstart
- start index to look from, pythonesque-1
if nothing was founddefault int findLast(@NotNull java.util.function.Predicate<? super T> matcher)
matcher
- matcher which returns true
when a matching element is found-1
if nothing was founddefault int findPrevious(@NotNull java.util.function.Predicate<? super T> matcher, int start)
matcher
- matcher which returns true
when a matching element is foundstart
- start index to look from, pythonesque-1
if nothing was found@NotNull default Indexable<T> findAll(@NotNull java.util.function.Predicate<? super T> filter)
filter
- filter to apply@NotNull default <X extends java.lang.Exception> Indexable<T> findAllX(@NotNull FragilePredicate1<X,? super T> filter) throws X extends java.lang.Exception
X
- exception typefilter
- filter to apply, might possibly throwX
- if filter throwsX extends java.lang.Exception
@NotNull default Indexable<T> withInsertedItemAt(int index, T item)
ExpandableIndexable
if you want to carry out more
stuff like this.
As this creates a view of this indexable, changes to this indexable might result in a disaster when using the returned indexable!
index
- index where the element is inserted before the current index
(not Pythonesque, because it is possible to add an element at index == size()
,
and it is expected that most insertion will happen at 0 or at the end)item
- inserted item at that indexwithAppendedItem(Object)
@NotNull default Indexable<T> withAppendedItem(T item)
item
- item to addwithInsertedItemAt(int, Object)
@NotNull default Indexable<T> withExchangedItemAt(int index, T value)
ExpandableIndexable
if you want to carry out more
stuff like this.
As this creates a view of this indexable, changes to this indexable could lead to unexpected results when using the returned indexable!
index
- index where the element is exchanged, hiding the current element.
(Pythonesque)value
- exchanged value at that index@NotNull default Indexable<T> withRemovedItemAt(int index)
index
- index of the removed element (Pythonesque)@NotNull default Indexable<T> withSwappedItemsAt(int index1, int index2)
index1
- index of the first element (Pythonesque)index2
- index of the second element (Pythonesque)@NotNull default Indexable<T> rotated(int steps)
steps
will rotate left, i.e. any index will be accessed
as if the number of steps is added before extraction (modulo length).
E.g. a rotation of -1
will return the last element when index 0
is
requested, and the first element for index 1
.steps
- steps to rotateCountable.frozen()
to create an indexable which no longer depends on this one@NotNull default DoubleIndexable viewAsDoubleIndexable(@NotNull java.util.function.ToDoubleFunction<? super T> extractor)
extractor
- extractor for double values@NotNull default FloatIndexable viewAsFloatIndexable(@NotNull ToFloatFunction<? super T> extractor)
extractor
- extractor for float values@NotNull default LongIndexable viewAsLongIndexable(@NotNull java.util.function.ToLongFunction<? super T> extractor)
extractor
- extractor for long values@NotNull default IntIndexable viewAsIntIndexable(@NotNull java.util.function.ToIntFunction<? super T> extractor)
extractor
- extractor for integer values@NotNull default ShortIndexable viewAsShortIndexable(@NotNull ToShortFunction<? super T> extractor)
extractor
- extractor for short values@NotNull default CharIndexable viewAsCharIndexable(@NotNull ToCharFunction<? super T> extractor)
extractor
- extractor for char values@NotNull default ByteIndexable viewAsByteIndexable(@NotNull ToByteFunction<? super T> extractor)
extractor
- extractor for byte values@NotNull default BooleanIndexable viewAsBooleanIndexable(@NotNull java.util.function.Predicate<? super T> extractor)
extractor
- extractor for boolean values@NotNull @Deprecated static <E> Indexable<E> fromList(@NotNull java.util.List<? extends E> list)
viewList(List)
instead
Please note that this method is defined in a way that it allows transparent type conversion
of the elements' type to a super type. This is possible because the returned interface
is read-only. If you need a more complex conversion use viewList(List, Function)
.
E
- element typelist
- list used as a base@NotNull static <E> Indexable<E> viewList(@NotNull java.util.List<? extends E> list)
Please note that this method is defined in a way that it allows transparent type conversion
of the elements' type to a super type. This is possible because the returned interface
is read-only. If you need a more complex conversion use viewList(List, Function)
.
E
- element typelist
- list used as a base@NotNull static <E> Indexable<E> viewListN(@Nullable java.util.List<? extends E> list)
null
as an indexable.
Please note that this method is defined in a way that it allows transparent type conversion
of the elements' type to a super type. This is possible because the returned interface
is read-only. If you need a more complex conversion use viewListN(List, Function)
.
E
- element typelist
- list used as a baselist
is null
@NotNull static <E,V> Indexable<E> viewList(@NotNull java.util.List<V> list, @NotNull java.util.function.Function<? super V,? extends E> mapper)
E
- element type of this indexableV
- element type of the listlist
- list to viewmapper
- mapper from list element type to the element type of this indexable,
will be applied for each access@NotNull static <E,V> Indexable<E> viewListN(@Nullable java.util.List<V> list, @NotNull java.util.function.Function<? super V,? extends E> mapper)
Compared to viewList(List, Function) this accepts null
for the list which is occasionally handy.
E
- element type of this indexableV
- element type of the listlist
- list to viewmapper
- mapper from list element type to the element type of this indexable,
will be applied for each accesslist
is null
@SafeVarargs @NotNull @Deprecated static <E> Indexable<E> fromArray(@NotNull E... array)
viewArray(Object[])
insteadsubSet(int, int)
.E
- element typearray
- array used as base@SafeVarargs @NotNull static <E> Indexable<E> viewArray(@NotNull E... array)
subSet(int, int)
.@NotNull static <E> Indexable<E> viewArray(@NotNull E[] array, int start, int len)
viewArray
in interface Countable<T>
E
- array typearray
- array to viewstart
- start of array slice represented by the returned indexablelen
- length of array slice represented by the returned indexableIndexable.viewArray(array).subset(start, start + len)
@NotNull static <E> Indexable<E> fromCollection(@NotNull java.util.Collection<? extends E> collection)
collection
and return them
as an indexable.E
- element type of the returned indexable, base type of the type
of the incoming collectioncollection
- collection to iterate over@NotNull static <E,V> Indexable<E> fromCollection(@NotNull java.util.Collection<V> collection, @NotNull java.util.function.Function<? super V,? extends E> mapper)
collection
, get its elements, convert them
using the mapper
, and return the result as an indexable.E
- element type of the returned indexableV
- element type of the incoming iterablecollection
- collection to iterate overmapper
- mapper from incoming element type to outgoing element type@NotNull static <E> Indexable<E> fromCountable(@NotNull Countable<? extends E> countable)
countable
and return them
as an indexable.E
- element type of the returned indexable, base type of the type
of the incoming countablecountable
- countable to iterate over@NotNull static <E,V> Indexable<E> fromCountable(@NotNull Countable<V> countable, @NotNull java.util.function.Function<? super V,? extends E> mapper)
countable
, get its elements, convert them
using the mapper
, and return the result as an indexable.E
- element type of the returned indexableV
- element type of the incoming iterablecountable
- countable to iterate overmapper
- mapper from incoming element type to outgoing element type@NotNull static <E> Indexable<E> fromIterable(@NotNull java.lang.Iterable<? extends E> iterable)
iterable
and return them
as an indexale.E
- element type of the returned indexable, base type of the type
of the incoming iterableiterable
- iterable to iterate over@NotNull static <E> Indexable<E> fromIterator(@NotNull java.util.Iterator<? extends E> iterator)
E
- element type of the returned indexable, base type of the type
of the incoming iteratoriterator
- iterator consumed by this method@NotNull static <E,V> Indexable<E> fromIterable(@NotNull java.lang.Iterable<V> iterable, @NotNull java.util.function.Function<? super V,? extends E> mapper)
iterable
, get its elements, convert them
using the mapper
, and return the result as an indexable.E
- element type of the returned indexableV
- element type of the incoming iterableiterable
- iterable to iterate overmapper
- mapper from incoming element type to outgoing element type@NotNull static <E> Indexable<E> fromIterable(@NotNull java.lang.Iterable<? extends E> iterable, int size)
iterable
and return them
as an indexale.E
- element type of the returned indexable, base type of the type
of the incoming iterableiterable
- iterable to iterate oversize
- expected size of the iterable, use 0
or negative for unknonw@NotNull static <E,V> Indexable<E> fromIterable(@NotNull java.lang.Iterable<V> iterable, int size, @NotNull java.util.function.Function<? super V,? extends E> mapper)
iterable
, get its elements, convert them
using the mapper
, and return the result as an indexable.E
- element type of the returned indexableV
- element type of the incoming iterableiterable
- iterable to iterate oversize
- expected size of the iterable, use 0
or negative for unknownmapper
- mapper from incoming element type to outgoing element type@NotNull static <E> Indexable<E> fromEnumeration(@NotNull java.util.Enumeration<? extends E> enumeration, int size)
enumeration
and return them
as an indexale.E
- element type of the returned indexable, base type of the type
of the incoming enumerationenumeration
- enumeration to iterate oversize
- expected size of the enumeration, use 0
or negative for unknonw@NotNull static <E,V> Indexable<E> fromEnumeration(@NotNull java.util.Enumeration<V> enumeration, int size, @NotNull java.util.function.Function<? super V,? extends E> mapper)
enumeration
, get its elements, convert them
using the mapper
, and return the result as an indexable.E
- element type of the returned indexableV
- element type of the incoming enumerationenumeration
- enumeration to iterate oversize
- expected size of the enumeration, use 0
or negative for unknownmapper
- mapper from incoming element type to outgoing element type@NotNull static <E> Indexable<E> downCast(@NotNull Indexable<? extends E> indexable)
E
- target type of returned indexableindexable
- indexable to be downcasted, needs to have a tyoe which extends or implements <E>
indexable
, but using a different element type@NotNull static <E> Indexable<E> singleton(E singleElement)
@NotNull static <E> Indexable<E> optional(@Nullable E optionalElement)
@NotNull static <E> Indexable<E> fromOptional(@NotNull java.util.Optional<E> optional)
fromOptional
in interface Countable<T>
E
- optional/indexable typeoptional
- optional to convert to indexable@NotNull @SafeVarargs static <E,V> Indexable<E> mapArray(@NotNull java.util.function.Function<? super V,? extends E> mapper, @NotNull V... array)
E
- element type of this indexableV
- element type of the arrayarray
- array to viewmapper
- mapper from array element type to the element type of this indexable,
will be applied for each access@NotNull static <V> Indexable<V> view(@NotNull Indexable<? extends V> indexable)
V
- super type of the incoming indexable
indexable
- indexable to be viewedindexable
, but with adapted entry type@NotNull static <V> Indexable<V> init(int size, @NotNull java.util.function.Supplier<? extends V> producer)
V
- element typesize
- size of the indexableproducer
- element producer which will be called for each element@NotNull static <V> Indexable<V> viewByIndex(int size, @NotNull java.util.function.IntFunction<? extends V> producer)
producer
when an element is requested.
Use Countable.frozen()
on the result to create an indexable which avoids this.V
- element typesize
- size of the indexableproducer
- element producer which will be called for each indexproducer
initByIndex(int, IntFunction)
@NotNull static <V> Indexable<V> initByIndex(int size, @NotNull java.util.function.IntFunction<? extends V> producer)
V
- element typesize
- size of the indexableproducer
- element producer which will be called for each indexviewByIndex(int, IntFunction)
@NotNull static <E> Indexable.Base<E> emptyIndexable()
E
- element type@NotNull @SafeVarargs static <E> Indexable<E> combine(@NotNull Indexable<? extends E>... parts)
@NotNull @Deprecated static java.lang.String toString(@NotNull Indexable<?> indexable)
Countable.toString(Countable)
indexable
- indexable@Deprecated static <E> boolean equal(@NotNull Indexable<? extends E> indexable1, @NotNull Indexable<? extends E> indexable2, @NotNull java.util.function.BiPredicate<E,E> equalityChecker)
Countable.equal(Countable, Countable, BiPredicate)
insteadE
- parameter type of equality checker, and super class of
both indexables' element typeindexable1
- first indexableindexable2
- second indexableequalityChecker
- checker for equality of both objectstrue
if both indexables contain the same values in the same sequencefalse
if sizes or values differ@Deprecated static <E> int compare(@NotNull Indexable<? extends E> indexable1, @NotNull Indexable<? extends E> indexable2, @NotNull java.util.Comparator<E> comparator)
Types.lexicalCompare(Iterable, Iterable, Comparator)
insteadcomparator
until either the first difference is found (smaller of the two
values define the lower indexable) or the end of one is met
(shorter indexable is less).E
- comparator type, needs to be a base type of
both indexables' element typeindexable1
- first indexableindexable2
- second indexablecomparator
- type< 0>
if indexable1 < indexable2
,
0
if indexable1 == indexable2
, or
> 0
if indexable1 > indexable2
@Deprecated static int hash(@NotNull Indexable<?> indexable)
Types.hash(Iterable)
insteadindexable
- indexable for which the hash code is required@NotNull static <E> Indexable<E> withCachedHash(@NotNull Indexable<E> indexable)
The wrapped indexable must not change after it is wrapped, otherwise strange things are expected to happen.
E
- element type of indexableindexable
- wrapped indexable, must not changeindexable
, but also provides
useful implementations for Object.hashCode()
, Object.equals(Object)
,
and Object.toString()
@NotNull static <C> Indexable<C> viewTuple(@NotNull ITuple2<? extends C,? extends C> tuple)
C
- common super type of the tuple's typestuple
- tuple to view@NotNull static <C> Indexable<C> viewTuple(@NotNull ITuple3<? extends C,? extends C,? extends C> tuple)
C
- common super type of the tuple's typestuple
- tuple to view@NotNull static <C> Indexable<C> viewTuple(@NotNull ITuple4<? extends C,? extends C,? extends C,? extends C> tuple)
C
- common super type of the tuple's typestuple
- tuple to view@NotNull static <C> Indexable<C> viewTuple(@NotNull ITuple5<? extends C,? extends C,? extends C,? extends C,? extends C> tuple)
C
- common super type of the tuple's typestuple
- tuple to view@NotNull static <C> Indexable<C> viewTuple(@NotNull ITuple6<? extends C,? extends C,? extends C,? extends C,? extends C,? extends C> tuple)
C
- common super type of the tuple's typestuple
- tuple to view@NotNull static <C> Indexable<C> viewTuple(@NotNull ITuple7<? extends C,? extends C,? extends C,? extends C,? extends C,? extends C,? extends C> tuple)
C
- common super type of the tuple's typestuple
- tuple to view@NotNull static <C> Indexable<C> viewTuple(@NotNull ITuple8<? extends C,? extends C,? extends C,? extends C,? extends C,? extends C,? extends C,? extends C> tuple)
C
- common super type of the tuple's typestuple
- tuple to view@NotNull static <C> Indexable<C> viewTuple(@NotNull ITuple9<? extends C,? extends C,? extends C,? extends C,? extends C,? extends C,? extends C,? extends C,? extends C> tuple)
C
- common super type of the tuple's typestuple
- tuple to view