com.amazon.ion.util

Class Equivalence

java.lang.Object

com.amazon.ion.util.Equivalence

public final class Equivalence
extends java.lang.Object

Provides equivalence comparisons between two IonValues, following the contract of IonValue.equals(Object).

Basic usage of this class is as follows:

    IonValue v1 = ...;
    IonValue v2 = ...;
    com.amazon.ion.util.Equivalence.ionEquals( v1, v2 );

More likely, a static import would make using this class easier.

    import static com.amazon.ion.util.Equivalence.ionEquals;
    ...
    boolean equivalent = ionEquals( v1, v2 );

Additional options are available by configuring an Equivalence instance using Equivalence.Builder. For example:

     com.amazon.ion.util.Equivalence equivalence =
         new com.amazon.ion.util.Equivalence.Builder()
             .withEpsilon(1e-6)
             .build();
     IonValue v1 = ...;
     IonValue v2 = ...;
     equivalence.ionValueEquals( v1, v2 );
 

Ion Equivalence

In order to make Ion a useful model to describe data, we must first define the notion of equivalence for all values representable in Ion. Equivalence with respect to Ion values means that if two Ion values, X and Y, are equivalent, they represent the same data and can be substituted for the other without loss of information. This relationship is:

• symmetric: X is equivalent to Y if and only if Y is equivalent to X.
• transitive: if X is equivalent to Y and Y is equivalent to Z, then X is equivalent to Z.
• reflexive: X is equivalent to X.

Ordered Sequence Equivalence

When an ordered sequence (i.e. tuple) of elements is specified in this document, equivalence over such an ordered sequence is defined as follows. A tuple, A = (a1, a2, ..., an), is equivalent to another tuple, B = (b1, b2, ..., bm) if and only if the cardinality (number of elements) of A equals the cardinality of B (i.e. n == m) and ai is equivalent to bi for i = 1 ... n.

Un-Ordered Sequence Equivalence

When an un-ordered sequence (i.e. bag or multi-set) is specified in this document, equivalence over such a sequence is defined as follows. A bag, A = {a1, a2, ..., an} is equivalent to B = {b1, b2, ..., bm} if and only if the cardinality of A is equal to the cardinality of B and for each element, x, in A there exists a distinct element, y, in B for which x is equivalent to y.

Values

Any arbitrary, atomic value in the Ion Language can be denoted as the tuple, (A, V), where A is an ordered list of annotations, and V is an Ion Primitive Data or Ion Complex Data value. The list of annotations, A is an tuple of Ion Symbols (a specific type of Ion Primitive).

Terminology

Within this class, strict equivalence refers to Ion data model equivalence as defined above and by the Ion Specification. Structural or non-strict equivalence follows the same rules as strict equivalence, except that

• Annotations are not considered, and
• Timestamps that represent the same instant in time are always considered equivalent.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	Equivalence.Builder Constructs Equivalence instances.

Method Summary

Modifier and Type	Method and Description
static boolean	ionEquals(IonValue v1, IonValue v2) Checks for strict data equivalence over two Ion Values.
static boolean	ionEqualsByContent(IonValue v1, IonValue v2) Checks for structural data equivalence over two Ion Values.
boolean	ionValueEquals(IonValue v1, IonValue v2) Checks for data equivalence over two Ion values using this Equivalence's configuration

Methods inherited from class java.lang.Object

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

Method Detail

ionEquals

public static boolean ionEquals(IonValue v1,
                                IonValue v2)

Checks for strict data equivalence over two Ion Values.

Parameters:

v1 - The first Ion value to compare.

v2 - The second Ion value to compare.

Returns:

true if two Ion Values represent the same data.

ionEqualsByContent

public static boolean ionEqualsByContent(IonValue v1,
                                         IonValue v2)

Checks for structural data equivalence over two Ion Values. That is, equivalence without considering any annotations.

Parameters:

v1 - The first Ion value to compare.

v2 - The second Ion value to compare.

Returns:

true if two Ion Values represent the same data without regard to annotations.

ionValueEquals

public boolean ionValueEquals(IonValue v1,
                              IonValue v2)

Checks for data equivalence over two Ion values using this Equivalence's configuration

Parameters:

v1 - The first Ion value to compare.

v2 - The second Ion value to compare.

Returns:

true if two Ion Values represent the same data.

See Also:

Equivalence.Builder