Package org.apache.cayenne.util

## Class CompareToBuilder

- java.lang.Object
- - org.apache.cayenne.util.CompareToBuilder

-     public class CompareToBuilder
      extends Object

  Assists in implementing `Comparable.compareTo(Object)` methods. This code is based on CompareToBuilder from commons-lang v2.6
  Since:
    4.1

- - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `CompareToBuilder()` | Constructor for CompareToBuilder.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `CompareToBuilder` | `append​(boolean[] lhs, boolean[] rhs)` | Appends to the `builder` the deep comparison of two `boolean` arrays.
    `CompareToBuilder` | `append​(boolean lhs, boolean rhs)` | Appends to the `builder` the comparison of two `booleans`s.
    `CompareToBuilder` | `append​(byte[] lhs, byte[] rhs)` | Appends to the `builder` the deep comparison of two `byte` arrays.
    `CompareToBuilder` | `append​(byte lhs, byte rhs)` | Appends to the `builder` the comparison of two `byte`s.
    `CompareToBuilder` | `append​(char[] lhs, char[] rhs)` | Appends to the `builder` the deep comparison of two `char` arrays.
    `CompareToBuilder` | `append​(char lhs, char rhs)` | Appends to the `builder` the comparison of two `char`s.
    `CompareToBuilder` | `append​(double[] lhs, double[] rhs)` | Appends to the `builder` the deep comparison of two `double` arrays.
    `CompareToBuilder` | `append​(double lhs, double rhs)` | Appends to the `builder` the comparison of two `double`s.
    `CompareToBuilder` | `append​(float[] lhs, float[] rhs)` | Appends to the `builder` the deep comparison of two `float` arrays.
    `CompareToBuilder` | `append​(float lhs, float rhs)` | Appends to the `builder` the comparison of two `float`s.
    `CompareToBuilder` | `append​(int[] lhs, int[] rhs)` | Appends to the `builder` the deep comparison of two `int` arrays.
    `CompareToBuilder` | `append​(int lhs, int rhs)` | Appends to the `builder` the comparison of two `int`s.
    `CompareToBuilder` | `append​(long[] lhs, long[] rhs)` | Appends to the `builder` the deep comparison of two `long` arrays.
    `CompareToBuilder` | `append​(long lhs, long rhs)` | Appends to the `builder` the comparison of two `long`s.
    `CompareToBuilder` | `append​(short[] lhs, short[] rhs)` | Appends to the `builder` the deep comparison of two `short` arrays.
    `CompareToBuilder` | `append​(short lhs, short rhs)` | Appends to the `builder` the comparison of two `short`s.
    `CompareToBuilder` | `append​(Object[] lhs, Object[] rhs)` | Appends to the `builder` the deep comparison of two `Object` arrays.
    `CompareToBuilder` | `append​(Object[] lhs, Object[] rhs, Comparator comparator)` | Appends to the `builder` the deep comparison of two `Object` arrays.
    `CompareToBuilder` | `append​(Object lhs, Object rhs)` | Appends to the `builder` the comparison of two `Object`s.
    `CompareToBuilder` | `append​(Object lhs, Object rhs, Comparator comparator)` | Appends to the `builder` the comparison of two `Object`s.
    `CompareToBuilder` | `appendSuper​(int superCompareTo)` | Appends to the `builder` the `compareTo(Object)` result of the superclass.
    `int` | `toComparison()` | Returns a negative integer, a positive integer, or zero as the `builder` has judged the "left-hand" side as less than, greater than, or equal to the "right-hand" side.

    - ### Methods inherited from class java.lang.Object

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

- - ### Constructor Detail

    - #### CompareToBuilder

          public CompareToBuilder()

      Constructor for CompareToBuilder.

      Starts off assuming that the objects are equal. Multiple calls are then made to the various append methods, followed by a call to `toComparison()` to get the result.

  - ### Method Detail

    - #### appendSuper

          public CompareToBuilder appendSuper​(int superCompareTo)

      Appends to the `builder` the `compareTo(Object)` result of the superclass.

      Parameters:
        `superCompareTo` - result of calling `super.compareTo(Object)`
      Returns:
        this - used to chain append calls

    - #### append

          public CompareToBuilder append​(Object lhs,
                                         Object rhs)

      Appends to the `builder` the comparison of two `Object`s.

      1. Check if `lhs == rhs`
      2. Check if either `lhs` or `rhs` is `null`, a `null` object is less than a non-`null` object
      3. Check the object contents

      `lhs` must either be an array or implement `Comparable`.

      Parameters:
        `lhs` - left-hand object
        `rhs` - right-hand object
      Returns:
        this - used to chain append calls
      Throws:
        `ClassCastException` - if `rhs` is not assignment-compatible with `lhs`

    - #### append

          public CompareToBuilder append​(Object lhs,
                                         Object rhs,
                                         Comparator comparator)

      Appends to the `builder` the comparison of two `Object`s.

      1. Check if `lhs == rhs`
      2. Check if either `lhs` or `rhs` is `null`, a `null` object is less than a non-`null` object
      3. Check the object contents

      If `lhs` is an array, array comparison methods will be used. Otherwise `comparator` will be used to compare the objects. If `comparator` is `null`, `lhs` must implement `Comparable` instead.

      Parameters:
        `lhs` - left-hand object
        `rhs` - right-hand object
        `comparator` - `Comparator` used to compare the objects, `null` means treat lhs as `Comparable`
      Returns:
        this - used to chain append calls
      Throws:
        `ClassCastException` - if `rhs` is not assignment-compatible with `lhs`
      Since:
        2.0

    - #### append

          public CompareToBuilder append​(long lhs,
                                         long rhs)

      Appends to the `builder` the comparison of two `long`s.
      Parameters:
        `lhs` - left-hand value
        `rhs` - right-hand value
      Returns:
        this - used to chain append calls

    - #### append

          public CompareToBuilder append​(int lhs,
                                         int rhs)

      Appends to the `builder` the comparison of two `int`s.
      Parameters:
        `lhs` - left-hand value
        `rhs` - right-hand value
      Returns:
        this - used to chain append calls

    - #### append

          public CompareToBuilder append​(short lhs,
                                         short rhs)

      Appends to the `builder` the comparison of two `short`s.
      Parameters:
        `lhs` - left-hand value
        `rhs` - right-hand value
      Returns:
        this - used to chain append calls

    - #### append

          public CompareToBuilder append​(char lhs,
                                         char rhs)

      Appends to the `builder` the comparison of two `char`s.
      Parameters:
        `lhs` - left-hand value
        `rhs` - right-hand value
      Returns:
        this - used to chain append calls

    - #### append

          public CompareToBuilder append​(byte lhs,
                                         byte rhs)

      Appends to the `builder` the comparison of two `byte`s.
      Parameters:
        `lhs` - left-hand value
        `rhs` - right-hand value
      Returns:
        this - used to chain append calls

    - #### append

          public CompareToBuilder append​(double lhs,
                                         double rhs)

      Appends to the `builder` the comparison of two `double`s.

      This handles NaNs, Infinities, and `-0.0`.

      It is compatible with the hash code generated by `HashCodeBuilder`.

      Parameters:
        `lhs` - left-hand value
        `rhs` - right-hand value
      Returns:
        this - used to chain append calls

    - #### append

          public CompareToBuilder append​(float lhs,
                                         float rhs)

      Appends to the `builder` the comparison of two `float`s.

      This handles NaNs, Infinities, and `-0.0`.

      It is compatible with the hash code generated by `HashCodeBuilder`.

      Parameters:
        `lhs` - left-hand value
        `rhs` - right-hand value
      Returns:
        this - used to chain append calls

    - #### append

          public CompareToBuilder append​(boolean lhs,
                                         boolean rhs)

      Appends to the `builder` the comparison of two `booleans`s.
      Parameters:
        `lhs` - left-hand value
        `rhs` - right-hand value
      Returns:
        this - used to chain append calls

    - #### append

          public CompareToBuilder append​(Object[] lhs,
                                         Object[] rhs)

      Appends to the `builder` the deep comparison of two `Object` arrays.

      1. Check if arrays are the same using `==`
      2. Check if for `null`, `null` is less than non-`null`
      3. Check array length, a short length array is less than a long length array
      4. Check array contents element by element using `append(Object, Object, Comparator)`

      This method will also will be called for the top level of multi-dimensional, ragged, and multi-typed arrays.

      Parameters:
        `lhs` - left-hand array
        `rhs` - right-hand array
      Returns:
        this - used to chain append calls
      Throws:
        `ClassCastException` - if `rhs` is not assignment-compatible with `lhs`

    - #### append

          public CompareToBuilder append​(Object[] lhs,
                                         Object[] rhs,
                                         Comparator comparator)

      Appends to the `builder` the deep comparison of two `Object` arrays.

      1. Check if arrays are the same using `==`
      2. Check if for `null`, `null` is less than non-`null`
      3. Check array length, a short length array is less than a long length array
      4. Check array contents element by element using `append(Object, Object, Comparator)`

      This method will also will be called for the top level of multi-dimensional, ragged, and multi-typed arrays.

      Parameters:
        `lhs` - left-hand array
        `rhs` - right-hand array
        `comparator` - `Comparator` to use to compare the array elements, `null` means to treat `lhs` elements as `Comparable`.
      Returns:
        this - used to chain append calls
      Throws:
        `ClassCastException` - if `rhs` is not assignment-compatible with `lhs`
      Since:
        2.0

    - #### append

          public CompareToBuilder append​(long[] lhs,
                                         long[] rhs)

      Appends to the `builder` the deep comparison of two `long` arrays.

      1. Check if arrays are the same using `==`
      2. Check if for `null`, `null` is less than non-`null`
      3. Check array length, a shorter length array is less than a longer length array
      4. Check array contents element by element using `append(long, long)`
      Parameters:
        `lhs` - left-hand array
        `rhs` - right-hand array
      Returns:
        this - used to chain append calls

    - #### append

          public CompareToBuilder append​(int[] lhs,
                                         int[] rhs)

      Appends to the `builder` the deep comparison of two `int` arrays.

      1. Check if arrays are the same using `==`
      2. Check if for `null`, `null` is less than non-`null`
      3. Check array length, a shorter length array is less than a longer length array
      4. Check array contents element by element using `append(int, int)`
      Parameters:
        `lhs` - left-hand array
        `rhs` - right-hand array
      Returns:
        this - used to chain append calls

    - #### append

          public CompareToBuilder append​(short[] lhs,
                                         short[] rhs)

      Appends to the `builder` the deep comparison of two `short` arrays.

      1. Check if arrays are the same using `==`
      2. Check if for `null`, `null` is less than non-`null`
      3. Check array length, a shorter length array is less than a longer length array
      4. Check array contents element by element using `append(short, short)`
      Parameters:
        `lhs` - left-hand array
        `rhs` - right-hand array
      Returns:
        this - used to chain append calls

    - #### append

          public CompareToBuilder append​(char[] lhs,
                                         char[] rhs)

      Appends to the `builder` the deep comparison of two `char` arrays.

      1. Check if arrays are the same using `==`
      2. Check if for `null`, `null` is less than non-`null`
      3. Check array length, a shorter length array is less than a longer length array
      4. Check array contents element by element using `append(char, char)`
      Parameters:
        `lhs` - left-hand array
        `rhs` - right-hand array
      Returns:
        this - used to chain append calls

    - #### append

          public CompareToBuilder append​(byte[] lhs,
                                         byte[] rhs)

      Appends to the `builder` the deep comparison of two `byte` arrays.

      1. Check if arrays are the same using `==`
      2. Check if for `null`, `null` is less than non-`null`
      3. Check array length, a shorter length array is less than a longer length array
      4. Check array contents element by element using `append(byte, byte)`
      Parameters:
        `lhs` - left-hand array
        `rhs` - right-hand array
      Returns:
        this - used to chain append calls

    - #### append

          public CompareToBuilder append​(double[] lhs,
                                         double[] rhs)

      Appends to the `builder` the deep comparison of two `double` arrays.

      1. Check if arrays are the same using `==`
      2. Check if for `null`, `null` is less than non-`null`
      3. Check array length, a shorter length array is less than a longer length array
      4. Check array contents element by element using `append(double, double)`
      Parameters:
        `lhs` - left-hand array
        `rhs` - right-hand array
      Returns:
        this - used to chain append calls

    - #### append

          public CompareToBuilder append​(float[] lhs,
                                         float[] rhs)

      Appends to the `builder` the deep comparison of two `float` arrays.

      1. Check if arrays are the same using `==`
      2. Check if for `null`, `null` is less than non-`null`
      3. Check array length, a shorter length array is less than a longer length array
      4. Check array contents element by element using `append(float, float)`
      Parameters:
        `lhs` - left-hand array
        `rhs` - right-hand array
      Returns:
        this - used to chain append calls

    - #### append

          public CompareToBuilder append​(boolean[] lhs,
                                         boolean[] rhs)

      Appends to the `builder` the deep comparison of two `boolean` arrays.

      1. Check if arrays are the same using `==`
      2. Check if for `null`, `null` is less than non-`null`
      3. Check array length, a shorter length array is less than a longer length array
      4. Check array contents element by element using `append(boolean, boolean)`
      Parameters:
        `lhs` - left-hand array
        `rhs` - right-hand array
      Returns:
        this - used to chain append calls

    - #### toComparison

          public int toComparison()

      Returns a negative integer, a positive integer, or zero as the `builder` has judged the "left-hand" side as less than, greater than, or equal to the "right-hand" side.
      Returns:
        final comparison result