de.caff.generics

## Interface PrimitiveIntIterable

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

      public interface PrimitiveIntIterable
      extends java.lang.Iterable<java.lang.Integer>

  Iterable which iterates over a primitive int.
  Since:
    December 13, 2021
  Author:
    Rammi
  See Also:
    `for creating one on the fly`

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static PrimitiveIntIterable` | `EMPTY` Empty iterable of primitive int values.
    `static java.util.PrimitiveIterator.OfInt` | `EMPTY_INT_ITERATOR` Empty iterator of primitive int values.

  - ### Method Summary

    All Methods Instance Methods Abstract Methods Default Methods
    Modifier and Type | Method and Description
    --- | ---
    `default java.util.OptionalDouble` | `average()` Calculate the average of all elements in this iterable.
    `default boolean` | `containsInt(int value)` Does this integer iterable contain the given value?
    `default void` | `forEachInt(java.util.function.IntConsumer action)` Invoke the given action with each int value in this iterable.
    `default <E extends java.lang.Exception> void` | `forEachIntFragile(FragileIntConsumer<E> action)` Invoke the given fragile action with each value in this iterable.
    `java.util.PrimitiveIterator.OfInt` | `intIterator()` Get a primitive int iterator.
    `default java.util.Iterator<java.lang.Integer>` | `iterator()`
    `default long` | `longSum()` Calculate the sum of the elements of this iterable as a long value.
    `default long` | `longSumX()` Calculate the sum of the elements of this iterable as a long value.
    `default java.util.Spliterator.OfInt` | `spliterator()`
    `default java.util.stream.IntStream` | `stream()` Get a stream of primitive integer values from this iterable.
    `default int` | `sum()` Calculate the sum of the elements of this iterable as an integer value.
    `default int` | `sumX()` Calculate the sum of the elements of this iterable as an integer value.

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

      `forEach`

- - ### Field Detail

    - #### EMPTY_INT_ITERATOR

          static final java.util.PrimitiveIterator.OfInt EMPTY_INT_ITERATOR

      Empty iterator of primitive int values.

    - #### EMPTY

          static final PrimitiveIntIterable EMPTY

      Empty iterable of primitive int values.

  - ### Method Detail

    - #### intIterator

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

      Get a primitive int iterator.
      Returns:
        int iterator

    - #### iterator

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

      Specified by:
        `iterator` in interface `java.lang.Iterable<java.lang.Integer>`

    - #### forEachInt

          default void forEachInt(@NotNull
                                  java.util.function.IntConsumer action)

      Invoke the given action with each int value in this iterable.
      Parameters:
        `action` - action to be called for each int value in sequence.

    - #### forEachIntFragile

          default <E extends java.lang.Exception> void forEachIntFragile(@NotNull
                                                                         FragileIntConsumer<E> action)
                                                                  throws E extends java.lang.Exception

      Invoke the given fragile action with each value in this iterable.
      Type Parameters:
        `E` - checked exception thrown by action
      Parameters:
        `action` - action to be called for each value in sequence
      Throws:
        `E` - if `action` throws it
        `E extends java.lang.Exception`

    - #### containsInt

          default boolean containsInt(int value)

      Does this integer iterable contain the given value? This is an operation which takes time linear to the size of this iterable and should only be used rarely.
      Parameters:
        `value` - value to check for
      Returns:
        `true` if the value is contained in this iterable, `false` if not

    - #### sum

          default int sum()

      Calculate the sum of the elements of this iterable as an integer value.

      Please note that this might silently overflow. See `sumX()` if you want to avoid this with the price of running much slower, or `longSum()` if you want to make an overflow unlikely.

      Returns:
        sum of all elements of this iterable

    - #### sumX

          default int sumX()

      Calculate the sum of the elements of this iterable as an integer value.

      This will throw an exception if summing up overflows.

      Returns:
        sum of all elements of this iterable
      Throws:
        `java.lang.ArithmeticException` - if summing up overflows the range of `int`

    - #### longSum

          default long longSum()

      Calculate the sum of the elements of this iterable as a long value. Please note that this might silently overflow when summing on very large (i.e. more than 2^32 iterations) iterables.
      Returns:
        sum of all elements of this iterable

    - #### longSumX

          default long longSumX()

      Calculate the sum of the elements of this iterable as a long value. This will throw an exception if summing up overflows the range of `long`.
      Returns:
        sum of all elements of this iterable
      Throws:
        `java.lang.ArithmeticException` - if summing up overflows the range of `long`

    - #### average

          @NotNull
          default java.util.OptionalDouble average()

      Calculate the average of all elements in this iterable.
      Returns:
        average, possibly `Double.NaN` if this iterable is empts

    - #### spliterator

          default java.util.Spliterator.OfInt spliterator()

      Specified by:
        `spliterator` in interface `java.lang.Iterable<java.lang.Integer>`

    - #### stream

          @NotNull
          default java.util.stream.IntStream stream()

      Get a stream of primitive integer values from this iterable.
      Returns:
        `int` stream