de.caff.generics

## Class BasicLoop<T extends BasicLoop.Item<T>>

- java.lang.Object
- - de.caff.generics.BasicLoop<T>

- All Implemented Interfaces:
    Countable<T>, Sizeable, java.lang.Iterable<T>
  Direct Known Subclasses:
    Loop

      public class BasicLoop<T extends BasicLoop.Item<T>>
      extends java.lang.Object
      implements Countable<T>

  Wrapper around a double linked list which forms a loop.

  This basic implementation allows to use user-defined double linked items based on `BasicLoop.Item` because it makes some algorithms easier to add behavior to the items themselves. For loop with items holding generic values see `Loop`.

  This class is not thread-safe.

  Since:
    November 02, 2022
  Author:
    Rammi

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static class` | `BasicLoop.Item<V extends BasicLoop.Item<V>>` Base implementation of a double linked loop item.

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

      `Countable.Base<TT>`

  - ### Field Summary

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

      `EMPTY`

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

      `NULL`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `BasicLoop()` Create an empty loop.
    `BasicLoop(java.util.function.Function<? super V,Function3<T,BasicLoop<T>,T,T>> creatorCreator, V... elements)` Create a loop from an array.
    `BasicLoop(java.lang.Iterable<V> elements, java.util.function.Function<? super V,Function3<T,BasicLoop<T>,T,T>> creatorCreator)` Create a loop from an iterable.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `T` | `add(Function3<T,BasicLoop<T>,T,T> creator)` Add an item.
    `<V> void` | `addAll(java.lang.Iterable<V> elements, java.util.function.Function<? super V,Function3<T,BasicLoop<T>,T,T>> creatorCreator)` Add all the elements to the loop.
    `void` | `clear()` Clear this loop.
    `Countable<T>` | `closedItemView()` View this loop's items as a countable which is "closed".
    `T` | `findFirst(java.util.function.Predicate<? super T> condition)` Find the first item in this loop which fulfills a condition.
    `T` | `findLast(java.util.function.Predicate<? super T> condition)` Find the first item in this loop which fulfills a condition.
    `T` | `getFirstItem()` Get the first item in the loop.
    `T` | `getFirstItemOrNull()` Get the first item in the loop, or `null` if the loop is empty.
    `T` | `getLastItem()` Get the last item in the loop.
    `T` | `getLastItemOrNull()` Get the last item in the loop, or `null` if the loop is empty.
    `boolean` | `isEmpty()` Is this countable empty?
    `java.util.Iterator<T>` | `iterator()` Get an iterator over the items of this loop.
    `void` | `removeSuccessiveDuplicates()` Remove duplicate items which are neighbors.
    `void` | `removeSuccessiveDuplicates(java.util.function.BiPredicate<? super T,? super T> equality)` Remove duplicate items which are neighbors.
    `void` | `rotate(int steps)` Rotate through the loop so the first item is exchanged
    `boolean` | `rotateBackwardUntil(java.util.function.Predicate<? super T> condition)` Rotate backward until a condition is fulfilled for the first item.
    `boolean` | `rotateForwardUntil(java.util.function.Predicate<? super T> condition)` Rotate forward until a condition is fulfilled for the first item.
    `int` | `size()` Get the size.
    `java.lang.String` | `toMultiLineString()` Create a multi-line string from this loop.
    `java.lang.String` | `toString()`
    `java.lang.String` | `toString(java.lang.String connect)` Create a string containing all items, connect with the given connector string.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

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

      `addAllTo, addToArray, asBase, asCollection, combined, combined, containsEq, containsRef, downCast, empty, equal, equals, filtered, filteredToIndexable, filterToCountable, first, firstOrNull, foldLeft, forEachFragile, freeze, fromOptional, frozen, frozen, getAny, groupingBy, groupingBy, hasAll, hasAny, isSorted, isStrictlySorted, last, lastOrNull, mappingBy, mappingBy, optFirst, optional, optLast, orderedCombination, parellelStream, singleton, sorted, spliterator, stream, toArray, toArray, toList, toString, uniform, view, viewArray, viewArray, viewCollection, viewCollection, viewCollectionN, viewCollectionN, viewFragile, withAppendedItem, withPrependedItem`

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

      `forEach`

- - ### Constructor Detail

    - #### BasicLoop

          public BasicLoop()

      Create an empty loop.

    - #### BasicLoop

          public BasicLoop(@NotNull
                           java.lang.Iterable<V> elements,
                           @NotNull
                           java.util.function.Function<? super V,Function3<T,BasicLoop<T>,T,T>> creatorCreator)

      Create a loop from an iterable.
      Type Parameters:
        `V` - element type of the iterable
      Parameters:
        `elements` - elements to insert into this loop, in the given order
        `creatorCreator` - function which maps the elements to an item creator

    - #### BasicLoop

          @SafeVarargs
          public BasicLoop(@NotNull
                                        java.util.function.Function<? super V,Function3<T,BasicLoop<T>,T,T>> creatorCreator,
                                        V... elements)

      Create a loop from an array.
      Type Parameters:
        `V` - element type of the array
      Parameters:
        `creatorCreator` - function which maps the array elements to an item creator
        `elements` - elements to add to this loop

  - ### Method Detail

    - #### getFirstItem

          @NotNull
          public T getFirstItem()

      Get the first item in the loop.
      Returns:
        first item
      Throws:
        `EmptyLoopError` - when loop is empty

    - #### getFirstItemOrNull

          @Nullable
          public T getFirstItemOrNull()

      Get the first item in the loop, or `null` if the loop is empty.
      Returns:
        first item, or `null`

    - #### getLastItem

          @NotNull
          public T getLastItem()

      Get the last item in the loop.
      Returns:
        last item
      Throws:
        `EmptyLoopError` - when loop is empty

    - #### getLastItemOrNull

          @Nullable
          public T getLastItemOrNull()

      Get the last item in the loop, or `null` if the loop is empty.
      Returns:
        last item, or `null`

    - #### rotate

          public void rotate(int steps)

      Rotate through the loop so the first item is exchanged
      Parameters:
        `steps` - steps to rotate,

    - #### rotateForwardUntil

          public boolean rotateForwardUntil(@NotNull
                                            java.util.function.Predicate<? super T> condition)

      Rotate forward until a condition is fulfilled for the first item. If the condition is `true` for the first value no rotation occurs.
      Parameters:
        `condition` - condition tested on value
      Returns:
        `true` if the condition is now fulfilled for the `first` value, `false` if not or if this loop is empty

    - #### rotateBackwardUntil

          public boolean rotateBackwardUntil(@NotNull
                                             java.util.function.Predicate<? super T> condition)

      Rotate backward until a condition is fulfilled for the first item. If the condition is `true` for the first value no rotation occurs.
      Parameters:
        `condition` - condition tested on value
      Returns:
        `true` if the condition is now fulfilled for the `first` value, `false` if not or if this loop is empty

    - #### findFirst

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

      Find the first item in this loop which fulfills a condition.

      Use `BasicLoop.Item.findNext(Predicate)` on the result to continue searching.

      Parameters:
        `condition` - condition to be checked
      Returns:
        item found or `null` if no item matches the condition

    - #### findLast

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

      Find the first item in this loop which fulfills a condition.

      Use `BasicLoop.Item.findPrevious(Predicate)` on the result to continue searching.

      Parameters:
        `condition` - condition to be checked
      Returns:
        item found or `null` if no item matches the condition

    - #### add

          @NotNull
          public T add(@NotNull
                                Function3<T,BasicLoop<T>,T,T> creator)

      Add an item.
      Parameters:
        `creator` - item creator, called with 2nd and 3rd arguments being `null` for the initial loop element
      Returns:
        added item

    - #### addAll

          public <V> void addAll(@NotNull
                                 java.lang.Iterable<V> elements,
                                 @NotNull
                                 java.util.function.Function<? super V,Function3<T,BasicLoop<T>,T,T>> creatorCreator)

      Add all the elements to the loop. This will add the given elements in the given order into the loop before the first element.
      Type Parameters:
        `V` - incoming value type
      Parameters:
        `elements` - elements to add to this loop
        `creatorCreator` - function which creates the loop element creators from the incoming elements

    - #### size

          public int size()

      Description copied from interface: `Sizeable`
      Get the size. Size is never negative.
      Specified by:
        `size` in interface `Sizeable`
      Returns:
        the size of this object, usually the number of contained elements, must not be negative

    - #### isEmpty

          public boolean isEmpty()

      Description copied from interface: `Countable`
      Is this countable empty? An empty countable does not contain any elements which means that `Sizeable.size()` will return `0`.

      This default implementation just checks for `Sizeable.size()` returning `0`

      Specified by:
        `isEmpty` in interface `Countable<T extends BasicLoop.Item<T>>`
      Returns:
        `true` if this countable is empty, `false` otherwise. Because calculating the size might be expensive sometimes in these cases implementations should override this method if possible.

    - #### clear

          public void clear()

      Clear this loop.

    - #### iterator

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

      Get an iterator over the items of this loop.
      Specified by:
        `iterator` in interface `java.lang.Iterable<T extends BasicLoop.Item<T>>`
      Returns:
        item iterator

    - #### closedItemView

          @NotNull
          public Countable<T> closedItemView()

      View this loop's items as a countable which is "closed". The returned countable will virtually close the loop by adding the first item of the loop again at the end. This simplifies some usages of the loop.
      Returns:
        closed item view of this loop

    - #### removeSuccessiveDuplicates

          public void removeSuccessiveDuplicates(@NotNull
                                                 java.util.function.BiPredicate<? super T,? super T> equality)

      Remove duplicate items which are neighbors.
      Parameters:
        `equality` - equality check for items, expected to return `true` for duplicates

    - #### removeSuccessiveDuplicates

          public void removeSuccessiveDuplicates()

      Remove duplicate items which are neighbors. This method calls `removeSuccessiveDuplicates(BiPredicate)` with `Objects.deepEquals(Object, Object)` as equality check.

    - #### toString

          public java.lang.String toString()

      Overrides:
        `toString` in class `java.lang.Object`

    - #### toString

          @NotNull
          public java.lang.String toString(@NotNull
                                                    java.lang.String connect)

      Create a string containing all items, connect with the given connector string.
      Parameters:
        `connect` - connector string
      Returns:
        string representation of this loop, items separated by `connect`

    - #### toMultiLineString

          @NotNull
          public java.lang.String toMultiLineString()

      Create a multi-line string from this loop.
      Returns:
        multi-line string