All Downloads are FREE. Search and download functionalities are using the official Maven repository.
  • Log In
  • Register

    • org.apache.commons.lang3.builder.CompareToBuilder Maven / Gradle / Ivy

    Go to download

    Apache Commons Lang, a package of Java utility classes for the classes that are in java.lang's hierarchy, or are considered to be so standard as to justify existence in java.lang. The code is tested using the latest revision of the JDK for supported LTS releases: 8, 11, 17 and 21 currently. See https://github.com/apache/commons-lang/blob/master/.github/workflows/maven.yml Please ensure your build environment is up-to-date and kindly report any build issues.

    There is a newer version: 3.17.0
    Show newest version
    /*
 * 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.apache.commons.lang3.builder;

import java.lang.reflect.AccessibleObject;
import java.lang.reflect.Field;
import java.lang.reflect.Modifier;
import java.util.Collection;
import java.util.Comparator;
import java.util.Objects;

import org.apache.commons.lang3.ArrayUtils;

/**
 * Assists in implementing {@link java.lang.Comparable#compareTo(Object)} methods.
 *
 * 
    It is consistent with {@code equals(Object)} and
 * {@code hashcode()} built with {@link EqualsBuilder} and
 * {@link HashCodeBuilder}.
    
 *
 * 
    Two Objects that compare equal using {@code equals(Object)} should normally
 * also compare equal using {@code compareTo(Object)}.
    
 *
 * 
    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)} and
 * {@code equals(Object)}.
    
 *
 * 
    To use this class write code as follows:
    
 *
 * 
     * 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();
 *   }
 * }
 * 
    
 *
 * 
    Values are compared in the order they are appended to the builder. If any comparison returns
 * a non-zero result, then that value will be the result returned by {@code toComparison()} and all
 * subsequent comparisons are skipped.
    
 *
 * 
    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} 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.
    
 *
 * 
    A typical implementation of {@code compareTo(Object)} using
 * {@code reflectionCompare} looks like:
    

 * 
     * public int compareTo(Object o) {
 *   return CompareToBuilder.reflectionCompare(this, o);
 * }
 * 
    
 *
 * 
    The reflective methods compare object fields in the order returned by
 * {@link Class#getDeclaredFields()}. The fields of the class are compared first, followed by those
 * of its parent classes (in order from the bottom to the top of the class hierarchy).
    
 *
 * @see java.lang.Comparable
 * @see java.lang.Object#equals(Object)
 * @see java.lang.Object#hashCode()
 * @see EqualsBuilder
 * @see HashCodeBuilder
 * @since 1.0
 */
public class CompareToBuilder implements Builder {

    /**
     * Current state of the comparison as appended fields are checked.
     */
    private int comparison;

    /**
     * 
    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
     * {@link #toComparison} to get the result.
    
     */
    public CompareToBuilder() {
        super();
        comparison = 0;
    }

    //-----------------------------------------------------------------------
    /**
     * 
    Compares two {@code Object}s via reflection.
    
     *
     * 
    Fields can be private, thus {@code AccessibleObject.setAccessible}
     * is used to bypass normal access control checks. This will fail under a
     * security manager unless the appropriate permissions are set.
    
     *
     * 
      
     * 
    • Static fields will not be compared
      • 
     * 
    • Transient members will be not be compared, as they are likely derived
     *     fields
      • 
     * 
    • Superclass fields will be compared
      • 
     * 
    
     *
     * 
    If both {@code lhs} and {@code rhs} are {@code null},
     * they are considered equal.
    
     *
     * @param lhs  left-hand object
     * @param rhs  right-hand object
     * @return a negative integer, zero, or a positive integer as {@code lhs}
     *  is less than, equal to, or greater than {@code rhs}
     * @throws NullPointerException  if either (but not both) parameters are
     *  {@code null}
     * @throws ClassCastException  if {@code rhs} is not assignment-compatible
     *  with {@code lhs}
     */
    public static int reflectionCompare(final Object lhs, final Object rhs) {
        return reflectionCompare(lhs, rhs, false, null);
    }

    /**
     * 
    Compares two {@code Object}s via reflection.
    
     *
     * 
    Fields can be private, thus {@code AccessibleObject.setAccessible}
     * is used to bypass normal access control checks. This will fail under a
     * security manager unless the appropriate permissions are set.
    
     *
     * 
      
     * 
    • Static fields will not be compared
      • 
     * 
    • If {@code compareTransients} is {@code true},
     *     compares transient members.  Otherwise ignores them, as they
     *     are likely derived fields.
      • 
     * 
    • Superclass fields will be compared
      • 
     * 
    
     *
     * 
    If both {@code lhs} and {@code rhs} are {@code null},
     * they are considered equal.
    
     *
     * @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}
     *  is less than, equal to, or greater than {@code rhs}
     * @throws NullPointerException  if either {@code lhs} or {@code rhs}
     *  (but not both) is {@code null}
     * @throws ClassCastException  if {@code rhs} is not assignment-compatible
     *  with {@code lhs}
     */
    public static int reflectionCompare(final Object lhs, final Object rhs, final boolean compareTransients) {
        return reflectionCompare(lhs, rhs, compareTransients, null);
    }

    /**
     * 
    Compares two {@code Object}s via reflection.
    
     *
     * 
    Fields can be private, thus {@code AccessibleObject.setAccessible}
     * is used to bypass normal access control checks. This will fail under a
     * security manager unless the appropriate permissions are set.
    
     *
     * 
      
     * 
    • Static fields will not be compared
      • 
     * 
    • If {@code compareTransients} is {@code true},
     *     compares transient members.  Otherwise ignores them, as they
     *     are likely derived fields.
      • 
     * 
    • Superclass fields will be compared
      • 
     * 
    
     *
     * 
    If both {@code lhs} and {@code rhs} are {@code null},
     * they are considered equal.
    
     *
     * @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}
     *  is less than, equal to, or greater than {@code rhs}
     * @throws NullPointerException  if either {@code lhs} or {@code rhs}
     *  (but not both) is {@code null}
     * @throws ClassCastException  if {@code rhs} is not assignment-compatible
     *  with {@code lhs}
     * @since 2.2
     */
    public static int reflectionCompare(final Object lhs, final Object rhs, final Collection excludeFields) {
        return reflectionCompare(lhs, rhs, ReflectionToStringBuilder.toNoNullStringArray(excludeFields));
    }

    /**
     * 
    Compares two {@code Object}s via reflection.
    
     *
     * 
    Fields can be private, thus {@code AccessibleObject.setAccessible}
     * is used to bypass normal access control checks. This will fail under a
     * security manager unless the appropriate permissions are set.
    
     *
     * 
      
     * 
    • Static fields will not be compared
      • 
     * 
    • If {@code compareTransients} is {@code true},
     *     compares transient members.  Otherwise ignores them, as they
     *     are likely derived fields.
      • 
     * 
    • Superclass fields will be compared
      • 
     * 
    
     *
     * 
    If both {@code lhs} and {@code rhs} are {@code null},
     * they are considered equal.
    
     *
     * @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}
     *  is less than, equal to, or greater than {@code rhs}
     * @throws NullPointerException  if either {@code lhs} or {@code rhs}
     *  (but not both) is {@code null}
     * @throws ClassCastException  if {@code rhs} is not assignment-compatible
     *  with {@code lhs}
     * @since 2.2
     */
    public static int reflectionCompare(final Object lhs, final Object rhs, final String... excludeFields) {
        return reflectionCompare(lhs, rhs, false, null, excludeFields);
    }

    /**
     * 
    Compares two {@code Object}s via reflection.
    
     *
     * 
    Fields can be private, thus {@code AccessibleObject.setAccessible}
     * is used to bypass normal access control checks. This will fail under a
     * security manager unless the appropriate permissions are set.
    
     *
     * 
      
     * 
    • Static fields will not be compared
      • 
     * 
    • If the {@code compareTransients} is {@code true},
     *     compares transient members.  Otherwise ignores them, as they
     *     are likely derived fields.
      • 
     * 
    • Compares superclass fields up to and including {@code reflectUpToClass}.
     *     If {@code reflectUpToClass} is {@code null}, compares all superclass fields.
      • 
     * 
    
     *
     * 
    If both {@code lhs} and {@code rhs} are {@code null},
     * they are considered equal.
    
     *
     * @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}
     *  is less than, equal to, or greater than {@code rhs}
     * @throws NullPointerException  if either {@code lhs} or {@code rhs}
     *  (but not both) is {@code null}
     * @throws ClassCastException  if {@code rhs} is not assignment-compatible
     *  with {@code lhs}
     * @since 2.2 (2.0 as {@code reflectionCompare(Object, Object, boolean, Class)})
     */
    public static int reflectionCompare(
        final Object lhs,
        final Object rhs,
        final boolean compareTransients,
        final Class reflectUpToClass,
        final String... excludeFields) {

        if (lhs == rhs) {
            return 0;
        }
        Objects.requireNonNull(lhs, "lhs");
        Objects.requireNonNull(rhs, "rhs");

        Class lhsClazz = lhs.getClass();
        if (!lhsClazz.isInstance(rhs)) {
            throw new ClassCastException();
        }
        final 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();
    }

    /**
     * 
    Appends to {@code builder} the comparison of {@code lhs}
     * to {@code rhs} using the fields defined in {@code clazz}.
    
     *
     * @param lhs  left-hand object
     * @param rhs  right-hand object
     * @param clazz  {@code Class} that defines fields to be compared
     * @param builder  {@code CompareToBuilder} to append to
     * @param useTransients  whether to compare transient fields
     * @param excludeFields  fields to exclude
     */
    private static void reflectionAppend(
        final Object lhs,
        final Object rhs,
        final Class clazz,
        final CompareToBuilder builder,
        final boolean useTransients,
        final String[] excludeFields) {

        final Field[] fields = clazz.getDeclaredFields();
        AccessibleObject.setAccessible(fields, true);
        for (int i = 0; i < fields.length && builder.comparison == 0; i++) {
            final Field f = fields[i];
            if (!ArrayUtils.contains(excludeFields, f.getName())
                && !f.getName().contains("$")
                && (useTransients || !Modifier.isTransient(f.getModifiers()))
                && !Modifier.isStatic(f.getModifiers())) {
                try {
                    builder.append(f.get(lhs), f.get(rhs));
                } catch (final 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");
                }
            }
        }
    }

    //-----------------------------------------------------------------------
    /**
     * 
    Appends to the {@code builder} the {@code compareTo(Object)}
     * result of the superclass.
    
     *
     * @param superCompareTo  result of calling {@code super.compareTo(Object)}
     * @return this - used to chain append calls
     * @since 2.0
     */
    public CompareToBuilder appendSuper(final int superCompareTo) {
        if (comparison != 0) {
            return this;
        }
        comparison = superCompareTo;
        return this;
    }

    //-----------------------------------------------------------------------
    /**
     * 
    Appends to the {@code builder} the comparison of
     * two {@code Object}s.
    
     *
     * 
      
     * 
    1. Check if {@code lhs == rhs}
      2. 
     * 
    2. Check if either {@code lhs} or {@code rhs} is {@code null},
     *     a {@code null} object is less than a non-{@code null} object
      3. 
     * 
    3. Check the object contents
      4. 
     * 
    
     *
     * 
    {@code lhs} must either be an array or implement {@link Comparable}.
    
     *
     * @param lhs  left-hand object
     * @param rhs  right-hand object
     * @return this - used to chain append calls
     * @throws ClassCastException  if {@code rhs} is not assignment-compatible
     *  with {@code lhs}
     */
    public CompareToBuilder append(final Object lhs, final Object rhs) {
        return append(lhs, rhs, null);
    }

    /**
     * 
    Appends to the {@code builder} the comparison of
     * two {@code Object}s.
    
     *
     * 
      
     * 
    1. Check if {@code lhs == rhs}
      2. 
     * 
    2. Check if either {@code lhs} or {@code rhs} is {@code null},
     *     a {@code null} object is less than a non-{@code null} object
      3. 
     * 
    3. Check the object contents
      4. 
     * 
    
     *
     * 
    If {@code lhs} is an array, array comparison methods will be used.
     * Otherwise {@code comparator} will be used to compare the objects.
     * If {@code comparator} is {@code null}, {@code lhs} must
     * implement {@link Comparable} instead.
    
     *
     * @param lhs  left-hand object
     * @param rhs  right-hand object
     * @param comparator  {@code Comparator} used to compare the objects,
     *  {@code null} means treat lhs as {@code Comparable}
     * @return this - used to chain append calls
     * @throws ClassCastException  if {@code rhs} is not assignment-compatible
     *  with {@code lhs}
     * @since 2.0
     */
    public CompareToBuilder append(final Object lhs, final Object rhs, final 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()) {
            // factor out array case in order to keep method small enough to be inlined
            appendArray(lhs, rhs, comparator);
        } else {
            // the simple case, not an array, just test the element
            if (comparator == null) {
                @SuppressWarnings("unchecked") // assume this can be done; if not throw CCE as per Javadoc
                final Comparable comparable = (Comparable) lhs;
                comparison = comparable.compareTo(rhs);
            } else {
                @SuppressWarnings("unchecked") // assume this can be done; if not throw CCE as per Javadoc
                final Comparator comparator2 = (Comparator) comparator;
                comparison = comparator2.compare(lhs, rhs);
            }
        }
        return this;
    }

    private void appendArray(final Object lhs, final Object rhs, final Comparator comparator) {
        // 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);
        }
    }

    //-------------------------------------------------------------------------
    /**
     * Appends to the {@code builder} the comparison of
     * two {@code long}s.
     *
     * @param lhs  left-hand value
     * @param rhs  right-hand value
     * @return this - used to chain append calls
     */
    public CompareToBuilder append(final long lhs, final long rhs) {
        if (comparison != 0) {
            return this;
        }
        comparison = Long.compare(lhs, rhs);
        return this;
    }

    /**
     * Appends to the {@code builder} the comparison of
     * two {@code int}s.
     *
     * @param lhs  left-hand value
     * @param rhs  right-hand value
     * @return this - used to chain append calls
     */
    public CompareToBuilder append(final int lhs, final int rhs) {
        if (comparison != 0) {
            return this;
        }
        comparison = Integer.compare(lhs, rhs);
        return this;
    }

    /**
     * Appends to the {@code builder} the comparison of
     * two {@code short}s.
     *
     * @param lhs  left-hand value
     * @param rhs  right-hand value
     * @return this - used to chain append calls
     */
    public CompareToBuilder append(final short lhs, final short rhs) {
        if (comparison != 0) {
            return this;
        }
        comparison = Short.compare(lhs, rhs);
        return this;
    }

    /**
     * Appends to the {@code builder} the comparison of
     * two {@code char}s.
     *
     * @param lhs  left-hand value
     * @param rhs  right-hand value
     * @return this - used to chain append calls
     */
    public CompareToBuilder append(final char lhs, final char rhs) {
        if (comparison != 0) {
            return this;
        }
        comparison = Character.compare(lhs, rhs);
        return this;
    }

    /**
     * Appends to the {@code builder} the comparison of
     * two {@code byte}s.
     *
     * @param lhs  left-hand value
     * @param rhs  right-hand value
     * @return this - used to chain append calls
     */
    public CompareToBuilder append(final byte lhs, final byte rhs) {
        if (comparison != 0) {
            return this;
        }
        comparison = Byte.compare(lhs, rhs);
        return this;
    }

    /**
     * 
    Appends to the {@code builder} the comparison of
     * two {@code double}s.
    
     *
     * 
    This handles NaNs, Infinities, and {@code -0.0}.
    
     *
     * 
    It is compatible with the hash code generated by
     * {@code HashCodeBuilder}.
    
     *
     * @param lhs  left-hand value
     * @param rhs  right-hand value
     * @return this - used to chain append calls
     */
    public CompareToBuilder append(final double lhs, final double rhs) {
        if (comparison != 0) {
            return this;
        }
        comparison = Double.compare(lhs, rhs);
        return this;
    }

    /**
     * 
    Appends to the {@code builder} the comparison of
     * two {@code float}s.
    
     *
     * 
    This handles NaNs, Infinities, and {@code -0.0}.
    
     *
     * 
    It is compatible with the hash code generated by
     * {@code HashCodeBuilder}.
    
     *
     * @param lhs  left-hand value
     * @param rhs  right-hand value
     * @return this - used to chain append calls
     */
    public CompareToBuilder append(final float lhs, final float rhs) {
        if (comparison != 0) {
            return this;
        }
        comparison = Float.compare(lhs, rhs);
        return this;
    }

    /**
     * Appends to the {@code builder} the comparison of
     * two {@code booleans}s.
     *
     * @param lhs  left-hand value
     * @param rhs  right-hand value
     * @return this - used to chain append calls
      */
    public CompareToBuilder append(final boolean lhs, final boolean rhs) {
        if (comparison != 0) {
            return this;
        }
        if (lhs == rhs) {
            return this;
        }
        if (lhs) {
            comparison = 1;
        } else {
            comparison = -1;
        }
        return this;
    }

    //-----------------------------------------------------------------------
    /**
     * 
    Appends to the {@code builder} the deep comparison of
     * two {@code Object} arrays.
    
     *
     * 
      
     *  
    1. Check if arrays are the same using {@code ==}
      2. 
     *  
    2. Check if for {@code null}, {@code null} is less than non-{@code null}
      3. 
     *  
    3. Check array length, a short length array is less than a long length array
      4. 
     *  
    4. Check array contents element by element using {@link #append(Object, Object, Comparator)}
      5. 
     * 
    
     *
     * 
    This method will also will be called for the top level of multi-dimensional,
     * ragged, and multi-typed arrays.
    
     *
     * @param lhs  left-hand array
     * @param rhs  right-hand array
     * @return this - used to chain append calls
     * @throws ClassCastException  if {@code rhs} is not assignment-compatible
     *  with {@code lhs}
     */
    public CompareToBuilder append(final Object[] lhs, final Object[] rhs) {
        return append(lhs, rhs, null);
    }

    /**
     * 
    Appends to the {@code builder} the deep comparison of
     * two {@code Object} arrays.
    
     *
     * 
      
     *  
    1. Check if arrays are the same using {@code ==}
      2. 
     *  
    2. Check if for {@code null}, {@code null} is less than non-{@code null}
      3. 
     *  
    3. Check array length, a short length array is less than a long length array
      4. 
     *  
    4. Check array contents element by element using {@link #append(Object, Object, Comparator)}
      5. 
     * 
    
     *
     * 
    This method will also will be called for the top level of multi-dimensional,
     * ragged, and multi-typed arrays.
    
     *
     * @param lhs  left-hand array
     * @param rhs  right-hand array
     * @param comparator  {@code Comparator} to use to compare the array elements,
     *  {@code null} means to treat {@code lhs} elements as {@code Comparable}.
     * @return this - used to chain append calls
     * @throws ClassCastException  if {@code rhs} is not assignment-compatible
     *  with {@code lhs}
     * @since 2.0
     */
    public CompareToBuilder append(final Object[] lhs, final Object[] rhs, final 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;
    }

    /**
     * 
    Appends to the {@code builder} the deep comparison of
     * two {@code long} arrays.
    
     *
     * 
      
     *  
    1. Check if arrays are the same using {@code ==}
      2. 
     *  
    2. Check if for {@code null}, {@code null} is less than non-{@code null}
      3. 
     *  
    3. Check array length, a shorter length array is less than a longer length array
      4. 
     *  
    4. Check array contents element by element using {@link #append(long, long)}
      5. 
     * 
    
     *
     * @param lhs  left-hand array
     * @param rhs  right-hand array
     * @return this - used to chain append calls
     */
    public CompareToBuilder append(final long[] lhs, final 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;
    }

    /**
     * 
    Appends to the {@code builder} the deep comparison of
     * two {@code int} arrays.
    
     *
     * 
      
     *  
    1. Check if arrays are the same using {@code ==}
      2. 
     *  
    2. Check if for {@code null}, {@code null} is less than non-{@code null}
      3. 
     *  
    3. Check array length, a shorter length array is less than a longer length array
      4. 
     *  
    4. Check array contents element by element using {@link #append(int, int)}
      5. 
     * 
    
     *
     * @param lhs  left-hand array
     * @param rhs  right-hand array
     * @return this - used to chain append calls
     */
    public CompareToBuilder append(final int[] lhs, final 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;
    }

    /**
     * 
    Appends to the {@code builder} the deep comparison of
     * two {@code short} arrays.
    
     *
     * 
      
     *  
    1. Check if arrays are the same using {@code ==}
      2. 
     *  
    2. Check if for {@code null}, {@code null} is less than non-{@code null}
      3. 
     *  
    3. Check array length, a shorter length array is less than a longer length array
      4. 
     *  
    4. Check array contents element by element using {@link #append(short, short)}
      5. 
     * 
    
     *
     * @param lhs  left-hand array
     * @param rhs  right-hand array
     * @return this - used to chain append calls
     */
    public CompareToBuilder append(final short[] lhs, final 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;
    }

    /**
     * 
    Appends to the {@code builder} the deep comparison of
     * two {@code char} arrays.
    
     *
     * 
      
     *  
    1. Check if arrays are the same using {@code ==}
      2. 
     *  
    2. Check if for {@code null}, {@code null} is less than non-{@code null}
      3. 
     *  
    3. Check array length, a shorter length array is less than a longer length array
      4. 
     *  
    4. Check array contents element by element using {@link #append(char, char)}
      5. 
     * 
    
     *
     * @param lhs  left-hand array
     * @param rhs  right-hand array
     * @return this - used to chain append calls
     */
    public CompareToBuilder append(final char[] lhs, final 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;
    }

    /**
     * 
    Appends to the {@code builder} the deep comparison of
     * two {@code byte} arrays.
    
     *
     * 
      
     *  
    1. Check if arrays are the same using {@code ==}
      2. 
     *  
    2. Check if for {@code null}, {@code null} is less than non-{@code null}
      3. 
     *  
    3. Check array length, a shorter length array is less than a longer length array
      4. 
     *  
    4. Check array contents element by element using {@link #append(byte, byte)}
      5. 
     * 
    
     *
     * @param lhs  left-hand array
     * @param rhs  right-hand array
     * @return this - used to chain append calls
     */
    public CompareToBuilder append(final byte[] lhs, final 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;
    }

    /**
     * 
    Appends to the {@code builder} the deep comparison of
     * two {@code double} arrays.
    
     *
     * 
      
     *  
    1. Check if arrays are the same using {@code ==}
      2. 
     *  
    2. Check if for {@code null}, {@code null} is less than non-{@code null}
      3. 
     *  
    3. Check array length, a shorter length array is less than a longer length array
      4. 
     *  
    4. Check array contents element by element using {@link #append(double, double)}
      5. 
     * 
    
     *
     * @param lhs  left-hand array
     * @param rhs  right-hand array
     * @return this - used to chain append calls
     */
    public CompareToBuilder append(final double[] lhs, final 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;
    }

    /**
     * 
    Appends to the {@code builder} the deep comparison of
     * two {@code float} arrays.
    
     *
     * 
      
     *  
    1. Check if arrays are the same using {@code ==}
      2. 
     *  
    2. Check if for {@code null}, {@code null} is less than non-{@code null}
      3. 
     *  
    3. Check array length, a shorter length array is less than a longer length array
      4. 
     *  
    4. Check array contents element by element using {@link #append(float, float)}
      5. 
     * 
    
     *
     * @param lhs  left-hand array
     * @param rhs  right-hand array
     * @return this - used to chain append calls
     */
    public CompareToBuilder append(final float[] lhs, final 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;
    }

    /**
     * 
    Appends to the {@code builder} the deep comparison of
     * two {@code boolean} arrays.
    
     *
     * 
      
     *  
    1. Check if arrays are the same using {@code ==}
      2. 
     *  
    2. Check if for {@code null}, {@code null} is less than non-{@code null}
      3. 
     *  
    3. Check array length, a shorter length array is less than a longer length array
      4. 
     *  
    4. Check array contents element by element using {@link #append(boolean, boolean)}
      5. 
     * 
    
     *
     * @param lhs  left-hand array
     * @param rhs  right-hand array
     * @return this - used to chain append calls
     */
    public CompareToBuilder append(final boolean[] lhs, final 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} has judged the "left-hand" side
     * as less than, greater than, or equal to the "right-hand"
     * side.
     *
     * @return final comparison result
     * @see #build()
     */
    public int toComparison() {
        return comparison;
    }

    /**
     * Returns a negative Integer, a positive Integer, or zero as
     * the {@code builder} has judged the "left-hand" side
     * as less than, greater than, or equal to the "right-hand"
     * side.
     *
     * @return final comparison result as an Integer
     * @see #toComparison()
     * @since 3.0
     */
    @Override
    public Integer build() {
        return Integer.valueOf(toComparison());
    }
}

    
    
    
    

    




    
    
    © 2015 - 2025 Weber Informatics LLC | Privacy Policy