CompareToBuilder (cayenne-doc: Cayenne Documentation 5.0-M2 API)
Description: declaration: package: org.apache.cayenne.util, class: CompareToBuilder

# 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

  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 Object

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

- ## Constructor Details

  - ### 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 Details

  - ### 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