de.caff.generics

## Class Sequences

- java.lang.Object
- - de.caff.generics.Sequences

-     public class Sequences
      extends java.lang.Object

  Equality and comparability for sequences.

  A sequence is an `Iterable` which is expected to provide the same sequence of items in the same order. E.g. a `HashSet` and a `SortedSet` provide different sequences, even if they contain the same elements.

  Since:
    November 20, 2023
  Author:
    Rammi

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static java.util.function.BiPredicate<java.lang.Object,java.lang.Object>` | `IDENTICAL` Are two objects identical?

  - ### Method Summary

    All Methods Static Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `static boolean` | `areEqual(java.lang.Iterable<?> seq1, java.lang.Iterable<?> seq2)` Are two sequences equal in the standard Java definition of equality?
    `static <T1,T2> boolean` | `areEqual(java.lang.Iterable<T1> seq1, java.lang.Iterable<T2> seq2, java.util.function.BiPredicate<? super T1,? super T2> equality)` Are two sequences equal?
    `static boolean` | `areEqual(java.util.Iterator<?> it1, java.util.Iterator<?> it2)` Do two iterators provide the same sequence, using the standard Java definition of equality?
    `static <T1,T2> boolean` | `areEqual(java.util.Iterator<T1> it1, java.util.Iterator<T2> it2, java.util.function.BiPredicate<? super T1,? super T2> equality)` Do two iterators provide the same sequence?
    `static <T1,T2> boolean` | `areEqual(T1[] arr1, int start1, int len1, T2[] arr2, int start2, int len2, java.util.function.BiPredicate<? super T1,? super T2> equality)` Are parts of two arrays equal?
    `static <T1,T2> boolean` | `areEqual(T1[] arr1, T2[] arr2, java.util.function.BiPredicate<? super T1,? super T2> equality)` Are two arrays equal?
    `static boolean` | `areIdentical(java.lang.Iterable<?> seq1, java.lang.Iterable<?> seq2)` Are two sequences equal in the standard Java definition of equality?
    `static boolean` | `areIdentical(java.util.Iterator<?> it1, java.util.Iterator<?> it2)` Do two iterators provide the same sequence, using the standard Java definition of equality?
    `static <T extends java.lang.Comparable<T>> Order` | `compare(java.lang.Iterable<? extends T> seq1, java.lang.Iterable<? extends T> seq2)` Compare two sequences of comparable elements and return the result.
    `static <T extends java.lang.Comparable<T>> Order` | `compare(java.lang.Iterable<? extends T> seq1, java.lang.Iterable<? extends T> seq2, Order longerOrder)` Compare two sequences of comparable elements and return the result.
    `static <T> Order` | `compare(java.lang.Iterable<? extends T> seq1, java.lang.Iterable<? extends T> seq2, Ordering<? super T> ordering)` Compare two sequences and return the result.
    `static <T> Order` | `compare(java.lang.Iterable<? extends T> seq1, java.lang.Iterable<? extends T> seq2, Order longerOrder, Ordering<? super T> ordering)` Compare two sequences and return the result.
    `static <T extends java.lang.Comparable<T>> Order` | `compare(java.util.Iterator<? extends T> it1, java.util.Iterator<? extends T> it2)` Compare the iterators of two sequences and return the result.
    `static <T extends java.lang.Comparable<T>> Order` | `compare(java.util.Iterator<? extends T> it1, java.util.Iterator<? extends T> it2, Order longerOrder)` Compare the iterators of two sequences of comparable elements and return the result.
    `static <T> Order` | `compare(java.util.Iterator<? extends T> it1, java.util.Iterator<? extends T> it2, Ordering<? super T> ordering)` Compare the iterators of two sequences and return the result.
    `static <T> Order` | `compare(java.util.Iterator<? extends T> it1, java.util.Iterator<? extends T> it2, Order longerOrder, Ordering<? super T> ordering)` Compare the iterators of two sequences and return the result.

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

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

- - ### Field Detail

    - #### IDENTICAL

          public static final java.util.function.BiPredicate<java.lang.Object,java.lang.Object> IDENTICAL

      Are two objects identical? This pours `e1 == e2` into a bi-predicate.

  - ### Method Detail

    - #### areEqual

          public static boolean areEqual(@NotNull
                                         java.lang.Iterable<?> seq1,
                                         @NotNull
                                         java.lang.Iterable<?> seq2)

      Are two sequences equal in the standard Java definition of equality? This convenience method compares two sequences element by element using `Objects.deepEquals(Object, Object)` as equality definition. Two sequences with different lengths are always considered unequal.

      This method deliberately allows comparison of sequences of different types.

      Parameters:
        `seq1` - first sequence
        `seq2` - second sequence
      Returns:
        `true` if both sequences are considered equal
        `false` if they are considered unequal

    - #### areEqual

          public static boolean areEqual(@NotNull
                                         java.util.Iterator<?> it1,
                                         @NotNull
                                         java.util.Iterator<?> it2)

      Do two iterators provide the same sequence, using the standard Java definition of equality? This method compares two iterators element by element for equality using `Objects.deepEquals(Object, Object)`. Two sequences with different lengths are always considered unequal.

      This method deliberately allows comparison of sequences of different types.

      The iterators used as parameters will be both exhausted if this method returns `true`. Otherwise, they will stand at the first inequality, which can mean that one is exhausted while the other is not.

      Parameters:
        `it1` - iterator over the first sequence
        `it2` - iterator over the second sequence
      Returns:
        `true` if both sequences are considered equal
        `false` if they are considered unequal

    - #### areIdentical

          public static boolean areIdentical(@NotNull
                                             java.lang.Iterable<?> seq1,
                                             @NotNull
                                             java.lang.Iterable<?> seq2)

      Are two sequences equal in the standard Java definition of equality? This convenience method compares two sequences element by element using `Objects.equals(Object, Object)` as equality definition. Two sequences with different lengths are always considered unequal.

      This method deliberately allows comparison of sequences of different types.

      Parameters:
        `seq1` - first sequence
        `seq2` - second sequence
      Returns:
        `true` if both sequences are considered equal
        `false` if they are considered unequal

    - #### areIdentical

          public static boolean areIdentical(@NotNull
                                             java.util.Iterator<?> it1,
                                             @NotNull
                                             java.util.Iterator<?> it2)

      Do two iterators provide the same sequence, using the standard Java definition of equality? This method compares two iterators element by element for equality using `Objects.equals(Object, Object)`. Two sequences with different lengths are always considered unequal.

      This method deliberately allows comparison of sequences of different types.

      The iterators used as parameters will be both exhausted if this method returns `true`. Otherwise, they will stand at the first inequality, which can mean that one is exhausted while the other is not.

      Parameters:
        `it1` - iterator over the first sequence
        `it2` - iterator over the second sequence
      Returns:
        `true` if both sequences are considered equal
        `false` if they are considered unequal

    - #### areEqual

          public static <T1,T2> boolean areEqual(@NotNull
                                                 java.lang.Iterable<T1> seq1,
                                                 @NotNull
                                                 java.lang.Iterable<T2> seq2,
                                                 @NotNull
                                                 java.util.function.BiPredicate<? super T1,? super T2> equality)

      Are two sequences equal? This method compares two sequences element by element for equality. The user is free to decide what is considered "equal". Two sequences with different lengths are always considered unequal.

      This method deliberately allows comparison of sequences of different types.

      Type Parameters:
        `T1` - element type of first sequence
        `T2` - element type of second sequence
      Parameters:
        `seq1` - first sequence
        `seq2` - second sequence
        `equality` - element equality definition, has to return `true` for elements considered, and `false` for elements considered unequal
      Returns:
        `true` if both sequences are considered equal
        `false` if they are considered unequal

    - #### areEqual

          public static <T1,T2> boolean areEqual(@NotNull
                                                 T1[] arr1,
                                                 @NotNull
                                                 T2[] arr2,
                                                 @NotNull
                                                 java.util.function.BiPredicate<? super T1,? super T2> equality)

      Are two arrays equal? This method compares two arrays element by element for equality. The user is free to decide what is considered "equal". Two arrays with different lengths are always considered unequal.

      This method deliberately allows comparison of arrays of different types.

      Type Parameters:
        `T1` - element type of first array
        `T2` - element type of second array
      Parameters:
        `arr1` - first array
        `arr2` - second array
        `equality` - element equality definition, has to return `true` for elements considered, and `false` for elements considered unequal
      Returns:
        `true` if both sequences are considered equal
        `false` if they are considered unequal

    - #### areEqual

          public static <T1,T2> boolean areEqual(@NotNull
                                                 T1[] arr1,
                                                 int start1,
                                                 int len1,
                                                 @NotNull
                                                 T2[] arr2,
                                                 int start2,
                                                 int len2,
                                                 @NotNull
                                                 java.util.function.BiPredicate<? super T1,? super T2> equality)

      Are parts of two arrays equal? This method compares intervals of two arrays element by element for equality. The user is free to decide what is considered "equal". Two intervals with different lengths are always considered unequal.

      This method deliberately allows comparison of arrays of different types.

      Type Parameters:
        `T1` - element type of first array
        `T2` - element type of second array
      Parameters:
        `arr1` - first array
        `start1` - index of the first relevant element in the first array
        `len1` - number of relevant elements in the first array
        `arr2` - second array
        `start2` - index of the first relevant element in the second array
        `len2` - number of relevant elements in the second array
        `equality` - element equality definition, has to return `true` for elements considered, and `false` for elements considered unequal
      Returns:
        `true` if both intervals are considered equal
        `false` if they are considered unequal

    - #### areEqual

          public static <T1,T2> boolean areEqual(@NotNull
                                                 java.util.Iterator<T1> it1,
                                                 @NotNull
                                                 java.util.Iterator<T2> it2,
                                                 @NotNull
                                                 java.util.function.BiPredicate<? super T1,? super T2> equality)

      Do two iterators provide the same sequence? This method compares two iterators element by element for equality. The user is free to decide what is considered "equal". Two sequences with different lengths are always considered unequal.

      This method deliberately allows comparison of sequences of different types.

      The iterators used as parameters will be both exhausted if this method returns `true`. Otherwise, they will stand at the first inequality, which can mean that one is exhausted while the other is not.

      Type Parameters:
        `T1` - element type of first sequence
        `T2` - element type of second sequence
      Parameters:
        `it1` - iterator over the first sequence
        `it2` - iterator over the second sequence
        `equality` - element equality definition, has to return `true` for elements considered, and `false` for elements considered unequal
      Returns:
        `true` if both sequences are considered equal
        `false` if they are considered unequal

    - #### compare

          @NotNull
          public static <T extends java.lang.Comparable<T>> Order compare(@NotNull
                                                                                   java.lang.Iterable<? extends T> seq1,
                                                                                   @NotNull
                                                                                   java.lang.Iterable<? extends T> seq2)

      Compare two sequences of comparable elements and return the result. This method will assume lexical ordering, i.e., if the sequences have the same elements, but one is longer, the longer sequence will be sorted after the shorter sequence.
      Type Parameters:
        `T` - common (super) element type of both sequences
      Parameters:
        `seq1` - first sequence
        `seq2` - second sequence
      Returns:
        `Order` enum value describing the order of both sequences

    - #### compare

          @NotNull
          public static <T extends java.lang.Comparable<T>> Order compare(@NotNull
                                                                                   java.lang.Iterable<? extends T> seq1,
                                                                                   @NotNull
                                                                                   java.lang.Iterable<? extends T> seq2,
                                                                                   @NotNull
                                                                                   Order longerOrder)

      Compare two sequences of comparable elements and return the result. This method will assume lexical ordering, i.e., if the sequences have the same elements, but one is longer, the longer sequence will be sorted after the shorter sequence.
      Type Parameters:
        `T` - common (super) element type of both sequences
      Parameters:
        `seq1` - first sequence
        `seq2` - second sequence
        `longerOrder` - order which is returned when both sequences contain the same elements, but the second sequence is longer. If in this case the first sequence is longer, the `Order.inverse()` of `longerOrder` will be returned.
      Returns:
        `Order` enum value describing the order of both sequences

    - #### compare

          @NotNull
          public static <T> Order compare(@NotNull
                                                   java.lang.Iterable<? extends T> seq1,
                                                   @NotNull
                                                   java.lang.Iterable<? extends T> seq2,
                                                   @NotNull
                                                   Ordering<? super T> ordering)

      Compare two sequences and return the result. This method will assume lexical ordering, i.e., if the sequences have the same elements, but one is longer, the longer sequence will be sorted after the shorter sequence.
      Type Parameters:
        `T` - common (super) element type of both sequences
      Parameters:
        `seq1` - first sequence
        `seq2` - second sequence
        `ordering` - ordering relation
      Returns:
        `Order` enum value describing the order of both sequences

    - #### compare

          @NotNull
          public static <T> Order compare(@NotNull
                                                   java.lang.Iterable<? extends T> seq1,
                                                   @NotNull
                                                   java.lang.Iterable<? extends T> seq2,
                                                   @NotNull
                                                   Order longerOrder,
                                                   @NotNull
                                                   Ordering<? super T> ordering)

      Compare two sequences and return the result.
      Type Parameters:
        `T` - common (super) element type of both sequences
      Parameters:
        `seq1` - first sequence
        `seq2` - second sequence
        `longerOrder` - order which is returned when both sequences contain the same elements, but the second sequence is longer. If in this case the first sequence is longer, the `Order.inverse()` of `longerOrder` will be returned.
        `ordering` - ordering relation
      Returns:
        `Order` enum value describing the order of both sequences

    - #### compare

          @NotNull
          public static <T> Order compare(@NotNull
                                                   java.util.Iterator<? extends T> it1,
                                                   @NotNull
                                                   java.util.Iterator<? extends T> it2,
                                                   @NotNull
                                                   Ordering<? super T> ordering)

      Compare the iterators of two sequences and return the result. This method will assume lexical ordering, i.e., if the sequences have the same elements, but one is longer, the longer sequence will be sorted after the shorter sequence.
      Type Parameters:
        `T` - common (super) element type of both sequences
      Parameters:
        `it1` - iterator of the first sequence (changed)
        `it2` - iterator of the second sequence (changed)
        `ordering` - ordering relation
      Returns:
        `Order` enum value describing the order of both sequences

    - #### compare

          @NotNull
          public static <T extends java.lang.Comparable<T>> Order compare(@NotNull
                                                                                   java.util.Iterator<? extends T> it1,
                                                                                   @NotNull
                                                                                   java.util.Iterator<? extends T> it2)

      Compare the iterators of two sequences and return the result. This method will assume lexical ordering, i.e., if the sequences have the same elements, but one is longer, the longer sequence will be sorted after the shorter sequence.
      Type Parameters:
        `T` - common (super) element type of both sequences
      Parameters:
        `it1` - iterator of the first sequence (changed)
        `it2` - iterator of the second sequence (changed)
      Returns:
        `Order` enum value describing the order of both sequences

    - #### compare

          @NotNull
          public static <T extends java.lang.Comparable<T>> Order compare(@NotNull
                                                                                   java.util.Iterator<? extends T> it1,
                                                                                   @NotNull
                                                                                   java.util.Iterator<? extends T> it2,
                                                                                   @NotNull
                                                                                   Order longerOrder)

      Compare the iterators of two sequences of comparable elements and return the result.
      Type Parameters:
        `T` - common (super) element type of both sequences
      Parameters:
        `it1` - iterator of the first sequence (changed)
        `it2` - iterator of the second sequence (changed)
        `longerOrder` - order which is returned when both sequences contain the same elements, but the second sequence is longer. If in this case the first sequence is longer, the `Order.inverse()` of `longerOrder` will be returned.
      Returns:
        `Order` enum value describing the order of both sequences

    - #### compare

          @NotNull
          public static <T> Order compare(@NotNull
                                                   java.util.Iterator<? extends T> it1,
                                                   @NotNull
                                                   java.util.Iterator<? extends T> it2,
                                                   @NotNull
                                                   Order longerOrder,
                                                   @NotNull
                                                   Ordering<? super T> ordering)

      Compare the iterators of two sequences and return the result.
      Type Parameters:
        `T` - common (super) element type of both sequences
      Parameters:
        `it1` - iterator of the first sequence (changed)
        `it2` - iterator of the second sequence (changed)
        `longerOrder` - order which is returned when both sequences contain the same elements, but the second sequence is longer. If in this case the first sequence is longer, the `Order.inverse()` of `longerOrder` will be returned.
        `ordering` - ordering relation
      Returns:
        `Order` enum value describing the order of both sequences