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

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