com.koloboke.collect

Class Equivalence<T>

Object

com.koloboke.collect.Equivalence<T>

Type Parameters:

T - type of objects compared by this equivalence

Direct Known Subclasses:

StatelessEquivalence

public abstract class Equivalence<T>
extends Object

A strategy for determining whether two instances are considered equivalent.

This class is inspired and very similar to Guava's Equivalence, with one notable difference: this Equivalence forces the actual implementation to override equals(Object) and hashCode(). Notice these are Equivalence's own equals and hashCode, not the strategy equivalent(Object, Object) and hash(Object) methods. It is needed because, for example, ObjCollection's equality depends on Equivalence equality.

In most cases, when Equivalence is stateless, you can extend StatelessEquivalence not to bother with implementing these methods. See examples in the documentation to identity and case insensitive equivalences.

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	Equivalence() Constructor for use by subclasses.

Method Summary

Modifier and Type	Method and Description
static Equivalence<String>	caseInsensitive() Returns the String equivalence that uses String.equalsIgnoreCase(java.lang.String) to compare strings.
static Equivalence<CharSequence>	charSequence() Returns the equivalence that compares CharSequences by their contents.
static <T> Equivalence<T>	defaultEquality() Returns the default, built-in equivalence in Java, driven by Object.equals(Object) and Object.hashCode() methods.
static <K,V> Equivalence<Map.Entry<K,V>>	entryEquivalence(Equivalence<K> keyEquivalence, Equivalence<V> valueEquivalence) Returns a Map.Entry equivalence for the given key and value equivalences.
abstract boolean	equals(Object o)
abstract boolean	equivalent(T a, T b) Returns true if a and b are considered equivalent, false otherwise.
abstract int	hash(T t) Returns a hash code for the given object.
abstract int	hashCode()
static <T> Equivalence<T>	identity() Returns the equivalence that uses == to compare objects and System.identityHashCode(Object) to compute the hash code.
boolean	nullableEquivalent(T a, T b) Returns true if a and b are considered equivalent, false otherwise.
int	nullableHash(T t) Returns a hash code for the given object.

Methods inherited from class Object

clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

Equivalence

protected Equivalence()

Constructor for use by subclasses.

Method Detail

defaultEquality

@Nonnull
public static <T> Equivalence<T> defaultEquality()

Returns the default, built-in equivalence in Java, driven by Object.equals(Object) and Object.hashCode() methods.

Type Parameters:

T - type of objects, needed to compare. Object.equals(java.lang.Object) could be applied to object of any type, so there aren't any constraints over the generic type parameter.

Returns:

the built-in Java equality

identity

@Nonnull
public static <T> Equivalence<T> identity()

Returns the equivalence that uses == to compare objects and System.identityHashCode(Object) to compute the hash code. nullableEquivalent(T, T) returns true if a == b, including in the case when a and b are both null.

This equivalence could be implemented as follows:

 final class Identity extends StatelessEquivalence<Object> {
     static final Identity INSTANCE = new Identity();
     private Identity() {}
     @Override
     public boolean equivalent(@Nonnull Object a, @Nonnull Object b) {
         return a == b;
     }
     @Override
     public int hash(@Nonnull Object t) {
         return System.identityHashCode(t);
     }
 }
 

Type Parameters:

T - type of objects, needed to compare. Identity check could be applied to objects of any type, so there aren't any constraints over the generic type parameter.

Returns:

the identity equivalence

charSequence

@Nonnull
public static Equivalence<CharSequence> charSequence()

Returns the equivalence that compares CharSequences by their contents.

This equivalence could be implemented as follows (actual implementation, of cause, is more efficient and doesn't allocate garbage objects):

 final class CharSequenceEquivalence extends StatelessEquivalence<CharSequence> {
     static final CharSequenceEquivalence INSTANCE = new CharSequenceEquivalence();
     private CharSequenceEquivalence() {}
     @Override
     public boolean equivalent(@Nonnull CharSequence a, @Nonnull CharSequence b) {
         return a.toString().equals(b.toString());
     }
     @Override
     public int hash(@Nonnull CharSequence cs) {
         return cs.toString().hashCode();
     }
 }

Returns:

the CharSequence equivalence

caseInsensitive

@Nonnull
public static Equivalence<String> caseInsensitive()

Returns the String equivalence that uses String.equalsIgnoreCase(java.lang.String) to compare strings.

This equivalence could be implemented as follows:

 final class CaseInsensitive extends StatelessEquivalence<String> {
     static final CaseInsensitive INSTANCE = new CaseInsensitive();
     private CaseInsensitive() {}
     @Override
     public boolean equivalent(@Nonnull String a, @Nonnull String b) {
         return a.equalsIgnoreCase(b);
     }
     @Override
     public int hash(@Nonnull String s) {
         return s.toLowerCase().hashCode();
     }
 }
 

Returns:

the case-insensitive String equivalence

entryEquivalence

@Nonnull
public static <K,V> Equivalence<Map.Entry<K,V>> entryEquivalence(@Nonnull
                                                                           Equivalence<K> keyEquivalence,
                                                                           @Nonnull
                                                                           Equivalence<V> valueEquivalence)

Returns a Map.Entry equivalence for the given key and value equivalences.

Type Parameters:

K - the entry key type

V - the entry value type

Parameters:

keyEquivalence - the entry key equivalence

valueEquivalence - the entry value equivalence

Returns:

a Map.Entry equivalence for the given key and value equivalences

nullableEquivalent

public boolean nullableEquivalent(@Nullable
                                  T a,
                                  @Nullable
                                  T b)

Returns true if a and b are considered equivalent, false otherwise. a and b both might be null.

If the implementation overrides this method, it must ensure that it returns true if both the given objects are nulls and false, if only one of them is null. If both a and b are non-null, this method should perform just the same as equivalent(Object, Object) method does.

Parameters:

a - the first object to compare

b - the second object to compare

Returns:

true if a and b are considered equivalent, false otherwise

equivalent

public abstract boolean equivalent(@Nonnull
                                   T a,
                                   @Nonnull
                                   T b)

Returns true if a and b are considered equivalent, false otherwise. a and b are assumed to be non-null.

This method implements an equivalence relation on object references:

• It is reflexive: for any reference x, equivalent(x, x) returns true.
• It is symmetric: for any references x and y, equivalent(x, y) == equivalent(y, x).
• It is transitive: for any references x, y, and z, if equivalent(x, y) returns true and equivalent(y, z) returns true, then equivalent(x, z) returns true.
• It is consistent: for any references x and y, multiple invocations of equivalent(x, y) consistently return true or consistently return false (provided that neither x nor y is modified).

This method is called by nullableEquivalent(Object, Object).

Parameters:

a - the first object to compare

b - the second object to compare

Returns:

true if a and b are considered equivalent, false otherwise

nullableHash

public int nullableHash(@Nullable
                        T t)

Returns a hash code for the given object. The t object might be null.

If the implementation overrides this method, it must ensure that it returns 0 if the given object is null. Otherwise this method should perform just the same as hash(Object) method does.

Parameters:

t - the object to compute hash code for

Returns:

a hash code for the given object

hash

public abstract int hash(@Nonnull
                         T t)

Returns a hash code for the given object. The t object is assumed to be non-null.

This method has the following properties:

• It is consistent: for any reference x, multiple invocations of hash(x) consistently return the same value provided x remains unchanged according to the definition of the equivalence. The hash need not remain consistent from one execution of an application to another execution of the same application.
• It is distributable across equivalence: for any references x and y, if equivalent(x, y), then hash(x) == hash(y). It is not necessary that the hash be distributable across inequivalence. If equivalence(x, y) is false, hash(x) == hash(y) may still be true.

This method is called by nullableHash(Object).

Parameters:

t - the object to compute hash code for

Returns:

a hash code for the given object

equals

public abstract boolean equals(Object o)

This method is made abstract to force the final implementation to override it. It is needed because, for example, ObjObjMap's equality depends on key and value Equivalence equality.

Overrides:

equals in class Object

hashCode

public abstract int hashCode()

This method is made abstract to force the final implementation to override it. It is needed because, equals(Object) is needed to be overridden, and in Java Object.equals(Object) and Object.hashCode() should always be overridden simultaneously.

Overrides:

hashCode in class Object