de.caff.generics

## Interface ExpandableIndexable<T>

- All Superinterfaces:
    Countable<T>, Indexable<T>, java.lang.Iterable<T>, Sizeable

      public interface ExpandableIndexable<T>
      extends Indexable<T>

  Immutable expandable indexable.

  This interface defines an indexable which allows to change (set, add, remove) its values but is immutable nevertheless. All changing methods return copies, thus guaranteeing immutability.

  The immutablility guarantee is only valid for the indexable implementation, mutable elements which are changed will lead to strange effects, eg they are changed in all copies.

  The internal implementation tries to keep copying a cheap operation, but some access patterns may result in performance degration. It is therefore recommended not to use this in time-critical code.

  Initial creation is done by using the following methods:

  - `empty()`
  - `nulled(int)`
  - `fromArray(Object...)`
  - `fromArray(Object[], int, int)`
  - `fromIndexable(Indexable)`
  - `fromCollection(Collection)`
  Since:
    September 24, 2020
  Author:
    Rammi

- - ### Nested Class Summary

    - ### Nested classes/interfaces inherited from interface de.caff.generics.Indexable

      `Indexable.Base<TT>, Indexable.IndexableSpliterator<TElem>, Indexable.ListView<T>`

  - ### Field Summary

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

      `EMPTY, EMPTY_INDEXABLE_STRING`

    - ### 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
    --- | ---
    `ExpandableIndexable<T>` | `add(int index, T value)` Return an expandable indexable where the the given value was inserted at the given index.
    `default ExpandableIndexable<T>` | `add(T value)` Return an expandable int indexable where the given value was added to the end of this indexable.
    `default ExpandableIndexable<T>` | `addAll(java.lang.Iterable<? extends T> elements)` Add all elements to this indexable and return the result.
    `static <E> ExpandableIndexable<E>` | `empty()` Convenience method to create an empty expandable int indexable.
    `static <E> ExpandableIndexable<E>` | `from(java.util.Collection<? extends E> values)` Deprecated. overlaps with other `from()` methods, use `fromCollection(Collection)` instead
    `static <E> ExpandableIndexable<E>` | `from(E... values)` Deprecated. overlaps with other `from()` methods, use `fromArray(Object[])` instead
    `static <E> ExpandableIndexable<E>` | `from(E[] array, int start, int length)` Deprecated. overlaps with other `from()` methods, use `fromArray(Object[], int, int)` instead
    `static <E> ExpandableIndexable<E>` | `from(Indexable<E> indexable)` Deprecated. overlaps with other `from()` methods, use `fromIndexable(Indexable)` instead
    `static <E> ExpandableIndexable<E>` | `fromArray(E... values)` Create an expandable integer indexable from an initial array of values.
    `static <E> ExpandableIndexable<E>` | `fromArray(E[] array, int start, int length)` Create an expandable integer indexable from part of an int array.
    `static <E> ExpandableIndexable<E>` | `fromCollection(java.util.Collection<? extends E> values)` Create an expandable integer indexable from a collection of numbers.
    `static <E> ExpandableIndexable<E>` | `fromIndexable(Indexable<E> indexable)` Get an expandable integer indexable from a normal integer indexable.
    `static <E> ExpandableIndexable<E>` | `initByIndex(int size, java.util.function.IntFunction<? extends E> producer)` Create an expandable indexable with a given size, and initialize its elements by index.
    `default java.util.Iterator<T>` | `iterator()` Returns an iterator over elements of type `T`.
    `static <E> ExpandableIndexable<E>` | `nulled(int size)` Create an expandable indexable with a given size, and initialize all its elements to `null`.
    `ExpandableIndexable<T>` | `remove(int index)` Return an expandable int indexable where the value at the given index was removed.
    `default ExpandableIndexable<T>` | `remyve(int index)` Pythonesque remove allowing negative indexes to remove from the end.
    `ExpandableIndexable<T>` | `set(int index, T value)` Set the value at the given index.
    `default ExpandableIndexable<T>` | `syt(int index, T value)` Pythonesque set the value at the given index.
    `default ExpandableIndexable<T>` | `ydd(int index, T value)` Pythonesque insertion allowing negative indexes to insert from the end.

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

      `addToArray, addToArray, addToCollection, asBase, asCollection, asList, binarySearch, checkIndex, combine, compare, downCast, emptyIndexable, equal, findAll, findAllX, findFirst, findFirst, findFirst, findFirstX, findLast, findLast, findLast, findNext, findNext, findNext, findNextX, findPrevious, findPrevious, findPrevious, first, firstMatch, firstMatch, firstMatchX, forEachEntry, forEachEntryFragile, fromCollection, fromCountable, fromCountable, fromEnumeration, fromEnumeration, fromIterable, fromIterable, fromIterable, fromIterable, fromIterator, fromList, fromOptional, frozenSpliterator, get, getMod, gyt, hash, headSet, indexedView, indexes, init, initByIndex, initFragile, intIndexes, isEmpty, isOrdered, isStrictlyOrdered, iterator, last, listIterator, mapArray, optional, ordered, reverse, rotated, singleton, spliterator, subSet, sybSet, tailSet, toString, view, view, viewArray, viewArray, viewAsBooleanIndexable, viewAsByteIndexable, viewAsCharIndexable, viewAsDict, viewAsDoubleIndexable, viewAsFloatIndexable, viewAsIntIndexable, viewAsLongIndexable, viewAsShortIndexable, viewByIndex, viewFragile, viewList, viewList, viewListN, viewListN, viewTuple, viewTuple, viewTuple, viewTuple, viewTuple, viewTuple, viewTuple, viewTuple, withAppendedItem, withCachedHash, withExchangedItemAt, withInsertedItemAt, withPrependedItem, withRemovedItemAt, withSwappedItemsAt`

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

      `addAllTo, combined, combined, containsEq, containsRef, downCast, 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`

- - ### Method Detail

    - #### add

          @NotNull
          ExpandableIndexable<T> add(int index,
                                              T value)

      Return an expandable indexable where the the given value was inserted at the given index.
      Parameters:
        `index` - index in the range `0` (insert at first position) to `size()` (insert after last position)
        `value` - value to insert at the given position
      Returns:
        new indexable with the given value inserted

    - #### remove

          @NotNull
          ExpandableIndexable<T> remove(int index)

      Return an expandable int indexable where the value at the given index was removed.
      Parameters:
        `index` - index to remove, in the range `0` to `size() - 1`
      Returns:
        new expandable indexable with the given index removed

    - #### set

          @NotNull
          ExpandableIndexable<T> set(int index,
                                              T value)

      Set the value at the given index.
      Parameters:
        `index` - index
        `value` - new value
      Returns:
        new expandable indexable with the given value exchanged

    - #### syt

          @NotNull
          default ExpandableIndexable<T> syt(int index,
                                                      T value)

      Pythonesque set the value at the given index.
      Parameters:
        `index` - index, negative to count from the back
        `value` - value to set
      Returns:
        new expandable indexable with the given value exchanged

    - #### add

          @NotNull
          default ExpandableIndexable<T> add(T value)

      Return an expandable int indexable where the given value was added to the end of this indexable.
      Parameters:
        `value` - value to add
      Returns:
        new expandable indexable with added value

    - #### ydd

          @NotNull
          default ExpandableIndexable<T> ydd(int index,
                                                      T value)

      Pythonesque insertion allowing negative indexes to insert from the end.
      Parameters:
        `index` - positive values behave the same way as `add(int, Object)`, but negative values count from the back, so `-1` will insert before the last element
        `value` - value to insert
      Returns:
        new expandable indexable with the given value inserted

    - #### remyve

          @NotNull
          default ExpandableIndexable<T> remyve(int index)

      Pythonesque remove allowing negative indexes to remove from the end.
      Parameters:
        `index` - positive values behave the same as `remove(int)`, while negative indexes count from the back, so `-1` will remove the last element
      Returns:
        new expandable indexable with the given index removed

    - #### addAll

          @NotNull
          default ExpandableIndexable<T> addAll(@NotNull
                                                         java.lang.Iterable<? extends T> elements)

      Add all elements to this indexable and return the result.
      Parameters:
        `elements` - elements to add
      Returns:
        resulting expandable indexable

    - #### iterator

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

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

    - #### empty

          @NotNull
          static <E> ExpandableIndexable<E> empty()

      Convenience method to create an empty expandable int indexable.
      Specified by:
        `empty` in interface `Countable<T>`
      Type Parameters:
        `E` - element type
      Returns:
        empty expandable int indexable

    - #### initByIndex

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

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

    - #### nulled

          @NotNull
          static <E> ExpandableIndexable<E> nulled(int size)

      Create an expandable indexable with a given size, and initialize all its elements to `null`.
      Type Parameters:
        `E` - element type
      Parameters:
        `size` - size of the returned indexable
      Returns:
        expandable indexable with the given size and `null` elements

    - #### from

          @NotNull
           @SafeVarargs
           @Deprecated
          static <E> ExpandableIndexable<E> from(@NotNull
                                                                                     E... values)

      Deprecated. overlaps with other `from()` methods, use `fromArray(Object[])` instead
      Create an expandable indexable from an initial array of values.
      Type Parameters:
        `E` - element type
      Parameters:
        `values` - array of values
      Returns:
        expandable integer indexable

    - #### fromArray

          @NotNull
           @SafeVarargs
          static <E> ExpandableIndexable<E> fromArray(@NotNull
                                                                             E... values)

      Create an expandable integer indexable from an initial array of values.
      Specified by:
        `fromArray` in interface `Indexable<T>`
      Type Parameters:
        `E` - element type
      Parameters:
        `values` - array of values
      Returns:
        expandable integer indexable

    - #### from

          @NotNull
           @Deprecated
          static <E> ExpandableIndexable<E> from(@NotNull
                                                                       E[] array,
                                                                       int start,
                                                                       int length)

      Deprecated. overlaps with other `from()` methods, use `fromArray(Object[], int, int)` instead
      Create an expandable integer indexable from part of an int array.
      Type Parameters:
        `E` - element type
      Parameters:
        `array` - integer array
        `start` - start position in array
        `length` - number of byte in array
      Returns:
        expandable integer indexable

    - #### fromArray

          @NotNull
          static <E> ExpandableIndexable<E> fromArray(@NotNull
                                                               E[] array,
                                                               int start,
                                                               int length)

      Create an expandable integer indexable from part of an int array.
      Type Parameters:
        `E` - element type
      Parameters:
        `array` - integer array
        `start` - start position in array
        `length` - number of byte in array
      Returns:
        expandable integer indexable

    - #### from

          @NotNull
           @Deprecated
          static <E> ExpandableIndexable<E> from(@NotNull
                                                                       Indexable<E> indexable)

      Deprecated. overlaps with other `from()` methods, use `fromIndexable(Indexable)` instead
      Get an expandable integer indexable from a normal integer indexable.
      Type Parameters:
        `E` - element type
      Parameters:
        `indexable` - standard integer indexable
      Returns:
        expandable copy of the given indexable

    - #### fromIndexable

          @NotNull
          static <E> ExpandableIndexable<E> fromIndexable(@NotNull
                                                                   Indexable<E> indexable)

      Get an expandable integer indexable from a normal integer indexable.
      Type Parameters:
        `E` - element type
      Parameters:
        `indexable` - standard integer indexable
      Returns:
        expandable copy of the given indexable

    - #### from

          @NotNull
           @Deprecated
          static <E> ExpandableIndexable<E> from(@NotNull
                                                                       java.util.Collection<? extends E> values)

      Deprecated. overlaps with other `from()` methods, use `fromCollection(Collection)` instead
      Create an expandable integer indexable from a collection of numbers.
      Type Parameters:
        `E` - element type
      Parameters:
        `values` - collection of numbers, `List` is strongly recommended for better performance
      Returns:
        expandable integer indexable

    - #### fromCollection

          @NotNull
          static <E> ExpandableIndexable<E> fromCollection(@NotNull
                                                                    java.util.Collection<? extends E> values)

      Create an expandable integer indexable from a collection of numbers.
      Specified by:
        `fromCollection` in interface `Indexable<T>`
      Type Parameters:
        `E` - element type
      Parameters:
        `values` - collection of numbers, `List` is strongly recommended for better performance
      Returns:
        expandable integer indexable