Package com.amazon.ion.util

Class Equivalence

java.lang.Object
com.amazon.ion.util.Equivalence
public final class Equivalence extends 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 Details

    • 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: