de.caff.generics

## Interface IntIndexable

- All Superinterfaces:
    IntCountable, java.lang.Iterable<java.lang.Integer>, PrimitiveIntIterable, Sizeable
  All Known Subinterfaces:
    ExpandableIntIndexable, MutableIntIndexable
  All Known Implementing Classes:
    IntIndexable.Base, IntPair, MutableIntIndexable.Base

      public interface IntIndexable
      extends IntCountable

  Class which allows readonly access of raw integers by index.

  The `EMPTY` constant or `emptyIndexable()` method provide the same useful return value to indicate emptiness.

  Simple implementations should extend `IntIndexable.Base` because that provides useful implementations for standard Object methods and implements `Comparable`.

  Since:
    July 7, 2020
  Author:
    Rammi
  See Also:
    `FastIntSequenceSearch`

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Interface and Description
    --- | ---
    `static class` | `IntIndexable.Base` Abstract base class which provides useful implementations for `Object.equals(Object)`, `Object.hashCode()`, `Object.toString()`.
    `static interface` | `IntIndexable.EntryConsumer` Consumer for index-value pairs with `int` values.
    `static class` | `IntIndexable.IntIndexableSpliterator` Spliterator for int indexables.

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static IntIndexable.Base` | `EMPTY` An empty indexable.
    `static IntIndexable.Base` | `SINGLE_0` Singleton integer indexable which has only `0` as its single element.

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

      `EMPTY_INT_ITERATOR`

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

      `NULL`

  - ### Method Summary

    All Methods Static Methods Instance Methods Abstract Methods Default Methods
    Modifier and Type | Method and Description
    --- | ---
    `default void` | `addAllTo(java.util.Collection<? super java.lang.Integer> collection)` Add all elements of this indexable to the given collection.
    `default int` | `addToArray(int[] array, int pos)` Add the content of this indexable to the given array.
    `default int` | `addToArray(int[] array, int arrayPos, int index, int length)` Add a part of the content of this indexable to the given array.
    `default IntIndexable.Base` | `asBase()` Make this integer indexable usable as a class with defined standard Object methods.
    `default java.util.Collection<java.lang.Integer>` | `asCollection()` Get a view on this indexable as an unmodifiable collection.
    `default Indexable<java.lang.Integer>` | `asIndexable()` Get a view of this indexable as a standard object-based indexable.
    `default java.util.List<java.lang.Integer>` | `asList()` Get a view on this indexable as an unmodifiable list.
    `default LongIndexable.Base` | `asLongIndexable()` View this integer indexable as a long indexable.
    `default LongIndexable.Base` | `asUnsignedIndexable()` View this integer indexable as a long indexable using unsigned values.
    `default int` | `binarySearch(int value)` Do a binary search in an indexable ordered in natural ascending order.
    `default int` | `binarySearch(int value, IntOrdering order)` Do a binary search in an ordered indexable.
    `static int` | `compare(IntIndexable indexable1, IntIndexable indexable2)` Compare two int indexables.
    `static int` | `compareUnsigned(IntIndexable indexable1, IntIndexable indexable2)` Compare two int indexables as if they contain unsigned int values.
    `static IntIndexable.Base` | `emptyIndexable()` Get an empty indexable set.
    `static boolean` | `equal(IntIndexable indexable1, IntIndexable indexable2)` Are two int indexables equal?
    `static boolean` | `equal(IntIndexable indexable1, java.lang.Object indexable2)` Are two int indexables equal?
    `default int` | `firstMatch(java.util.function.IntPredicate check)` Get the first index for which the given check is fulfilled.
    `default int` | `foldLeft(int initialValue, java.util.function.IntBinaryOperator foldOperation)` Go over all values and do a cumulative calculation.
    `default void` | `forEachIntEntry(IntIndexable.EntryConsumer consumer)` Call an entry consumer foreach entry in this indexable.
    `default IntIndexable` | `frozen()` Get a frozen version of this indexable.
    `default java.util.Spliterator.OfInt` | `frozenIntSpliterator()` Get an immutable spliterator on a frozen copy of this indexable.
    `int` | `get(int index)` Get the element at the given index.
    `default int` | `getMod(int index)` Get an element modulo size.
    `default int` | `gyt(int index)` Pythonesque get.
    `static int` | `hash(IntIndexable indexable)` Calculate a hashcode for a int indexable.
    `default IntIndexable.Base` | `headSet(int toIndex)` Create an indexable subset from the last elements of this indexable set.
    `default java.lang.Iterable<java.lang.Integer>` | `indexes()` Get the indexes of this indexable as an iterable range.
    `static IntIndexable.Base` | `init(int size, int value)` Get an integer indexable of a given size which always returns the same value.
    `static IntIndexable` | `initByIndex(int size, java.util.function.IntUnaryOperator producer)` Get an integer indexable of a given size which returns elements created by index.
    `default IntIndexable` | `intIndexes()` Get the indexes of this indexable as an integer indexable.
    `default java.util.PrimitiveIterator.OfInt` | `intIterator()` Get a primitive int iterator.
    `default java.util.PrimitiveIterator.OfInt` | `intIterator(int from, int to)` Get an int iterator from the given sub set.
    `default java.util.Spliterator.OfInt` | `intSpliterator()` Get a spliterator on this indexable.
    `default boolean` | `isEmpty()` Is this indexable empty?
    `default boolean` | `isOrdered(IntOrdering order)` Is this indexable sorted according to the given ordering?
    `default boolean` | `isStrictlyOrdered(IntOrdering order)` Is this indexable strictly sorted according to the given ordering?
    `default java.util.Iterator<java.lang.Integer>` | `iterator()` Returns an iterator over elements of type `T`.
    `default int` | `lastMatch(java.util.function.IntPredicate check)` Get the last index for which the given check is fulfilled.
    `default java.util.ListIterator<java.lang.Integer>` | `listIterator()` Returns a list iterator over elements of type `T`.
    `default int` | `nextMatch(int startIndex, java.util.function.IntPredicate check)` Get the next index for which the given check is fulfilled.
    `default MutableIntIndexable` | `ordered()` Create a (mutable) int indexable from the values of this indexable which is ordered in natural order.
    `default MutableIntIndexable` | `ordered(IntOrdering order)` Create a (mutable) int indexable from the values of this indexable which is ordered as defined by the given ordering.
    `default int` | `previousMatch(int startIndex, java.util.function.IntPredicate check)` Get the previous index for which the given check is fulfilled.
    `static IntIndexable` | `range(int startValue, int endValue)` Create an integer indexable which represents a range with step size 1.
    `static IntIndexable` | `range(int startValue, int maxValue, int stepSize)` Create an integer indexable which is defined by a given range.
    `static IntIndexable` | `rangeFromSize(int size)` Create an integer range from `0` with the given size.
    `default IntIndexable.Base` | `reverse()` Get this indexable but with inverted order.
    `default IntIndexable` | `rotated(int steps)` Get a rotated view of this int indexable.
    `static IntIndexable.Base` | `singleton(int value)` View a single int value as a int indexable of size 1.
    `default IntIndexable.Base` | `subSet(int fromIndex, int toIndex)` Get an indexable subset.
    `default IntIndexable.Base` | `sybSet(int fromIndex, int toIndex)` Get an indexable subset.
    `default IntIndexable.Base` | `tailSet(int fromIndex)` Create an indexable subset from the last elements of this indexable set.
    `default int[]` | `toArray()` Convert this into an integer array.
    `default java.util.ArrayList<java.lang.Integer>` | `toList()` Create a list from this integer indexable.
    `static java.lang.String` | `toString(IntIndexable indexable)` Create a string representation of the given indexable.
    `default <T> Indexable<T>` | `view(java.util.function.IntFunction<? extends T> mapper)` Return a mapped view on this integer indexable.
    `static IntIndexable.Base` | `viewArray(int... array)` View an int array as an Indexable.
    `static IntIndexable.Base` | `viewArray(int[] array, int start, int length)` View part of an integer array as an Indexable.
    `static <T> IntIndexable.Base` | `viewArray(T[] array, java.util.function.ToIntFunction<? super T> valueExtract)` View an object array as an integer indexable.
    `default BooleanIndexable` | `viewAsBoolean(java.util.function.IntPredicate convert)` View this indexable as a boolean indexable while using a conversion for each value.
    `default ByteIndexable` | `viewAsByte()` View this integer indexable as a byte integer indexable.
    `default CharIndexable` | `viewAsChar(IntToCharFunction1 convert)` View this int indexable as a char indexable.
    `default DoubleIndexable` | `viewAsDouble()` View this integer indexable as a double indexable.
    `default DoubleIndexable` | `viewAsDouble(java.util.function.IntToDoubleFunction convert)` View this indexable as a double indexable while using a conversion for each value.
    `default FloatIndexable` | `viewAsFloat()` View this integer indexable as a float indexable.
    `default LongIndexable` | `viewAsLong()` View this integer indexable as a long integer indexable.
    `default LongIndexable` | `viewAsLong(java.util.function.IntToLongFunction convert)` View this indexable as a long integer indexable while using a conversion for each value.
    `default ShortIndexable` | `viewAsShort()` View this integer indexable as a short integer indexable.
    `default LongIndexable` | `viewAsUnsignedLong()` View this integer indexable as an unsigned long integer indexable.
    `static IntIndexable.Base` | `viewByIndex(int size, java.util.function.IntUnaryOperator producer)` Get an integer indexable of a given size which returns elements created by index.
    `static IntIndexable.Base` | `viewIndexable(Indexable<? extends java.lang.Number> indexable)` View a generic Number indexable as integer indexable.
    `static IntIndexable.Base` | `viewIndexable(Indexable<? extends java.lang.Number> indexable, int nullFallback)` View a generic Number indexable as integer indexable.
    `static <T> IntIndexable.Base` | `viewIndexable(Indexable<T> indexable, java.util.function.ToIntFunction<? super T> extractor)` View a generic indexable as an int indexable.
    `static IntIndexable.Base` | `viewList(java.util.List<? extends java.lang.Number> list)` View a list as an Indexable.
    `static IntIndexable.Base` | `viewList(java.util.List<? extends java.lang.Number> list, int nullFallback)` View a list as an Indexable.
    `static <T> IntIndexable.Base` | `viewList(java.util.List<T> list, java.util.function.ToIntFunction<? super T> extractor)` View a generic list as a int indexable.
    `static IntIndexable.Base` | `viewNumberArray(java.lang.Number... array)` View a Number array as an Indexable.
    `default IntIndexable` | `viewOp(java.util.function.IntUnaryOperator op)` View this int indexable transformed by an operator.
    `default IntIndexable.Base` | `with(int index, int value)` Return a new integer indexable where the given index is changed.
    `default IntIndexable` | `withAppendedValue(int value)` Create a view with of this indexable with another value added at the end.
    `static IntIndexable.Base` | `withCachedHash(IntIndexable indexable)` Wrap an indexable with one which caches the hash value.
    `default IntIndexable` | `withExchangedValueAt(int index, int value)` Create a view of this int indexable with an exchanged value.
    `default IntIndexable` | `withInsertedValueAt(int index, int value)` Create a view of this int indexable with an inserted value.
    `default IntIndexable` | `withRemovedValueAt(int index)` Create a view of this indexable with one value removed.
    `default IntIndexable` | `withSwappedValuesAt(int index1, int index2)` Create a view of this int indexable with two values swapped.
    `default IntIndexable.Base` | `wyth(int index, int value)` Return a new integer indexable where the given index is changed (Pythonesque version) This allows to index elements from the end by using negative indexes.

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

      `empty, filtered, first, isEqual, isSorted, isStrictlySorted, last, sorted, toString, uniform, viewCollection, viewCollection, viewCollectionN, viewCollectionN`

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

      `average, containsInt, forEachInt, forEachIntFragile, longSum, longSumX, spliterator, stream, sum, sumX`

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

      `forEach`

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

      `size`

- - ### Field Detail

    - #### EMPTY

          @NotNull
          static final IntIndexable.Base EMPTY

      An empty indexable.

    - #### SINGLE_0

          @NotNull
          static final IntIndexable.Base SINGLE_0

      Singleton integer indexable which has only `0` as its single element.

  - ### Method Detail

    - #### get

          int get(int index)

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

    - #### gyt

          default int 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 int 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

    - #### with

          @NotNull
          default IntIndexable.Base with(int index,
                                                  int value)

      Return a new integer indexable where the given index is changed. This default implementation will copy all values, so this should be used for small arrays preferably.
      Parameters:
        `index` - index between `0` and `size() - 1`
        `value` - value to be set
      Returns:
        new integer indexable with changed value

    - #### wyth

          @NotNull
          default IntIndexable.Base wyth(int index,
                                                  int value)

      Return a new integer indexable where the given index is changed (Pythonesque version) This allows to index elements from the end by using negative indexes. This default implementation will forward everything to `with(int, int)` which by default copies all values, so this should be used for small arrays preferably.
      Parameters:
        `index` - index between `-size()` and `size() - 1`
        `value` - value to be set
      Returns:
        new integer indexable with changed value

    - #### reverse

          @NotNull
          default IntIndexable.Base reverse()

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

    - #### isEmpty

          default boolean isEmpty()

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

    - #### intIterator

          @NotNull
          default java.util.PrimitiveIterator.OfInt intIterator()

      Get a primitive int iterator.
      Specified by:
        `intIterator` in interface `PrimitiveIntIterable`
      Returns:
        int iterator which iterates over this indexable

    - #### intIterator

          @NotNull
          default java.util.PrimitiveIterator.OfInt intIterator(int from,
                                                                         int to)

      Get an int iterator from the given sub set.
      Parameters:
        `from` - first index of iterator
        `to` - one past last index of iterator
      Returns:
        int iterator which iterates over the given part of this indexable

    - #### forEachIntEntry

          default void forEachIntEntry(@NotNull
                                       IntIndexable.EntryConsumer consumer)

      Call an entry consumer foreach entry in this indexable.
      Parameters:
        `consumer` - consumer to be called

    - #### iterator

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

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

    - #### listIterator

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

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

    - #### subSet

          @NotNull
          default IntIndexable.Base 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:
        indxable subset view of this indexable

    - #### sybSet

          @NotNull
          default IntIndexable.Base 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 IntIndexable.Base 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 IntIndexable.Base 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

    - #### toArray

          @NotNull
          default int[] toArray()

      Convert this into an integer array.
      Specified by:
        `toArray` in interface `IntCountable`
      Returns:
        integer array

    - #### addToArray

          default int addToArray(@NotNull
                                 int[] array,
                                 int pos)

      Add the content of this indexable to the given array.
      Specified by:
        `addToArray` in interface `IntCountable`
      Parameters:
        `array` - array where the content is added
        `pos` - position in the array where the content of this indexable is added
      Returns:
        array position after this indexable

    - #### addToArray

          default int addToArray(@NotNull
                                 int[] 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` - position in hte 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

    - #### asCollection

          @NotNull
          default java.util.Collection<java.lang.Integer> 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 `IntCountable`
      Returns:
        collection view

    - #### asList

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

      Get a view on 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)`.
      Returns:
        collection view
      See Also:
        `toList()`

    - #### toList

          @NotNull
          default java.util.ArrayList<java.lang.Integer> toList()

      Create a list from this integer indexable. This creates an independent list to which the elements of this indexable are copied.
      Specified by:
        `toList` in interface `IntCountable`
      Returns:
        list copy of this indexable
      See Also:
        `asList()`

    - #### addAllTo

          default void addAllTo(@NotNull
                                java.util.Collection<? super java.lang.Integer> collection)

      Add all elements of this indexable to the given collection.
      Specified by:
        `addAllTo` in interface `IntCountable`
      Parameters:
        `collection` - collection to add to

    - #### asIndexable

          @NotNull
          default Indexable<java.lang.Integer> asIndexable()

      Get a view of this indexable as a standard object-based indexable.
      Returns:
        indexable with non-null `Integer` values

    - #### 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 indexes of this indexable as an integer indexable.
      Returns:
        ordered indexes
      See Also:
        `indexes()`, `rangeFromSize(int)`

    - #### asLongIndexable

          @NotNull
          default LongIndexable.Base asLongIndexable()

      View this integer indexable as a long indexable.
      Returns:
        long indexable view

    - #### view

          @NotNull
          default <T> Indexable<T> view(@NotNull
                                                 java.util.function.IntFunction<? extends T> mapper)

      Return a mapped view on this integer indexable.
      Specified by:
        `view` in interface `IntCountable`
      Type Parameters:
        `T` - result type pf mapper
      Parameters:
        `mapper` - mapper
      Returns:
        mapped indexable

    - #### asUnsignedIndexable

          @NotNull
          default LongIndexable.Base asUnsignedIndexable()

      View this integer indexable as a long indexable using unsigned values.
      Returns:
        long indexable view

    - #### foldLeft

          default int foldLeft(int initialValue,
                               @NotNull
                               java.util.function.IntBinaryOperator foldOperation)

      Go over all values and do a cumulative calculation.

      Eg calculate the maximum of this indexable use

             int max = indexable.foldLeft(Pythonesque.UNMAPPABLE, Math::max);

      Parameters:
        `initialValue` - start value for the operation, will be returned if this iterable is empty
        `foldOperation` - operation applied to each value, will get the accumulated value as its first and the current element value as its second argument
      Returns:
        accumulated value, result of applying fold operation to all values of this indexable iteratively

    - #### nextMatch

          default int nextMatch(int startIndex,
                                @NotNull
                                java.util.function.IntPredicate check)

      Get the next index for which the given check is fulfilled.
      Parameters:
        `startIndex` - start index for checking, `Pythonesque` indexing supported
        `check` - check to perform on elements of this indexable until `true`
      Returns:
        next index starting with `startIndex` for which the check returns `true`, `Pythonesque.UNMAPPABLE` if none

    - #### firstMatch

          default int firstMatch(@NotNull
                                 java.util.function.IntPredicate check)

      Get the first index for which the given check is fulfilled.
      Parameters:
        `check` - check to perform on elements of this indexable until `true`
      Returns:
        first index for which the check returns `true`, `-1` if none

    - #### previousMatch

          default int previousMatch(int startIndex,
                                    @NotNull
                                    java.util.function.IntPredicate check)

      Get the previous index for which the given check is fulfilled.
      Parameters:
        `startIndex` - start index for checking, `Pythonesque` indexing supported
        `check` - check to perform on elements of this indexable until `true`
      Returns:
        next index starting with `startIndex` for which the check returns `true`, `Pythonesque.UNMAPPABLE` if none

    - #### lastMatch

          default int lastMatch(@NotNull
                                java.util.function.IntPredicate check)

      Get the last index for which the given check is fulfilled.
      Parameters:
        `check` - check to perform on elements of this indexable until `true`
      Returns:
        last index for which the check returns `true`, `-1` if none

    - #### frozen

          @NotNull
          default IntIndexable frozen()

      Get a frozen version of this indexable.

      Often Indexables are used as a view to underlying collections. Although this interface is immutable, the underlying colelction might nevertheless change. This copies the current state of this indexable into an unmodifiable state, and returns an Indexable which is stable in size and will return always the same element for a given index. Beware: it is still possible that any element itself changes when the elements are mutable.

      Calling `frozen()` again on the returned object will just return the object itself, so you can safely call this method more than once.

      Specified by:
        `frozen` in interface `IntCountable`
      Returns:
        frozen version of this Indexable

    - #### intSpliterator

          @NotNull
          default java.util.Spliterator.OfInt intSpliterator()

      Get a spliterator on this indexable. The returned spliterator will not have its `Spliterator.IMMUTABLE` flag set, see `frozenIntSpliterator()` for an alternative.
      Returns:
        a spliterator on this indexable

    - #### frozenIntSpliterator

          @NotNull
          default java.util.Spliterator.OfInt frozenIntSpliterator()

      Get an immutable spliterator on a frozen copy of this indexable. If this indexable is already immutable (i.e. if `frozen()` returns `this`) then this is the same as `PrimitiveIntIterable.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 `frozen()` to understand what level of immutabiliy it will provide.
      Returns:
        an "immutable" spliterator with the possible cost of copying this indexable

    - #### withInsertedValueAt

          @NotNull
          default IntIndexable withInsertedValueAt(int index,
                                                            int value)

      Create a view of this int indexable with an inserted value. Note that this is not efficient, but handy in certain situations where only 1 or a few values are inserted. Use `ExpandableIntIndexable` 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 value is inserted before the current index (not Pythonesque, because it is possible to add an value at `index == size()`, and it is expected that most insertion will happen at 0 or at the end)
        `value` - inserted value at that index
      Returns:
        a view of this indexable with 1 more value at the given index, all values beyond are moved one index forward
      See Also:
        `withAppendedValue(int)`

    - #### withAppendedValue

          @NotNull
          default IntIndexable withAppendedValue(int value)

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

    - #### withExchangedValueAt

          @NotNull
          default IntIndexable withExchangedValueAt(int index,
                                                             int value)

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

    - #### withRemovedValueAt

          @NotNull
          default IntIndexable withRemovedValueAt(int index)

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

    - #### withSwappedValuesAt

          @NotNull
          default IntIndexable withSwappedValuesAt(int index1,
                                                            int index2)

      Create a view of this int indexable with two values 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 value (Pythonesque)
        `index2` - index of the second value (Pythonesque)
      Returns:
        a view of this indexable where the first and second value have exchanged places

    - #### rotated

          @NotNull
          default IntIndexable rotated(int steps)

      Get a rotated view of this int 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 `frozen()` to create an indexable which no longer depends on this one

    - #### viewOp

          @NotNull
          default IntIndexable viewOp(@NotNull
                                               java.util.function.IntUnaryOperator op)

      View this int indexable transformed by an operator.
      Parameters:
        `op` - transforming operator
      Returns:
        view of this indexable with transformed values

    - #### viewAsDouble

          @NotNull
          default DoubleIndexable viewAsDouble()

      View this integer indexable as a double indexable. This will cast the values of this indexable on each request, use `frozen()` on the result to create an independent copy if this seems like a problem to you.
      Returns:
        a double indexable view of this indexable

    - #### viewAsDouble

          @NotNull
          default DoubleIndexable viewAsDouble(@NotNull
                                                        java.util.function.IntToDoubleFunction convert)

      View this indexable as a double indexable while using a conversion for each value.

      Use `frozen()` on the result to decouple it from this indexable.

      Parameters:
        `convert` - converter applied to each value of this indexable before it is returned from the resulting indexable
      Returns:
        double indexable view of this indexable

    - #### viewAsFloat

          @NotNull
          default FloatIndexable viewAsFloat()

      View this integer indexable as a float indexable. Note that not all integer values have an exact float representation. This will cast the values of this indexable on each request, use `frozen()` on the result to create an independent copy if this seems like a problem to you.
      Returns:
        a float indexable view of this indexable

    - #### viewAsLong

          @NotNull
          default LongIndexable viewAsLong()

      View this integer indexable as a long integer indexable. This will cast the values of this indexable on each request, use `frozen()` on the result to create an independent copy if this seems like a problem to you.
      Returns:
        a long integer indexable view of this indexable

    - #### viewAsUnsignedLong

          @NotNull
          default LongIndexable viewAsUnsignedLong()

      View this integer indexable as an unsigned long integer indexable. This will assume that the values of this indexable don't have a sign bit and range from 0 to 4,294,967,295. This will cast the values of this indexable on each request, use `frozen()` on the result to create an independent copy if this seems like a problem to you.
      Returns:
        an unsigned long integer indexable view of this indexable

    - #### viewAsLong

          @NotNull
          default LongIndexable viewAsLong(@NotNull
                                                    java.util.function.IntToLongFunction convert)

      View this indexable as a long integer indexable while using a conversion for each value.

      Use `frozen()` on the result to decouple it from this indexable.

      Parameters:
        `convert` - converter applied to each value of this indexable before it is returned from the resulting indexable
      Returns:
        long indexable view of this indexable

    - #### viewAsShort

          @NotNull
          default ShortIndexable viewAsShort()

      View this integer indexable as a short integer indexable. Note that this may result in loss of numeric range of the values. This will cast the values of this indexable on each request, use `frozen()` on the result to create an independent copy if this seems like a problem to you.
      Returns:
        a short integer indexable view of this indexable

    - #### viewAsByte

          @NotNull
          default ByteIndexable viewAsByte()

      View this integer indexable as a byte integer indexable. Note that this may result in severe loss of numeric range of the values. This will cast the float values of this indexable on each request, use `frozen()` on the result to create an independent copy if this seems like a problem to you.
      Returns:
        a byte integer indexable view of this indexable

    - #### viewAsBoolean

          @NotNull
          default BooleanIndexable viewAsBoolean(@NotNull
                                                          java.util.function.IntPredicate convert)

      View this indexable as a boolean indexable while using a conversion for each value.

      Use `frozen()` on the result to decouple it from this indexable.

      Parameters:
        `convert` - converter applied to each value of this indexable before it is returned from the resulting indexable
      Returns:
        boolean indexable view of this indexable

    - #### viewAsChar

          @NotNull
          default CharIndexable viewAsChar(@NotNull
                                                    IntToCharFunction1 convert)

      View this int indexable as a char indexable.
      Parameters:
        `convert` - conversion function which turns the values of this indexable into characters
      Returns:
        char indexable view of this indexable

    - #### viewList

          @NotNull
          static IntIndexable.Base viewList(@NotNull
                                                     java.util.List<? extends java.lang.Number> list)

      View a list as an Indexable. This requires a list of non-null numbers as a base.
      Parameters:
        `list` - list used as a base, required to have only non-null elements
      Returns:
        indexable view of the given list, so any changes of the list will be reflected by the returned Indexable

    - #### viewList

          @NotNull
          static IntIndexable.Base viewList(@NotNull
                                                     java.util.List<? extends java.lang.Number> list,
                                                     int nullFallback)

      View a list as an Indexable. This allows to provide a fallback for null elements in the list.
      Parameters:
        `list` - list used as a base, required to have only non-null elements
        `nullFallback` - value returned for `null` elements in the list
      Returns:
        indexable view of the given list, so any changes of the list will be reflected by the returned Indexable

    - #### viewList

          @NotNull
          static <T> IntIndexable.Base viewList(@NotNull
                                                         java.util.List<T> list,
                                                         @NotNull
                                                         java.util.function.ToIntFunction<? super T> extractor)

      View a generic list as a int indexable.
      Type Parameters:
        `T` - element type of list
      Parameters:
        `list` - generic list
        `extractor` - extractor function which extracts a int from the elements of `list`
      Returns:
        a int indexable view of `list`

    - #### viewIndexable

          @NotNull
          static IntIndexable.Base viewIndexable(@NotNull
                                                          Indexable<? extends java.lang.Number> indexable)

      View a generic Number indexable as integer indexable.
      Parameters:
        `indexable` - generic indexable with Number elements, required to have only non-null elements
      Returns:
        integer indexable view

    - #### viewIndexable

          @NotNull
          static IntIndexable.Base viewIndexable(@NotNull
                                                          Indexable<? extends java.lang.Number> indexable,
                                                          int nullFallback)

      View a generic Number indexable as integer indexable.
      Parameters:
        `indexable` - generic indexable with Number elements
        `nullFallback` - fallback for `null` elements
      Returns:
        integer indexable view

    - #### viewIndexable

          @NotNull
          static <T> IntIndexable.Base viewIndexable(@NotNull
                                                              Indexable<T> indexable,
                                                              @NotNull
                                                              java.util.function.ToIntFunction<? super T> extractor)

      View a generic indexable as an int indexable.
      Type Parameters:
        `T` - element type of indexable
      Parameters:
        `indexable` - generic indexable
        `extractor` - extractor function which extracts an int from the elements of `indexable`
      Returns:
        an int indexable view of `indexable`

    - #### viewNumberArray

          @NotNull
          static IntIndexable.Base viewNumberArray(@NotNull
                                                            java.lang.Number... array)

      View a Number array as an Indexable. To view only part of the array use `subSet(int, int)`.
      Parameters:
        `array` - array used as base, required to hold only non-null values
      Returns:
        indexable view of the given array, any changes to the underlying array will be reflected by the returned Indexable

    - #### viewArray

          @NotNull
          static IntIndexable.Base viewArray(@NotNull
                                                      int... array)

      View an int array as an Indexable. To view only part of the array use `viewArray(int[], int, int)`.
      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 IntIndexable.Base viewArray(@NotNull
                                                      int[] array,
                                                      int start,
                                                      int length)

      View part of an integer array as an Indexable.
      Parameters:
        `array` - array used as base
        `start` - index of first byte to use from the array
        `length` - number of elements to use from the array
      Returns:
        indexable view of the given array, any changes to the underlying array will be reflected by the returned Indexable

    - #### viewArray

          @NotNull
          static <T> IntIndexable.Base viewArray(@NotNull
                                                          T[] array,
                                                          @NotNull
                                                          java.util.function.ToIntFunction<? super T> valueExtract)

      View an object array as an integer indexable.
      Type Parameters:
        `T` - array element type
      Parameters:
        `array` - viewed array
        `valueExtract` - converter from array elements to the integer values of this indexable
      Returns:
        indexable view of the given array, any changes to the underlying array will be reflected by the returned Indexable

    - #### init

          @NotNull
          static IntIndexable.Base init(int size,
                                                 int value)

      Get an integer indexable of a given size which always returns the same value.
      Parameters:
        `size` - size of the returned indexable
        `value` - value returned for each element
      Returns:
        indexable of size `size` with always the same element

    - #### viewByIndex

          @NotNull
          static IntIndexable.Base viewByIndex(int size,
                                                        @NotNull
                                                        java.util.function.IntUnaryOperator producer)

      Get an integer indexable of a given size which returns elements created by index. This will always call the `producer` when an element is requested. Use `frozen()` on the result to create an indexable which avoids this.
      Parameters:
        `size` - size of the returned indexable
        `producer` - producer which is called with an index and expected to return the associated value
      Returns:
        indexable view which calls the `producer` with the given index when an element is requested
      See Also:
        `initByIndex(int, IntUnaryOperator)`

    - #### initByIndex

          @NotNull
          static IntIndexable initByIndex(int size,
                                                   @NotNull
                                                   java.util.function.IntUnaryOperator producer)

      Get an integer indexable of a given size which returns elements created by index. This will call the producer only once for each element during the call of this method, and return the results on later requests.
      Parameters:
        `size` - size of the returned indexable
        `producer` - producer which is called with an index and expected to return the associated value
      Returns:
        indexable with elements initialized by the `producer`
      See Also:
        `viewByIndex(int, IntUnaryOperator)`

    - #### singleton

          @NotNull
          static IntIndexable.Base singleton(int value)

      View a single int value as a int indexable of size 1.
      Specified by:
        `singleton` in interface `IntCountable`
      Parameters:
        `value` - single value
      Returns:
        indexable with one value

    - #### emptyIndexable

          @NotNull
          static IntIndexable.Base emptyIndexable()

      Get an empty indexable set.
      Returns:
        empty indexable

    - #### toString

          @NotNull
          static java.lang.String toString(@NotNull
                                                    IntIndexable indexable)

      Create a string representation of the given indexable.
      Parameters:
        `indexable` - indexable
      Returns:
        string representation

    - #### equal

          static boolean equal(@NotNull
                               IntIndexable indexable1,
                               @NotNull
                               IntIndexable indexable2)

      Are two int indexables equal?
      Parameters:
        `indexable1` - first indexable
        `indexable2` - second indexable
      Returns:
        `true` if both indexables contain the same values in the same sequence
        `false` if sizes or values differ

    - #### equal

          static boolean equal(@NotNull
                               IntIndexable indexable1,
                               @Nullable
                               java.lang.Object indexable2)

      Are two int indexables equal? This is a convenience method which may be called from implementations for their `Object.equals(Object)` method.
      Parameters:
        `indexable1` - first indexable
        `indexable2` - object expected to be an indexable itself
      Returns:
        `true` if both indexables contain the same values in the same sequence
        `false` if the second object is not an indexable, of if sizes or values differ

    - #### compare

          static int compare(@NotNull
                             IntIndexable indexable1,
                             @NotNull
                             IntIndexable indexable2)

      Compare two int indexables. This compares the two indexable lexically element by element 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).
      Parameters:
        `indexable1` - first indexable
        `indexable2` - second indexable
      Returns:
        `< 0>` if `indexable1 < indxable2`, `0` if `indexable1 == indexable2`, or `> 0` if `indexable1 > indexable2`

    - #### compareUnsigned

          static int compareUnsigned(@NotNull
                                     IntIndexable indexable1,
                                     @NotNull
                                     IntIndexable indexable2)

      Compare two int indexables as if they contain unsigned int values. This compares the two indexable lexically element by element 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).
      Parameters:
        `indexable1` - first indexable
        `indexable2` - second indexable
      Returns:
        `< 0>` if `indexable1 < indxable2`, `0` if `indexable1 == indexable2`, or `> 0` if `indexable1 > indexable2`

    - #### hash

          static int hash(@NotNull
                          IntIndexable indexable)

      Calculate a hashcode for a int indexable.
      Parameters:
        `indexable` - indexable for which the hash code is required
      Returns:
        hash code for the given indexable

    - #### withCachedHash

          @NotNull
          static IntIndexable.Base withCachedHash(@NotNull
                                                           IntIndexable 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.

      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()`

    - #### range

          @NotNull
          static IntIndexable range(int startValue,
                                             int maxValue,
                                             int stepSize)

      Create an integer indexable which is defined by a given range. This returns an indexable which returns successive numbers in a given range. As indexables have an integer size this method will throw an `IllegalArgumentException` if the parameters require a range of a larger size. If such larger size is required, but indexing is not, see `Range.of(int, int, int)`.
      Parameters:
        `startValue` - start value of range (included)
        `maxValue` - end value of range (included if stepped on)
        `stepSize` - step size, not `0`, may be negative if `startValue < endValue`
      Returns:
        indexable returning the given range of integers

    - #### range

          @NotNull
          static IntIndexable range(int startValue,
                                             int endValue)

      Create an integer indexable which represents a range with step size 1. Depending on the arguments a range with a size larger than the maximal allowed value for integers may be required, which will raise an `IllegalArgumentException`. If in need of such large ranges but not of indexing see `Range.of(int, int)`.
      Parameters:
        `startValue` - start value of range (included)
        `endValue` - end value of range (included)
      Returns:
        range from `startValue` to `endValue` with step size `1` or `-1` (if `startValue > endValue` )

    - #### rangeFromSize

          @NotNull
          static IntIndexable rangeFromSize(int size)

      Create an integer range from `0` with the given size. As zero is included last index of the range is `size - 1`
      Parameters:
        `size` - range size
      Returns:
        zero based range

    - #### isOrdered

          default boolean isOrdered(@NotNull
                                    IntOrdering 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(IntOrdering) 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
                                            IntOrdering 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(IntOrdering) 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(int value)

      Do a binary search in an indexable ordered in natural ascending order. This requires this indexable to be ordered in `natural ascending order`, i.e. isOrdered(IntOrdering) has to return `true` to make this method work.

      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
      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)`.

    - #### binarySearch

          default int binarySearch(int value,
                                   @NotNull
                                   IntOrdering 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(IntOrdering) 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 MutableIntIndexable ordered(@NotNull
                                                       IntOrdering order)

      Create a (mutable) int indexable from the values of this indexable which is ordered as defined by the given ordering.

      If natural ordering is required prefer calling `ordered()` because that typically runs 1.5 times faster.

      Parameters:
        `order` - sort order
      Returns:
        independent indexable with sorted values

    - #### ordered

          @NotNull
          default MutableIntIndexable ordered()

      Create a (mutable) int indexable from the values of this indexable which is ordered in natural order.

      This can be some 1.5x faster than using `ordered(IntOrdering)` with `natural order`.

      Returns:
        independent indexable with sorted values

    - #### asBase

          @NotNull
          default IntIndexable.Base asBase()

      Make this integer indexable usable as a class with defined standard Object methods.
      Specified by:
        `asBase` in interface `IntCountable`
      Returns:
        based version of this indexable