/*
* Licensed to the Apache Software Foundation (ASF) under one or more
* contributor license agreements. See the NOTICE file distributed with
* this work for additional information regarding copyright ownership.
* The ASF licenses this file to You under the Apache License, Version 2.0
* (the "License"); you may not use this file except in compliance with
* the License. You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package org.caudexorigo.builder;
import java.lang.reflect.AccessibleObject;
import java.lang.reflect.Field;
import java.lang.reflect.Modifier;
import java.util.Arrays;
import java.util.Collection;
import java.util.Collections;
import java.util.Comparator;
import java.util.List;
import org.caudexorigo.lang.math.NumberUtils;
/**
* Assists in implementing {@link java.lang.Comparable#compareTo(Object)} methods.
*
* It is consistent with <code>equals(Object)</code> and <code>hashcode()</code> built with {@link EqualsBuilder} and {@link HashCodeBuilder}.</p>
*
* <p>
* Two Objects that compare equal using <code>equals(Object)</code> should normally also compare equal using <code>compareTo(Object)</code>.
* </p>
*
* <p>
* All relevant fields should be included in the calculation of the comparison. Derived fields may be ignored. The same fields, in the same order, should be used in both <code>compareTo(Object)</code> and <code>equals(Object)</code>.
* </p>
*
* <p>
* To use this class write code as follows:
* </p>
*
* <pre>
* public class MyClass {
* String field1;
* int field2;
* boolean field3;
* ...
* public int compareTo(Object o) {
* MyClass myClass = (MyClass) o;
* return new CompareToBuilder()
* .appendSuper(super.compareTo(o)
* .append(this.field1, myClass.field1)
* .append(this.field2, myClass.field2)
* .append(this.field3, myClass.field3)
* .toComparison();
* }
* }
* </pre>
*
* <p>
* Alternatively, there are {@link #reflectionCompare(Object, Object) reflectionCompare} methods that use reflection to determine the fields to append. Because fields can be private, <code>reflectionCompare</code> uses {@link java.lang.reflect.AccessibleObject#setAccessible(boolean)} to bypass normal access control checks. This will fail under a security manager, unless the appropriate permissions are set up correctly. It is also slower than appending explicitly.
* </p>
*
* <p>
* A typical implementation of <code>compareTo(Object)</code> using <code>reflectionCompare</code> looks like:
* </p>
*
* <pre>
* public int compareTo(Object o)
* {
* return CompareToBuilder.reflectionCompare(this, o);
* }
* </pre>
*
* @see java.lang.Comparable
* @see java.lang.Object#equals(Object)
* @see java.lang.Object#hashCode()
* @see EqualsBuilder
* @see HashCodeBuilder
* @author <a href="mailto:steve.downey@netfolio.com">Steve Downey</a>
* @author Stephen Colebourne
* @author Gary Gregory
* @author Pete Gieser
* @since 1.0
* @version $Id: CompareToBuilder.java 583666 2007-10-11 01:38:13Z ggregory $
*/
public class CompareToBuilder
{
/**
* Current state of the comparison as appended fields are checked.
*/
private int comparison;
/**
* <p>
* Constructor for CompareToBuilder.
* </p>
*
* <p>
* Starts off assuming that the objects are equal. Multiple calls are then made to the various append methods, followed by a call to {@link #toComparison} to get the result.
* </p>
*/
public CompareToBuilder()
{
super();
comparison = 0;
}
// -----------------------------------------------------------------------
/**
* <p>
* Compares two <code>Object</code>s via reflection.
* </p>
*
* <p>
* Fields can be private, thus <code>AccessibleObject.setAccessible</code> is used to bypass normal access control checks. This will fail under a security manager unless the appropriate permissions are set.
* </p>
*
* <ul>
* <li>Static fields will not be compared</li>
* <li>Transient members will be not be compared, as they are likely derived fields</li>
* <li>Superclass fields will be compared</li>
* </ul>
*
* <p>
* If both <code>lhs</code> and <code>rhs</code> are <code>null</code>, they are considered equal.
* </p>
*
* @param lhs
* left-hand object
* @param rhs
* right-hand object
* @return a negative integer, zero, or a positive integer as <code>lhs</code> is less than, equal to, or greater than <code>rhs</code>
* @throws NullPointerException
* if either (but not both) parameters are <code>null</code>
* @throws ClassCastException
* if <code>rhs</code> is not assignment-compatible with <code>lhs</code>
*/
public static int reflectionCompare(Object lhs, Object rhs)
{
return reflectionCompare(lhs, rhs, false, null, null);
}
/**
* <p>
* Compares two <code>Object</code>s via reflection.
* </p>
*
* <p>
* Fields can be private, thus <code>AccessibleObject.setAccessible</code> is used to bypass normal access control checks. This will fail under a security manager unless the appropriate permissions are set.
* </p>
*
* <ul>
* <li>Static fields will not be compared</li>
* <li>If <code>compareTransients</code> is <code>true</code>, compares transient members. Otherwise ignores them, as they are likely derived fields.</li>
* <li>Superclass fields will be compared</li>
* </ul>
*
* <p>
* If both <code>lhs</code> and <code>rhs</code> are <code>null</code>, they are considered equal.
* </p>
*
* @param lhs
* left-hand object
* @param rhs
* right-hand object
* @param compareTransients
* whether to compare transient fields
* @return a negative integer, zero, or a positive integer as <code>lhs</code> is less than, equal to, or greater than <code>rhs</code>
* @throws NullPointerException
* if either <code>lhs</code> or <code>rhs</code> (but not both) is <code>null</code>
* @throws ClassCastException
* if <code>rhs</code> is not assignment-compatible with <code>lhs</code>
*/
public static int reflectionCompare(Object lhs, Object rhs, boolean compareTransients)
{
return reflectionCompare(lhs, rhs, compareTransients, null, null);
}
/**
* <p>
* Compares two <code>Object</code>s via reflection.
* </p>
*
* <p>
* Fields can be private, thus <code>AccessibleObject.setAccessible</code> is used to bypass normal access control checks. This will fail under a security manager unless the appropriate permissions are set.
* </p>
*
* <ul>
* <li>Static fields will not be compared</li>
* <li>If <code>compareTransients</code> is <code>true</code>, compares transient members. Otherwise ignores them, as they are likely derived fields.</li>
* <li>Superclass fields will be compared</li>
* </ul>
*
* <p>
* If both <code>lhs</code> and <code>rhs</code> are <code>null</code>, they are considered equal.
* </p>
*
* @param lhs
* left-hand object
* @param rhs
* right-hand object
* @param excludeFields
* Collection of String fields to exclude
* @return a negative integer, zero, or a positive integer as <code>lhs</code> is less than, equal to, or greater than <code>rhs</code>
* @throws NullPointerException
* if either <code>lhs</code> or <code>rhs</code> (but not both) is <code>null</code>
* @throws ClassCastException
* if <code>rhs</code> is not assignment-compatible with <code>lhs</code>
* @since 2.2
*/
public static int reflectionCompare(Object lhs, Object rhs, Collection /* String */excludeFields)
{
return reflectionCompare(lhs, rhs, ReflectionToStringBuilder.toNoNullStringArray(excludeFields));
}
/**
* <p>
* Compares two <code>Object</code>s via reflection.
* </p>
*
* <p>
* Fields can be private, thus <code>AccessibleObject.setAccessible</code> is used to bypass normal access control checks. This will fail under a security manager unless the appropriate permissions are set.
* </p>
*
* <ul>
* <li>Static fields will not be compared</li>
* <li>If <code>compareTransients</code> is <code>true</code>, compares transient members. Otherwise ignores them, as they are likely derived fields.</li>
* <li>Superclass fields will be compared</li>
* </ul>
*
* <p>
* If both <code>lhs</code> and <code>rhs</code> are <code>null</code>, they are considered equal.
* </p>
*
* @param lhs
* left-hand object
* @param rhs
* right-hand object
* @param excludeFields
* array of fields to exclude
* @return a negative integer, zero, or a positive integer as <code>lhs</code> is less than, equal to, or greater than <code>rhs</code>
* @throws NullPointerException
* if either <code>lhs</code> or <code>rhs</code> (but not both) is <code>null</code>
* @throws ClassCastException
* if <code>rhs</code> is not assignment-compatible with <code>lhs</code>
* @since 2.2
*/
public static int reflectionCompare(Object lhs, Object rhs, String[] excludeFields)
{
return reflectionCompare(lhs, rhs, false, null, excludeFields);
}
/**
* <p>
* Compares two <code>Object</code>s via reflection.
* </p>
*
* <p>
* Fields can be private, thus <code>AccessibleObject.setAccessible</code> is used to bypass normal access control checks. This will fail under a security manager unless the appropriate permissions are set.
* </p>
*
* <ul>
* <li>Static fields will not be compared</li>
* <li>If the <code>compareTransients</code> is <code>true</code>, compares transient members. Otherwise ignores them, as they are likely derived fields.</li>
* <li>Compares superclass fields up to and including <code>reflectUpToClass</code>. If <code>reflectUpToClass</code> is <code>null</code>, compares all superclass fields.</li>
* </ul>
*
* <p>
* If both <code>lhs</code> and <code>rhs</code> are <code>null</code>, they are considered equal.
* </p>
*
* @param lhs
* left-hand object
* @param rhs
* right-hand object
* @param compareTransients
* whether to compare transient fields
* @param reflectUpToClass
* last superclass for which fields are compared
* @return a negative integer, zero, or a positive integer as <code>lhs</code> is less than, equal to, or greater than <code>rhs</code>
* @throws NullPointerException
* if either <code>lhs</code> or <code>rhs</code> (but not both) is <code>null</code>
* @throws ClassCastException
* if <code>rhs</code> is not assignment-compatible with <code>lhs</code>
* @since 2.0
*/
public static int reflectionCompare(Object lhs, Object rhs, boolean compareTransients, Class reflectUpToClass)
{
return reflectionCompare(lhs, rhs, false, reflectUpToClass, null);
}
/**
* <p>
* Compares two <code>Object</code>s via reflection.
* </p>
*
* <p>
* Fields can be private, thus <code>AccessibleObject.setAccessible</code> is used to bypass normal access control checks. This will fail under a security manager unless the appropriate permissions are set.
* </p>
*
* <ul>
* <li>Static fields will not be compared</li>
* <li>If the <code>compareTransients</code> is <code>true</code>, compares transient members. Otherwise ignores them, as they are likely derived fields.</li>
* <li>Compares superclass fields up to and including <code>reflectUpToClass</code>. If <code>reflectUpToClass</code> is <code>null</code>, compares all superclass fields.</li>
* </ul>
*
* <p>
* If both <code>lhs</code> and <code>rhs</code> are <code>null</code>, they are considered equal.
* </p>
*
* @param lhs
* left-hand object
* @param rhs
* right-hand object
* @param compareTransients
* whether to compare transient fields
* @param reflectUpToClass
* last superclass for which fields are compared
* @param excludeFields
* fields to exclude
* @return a negative integer, zero, or a positive integer as <code>lhs</code> is less than, equal to, or greater than <code>rhs</code>
* @throws NullPointerException
* if either <code>lhs</code> or <code>rhs</code> (but not both) is <code>null</code>
* @throws ClassCastException
* if <code>rhs</code> is not assignment-compatible with <code>lhs</code>
* @since 2.2
*/
public static int reflectionCompare(Object lhs, Object rhs, boolean compareTransients, Class reflectUpToClass, String[] excludeFields)
{
if (lhs == rhs)
{
return 0;
}
if (lhs == null || rhs == null)
{
throw new NullPointerException();
}
Class lhsClazz = lhs.getClass();
if (!lhsClazz.isInstance(rhs))
{
throw new ClassCastException();
}
CompareToBuilder compareToBuilder = new CompareToBuilder();
reflectionAppend(lhs, rhs, lhsClazz, compareToBuilder, compareTransients, excludeFields);
while (lhsClazz.getSuperclass() != null && lhsClazz != reflectUpToClass)
{
lhsClazz = lhsClazz.getSuperclass();
reflectionAppend(lhs, rhs, lhsClazz, compareToBuilder, compareTransients, excludeFields);
}
return compareToBuilder.toComparison();
}
/**
* <p>
* Appends to <code>builder</code> the comparison of <code>lhs</code> to <code>rhs</code> using the fields defined in <code>clazz</code>.
* </p>
*
* @param lhs
* left-hand object
* @param rhs
* right-hand object
* @param clazz
* <code>Class</code> that defines fields to be compared
* @param builder
* <code>CompareToBuilder</code> to append to
* @param useTransients
* whether to compare transient fields
* @param excludeFields
* fields to exclude
*/
private static void reflectionAppend(Object lhs, Object rhs, Class clazz, CompareToBuilder builder, boolean useTransients, String[] excludeFields)
{
Field[] fields = clazz.getDeclaredFields();
List excludedFieldList = excludeFields != null ? Arrays.asList(excludeFields) : Collections.EMPTY_LIST;
AccessibleObject.setAccessible(fields, true);
for (int i = 0; i < fields.length && builder.comparison == 0; i++)
{
Field f = fields[i];
if (!excludedFieldList.contains(f.getName()) && (f.getName().indexOf('$') == -1) && (useTransients || !Modifier.isTransient(f.getModifiers())) && (!Modifier.isStatic(f.getModifiers())))
{
try
{
builder.append(f.get(lhs), f.get(rhs));
}
catch (IllegalAccessException e)
{
// This can't happen. Would get a Security exception instead.
// Throw a runtime exception in case the impossible happens.
throw new InternalError("Unexpected IllegalAccessException");
}
}
}
}
// -----------------------------------------------------------------------
/**
* <p>
* Appends to the <code>builder</code> the <code>compareTo(Object)</code> result of the superclass.
* </p>
*
* @param superCompareTo
* result of calling <code>super.compareTo(Object)</code>
* @return this - used to chain append calls
* @since 2.0
*/
public CompareToBuilder appendSuper(int superCompareTo)
{
if (comparison != 0)
{
return this;
}
comparison = superCompareTo;
return this;
}
// -----------------------------------------------------------------------
/**
* <p>
* Appends to the <code>builder</code> the comparison of two <code>Object</code>s.
* </p>
*
* <ol>
* <li>Check if <code>lhs == rhs</code></li>
* <li>Check if either <code>lhs</code> or <code>rhs</code> is <code>null</code>, a <code>null</code> object is less than a non-<code>null</code> object</li>
* <li>Check the object contents</li>
* </ol>
*
* <p>
* <code>lhs</code> must either be an array or implement {@link Comparable}.
* </p>
*
* @param lhs
* left-hand object
* @param rhs
* right-hand object
* @return this - used to chain append calls
* @throws ClassCastException
* if <code>rhs</code> is not assignment-compatible with <code>lhs</code>
*/
public CompareToBuilder append(Object lhs, Object rhs)
{
return append(lhs, rhs, null);
}
/**
* <p>
* Appends to the <code>builder</code> the comparison of two <code>Object</code>s.
* </p>
*
* <ol>
* <li>Check if <code>lhs == rhs</code></li>
* <li>Check if either <code>lhs</code> or <code>rhs</code> is <code>null</code>, a <code>null</code> object is less than a non-<code>null</code> object</li>
* <li>Check the object contents</li>
* </ol>
*
* <p>
* If <code>lhs</code> is an array, array comparison methods will be used. Otherwise <code>comparator</code> will be used to compare the objects. If <code>comparator</code> is <code>null</code>, <code>lhs</code> must implement {@link Comparable} instead.
* </p>
*
* @param lhs
* left-hand object
* @param rhs
* right-hand object
* @param comparator
* <code>Comparator</code> used to compare the objects, <code>null</code> means treat lhs as <code>Comparable</code>
* @return this - used to chain append calls
* @throws ClassCastException
* if <code>rhs</code> is not assignment-compatible with <code>lhs</code>
* @since 2.0
*/
public CompareToBuilder append(Object lhs, Object rhs, Comparator comparator)
{
if (comparison != 0)
{
return this;
}
if (lhs == rhs)
{
return this;
}
if (lhs == null)
{
comparison = -1;
return this;
}
if (rhs == null)
{
comparison = +1;
return this;
}
if (lhs.getClass().isArray())
{
// switch on type of array, to dispatch to the correct handler
// handles multi dimensional arrays
// throws a ClassCastException if rhs is not the correct array type
if (lhs instanceof long[])
{
append((long[]) lhs, (long[]) rhs);
}
else if (lhs instanceof int[])
{
append((int[]) lhs, (int[]) rhs);
}
else if (lhs instanceof short[])
{
append((short[]) lhs, (short[]) rhs);
}
else if (lhs instanceof char[])
{
append((char[]) lhs, (char[]) rhs);
}
else if (lhs instanceof byte[])
{
append((byte[]) lhs, (byte[]) rhs);
}
else if (lhs instanceof double[])
{
append((double[]) lhs, (double[]) rhs);
}
else if (lhs instanceof float[])
{
append((float[]) lhs, (float[]) rhs);
}
else if (lhs instanceof boolean[])
{
append((boolean[]) lhs, (boolean[]) rhs);
}
else
{
// not an array of primitives
// throws a ClassCastException if rhs is not an array
append((Object[]) lhs, (Object[]) rhs, comparator);
}
}
else
{
// the simple case, not an array, just test the element
if (comparator == null)
{
comparison = ((Comparable) lhs).compareTo(rhs);
}
else
{
comparison = comparator.compare(lhs, rhs);
}
}
return this;
}
// -------------------------------------------------------------------------
/**
* Appends to the <code>builder</code> the comparison of two <code>long</code>s.
*
* @param lhs
* left-hand value
* @param rhs
* right-hand value
* @return this - used to chain append calls
*/
public CompareToBuilder append(long lhs, long rhs)
{
if (comparison != 0)
{
return this;
}
comparison = ((lhs < rhs) ? -1 : ((lhs > rhs) ? 1 : 0));
return this;
}
/**
* Appends to the <code>builder</code> the comparison of two <code>int</code>s.
*
* @param lhs
* left-hand value
* @param rhs
* right-hand value
* @return this - used to chain append calls
*/
public CompareToBuilder append(int lhs, int rhs)
{
if (comparison != 0)
{
return this;
}
comparison = ((lhs < rhs) ? -1 : ((lhs > rhs) ? 1 : 0));
return this;
}
/**
* Appends to the <code>builder</code> the comparison of two <code>short</code>s.
*
* @param lhs
* left-hand value
* @param rhs
* right-hand value
* @return this - used to chain append calls
*/
public CompareToBuilder append(short lhs, short rhs)
{
if (comparison != 0)
{
return this;
}
comparison = ((lhs < rhs) ? -1 : ((lhs > rhs) ? 1 : 0));
return this;
}
/**
* Appends to the <code>builder</code> the comparison of two <code>char</code>s.
*
* @param lhs
* left-hand value
* @param rhs
* right-hand value
* @return this - used to chain append calls
*/
public CompareToBuilder append(char lhs, char rhs)
{
if (comparison != 0)
{
return this;
}
comparison = ((lhs < rhs) ? -1 : ((lhs > rhs) ? 1 : 0));
return this;
}
/**
* Appends to the <code>builder</code> the comparison of two <code>byte</code>s.
*
* @param lhs
* left-hand value
* @param rhs
* right-hand value
* @return this - used to chain append calls
*/
public CompareToBuilder append(byte lhs, byte rhs)
{
if (comparison != 0)
{
return this;
}
comparison = ((lhs < rhs) ? -1 : ((lhs > rhs) ? 1 : 0));
return this;
}
/**
* <p>
* Appends to the <code>builder</code> the comparison of two <code>double</code>s.
* </p>
*
* <p>
* This handles NaNs, Infinities, and <code>-0.0</code>.
* </p>
*
* <p>
* It is compatible with the hash code generated by <code>HashCodeBuilder</code>.
* </p>
*
* @param lhs
* left-hand value
* @param rhs
* right-hand value
* @return this - used to chain append calls
*/
public CompareToBuilder append(double lhs, double rhs)
{
if (comparison != 0)
{
return this;
}
comparison = NumberUtils.compare(lhs, rhs);
return this;
}
/**
* <p>
* Appends to the <code>builder</code> the comparison of two <code>float</code>s.
* </p>
*
* <p>
* This handles NaNs, Infinities, and <code>-0.0</code>.
* </p>
*
* <p>
* It is compatible with the hash code generated by <code>HashCodeBuilder</code>.
* </p>
*
* @param lhs
* left-hand value
* @param rhs
* right-hand value
* @return this - used to chain append calls
*/
public CompareToBuilder append(float lhs, float rhs)
{
if (comparison != 0)
{
return this;
}
comparison = NumberUtils.compare(lhs, rhs);
return this;
}
/**
* Appends to the <code>builder</code> the comparison of two <code>booleans</code>s.
*
* @param lhs
* left-hand value
* @param rhs
* right-hand value
* @return this - used to chain append calls
*/
public CompareToBuilder append(boolean lhs, boolean rhs)
{
if (comparison != 0)
{
return this;
}
if (lhs == rhs)
{
return this;
}
if (lhs == false)
{
comparison = -1;
}
else
{
comparison = +1;
}
return this;
}
// -----------------------------------------------------------------------
/**
* <p>
* Appends to the <code>builder</code> the deep comparison of two <code>Object</code> arrays.
* </p>
*
* <ol>
* <li>Check if arrays are the same using <code>==</code></li>
* <li>Check if for <code>null</code>, <code>null</code> is less than non-<code>null</code></li>
* <li>Check array length, a short length array is less than a long length array</li>
* <li>Check array contents element by element using {@link #append(Object, Object, Comparator)}</li>
* </ol>
*
* <p>
* This method will also will be called for the top level of multi-dimensional, ragged, and multi-typed arrays.
* </p>
*
* @param lhs
* left-hand array
* @param rhs
* right-hand array
* @return this - used to chain append calls
* @throws ClassCastException
* if <code>rhs</code> is not assignment-compatible with <code>lhs</code>
*/
public CompareToBuilder append(Object[] lhs, Object[] rhs)
{
return append(lhs, rhs, null);
}
/**
* <p>
* Appends to the <code>builder</code> the deep comparison of two <code>Object</code> arrays.
* </p>
*
* <ol>
* <li>Check if arrays are the same using <code>==</code></li>
* <li>Check if for <code>null</code>, <code>null</code> is less than non-<code>null</code></li>
* <li>Check array length, a short length array is less than a long length array</li>
* <li>Check array contents element by element using {@link #append(Object, Object, Comparator)}</li>
* </ol>
*
* <p>
* This method will also will be called for the top level of multi-dimensional, ragged, and multi-typed arrays.
* </p>
*
* @param lhs
* left-hand array
* @param rhs
* right-hand array
* @param comparator
* <code>Comparator</code> to use to compare the array elements, <code>null</code> means to treat <code>lhs</code> elements as <code>Comparable</code>.
* @return this - used to chain append calls
* @throws ClassCastException
* if <code>rhs</code> is not assignment-compatible with <code>lhs</code>
* @since 2.0
*/
public CompareToBuilder append(Object[] lhs, Object[] rhs, Comparator comparator)
{
if (comparison != 0)
{
return this;
}
if (lhs == rhs)
{
return this;
}
if (lhs == null)
{
comparison = -1;
return this;
}
if (rhs == null)
{
comparison = +1;
return this;
}
if (lhs.length != rhs.length)
{
comparison = (lhs.length < rhs.length) ? -1 : +1;
return this;
}
for (int i = 0; i < lhs.length && comparison == 0; i++)
{
append(lhs[i], rhs[i], comparator);
}
return this;
}
/**
* <p>
* Appends to the <code>builder</code> the deep comparison of two <code>long</code> arrays.
* </p>
*
* <ol>
* <li>Check if arrays are the same using <code>==</code></li>
* <li>Check if for <code>null</code>, <code>null</code> is less than non-<code>null</code></li>
* <li>Check array length, a shorter length array is less than a longer length array</li>
* <li>Check array contents element by element using {@link #append(long, long)}</li>
* </ol>
*
* @param lhs
* left-hand array
* @param rhs
* right-hand array
* @return this - used to chain append calls
*/
public CompareToBuilder append(long[] lhs, long[] rhs)
{
if (comparison != 0)
{
return this;
}
if (lhs == rhs)
{
return this;
}
if (lhs == null)
{
comparison = -1;
return this;
}
if (rhs == null)
{
comparison = +1;
return this;
}
if (lhs.length != rhs.length)
{
comparison = (lhs.length < rhs.length) ? -1 : +1;
return this;
}
for (int i = 0; i < lhs.length && comparison == 0; i++)
{
append(lhs[i], rhs[i]);
}
return this;
}
/**
* <p>
* Appends to the <code>builder</code> the deep comparison of two <code>int</code> arrays.
* </p>
*
* <ol>
* <li>Check if arrays are the same using <code>==</code></li>
* <li>Check if for <code>null</code>, <code>null</code> is less than non-<code>null</code></li>
* <li>Check array length, a shorter length array is less than a longer length array</li>
* <li>Check array contents element by element using {@link #append(int, int)}</li>
* </ol>
*
* @param lhs
* left-hand array
* @param rhs
* right-hand array
* @return this - used to chain append calls
*/
public CompareToBuilder append(int[] lhs, int[] rhs)
{
if (comparison != 0)
{
return this;
}
if (lhs == rhs)
{
return this;
}
if (lhs == null)
{
comparison = -1;
return this;
}
if (rhs == null)
{
comparison = +1;
return this;
}
if (lhs.length != rhs.length)
{
comparison = (lhs.length < rhs.length) ? -1 : +1;
return this;
}
for (int i = 0; i < lhs.length && comparison == 0; i++)
{
append(lhs[i], rhs[i]);
}
return this;
}
/**
* <p>
* Appends to the <code>builder</code> the deep comparison of two <code>short</code> arrays.
* </p>
*
* <ol>
* <li>Check if arrays are the same using <code>==</code></li>
* <li>Check if for <code>null</code>, <code>null</code> is less than non-<code>null</code></li>
* <li>Check array length, a shorter length array is less than a longer length array</li>
* <li>Check array contents element by element using {@link #append(short, short)}</li>
* </ol>
*
* @param lhs
* left-hand array
* @param rhs
* right-hand array
* @return this - used to chain append calls
*/
public CompareToBuilder append(short[] lhs, short[] rhs)
{
if (comparison != 0)
{
return this;
}
if (lhs == rhs)
{
return this;
}
if (lhs == null)
{
comparison = -1;
return this;
}
if (rhs == null)
{
comparison = +1;
return this;
}
if (lhs.length != rhs.length)
{
comparison = (lhs.length < rhs.length) ? -1 : +1;
return this;
}
for (int i = 0; i < lhs.length && comparison == 0; i++)
{
append(lhs[i], rhs[i]);
}
return this;
}
/**
* <p>
* Appends to the <code>builder</code> the deep comparison of two <code>char</code> arrays.
* </p>
*
* <ol>
* <li>Check if arrays are the same using <code>==</code></li>
* <li>Check if for <code>null</code>, <code>null</code> is less than non-<code>null</code></li>
* <li>Check array length, a shorter length array is less than a longer length array</li>
* <li>Check array contents element by element using {@link #append(char, char)}</li>
* </ol>
*
* @param lhs
* left-hand array
* @param rhs
* right-hand array
* @return this - used to chain append calls
*/
public CompareToBuilder append(char[] lhs, char[] rhs)
{
if (comparison != 0)
{
return this;
}
if (lhs == rhs)
{
return this;
}
if (lhs == null)
{
comparison = -1;
return this;
}
if (rhs == null)
{
comparison = +1;
return this;
}
if (lhs.length != rhs.length)
{
comparison = (lhs.length < rhs.length) ? -1 : +1;
return this;
}
for (int i = 0; i < lhs.length && comparison == 0; i++)
{
append(lhs[i], rhs[i]);
}
return this;
}
/**
* <p>
* Appends to the <code>builder</code> the deep comparison of two <code>byte</code> arrays.
* </p>
*
* <ol>
* <li>Check if arrays are the same using <code>==</code></li>
* <li>Check if for <code>null</code>, <code>null</code> is less than non-<code>null</code></li>
* <li>Check array length, a shorter length array is less than a longer length array</li>
* <li>Check array contents element by element using {@link #append(byte, byte)}</li>
* </ol>
*
* @param lhs
* left-hand array
* @param rhs
* right-hand array
* @return this - used to chain append calls
*/
public CompareToBuilder append(byte[] lhs, byte[] rhs)
{
if (comparison != 0)
{
return this;
}
if (lhs == rhs)
{
return this;
}
if (lhs == null)
{
comparison = -1;
return this;
}
if (rhs == null)
{
comparison = +1;
return this;
}
if (lhs.length != rhs.length)
{
comparison = (lhs.length < rhs.length) ? -1 : +1;
return this;
}
for (int i = 0; i < lhs.length && comparison == 0; i++)
{
append(lhs[i], rhs[i]);
}
return this;
}
/**
* <p>
* Appends to the <code>builder</code> the deep comparison of two <code>double</code> arrays.
* </p>
*
* <ol>
* <li>Check if arrays are the same using <code>==</code></li>
* <li>Check if for <code>null</code>, <code>null</code> is less than non-<code>null</code></li>
* <li>Check array length, a shorter length array is less than a longer length array</li>
* <li>Check array contents element by element using {@link #append(double, double)}</li>
* </ol>
*
* @param lhs
* left-hand array
* @param rhs
* right-hand array
* @return this - used to chain append calls
*/
public CompareToBuilder append(double[] lhs, double[] rhs)
{
if (comparison != 0)
{
return this;
}
if (lhs == rhs)
{
return this;
}
if (lhs == null)
{
comparison = -1;
return this;
}
if (rhs == null)
{
comparison = +1;
return this;
}
if (lhs.length != rhs.length)
{
comparison = (lhs.length < rhs.length) ? -1 : +1;
return this;
}
for (int i = 0; i < lhs.length && comparison == 0; i++)
{
append(lhs[i], rhs[i]);
}
return this;
}
/**
* <p>
* Appends to the <code>builder</code> the deep comparison of two <code>float</code> arrays.
* </p>
*
* <ol>
* <li>Check if arrays are the same using <code>==</code></li>
* <li>Check if for <code>null</code>, <code>null</code> is less than non-<code>null</code></li>
* <li>Check array length, a shorter length array is less than a longer length array</li>
* <li>Check array contents element by element using {@link #append(float, float)}</li>
* </ol>
*
* @param lhs
* left-hand array
* @param rhs
* right-hand array
* @return this - used to chain append calls
*/
public CompareToBuilder append(float[] lhs, float[] rhs)
{
if (comparison != 0)
{
return this;
}
if (lhs == rhs)
{
return this;
}
if (lhs == null)
{
comparison = -1;
return this;
}
if (rhs == null)
{
comparison = +1;
return this;
}
if (lhs.length != rhs.length)
{
comparison = (lhs.length < rhs.length) ? -1 : +1;
return this;
}
for (int i = 0; i < lhs.length && comparison == 0; i++)
{
append(lhs[i], rhs[i]);
}
return this;
}
/**
* <p>
* Appends to the <code>builder</code> the deep comparison of two <code>boolean</code> arrays.
* </p>
*
* <ol>
* <li>Check if arrays are the same using <code>==</code></li>
* <li>Check if for <code>null</code>, <code>null</code> is less than non-<code>null</code></li>
* <li>Check array length, a shorter length array is less than a longer length array</li>
* <li>Check array contents element by element using {@link #append(boolean, boolean)}</li>
* </ol>
*
* @param lhs
* left-hand array
* @param rhs
* right-hand array
* @return this - used to chain append calls
*/
public CompareToBuilder append(boolean[] lhs, boolean[] rhs)
{
if (comparison != 0)
{
return this;
}
if (lhs == rhs)
{
return this;
}
if (lhs == null)
{
comparison = -1;
return this;
}
if (rhs == null)
{
comparison = +1;
return this;
}
if (lhs.length != rhs.length)
{
comparison = (lhs.length < rhs.length) ? -1 : +1;
return this;
}
for (int i = 0; i < lhs.length && comparison == 0; i++)
{
append(lhs[i], rhs[i]);
}
return this;
}
// -----------------------------------------------------------------------
/**
* Returns a negative integer, a positive integer, or zero as the <code>builder</code> has judged the "left-hand" side as less than, greater than, or equal to the "right-hand" side.
*
* @return final comparison result
*/
public int toComparison()
{
return comparison;
}
}