Package org.apache.sis.util

## Class Utilities

- Object
- - Static
  - - Utilities

-     public final class Utilities
      extends Static

  Static methods for object comparisons in different ways (deeply, approximately, etc).
  Since:
    0.3

  Defined in the `sis-utility` module

- - ### Method Summary

    All Methods Static Methods Concrete Methods Deprecated Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `static boolean` | `deepEquals​(Object object1, Object object2, ComparisonMode mode)` | Convenience method for testing two objects for equality using the given level of strictness.
    `static int` | `deepHashCode​(Object object)` | Returns a hash code for the specified object, which may be an array.
    `static String` | `deepToString​(Object object)` | Returns a string representation of the specified object, which may be an array.
    `static boolean` | `equalsApproximately​(Object object1, Object object2)` | Compares the specified objects for equality, ignoring metadata and slight differences in numerical values.
    `static boolean` | `equalsApproximatively​(Object object1, Object object2)` | Deprecated. Renamed `equalsApproximately(Object, Object)`.
    `static boolean` | `equalsIgnoreMetadata​(Object object1, Object object2)` | Compares the specified objects for equality, ignoring metadata.

    - ### Methods inherited from class Object

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

- - ### Method Detail

    - #### equalsIgnoreMetadata

          public static boolean equalsIgnoreMetadata​(Object object1,
                                                     Object object2)

      Compares the specified objects for equality, ignoring metadata. If this method returns `true`, then:
      - If the two given objects are math transforms, then transforming a set of coordinate values using one transform will produce the same results than transforming the same coordinates with the other transform.
      - If the two given objects are Coordinate Reference Systems (CRS), then a call to `findOperation(crs1, crs2, null)` will return an identity operation.
      If a more lenient comparison allowing slight differences in numerical values is wanted, then `equalsApproximately(Object, Object)` can be used instead.
      Implementation note
      This is a convenience method for the following method call:

      >     return deepEquals(object1, object2, ComparisonMode.IGNORE_METADATA);

      Parameters:
        `object1` - the first object to compare (may be null).
        `object2` - the second object to compare (may be null).
      Returns:
        `true` if both objects are equal, ignoring metadata.
      See Also:
        `deepEquals(Object, Object, ComparisonMode)`, `ComparisonMode​.IGNORE_METADATA`

    - #### equalsApproximately

          public static boolean equalsApproximately​(Object object1,
                                                    Object object2)

      Compares the specified objects for equality, ignoring metadata and slight differences in numerical values. If this method returns `true`, then:
      - If the two given objects are math transforms, then transforming a set of coordinate values using one transform will produce approximately the same results than transforming the same coordinates with the other transform.
      - If the two given objects are Coordinate Reference Systems (CRS), then a call to `findOperation(crs1, crs2, null)` will return an operation close to identity.
      Implementation note
      This is a convenience method for the following method call:

      >     return deepEquals(object1, object2, ComparisonMode.APPROXIMATE);

      Parameters:
        `object1` - the first object to compare (may be null).
        `object2` - the second object to compare (may be null).
      Returns:
        `true` if both objects are approximately equal.
      See Also:
        `deepEquals(Object, Object, ComparisonMode)`, `ComparisonMode​.APPROXIMATE`

    - #### equalsApproximatively

          @Deprecated
          public static boolean equalsApproximatively​(Object object1,
                                                      Object object2)

      Deprecated.
      Renamed `equalsApproximately(Object, Object)`.
      See Also:
        SIS-440

    - #### deepEquals

          public static boolean deepEquals​(Object object1,
                                           Object object2,
                                           ComparisonMode mode)

      Convenience method for testing two objects for equality using the given level of strictness. If at least one of the given objects implement the `LenientComparable` interface, then the comparison is performed using the `LenientComparable​.equals(Object, ComparisonMode)` method. Otherwise this method performs the same work than the `Objects​.deepEquals(Object, Object)` convenience method.

      If both arguments are arrays or collections, then the elements are compared recursively.

      Parameters:
        `object1` - the first object to compare, or `null`.
        `object2` - the second object to compare, or `null`.
        `mode` - the strictness level of the comparison.
      Returns:
        `true` if both objects are equal for the given level of strictness.
      See Also:
        `equalsIgnoreMetadata(Object, Object)`, `equalsApproximately(Object, Object)`

    - #### deepHashCode

          public static int deepHashCode​(Object object)

      Returns a hash code for the specified object, which may be an array. This method returns one of the following values:
      - If the supplied object is `null`, then this method returns 0.
      - Otherwise if the object is an array of objects, then `Arrays​.deepHashCode(Object[])` is invoked.
      - Otherwise if the object is an array of primitive type, then the corresponding `Arrays​.hashCode(...)` method is invoked.
      - Otherwise `Object​.hashCode()` is invoked.
      This method should be invoked only if the object type is declared exactly as `Object`, not as some subtype like `Object[]`, `String` or `float[]`. In the later cases, use the appropriate `Arrays` method instead.
      Parameters:
        `object` - the object to compute hash code. May be `null`.
      Returns:
        the hash code of the given object.

    - #### deepToString

          public static String deepToString​(Object object)

      Returns a string representation of the specified object, which may be an array. This method returns one of the following values:
      - If the object is an array of objects, then `Arrays​.deepToString(Object[])` is invoked.
      - Otherwise if the object is an array of primitive type, then the corresponding `Arrays​.toString(...)` method is invoked.
      - Otherwise `String​.valueOf(Object)` is invoked.
      This method should be invoked only if the object type is declared exactly as `Object`, not as some subtype like `Object[]`, `Number` or `float[]`. In the later cases, use the appropriate `Arrays` method instead.
      Parameters:
        `object` - the object to format as a string. May be `null`.
      Returns:
        a string representation of the given object.