de.caff.generics

## Interface Indexable<T>

- Type Parameters:
    `T` - type parameter
  All Superinterfaces:
    Countable<T>, java.lang.Iterable<T>, Sizeable
  All Known Subinterfaces:
    ExpandableIndexable<T>, MultiIndexLinearizer.Sequencer, MutableIndexable<T>, OneDimensionalAccess<T>, OneDimensionalBooleanAccess, OneDimensionalBooleanReadAccess, OneDimensionalByteAccess, OneDimensionalByteReadAccess, OneDimensionalCharAccess, OneDimensionalCharReadAccess, OneDimensionalDoubleAccess, OneDimensionalDoubleReadAccess, OneDimensionalFloatAccess, OneDimensionalFloatReadAccess, OneDimensionalIntAccess, OneDimensionalIntReadAccess, OneDimensionalLongAccess, OneDimensionalLongReadAccess, OneDimensionalReadAccess<T>, OneDimensionalShortAccess, OneDimensionalShortReadAccess
  All Known Implementing Classes:
    Indexable.Base, IntPartitions.Partition, MultiIndexLinearizer.BasicSequencer, MutableIndexable.Base, OneDimensionalArray, OneDimensionalBooleanArray, OneDimensionalBooleanReadAccess.Base, OneDimensionalByteArray, OneDimensionalByteReadAccess.Base, OneDimensionalCharArray, OneDimensionalCharReadAccess.Base, OneDimensionalDoubleArray, OneDimensionalDoubleReadAccess.Base, OneDimensionalFloatArray, OneDimensionalFloatReadAccess.Base, OneDimensionalIntArray, OneDimensionalIntReadAccess.Base, OneDimensionalLongArray, OneDimensionalLongReadAccess.Base, OneDimensionalReadAccess.Base, OneDimensionalShortArray, OneDimensionalShortReadAccess.Base, SemVer.Prerelease

      public interface Indexable<T>
      extends Countable<T>

  Class which allows readonly access by index.

  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.

  ## Factory Methods

  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.

  Since:
    December 04, 2018
  Author:
    Rammi
  See Also:
    `FastSequenceSearch`

- - ### Nested Class Summary

    Nested Classes
    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.

  - ### Field Summary

    Fields
    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.

    - ### Fields inherited from interface de.caff.generics.Sizeable

      `NULL`

  - ### Method Summary

    All Methods Static Methods Instance Methods Abstract Methods Default Methods Deprecated Methods
    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)` Combine a set of indexables into one large indexable.
    `static <E> int` | `compare(Indexable<? extends E> indexable1, Indexable<? extends E> indexable2, java.util.Comparator<E> comparator)` Deprecated. use `Types.lexicalCompare(Iterable, Iterable, Comparator)` instead
    `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. use `Countable.equal(Countable, Countable, BiPredicate)` instead
    `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> Indexable<T>` | `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> int` | `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> int` | `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> T` | `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> void` | `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.
    `static <E,X extends java.lang.Exception> Indexable<E>` | `initFragile(int size, FragileFunction0<E,X> creator)` Initialize an indexable to a given size while allowing exceptions.
    `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 subset 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. use `Countable.toString(Countable)`
    `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 Dict<java.lang.Integer,T>` | `viewAsDict()` Get a view of this indexable which behaves like a dictionary with `Integer` keys.
    `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> Indexable<R>` | `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>` | `withPrependedItem(T item)` Return a view of this countable which has the given item prepended.
    `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.

    - ### Methods inherited from interface de.caff.generics.Countable

      `addAllTo, combined, combined, containsEq, containsRef, downCast, empty, equal, equals, filtered, filteredToIndexable, filterToCountable, firstOrNull, foldLeft, forEachFragile, freeze, frozen, frozen, getAny, groupingBy, groupingBy, hasAll, hasAny, isSorted, isStrictlySorted, lastOrNull, mappingBy, mappingBy, optFirst, optLast, orderedCombination, parellelStream, sorted, stream, toArray, toArray, toList, toString, uniform, viewCollection, viewCollection, viewCollectionN, viewCollectionN`

    - ### Methods inherited from interface java.lang.Iterable

      `forEach`

    - ### Methods inherited from interface de.caff.generics.Sizeable

      `size`

- - ### Field Detail

    - #### EMPTY_INDEXABLE_STRING

          static final java.lang.String EMPTY_INDEXABLE_STRING

      String representation of an empty indexable.
      See Also:
        Constant Field Values

    - #### EMPTY

          @NotNull
          static final Indexable<?> EMPTY

      An empty indexable. Use `emptyIndexable()` instead for compiler-safe access.

  - ### Method Detail

    - #### get

          T get(int index)

      Get the element at the given index.
      Parameters:
        `index` - index between `0` and `size() - 1`
      Returns:
        element at the given index

    - #### checkIndex

          static void checkIndex(int idx,
                                 int size)

      Check the index if it is between 0 (included) and the given size (excluded). Throw an exception if not.
      Parameters:
        `idx` - index to check
        `size` - size of indexable
      Throws:
        `java.lang.IndexOutOfBoundsException` - if `idx` is outside range

    - #### gyt

          default T gyt(int index)

      Pythonesque get. This allows accessing elements from the back by using negative indexes, e.g. `-1` references the last element, `-2` its predecessor, and so on.
      Parameters:
        `index` - index between `-size()` and `size() - 1`
      Returns:
        element at the given index

    - #### getMod

          default T getMod(int index)

      Get an element modulo size.

      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.

      Parameters:
        `index` - index, possibly out of range, possibly even negative for Pythonesque access
      Returns:
        element at the given, possibly modulated, index

    - #### reverse

          @NotNull
          default Indexable<T> reverse()

      Get this indexable but with inverted order.
      Returns:
        a view of this indexable which accesses the elements in reverse order

    - #### isEmpty

          default boolean isEmpty()

      Is this indexable empty?
      Specified by:
        `isEmpty` in interface `Countable<T>`
      Returns:
        `true`: there are no elements in this indexable
        `false`: this indexable has elements

    - #### iterator

          @NotNull
          default java.util.Iterator<T> iterator()

      Returns an iterator over elements of type `T`.
      Specified by:
        `iterator` in interface `java.lang.Iterable<T>`
      Returns:
        an Iterator.

    - #### iterator

          @NotNull
          default java.util.Iterator<T> iterator(int fromIndex,
                                                          int toIndex)

      Get a subset iterator.
      Parameters:
        `fromIndex` - start index
        `toIndex` - end index
      Returns:
        subset iterator

    - #### listIterator

          @NotNull
          default java.util.ListIterator<T> listIterator()

      Returns a list iterator over elements of type `T`.
      Returns:
        a list iterator.

    - #### first

          default T first()

      Description copied from interface: `Countable`
      Get the first element.
      Specified by:
        `first` in interface `Countable<T>`
      Returns:
        first element in this countable
      See Also:
        `Countable.firstOrNull()`, `Countable.optFirst()`

    - #### last

          default T last()

      Description copied from interface: `Countable`
      Get the last element. In the base implementation iterates over all elements in this countable to reach the last element.
      Specified by:
        `last` in interface `Countable<T>`
      Returns:
        last element in this countable
      See Also:
        `Countable.lastOrNull()`, `Countable.optLast()`

    - #### subSet

          @NotNull
          default Indexable<T> subSet(int fromIndex,
                                               int toIndex)

      Get an indexable subset. The subset includes indices `fromIndex` to `toIndex - 1`.
      Parameters:
        `fromIndex` - start index of sub set
        `toIndex` - index after last index
      Returns:
        indexable subset view of this indexable

    - #### sybSet

          @NotNull
          default Indexable<T> sybSet(int fromIndex,
                                               int toIndex)

      Get an indexable subset. This is the Pythonesque version which allows negative indexes.
      Parameters:
        `fromIndex` - start index of sub set
        `toIndex` - end index of sub set
      Returns:
        indexable subset view of this indexable set

    - #### tailSet

          @NotNull
          default Indexable<T> tailSet(int fromIndex)

      Create an indexable subset from the last elements of this indexable set. This already allows Pythonesquew indexing.
      Parameters:
        `fromIndex` - index to start with, negative counts from the back
      Returns:
        indexable subset view of this indexable set

    - #### headSet

          @NotNull
          default Indexable<T> headSet(int toIndex)

      Create an indexable subset from the last elements of this indexable set. This already allows Pythonesquew indexing.
      Parameters:
        `toIndex` - index one after the end (equal to the length of the returned set), negative counts from the back
      Returns:
        indexable subset view of this indexable set

    - #### viewAsDict

          @NotNull
          default Dict<java.lang.Integer,T> viewAsDict()

      Get a view of this indexable which behaves like a dictionary with `Integer` keys. The valid keys are `0` to `size() - 1`.

      As the returned value is a view, it will reflect all changes of this indexable. To avoid this either `freeze this indexable` and call this method on the result, or `freeze the returned Dict`. The former is usually preferable as this may already be frozen, and then freezing will just return `this`.

      Returns:
        dictionary view of this indexable

    - #### asCollection

          @NotNull
          default java.util.Collection<T> asCollection()

      Get a view on this indexable as an unmodifiable collection. This is especially useful for conversion to standard collection classes, eg for adding all elements via `Collection.addAll(Collection)`.
      Specified by:
        `asCollection` in interface `Countable<T>`
      Returns:
        collection view

    - #### asList

          @NotNull
          default java.util.List<T> asList()

      Get a view of this indexable as an unmodifiable list. This is especially useful for conversion to standard collection classes, eg for adding all elements via `Collection.addAll(Collection)` (but have a look at `Countable.addAllTo(Collection)`).
      Returns:
        collection view
      See Also:
        `Countable.toList()`

    - #### indexes

          @NotNull
          default java.lang.Iterable<java.lang.Integer> indexes()

      Get the indexes of this indexable as an iterable range.
      Returns:
        iterable indexes
      See Also:
        `intIndexes()`, `Range.indexes(int)`

    - #### intIndexes

          @NotNull
          default IntIndexable intIndexes()

      Get the valid set of indexes as in integer indexable.
      Returns:
        indexable indices of this indexable
      See Also:
        `indexes()`, `IntIndexable.rangeFromSize(int)`

    - #### view

          @NotNull
          default <E> Indexable<E> view(@NotNull
                                                 java.util.function.Function<? super T,? extends E> mapper)

      View this indexable as if it has another type.
      Specified by:
        `view` in interface `Countable<T>`
      Type Parameters:
        `E` - element type of returned view
      Parameters:
        `mapper` - mapper used to convert the element type of this indexable to the expected type, will be applied on each access
      Returns:
        view of this indexable with mapped elements, so any changes of this indexable will be reflected by the returned indexable. Use `Countable.frozen()` on the resulting indexable to change this.

    - #### viewFragile

          @NotNull
          default <R,E extends java.lang.Exception> Indexable<R> viewFragile(@NotNull
                                                                                      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.

      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!");
               }
             }

      Specified by:
        `viewFragile` in interface `Countable<T>`
      Type Parameters:
        `R` - target type of the elements of the returned indexable
        `E` - possible exception thrown by `mapper`
      Parameters:
        `mapper` - mapper from incoming to outgoing objects which might throw an exception
      Returns:
        lazy view of this indexable which will seem to contain target type elements

    - #### indexedView

          @NotNull
          default <E> Indexable<E> indexedView(@NotNull
                                                        java.util.function.BiFunction<? super java.lang.Integer,? super T,? extends E> mapper)

      View this indexable as if it has another type. Compared to `view(Function)` this calls the mapper with an additional index argument.
      Type Parameters:
        `E` - element type of returned view
      Parameters:
        `mapper` - 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 indexable
      Returns:
        view of this indexable with mapped elements, so any changes of this indexable will be reflected by the returned indexable. Use `Countable.frozen()` on the resulting indexable to change this.

    - #### addToArray

          default int addToArray(@NotNull
                                 T[] array,
                                 int arrayPos,
                                 int index,
                                 int length)

      Add a part of the content of this indexable to the given array.
      Parameters:
        `array` - array where the content is added
        `arrayPos` - start position in the array where the content is added
        `index` - start index of this indexable which is added first
        `length` - number of entries of this indexable added to the array
      Returns:
        array position after the added content

    - #### addToArray

          default int addToArray(@NotNull
                                 T[] array,
                                 int arrayPos)

      Add the complete content of this indexable to the gien array.
      Specified by:
        `addToArray` in interface `Countable<T>`
      Parameters:
        `array` - array where the content is added
        `arrayPos` - start position in hte array where the content is added
      Returns:
        array position after the added content

    - #### addToCollection

          @Deprecated
          default void addToCollection(@NotNull
                                                   java.util.Collection<? super T> collection)

      Deprecated. use `Countable.addAllTo(Collection)` instead
      Add all elements of this indexable to the given collection.
      Parameters:
        `collection` - collection for collecting this indexable

    - #### forEachEntry

          default void forEachEntry(@NotNull
                                    java.util.function.BiConsumer<java.lang.Integer,? super T> action)

      Call an action for each entry. This is similar to `Iterable.forEach(Consumer)`, but also provides the index.
      Parameters:
        `action` - action which will be called for each entry with index and element at that index
      See Also:
        `forEachEntryFragile(FragileProcedure2)`, `Iterable.forEach(Consumer)`

    - #### forEachEntryFragile

          default <E extends java.lang.Exception> void forEachEntryFragile(@NotNull
                                                                           FragileProcedure2<E,java.lang.Integer,? super T> action)
                                                                    throws E extends java.lang.Exception

      Call a fragile action for each entry. This is similar to `forEachEntry(BiConsumer)` but allows an action which might throw an exception.
      Type Parameters:
        `E` - exception type
      Parameters:
        `action` - action which will be called for each entry with index and associated element, might throw an exception
      Throws:
        `E` - if `action` throws
        `E extends java.lang.Exception`

    - #### spliterator

          @NotNull
          default java.util.Spliterator<T> spliterator()

      Get a spliterator on this indexable. The returned spliterator will not have its `Spliterator.IMMUTABLE` flag set, see `frozenSpliterator()` for an alternative.
      Specified by:
        `spliterator` in interface `Countable<T>`
      Specified by:
        `spliterator` in interface `java.lang.Iterable<T>`
      Returns:
        a spliterator on this indexable

    - #### frozenSpliterator

          @NotNull
          default java.util.Spliterator<T> frozenSpliterator()

      Get an immutable spliterator on a frozen copy of this indexable. If this indexable is already immutable (i.e. if `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.
      Returns:
        an "immutable" spliterator with the possible cost of copying this indexable

    - #### isOrdered

          default boolean isOrdered(@NotNull
                                    Ordering<? super T> order)

      Is this indexable sorted according to the given ordering? This method tests that consecutive elements in this indexable or either ascending or the same, but never descending. See isStrictlyOrdered(Ordering) for a stricter alternative.
      Parameters:
        `order` - expected ordering
      Returns:
        `true` if this indexable is sorted as defined by `order`
        `false` if not

    - #### isStrictlyOrdered

          default boolean isStrictlyOrdered(@NotNull
                                            Ordering<? super T> order)

      Is this indexable strictly sorted according to the given ordering? This method tests that consecutive elements in this indexable or strictly ascending or the same, but never descending. See isOrdered(Ordering) for a more relaxed alternative.
      Parameters:
        `order` - expected ordering
      Returns:
        `true` if this indexable is sorted as defined by `order`
        `false` if not

    - #### binarySearch

          default int binarySearch(T value,
                                   @NotNull
                                   Ordering<? super T> order)

      Do a binary search in an ordered indexable. This requires this indexable to be ordered in non-descending order as defined by the given `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.
      Parameters:
        `value` - value to look up
        `order` - sort order
      Returns:
        a positive integer defining the index where the given value was found, and a negative integer if the value is not contained. The latter defines the insertion point where the looked up value would match into this sorted indexable in the form `-(insertIndex + 1)`.

    - #### ordered

          @NotNull
          default MutableIndexable<T> ordered(@NotNull
                                                       Ordering<? super T> order)

      Create a (mutable) double indexable from the values of this indexable which is ordered as defined by the given ordering.
      Parameters:
        `order` - sort order
      Returns:
        independent indexable with sorted values

    - #### asBase

          @NotNull
          default Indexable.Base<T> asBase()

      Convert this into a base indexable. Base indexables have useful default implementation for `Object.equals(Object)`, `Object.hashCode()`, and `Object.toString()`.
      Specified by:
        `asBase` in interface `Countable<T>`
      Returns:
        base indexable

    - #### findFirst

          default int findFirst(T element)

      Do a linear forward search from the beginning. This uses `Objects.deepEquals(Object, Object)` for checking if a given element is the same as the searched one.
      Parameters:
        `element` - element to look for
      Returns:
        index found (non-pythonesque), `-1` if nothing was found

    - #### findNext

          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. This uses `Objects.deepEquals(Object, Object)` for checking if a given element is the same as the searched one.
      Parameters:
        `element` - element to look for
        `start` - start index to look from, pythonesque
      Returns:
        index found (non-pythonesque), `-1` if nothing was found

    - #### findFirst

          default <U> int findFirst(U object,
                                    @NotNull
                                    Matcher<? super U,? super T> equality)

      Do a linear forward search from an element (or a substitute) from the beginning.
      Type Parameters:
        `U` - type of search element
      Parameters:
        `object` - element to look for
        `equality` - equality check used
      Returns:
        index found (non-pythonesque), `-1` if nothing was found

    - #### findNext

          default <U> int findNext(U object,
                                   @NotNull
                                   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.
      Type Parameters:
        `U` - pattern object type, depending on the matcher this may differ from the element type
      Parameters:
        `object` - element to look for
        `equality` - equality check used
        `start` - start index to look from, pythonesque
      Returns:
        index found (non-pythonesque), `-1` if nothing was found

    - #### findFirst

          default int findFirst(@NotNull
                                java.util.function.Predicate<? super T> matcher)

      Do a linear forward search from the beginning.
      Parameters:
        `matcher` - test which returns `true` when a matching element is found
      Returns:
        index found (non-pythonesque), `-1` if nothing was found

    - #### findFirstX

          default <X extends java.lang.Exception> int findFirstX(@NotNull
                                                                 FragilePredicate1<X,? super T> matcher)
                                                          throws X extends java.lang.Exception

      Do a linear forward search from the beginning. This method accepts a matcher which might throw a checked exception.
      Type Parameters:
        `X` - exception type thrown by matcher
      Parameters:
        `matcher` - test which returns `true` when a matching element is found
      Returns:
        index found (non-pythonesque), `-1` if nothing was found
      Throws:
        `X` - if `matcher` throws
        `X extends java.lang.Exception`

    - #### findNext

          default int findNext(@NotNull
                               java.util.function.Predicate<? super T> matcher,
                               int start)

      Do a linear forward search from the beginning.
      Parameters:
        `matcher` - test which returns `true` when a matching element is found
        `start` - start index where the search begins
      Returns:
        index found (non-pythonesque), `-1` if nothing was found

    - #### findNextX

          default <X extends java.lang.Exception> int findNextX(@NotNull
                                                                FragilePredicate1<X,? super T> matcher,
                                                                int start)
                                                         throws X extends java.lang.Exception

      Do a linear forward search from the beginning.
      Type Parameters:
        `X` - exception type thrown by matcher
      Parameters:
        `matcher` - test which returns `true` when a matching element is found
        `start` - start index where the search begins
      Returns:
        index found (non-pythonesque), `-1` if nothing was found
      Throws:
        `X` - if `matcher` throws
        `X extends java.lang.Exception`

    - #### firstMatch

          @Nullable
          default T firstMatch(@NotNull
                                         java.util.function.Predicate<? super T> condition)

      Get the first element which matches a given condition.
      Parameters:
        `condition` - matching condition
      Returns:
        the first element for which the condition returns `true`, or `null` if no element fulfills the condition
      See Also:
        `Types.findFirst(Iterable, Predicate)`

    - #### firstMatchX

          @Nullable
          default <X extends java.lang.Exception> T firstMatchX(@NotNull
                                                                          FragilePredicate1<X,? super T> condition)
                                                                   throws X extends java.lang.Exception

      Get the first element which matches a given fragile condition.
      Type Parameters:
        `X` - exception type
      Parameters:
        `condition` - matching condition which might throw an exception
      Returns:
        the first element for which the condition returns `true`, or `null` if no element fulfills the condition
      Throws:
        `X` - if the condition throws
        `X extends java.lang.Exception`

    - #### firstMatch

          @Nullable
          default <R> R firstMatch(@NotNull
                                             java.util.function.Predicate<? super T> condition,
                                             @NotNull
                                             java.util.function.Function<? super T,? extends R> adaptor)

      Get an adapted value from the first element which matches a given condition. This method allows to avoid a `null` check in your code. Indexables which may contain `null` values which the `condition` considers a match should not use this method.
      Type Parameters:
        `R` - result type
      Parameters:
        `condition` - matching condition
        `adaptor` - adaptor which adapts a possible match to your needs, only called with non-null values
      Returns:
        first matching and adapted result or `null` if no match was found

    - #### findLast

          default int findLast(T element)

      Do a linear backward search from the end. This uses `Objects.deepEquals(Object, Object)` for checking if a given element is the same as the searched one.
      Parameters:
        `element` - element to look for
      Returns:
        index found (non-pythonesque), `-1` if nothing was found

    - #### findPrevious

          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. This uses `Objects.deepEquals(Object, Object)` for checking if a given element is the same as the searched one.
      Parameters:
        `element` - element to look for
        `start` - start index to look from, pythonesque, use `-1` to start with the last element
      Returns:
        index found (non-pythonesque), `-1` if nothing was found

    - #### findLast

          default <U> int findLast(U object,
                                   @NotNull
                                   Matcher<? super U,? super T> equality)

      Do a linear backward search from an element (or a substitute) from the beginning.
      Type Parameters:
        `U` - type of search element
      Parameters:
        `object` - element to look for
        `equality` - equality check used
      Returns:
        index found (non-pythonesque), `-1` if nothing was found

    - #### findPrevious

          default <U> int findPrevious(U object,
                                       @NotNull
                                       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.
      Type Parameters:
        `U` - pattern object type, depending on the matcher this may differ from the element type
      Parameters:
        `object` - element to look for
        `equality` - equality check used
        `start` - start index to look from, pythonesque
      Returns:
        index found (non-pythonesque), `-1` if nothing was found

    - #### findLast

          default int findLast(@NotNull
                               java.util.function.Predicate<? super T> matcher)

      Do a linear backward search from the beginning.
      Parameters:
        `matcher` - matcher which returns `true` when a matching element is found
      Returns:
        index of first matching element (non-pythonesque), `-1` if nothing was found

    - #### findPrevious

          default int findPrevious(@NotNull
                                   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.
      Parameters:
        `matcher` - matcher which returns `true` when a matching element is found
        `start` - start index to look from, pythonesque
      Returns:
        index of first matching element (non-pythonesque), `-1` if nothing was found

    - #### findAll

          @NotNull
          default Indexable<T> findAll(@NotNull
                                                java.util.function.Predicate<? super T> filter)

      Find all elements that fulfill a given condition. This will not return a view but a new copy containing the filtered elements.
      Parameters:
        `filter` - filter to apply
      Returns:
        filtered elements

    - #### findAllX

          @NotNull
          default <X extends java.lang.Exception> Indexable<T> findAllX(@NotNull
                                                                                 FragilePredicate1<X,? super T> filter)
                                                                          throws X extends java.lang.Exception

      Find all elements that fulfill a given condition that might throw a checked exception. This will not return a view but a new copy containing the filtered elements.
      Type Parameters:
        `X` - exception type
      Parameters:
        `filter` - filter to apply, might possibly throw
      Returns:
        filtered elements
      Throws:
        `X` - if filter throws
        `X extends java.lang.Exception`

    - #### withInsertedItemAt

          @NotNull
          default Indexable<T> withInsertedItemAt(int index,
                                                           T item)

      Create a view of this indexable with an inserted element. Note that this is not efficient, but handy in certain situations where only 1 or a few items are inserted. Use `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!

      Parameters:
        `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 index
      Returns:
        a view of this indexable with 1 more element at the given index, all elements beyond are moved one index forward
      See Also:
        `withAppendedItem(Object)`

    - #### withAppendedItem

          @NotNull
          default Indexable<T> withAppendedItem(T item)

      Create a view with of this indexable with another item added at the end. Note that this is not efficient, but handy in certain situations where only 1 or a few items are added.
      Specified by:
        `withAppendedItem` in interface `Countable<T>`
      Parameters:
        `item` - item to add
      Returns:
        indexable view of this indexable, with the given item added at the end, so size is larger by 1
      See Also:
        `withInsertedItemAt(int, Object)`

    - #### withPrependedItem

          @NotNull
          default Indexable<T> withPrependedItem(T item)

      Description copied from interface: `Countable`
      Return a view of this countable which has the given item prepended.
      Specified by:
        `withPrependedItem` in interface `Countable<T>`
      Parameters:
        `item` - item to appear first when iterating
      Returns:
        a view of this countable with the given item prepended

    - #### withExchangedItemAt

          @NotNull
          default Indexable<T> withExchangedItemAt(int index,
                                                            T value)

      Create a view of this indexable with an exchanged element. Note that this is not efficient, but handy in certain situations where only one or a few items are exchanged. Use `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!

      Parameters:
        `index` - index where the element is exchanged, hiding the current element. (Pythonesque)
        `value` - exchanged value at that index
      Returns:
        a view of this indexable with 1 more element at the given index, all elements beyond are moved one index forward

    - #### withRemovedItemAt

          @NotNull
          default Indexable<T> withRemovedItemAt(int index)

      Create a view of this indexable with one item removed. Note that this is not efficient, but handy in certain situations where only one or a few items are removed.
      Parameters:
        `index` - index of the removed element (Pythonesque)
      Returns:
        a view of this indexable where the item at the given index is removed

    - #### withSwappedItemsAt

          @NotNull
          default Indexable<T> withSwappedItemsAt(int index1,
                                                           int index2)

      Create a view of this indexable with two items swapped. Note that this is not efficient, but handy in certain situations where only a few items are swapped.
      Parameters:
        `index1` - index of the first element (Pythonesque)
        `index2` - index of the second element (Pythonesque)
      Returns:
        a view of this indexable where the first and second element have exchanged places

    - #### rotated

          @NotNull
          default Indexable<T> rotated(int steps)

      Get a rotated view of this indexable. The returned indexable will show this indexable with rotated indexes. A positive `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`.
      Parameters:
        `steps` - steps to rotate
      Returns:
        rotated view of this indexable, use `Countable.frozen()` to create an indexable which no longer depends on this one

    - #### viewAsDoubleIndexable

          @NotNull
          default DoubleIndexable viewAsDoubleIndexable(@NotNull
                                                                 java.util.function.ToDoubleFunction<? super T> extractor)

      View this indexable as a double indexable.
      Parameters:
        `extractor` - extractor for double values
      Returns:
        double indexable view of this indexable

    - #### viewAsFloatIndexable

          @NotNull
          default FloatIndexable viewAsFloatIndexable(@NotNull
                                                               ToFloatFunction<? super T> extractor)

      View this indexable as a float indexable.
      Parameters:
        `extractor` - extractor for float values
      Returns:
        float indexable view of this indexable

    - #### viewAsLongIndexable

          @NotNull
          default LongIndexable viewAsLongIndexable(@NotNull
                                                             java.util.function.ToLongFunction<? super T> extractor)

      View this indexable as a long indexable.
      Parameters:
        `extractor` - extractor for long values
      Returns:
        long indexable view of this indexable

    - #### viewAsIntIndexable

          @NotNull
          default IntIndexable viewAsIntIndexable(@NotNull
                                                           java.util.function.ToIntFunction<? super T> extractor)

      View this indexable as an integer indexable.
      Parameters:
        `extractor` - extractor for integer values
      Returns:
        integer indexable view of this indexable

    - #### viewAsShortIndexable

          @NotNull
          default ShortIndexable viewAsShortIndexable(@NotNull
                                                               ToShortFunction<? super T> extractor)

      View this indexable as a short indexable.
      Parameters:
        `extractor` - extractor for short values
      Returns:
        short indexable view of this indexable

    - #### viewAsCharIndexable

          @NotNull
          default CharIndexable viewAsCharIndexable(@NotNull
                                                             ToCharFunction<? super T> extractor)

      View this indexable as a char indexable.
      Parameters:
        `extractor` - extractor for char values
      Returns:
        char indexable view of this indexable

    - #### viewAsByteIndexable

          @NotNull
          default ByteIndexable viewAsByteIndexable(@NotNull
                                                             ToByteFunction<? super T> extractor)

      View this indexable as a byte indexable.
      Parameters:
        `extractor` - extractor for byte values
      Returns:
        byte indexable view of this indexable

    - #### viewAsBooleanIndexable

          @NotNull
          default BooleanIndexable viewAsBooleanIndexable(@NotNull
                                                                   java.util.function.Predicate<? super T> extractor)

      View this indexable as a boolean indexable.
      Parameters:
        `extractor` - extractor for boolean values
      Returns:
        boolean indexable view of this indexable

    - #### fromList

          @NotNull
           @Deprecated
          static <E> Indexable<E> fromList(@NotNull
                                                                 java.util.List<? extends E> list)

      Deprecated. this was inconsistently named, use `viewList(List)` instead
      View a list 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 `viewList(List, Function)`.

      Type Parameters:
        `E` - element type
      Parameters:
        `list` - list used as a base
      Returns:
        indexable view of the given list, so any changes of the list will be reflected by the returned Indexable

    - #### viewList

          @NotNull
          static <E> Indexable<E> viewList(@NotNull
                                                    java.util.List<? extends E> list)

      View a list 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 `viewList(List, Function)`.

      You should only view larger lists when they are `random accessible`. It is strongly recommended to `freeze` views of other list types (like `LinkedList`) immediately.

      The only guarantee given for non-random-accessible lists is that iterating is fast. Using other methods of this interface might become awfully slow for non-random-accessible lists!

      Type Parameters:
        `E` - element type
      Parameters:
        `list` - list used as a base
      Returns:
        indexable view of the given list, so any changes of the list will be reflected by the returned Indexable

    - #### viewListN

          @NotNull
          static <E> Indexable<E> viewListN(@Nullable
                                                     java.util.List<? extends E> list)

      View a list which is possibly `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)`.

      Type Parameters:
        `E` - element type
      Parameters:
        `list` - list used as a base
      Returns:
        indexable view of the given list, so any changes of the list will be reflected by the returned Indexable, or an empty indexable if `list` is `null`

    - #### viewList

          @NotNull
          static <E,V> Indexable<E> viewList(@NotNull
                                                      java.util.List<V> list,
                                                      @NotNull
                                                      java.util.function.Function<? super V,? extends E> mapper)

      View a list as an indexable of another type.

      The mapper function will be applied on each access. So it is strongly recommended to `freeze` the result of this method if it is used more than once.

      You should only view larger lists when they are `random accessible`. It is strongly recommended to `freeze` views of other list types (like `LinkedList`) immediately. The implementation takes care to make iteration fast.

      The only guarantee given for non-random-accessible lists is that iterating is fast. Using other methods of this interface might become awfully slow for non-random-accessible lists!

      Type Parameters:
        `E` - element type of this indexable
        `V` - element type of the list
      Parameters:
        `list` - list to view
        `mapper` - mapper from list element type to the element type of this indexable, it will be applied for each access
      Returns:
        indexable view of the given list, so any changes of the list will be reflected by the returned indexable

    - #### viewListN

          @NotNull
          static <E,V> Indexable<E> viewListN(@Nullable
                                                       java.util.List<V> list,
                                                       @NotNull
                                                       java.util.function.Function<? super V,? extends E> mapper)

      View a list as an indexable of another type.

      Compared to viewList(List, Function) this accepts `null` for the list which is occasionally handy.

      Type Parameters:
        `E` - element type of this indexable
        `V` - element type of the list
      Parameters:
        `list` - list to view
        `mapper` - mapper from list element type to the element type of this indexable, will be applied for each access
      Returns:
        indexable view of the given list, so any changes of the list will be reflected by the returned indexable, or an empty indexable if `list` is `null`

    - #### fromArray

          @SafeVarargs
           @NotNull
           @Deprecated
          static <E> Indexable<E> fromArray(@NotNull
                                                                                E... array)

      Deprecated. this was inconsistently named, use `viewArray(Object[])` instead
      View an array as an Indexable. To view only part of the array use `subSet(int, int)`.
      Type Parameters:
        `E` - element type
      Parameters:
        `array` - array used as base
      Returns:
        indexable view of the given array, any changes to the underlying array will be reflected by the returned Indexable

    - #### viewArray

          @SafeVarargs
           @NotNull
          static <E> Indexable<E> viewArray(@NotNull
                                                                   E... array)

      View an array as an Indexable. To view only part of the array use `subSet(int, int)`.
      Specified by:
        `viewArray` in interface `Countable<T>`
      Type Parameters:
        `E` - element type
      Parameters:
        `array` - array used as base
      Returns:
        indexable view of the given array, any changes to the underlying array will be reflected by the returned Indexable

    - #### viewArray

          @NotNull
          static <E> Indexable<E> viewArray(@NotNull
                                                     E[] array,
                                                     int start,
                                                     int len)

      View a slice of an array.
      Specified by:
        `viewArray` in interface `Countable<T>`
      Type Parameters:
        `E` - array type
      Parameters:
        `array` - array to view
        `start` - start of array slice represented by the returned indexable
        `len` - length of array slice represented by the returned indexable
      Returns:
        indexable view of the given array slice, basically the same as `Indexable.viewArray(array).subset(start, start + len)`

    - #### fromCollection

          @NotNull
          static <E> Indexable<E> fromCollection(@NotNull
                                                          java.util.Collection<? extends E> collection)

      Convert a collection into an indexable. This will collect all elements from the `collection` and return them as an indexable.
      Type Parameters:
        `E` - element type of the returned indexable, base type of the type of the incoming collection
      Parameters:
        `collection` - collection to iterate over
      Returns:
        indexable created from the collection

    - #### fromCollection

          @NotNull
          static <E,V> Indexable<E> fromCollection(@NotNull
                                                            java.util.Collection<V> collection,
                                                            @NotNull
                                                            java.util.function.Function<? super V,? extends E> mapper)

      Convert a collection into an indexable. This will iterate over the given `collection`, get its elements, convert them using the `mapper`, and return the result as an indexable.
      Type Parameters:
        `E` - element type of the returned indexable
        `V` - element type of the incoming iterable
      Parameters:
        `collection` - collection to iterate over
        `mapper` - mapper from incoming element type to outgoing element type
      Returns:
        indexable created from the collection

    - #### fromCountable

          @NotNull
          static <E> Indexable<E> fromCountable(@NotNull
                                                         Countable<? extends E> countable)

      Convert a countable into an indexable. This will collect all elements from the `countable` and return them as an indexable.
      Type Parameters:
        `E` - element type of the returned indexable, base type of the type of the incoming countable
      Parameters:
        `countable` - countable to iterate over
      Returns:
        indexable created from the countable

    - #### fromCountable

          @NotNull
          static <E,V> Indexable<E> fromCountable(@NotNull
                                                           Countable<V> countable,
                                                           @NotNull
                                                           java.util.function.Function<? super V,? extends E> mapper)

      Convert a countable into an indexable. This will iterate over the given `countable`, get its elements, convert them using the `mapper`, and return the result as an indexable.
      Type Parameters:
        `E` - element type of the returned indexable
        `V` - element type of the incoming iterable
      Parameters:
        `countable` - countable to iterate over
        `mapper` - mapper from incoming element type to outgoing element type
      Returns:
        indexable created from the countable

    - #### fromIterable

          @NotNull
          static <E> Indexable<E> fromIterable(@NotNull
                                                        java.lang.Iterable<? extends E> iterable)

      Convert an iterable into an indexable. This will collect all elements from the `iterable` and return them as an indexable.
      Type Parameters:
        `E` - element type of the returned indexable, base type of the type of the incoming iterable
      Parameters:
        `iterable` - iterable to iterate over
      Returns:
        indexable created from the iterable

    - #### fromIterator

          @NotNull
          static <E> Indexable<E> fromIterator(@NotNull
                                                        java.util.Iterator<? extends E> iterator)

      Convert an iterator to an indexable.
      Type Parameters:
        `E` - element type of the returned indexable, base type of the type of the incoming iterator
      Parameters:
        `iterator` - iterator consumed by this method
      Returns:
        indexable created from the iterator

    - #### fromIterable

          @NotNull
          static <E,V> Indexable<E> fromIterable(@NotNull
                                                          java.lang.Iterable<V> iterable,
                                                          @NotNull
                                                          java.util.function.Function<? super V,? extends E> mapper)

      Convert an iterable into an indexable. This will iterate over the given `iterable`, get its elements, convert them using the `mapper`, and return the result as an indexable.
      Type Parameters:
        `E` - element type of the returned indexable
        `V` - element type of the incoming iterable
      Parameters:
        `iterable` - iterable to iterate over
        `mapper` - mapper from incoming element type to outgoing element type
      Returns:
        indexable created from the iterable

    - #### fromIterable

          @NotNull
          static <E> Indexable<E> fromIterable(@NotNull
                                                        java.lang.Iterable<? extends E> iterable,
                                                        int size)

      Convert an iterable into an indexable. This will collect all elements from the `iterable` and return them as an indexable.
      Type Parameters:
        `E` - element type of the returned indexable, base type of the type of the incoming iterable
      Parameters:
        `iterable` - iterable to iterate over
        `size` - expected size of the iterable, use `0` or negative for unknonw
      Returns:
        indexable created from the iterable

    - #### fromIterable

          @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)

      Convert an iterable into an indexable. This will iterate over the given `iterable`, get its elements, convert them using the `mapper`, and return the result as an indexable.
      Type Parameters:
        `E` - element type of the returned indexable
        `V` - element type of the incoming iterable
      Parameters:
        `iterable` - iterable to iterate over
        `size` - expected size of the iterable, use `0` or negative for unknown
        `mapper` - mapper from incoming element type to outgoing element type
      Returns:
        indexable created from the iterable

    - #### fromEnumeration

          @NotNull
          static <E> Indexable<E> fromEnumeration(@NotNull
                                                           java.util.Enumeration<? extends E> enumeration,
                                                           int size)

      Convert an enumeration into an indexable. This will collect all elements from the `enumeration` and return them as an indexale.
      Type Parameters:
        `E` - element type of the returned indexable, base type of the type of the incoming enumeration
      Parameters:
        `enumeration` - enumeration to iterate over
        `size` - expected size of the enumeration, use `0` or negative for unknonw
      Returns:
        indexable created from the enumeration

    - #### fromEnumeration

          @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)

      Convert an enumeration into an indexable. This will iterate over the given `enumeration`, get its elements, convert them using the `mapper`, and return the result as an indexable.
      Type Parameters:
        `E` - element type of the returned indexable
        `V` - element type of the incoming enumeration
      Parameters:
        `enumeration` - enumeration to iterate over
        `size` - expected size of the enumeration, use `0` or negative for unknown
        `mapper` - mapper from incoming element type to outgoing element type
      Returns:
        indexable created from the enumeration

    - #### downCast

          @NotNull
          static <E> Indexable<E> downCast(@NotNull
                                                    Indexable<? extends E> indexable)

      Downcast an indexable of a given type so that it appears at an indexable of a super type. This method does nothing, it only returns its argument. But using it keeps the compiler happy.

      Downcasting indexables is no problem, as they don't allow adding new elements.

      Example:

      >      Indexable<String> a = Indexable.viewArray("a", "b", "c");
      >      Indexable<Object> b = Indexable.downCast(a); // no compiler warning here
      >      assert a == b;

      Type Parameters:
        `E` - target type of returned indexable
      Parameters:
        `indexable` - indexable to be downcasted, needs to have a type which extends or implements `<E>`
      Returns:
        `indexable`, but using a different element type

    - #### singleton

          @NotNull
          static <E> Indexable<E> singleton(E singleElement)

      Create an indexable with only one element.
      Specified by:
        `singleton` in interface `Countable<T>`
      Type Parameters:
        `E` - element type
      Parameters:
        `singleElement` - single element
      Returns:
        indexable view of the given element

    - #### optional

          @NotNull
          static <E> Indexable<E> optional(@Nullable
                                                    E optionalElement)

      Get an indexable with a single or no element.
      Specified by:
        `optional` in interface `Countable<T>`
      Type Parameters:
        `E` - element type
      Parameters:
        `optionalElement` - optional element
      Returns:
        indexable with size 1 with the given element if it is not `null`, or an empty countable if it is `null`

    - #### fromOptional

          @NotNull
          static <E> Indexable<E> fromOptional(@NotNull
                                                        java.util.Optional<E> optional)

      Convert a standard Optional to an Indexable with either one or no element.
      Specified by:
        `fromOptional` in interface `Countable<T>`
      Type Parameters:
        `E` - optional/indexable type
      Parameters:
        `optional` - optional to convert to indexable
      Returns:
        indexable with either 1 element (if the optional has an element) or 0 elements (if the optional has no element)

    - #### mapArray

          @NotNull
           @SafeVarargs
          static <E,V> Indexable<E> mapArray(@NotNull
                                                                    java.util.function.Function<? super V,? extends E> mapper,
                                                                    @NotNull
                                                                    V... array)

      View an array as an indexable of another type.
      Type Parameters:
        `E` - element type of this indexable
        `V` - element type of the array
      Parameters:
        `array` - array to view
        `mapper` - mapper from array element type to the element type of this indexable, will be applied for each access
      Returns:
        indexable view of the given list, so any changes of the list will be reflected by the returned indexable

    - #### view

          @NotNull
          static <V> Indexable<V> view(@NotNull
                                                Indexable<? extends V> indexable)

      View an indexable as if it has entries belonging to a super class. This allows to use an indexable with a different element type in places where an indexable with a super element type is expected.
      Type Parameters:
        `V` - super type of the incoming `indexable`
      Parameters:
        `indexable` - indexable to be viewed
      Returns:
        `indexable`, but with adapted entry type

    - #### init

          @NotNull
          static <V> Indexable<V> init(int size,
                                                @NotNull
                                                java.util.function.Supplier<? extends V> producer)

      Create an indexable with a given size, and initialize its elements.
      Type Parameters:
        `V` - element type
      Parameters:
        `size` - size of the indexable
        `producer` - element producer which will be called for each element
      Returns:
        indexable with the given size containing the elements created by the producer

    - #### initFragile

          @NotNull
          static <E,X extends java.lang.Exception> Indexable<E> initFragile(int size,
                                                                                     @NotNull
                                                                                     FragileFunction0<E,X> creator)
                                                                              throws X extends java.lang.Exception

      Initialize an indexable to a given size while allowing exceptions.
      Type Parameters:
        `E` - element type
        `X` - exception type
      Parameters:
        `size` - size of indexable
        `creator` - creator for the initial elements, called in order for each element, may throw an exception
      Returns:
        indexable with the given size
      Throws:
        `X` - if `creator` throws
        `X extends java.lang.Exception`

    - #### viewByIndex

          @NotNull
          static <V> Indexable<V> viewByIndex(int size,
                                                       @NotNull
                                                       java.util.function.IntFunction<? extends V> producer)

      Create an indexable with a given size which returns its elements by calling a producer. This will always call the `producer` when an element is requested. Use `Countable.frozen()` on the result to create an indexable which avoids this.
      Type Parameters:
        `V` - element type
      Parameters:
        `size` - size of the indexable
        `producer` - element producer which will be called for each index
      Returns:
        an indexable with the given size which will return elements by calling the `producer`
      See Also:
        `initByIndex(int, IntFunction)`

    - #### initByIndex

          @NotNull
          static <V> Indexable<V> initByIndex(int size,
                                                       @NotNull
                                                       java.util.function.IntFunction<? extends V> producer)

      Create an indexable with a given size, and initialize its elements by index.
      Type Parameters:
        `V` - element type
      Parameters:
        `size` - size of the indexable
        `producer` - element producer which will be called for each index
      Returns:
        indexable with the given size containing the elements created by the producer
      See Also:
        `viewByIndex(int, IntFunction)`

    - #### emptyIndexable

          @NotNull
          static <E> Indexable.Base<E> emptyIndexable()

      Get an empty indexable set.
      Type Parameters:
        `E` - element type
      Returns:
        empty indexable

    - #### combine

          @NotNull
           @SafeVarargs
          static <E> Indexable<E> combine(@NotNull
                                                                 Indexable<? extends E>... parts)

      Combine a set of indexables into one large indexable.
      Type Parameters:
        `E` - element type of the returned indexable
      Parameters:
        `parts` - parts of the returned indexable
      Returns:
        combined indexable

    - #### toString

          @NotNull
           @Deprecated
          static java.lang.String toString(@NotNull
                                                                 Indexable<?> indexable)

      Deprecated. use `Countable.toString(Countable)`
      Create a string representation of the given indexable.
      Parameters:
        `indexable` - indexable
      Returns:
        string representation

    - #### equal

          @Deprecated
          static <E> boolean equal(@NotNull
                                               Indexable<? extends E> indexable1,
                                               @NotNull
                                               Indexable<? extends E> indexable2,
                                               @NotNull
                                               java.util.function.BiPredicate<E,E> equalityChecker)

      Deprecated. use `Countable.equal(Countable, Countable, BiPredicate)` instead
      Are two indexables equal?
      Type Parameters:
        `E` - parameter type of equality checker, and super class of both indexables' element type
      Parameters:
        `indexable1` - first indexable
        `indexable2` - second indexable
        `equalityChecker` - checker for equality of both objects
      Returns:
        `true` if both indexables contain the same values in the same sequence
        `false` if sizes or values differ

    - #### compare

          @Deprecated
          static <E> int compare(@NotNull
                                             Indexable<? extends E> indexable1,
                                             @NotNull
                                             Indexable<? extends E> indexable2,
                                             @NotNull
                                             java.util.Comparator<E> comparator)

      Deprecated. use `Types.lexicalCompare(Iterable, Iterable, Comparator)` instead
      Compare two indexables. This compares the two indexables lexically element by element using `comparator` 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).
      Type Parameters:
        `E` - comparator type, needs to be a base type of both indexables' element type
      Parameters:
        `indexable1` - first indexable
        `indexable2` - second indexable
        `comparator` - type
      Returns:
        `< 0>` if `indexable1 < indexable2`, `0` if `indexable1 == indexable2`, or `> 0` if `indexable1 > indexable2`

    - #### hash

          @Deprecated
          static int hash(@NotNull
                                      Indexable<?> indexable)

      Deprecated. use `Types.hash(Iterable)` instead
      Calculate a hashcode for a generic indexable.
      Parameters:
        `indexable` - indexable for which the hash code is required
      Returns:
        hash code for the given indexable

    - #### withCachedHash

          @NotNull
          static <E> Indexable<E> withCachedHash(@NotNull
                                                          Indexable<E> indexable)

      Wrap an indexable with one which caches the hash value. This is useful if indexables are used as hash keys because hash value calculation is expensive.

      The wrapped indexable must not change after it is wrapped, otherwise strange things are expected to happen.

      Type Parameters:
        `E` - element type of indexable
      Parameters:
        `indexable` - wrapped indexable, must not change
      Returns:
        indexable which forwards most methods to `indexable`, but also provides useful implementations for `Object.hashCode()`, `Object.equals(Object)`, and `Object.toString()`

    - #### viewTuple

          @NotNull
          static <C> Indexable<C> viewTuple(@NotNull
                                                     ITuple2<? extends C,? extends C> tuple)

      View a 2-element tuple as an indexable.
      Type Parameters:
        `C` - common super type of the tuple's types
      Parameters:
        `tuple` - tuple to view
      Returns:
        indexable with 2 elements

    - #### viewTuple

          @NotNull
          static <C> Indexable<C> viewTuple(@NotNull
                                                     ITuple3<? extends C,? extends C,? extends C> tuple)

      View a 3-element tuple as an indexable.
      Type Parameters:
        `C` - common super type of the tuple's types
      Parameters:
        `tuple` - tuple to view
      Returns:
        indexable with 3 elements

    - #### viewTuple

          @NotNull
          static <C> Indexable<C> viewTuple(@NotNull
                                                     ITuple4<? extends C,? extends C,? extends C,? extends C> tuple)

      View a 4-element tuple as an indexable.
      Type Parameters:
        `C` - common super type of the tuple's types
      Parameters:
        `tuple` - tuple to view
      Returns:
        indexable with 4 elements

    - #### viewTuple

          @NotNull
          static <C> Indexable<C> viewTuple(@NotNull
                                                     ITuple5<? extends C,? extends C,? extends C,? extends C,? extends C> tuple)

      View a 5-element tuple as an indexable.
      Type Parameters:
        `C` - common super type of the tuple's types
      Parameters:
        `tuple` - tuple to view
      Returns:
        indexable with 5 elements

    - #### viewTuple

          @NotNull
          static <C> Indexable<C> viewTuple(@NotNull
                                                     ITuple6<? extends C,? extends C,? extends C,? extends C,? extends C,? extends C> tuple)

      View a 6-element tuple as an indexable.
      Type Parameters:
        `C` - common super type of the tuple's types
      Parameters:
        `tuple` - tuple to view
      Returns:
        indexable with 6 elements

    - #### viewTuple

          @NotNull
          static <C> Indexable<C> viewTuple(@NotNull
                                                     ITuple7<? extends C,? extends C,? extends C,? extends C,? extends C,? extends C,? extends C> tuple)

      View a 7-element tuple as an indexable.
      Type Parameters:
        `C` - common super type of the tuple's types
      Parameters:
        `tuple` - tuple to view
      Returns:
        indexable with 7 elements

    - #### viewTuple

          @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)

      View a 8-element tuple as an indexable.
      Type Parameters:
        `C` - common super type of the tuple's types
      Parameters:
        `tuple` - tuple to view
      Returns:
        indexable with 8 elements

    - #### viewTuple

          @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)

      View a 9-element tuple as an indexable.
      Type Parameters:
        `C` - common super type of the tuple's types
      Parameters:
        `tuple` - tuple to view
      Returns:
        indexable with 9 elements