Package com.amazon.ion.util

Class 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.

    • 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