Class StructuralEqualityComparer

Namespace

ShapeShift.Equality

Assembly

ShapeShift.dll

Creates deep, structural IEqualityComparer<T> implementations for types described by PolyType shapes.

public static class StructuralEqualityComparer

Inheritance

object

StructuralEqualityComparer

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Remarks

The comparers created by this class compare entire object graphs by value: two values are equal when their corresponding leaves are equal, regardless of whether they are the same object, how many objects they are built from, or in what order a dictionary or set happens to enumerate its contents. Reference cycles are supported.

The comparers are trimming and NativeAOT safe because they are built exclusively from source generated shapes; no reflection is used.

Every method here is a shortcut for the equivalent method on Default or CollisionResistant. Use the provider directly when comparers for particular types should be customized.

Methods

CreateCollisionResistant<T>()

Creates a structural comparer whose hash codes are randomized per process and resistant to deliberately constructed collisions.

public static IEqualityComparer<T> CreateCollisionResistant<T>() where T : IShapeable<T>

Returns

IEqualityComparer<T>

A structural comparer.

Type Parameters

T

The type to compare.

Remarks

Equality is identical to that of the comparers returned by the Create methods. Only the hash codes differ.

The hash codes are computed with SipHash-2-4 over the content of each leaf value, under a key that is randomly generated once per process. This makes it impractical for an untrusted party to craft inputs that collide, which protects hash based collections from algorithmic complexity attacks.

The caveats are important: hash codes are not comparable across processes or machines and must never be persisted or transmitted; hashing is meaningfully slower than the default policy because every leaf is hashed by content; and the result is not a message authentication code, since the hash is truncated to 32 bits.

CreateCollisionResistant<T>(ITypeShape<T>)

Creates a structural comparer whose hash codes are randomized per process and resistant to deliberately constructed collisions.

public static IEqualityComparer<T> CreateCollisionResistant<T>(ITypeShape<T> shape)

Parameters

shape ITypeShape<T>

The shape of the type to compare.

Returns

IEqualityComparer<T>

A structural comparer.

Type Parameters

T

The type to compare.

Remarks

Equality is identical to that of the comparers returned by the Create methods. Only the hash codes differ.

The hash codes are computed with SipHash-2-4 over the content of each leaf value, under a key that is randomly generated once per process. This makes it impractical for an untrusted party to craft inputs that collide, which protects hash based collections from algorithmic complexity attacks.

The caveats are important: hash codes are not comparable across processes or machines and must never be persisted or transmitted; hashing is meaningfully slower than the default policy because every leaf is hashed by content; and the result is not a message authentication code, since the hash is truncated to 32 bits.

CreateCollisionResistant<T, TProvider>()

Creates a structural comparer whose hash codes are randomized per process and resistant to deliberately constructed collisions.

public static IEqualityComparer<T> CreateCollisionResistant<T, TProvider>() where TProvider : IShapeable<T>

Returns

IEqualityComparer<T>

A structural comparer.

Type Parameters

T

The type to compare.

TProvider

The witness type that describes T.

Remarks

Equality is identical to that of the comparers returned by the Create methods. Only the hash codes differ.

The hash codes are computed with SipHash-2-4 over the content of each leaf value, under a key that is randomly generated once per process. This makes it impractical for an untrusted party to craft inputs that collide, which protects hash based collections from algorithmic complexity attacks.

The caveats are important: hash codes are not comparable across processes or machines and must never be persisted or transmitted; hashing is meaningfully slower than the default policy because every leaf is hashed by content; and the result is not a message authentication code, since the hash is truncated to 32 bits.

Create<T>()

Creates a structural comparer for a self-describing type.

public static IEqualityComparer<T> Create<T>() where T : IShapeable<T>

Returns

IEqualityComparer<T>

A structural comparer.

Type Parameters

T

The type to compare.

Create<T>(ITypeShape<T>)

Creates a structural comparer for a type with a known shape.

public static IEqualityComparer<T> Create<T>(ITypeShape<T> shape)

Parameters

shape ITypeShape<T>

The shape of the type to compare.

Returns

IEqualityComparer<T>

A structural comparer.

Type Parameters

T

The type to compare.

Create<T, TProvider>()

Creates a structural comparer for a type whose shape is provided by a witness type.

public static IEqualityComparer<T> Create<T, TProvider>() where TProvider : IShapeable<T>

Returns

IEqualityComparer<T>

A structural comparer.

Type Parameters

T

The type to compare.

TProvider

The witness type that describes T.