de.caff.generics

## Class Loop<T>

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

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

      public class Loop<T>
      extends BasicLoop<Loop.Item<T>>

  Generic version of a loop where loop items can contain any value.

  This is useful in cases when the loop is manipulated from the outside. It is also restricted to non-`null` values.

  As the underlying `BasicLoop` 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` | `Loop.Item<T>` Generic 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
    `Loop()` Empty loop constructor.
    `Loop(java.lang.Iterable<T> elements)` Constructor.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `Loop.Item<T>` | `add(T value)` Add a value to the end of the loop.
    `void` | `addAll(java.lang.Iterable<? extends T> values)` Add all values.
    `void` | `clear()` Clear this loop.
    `Countable<T>` | `closedValueView()` View this loop's values as a countable which is "closed".
    `Loop.Item<T>` | `findFirstValue(java.util.function.Predicate<? super T> condition)` Find the first item in this loop for which the value fulfills a given condition.
    `Loop.Item<T>` | `findLastValue(java.util.function.Predicate<? super T> condition)` Find the last item in this loop for which the value fulfills a given condition.
    `T` | `firstValue()` Get the value of the first item in this loop.
    `void` | `forEachValue(java.util.function.Consumer<? super T> valueAction)` Perform an action for each value in this loop.
    `T` | `lastValue()` Get the value of the last item in this loop.
    `boolean` | `rotateBackwardUntilValue(java.util.function.Predicate<? super T> condition)` Rotate this loop backward until the value of the first item fulfills a given condition.
    `boolean` | `rotateForwardUntilValue(java.util.function.Predicate<? super T> condition)` Rotate this loop forward until the value of the first item fulfills a given condition.
    `Countable<T>` | `values()` Get a countable view of the values of this loop.

    - ### Methods inherited from class de.caff.generics.BasicLoop

      `add, addAll, closedItemView, findFirst, findLast, getFirstItem, getFirstItemOrNull, getLastItem, getLastItemOrNull, isEmpty, iterator, removeSuccessiveDuplicates, removeSuccessiveDuplicates, rotate, rotateBackwardUntil, rotateForwardUntil, size, toMultiLineString, toString, toString`

    - ### 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

    - #### Loop

          public Loop()

      Empty loop constructor.

    - #### Loop

          public Loop(@NotNull
                      java.lang.Iterable<T> elements)

      Constructor.
      Parameters:
        `elements` - initial loop elements

  - ### Method Detail

    - #### values

          @NotNull
          public final Countable<T> values()

      Get a countable view of the values of this loop.
      Returns:
        countable value view
      See Also:
        `closedValueView()`

    - #### closedValueView

          @NotNull
          public Countable<T> closedValueView()

      View this loop's values as a countable which is "closed". The returned countable will virtually close the view by adding the first value of the loop again at the end. This simplifies some usages of the loop.
      Returns:
        closed value view of this loop
      See Also:
        `values()`

    - #### add

          @NotNull
          public Loop.Item<T> add(@NotNull
                                           T value)

      Add a value to the end of the loop.
      Parameters:
        `value` - value to add
      Returns:
        added loop item

    - #### addAll

          public void addAll(@NotNull
                             java.lang.Iterable<? extends T> values)

      Add all values.
      Parameters:
        `values` - values to add to this loop

    - #### firstValue

          public T firstValue()

      Get the value of the first item in this loop.
      Returns:
        first item's value
      Throws:
        `java.util.NoSuchElementException` - if this countable is empty

    - #### lastValue

          public T lastValue()

      Get the value of the last item in this loop.
      Returns:
        last item's value
      Throws:
        `java.util.NoSuchElementException` - if this countable is empty

    - #### findFirstValue

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

      Find the first item in this loop for which the value fulfills a given condition.
      Parameters:
        `condition` - value condition
      Returns:
        first matching item, or `null` if none matches

    - #### findLastValue

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

      Find the last item in this loop for which the value fulfills a given condition.
      Parameters:
        `condition` - value condition
      Returns:
        last matching item, or `null` if none matches

    - #### rotateForwardUntilValue

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

      Rotate this loop forward until the value of the first item fulfills a given condition.
      Parameters:
        `condition` - value condition
      Returns:
        `true` if the condition is now fulfilled for the `first` value, `false` if not or if this loop is empty

    - #### rotateBackwardUntilValue

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

      Rotate this loop backward until the value of the first item fulfills a given condition.
      Parameters:
        `condition` - value condition
      Returns:
        `true` if the condition is now fulfilled for the `first` value, `false` if not or if this loop is empty

    - #### forEachValue

          public void forEachValue(@NotNull
                                   java.util.function.Consumer<? super T> valueAction)

      Perform an action for each value in this loop.
      Parameters:
        `valueAction` - action to be performed for each value

    - #### clear

          public void clear()

      Clear this loop.
      Overrides:
        `clear` in class `BasicLoop<Loop.Item<T>>`