org.apache.sis.util

## Class Utilities

- Object
- - Static
  - - Utilities

-     public final class Utilities
      extends Static

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

  Defined in the `sis-utility` module

- - ### Method Summary

    All Methods Static Methods Concrete Methods
    Modifier and Type | Method and 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` | `equalsApproximatively(Object object1, Object object2)` Compares the specified objects for equality, ignoring metadata and slight differences in numerical values.
    `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 `equalsApproximatively(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`

    - #### equalsApproximatively

          public static boolean equalsApproximatively(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 approximatively 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.APPROXIMATIVE);

      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 approximatively equal.
      See Also:
        `deepEquals(Object, Object, ComparisonMode)`, `ComparisonMode​.APPROXIMATIVE`

    - #### 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)`, `equalsApproximatively(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.

Copyright © 2010–2017 The Apache Software Foundation. All rights reserved.