/*
 * 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;

import java.io.IOException;
import java.io.Serializable;
import java.lang.reflect.Array;
import java.lang.reflect.InvocationTargetException;
import java.lang.reflect.Method;
import java.util.Collection;
import java.util.Collections;
import java.util.Comparator;
import java.util.HashMap;
import java.util.Map;
import java.util.TreeSet;
import java.util.function.Supplier;

import org.apache.commons.lang3.exception.CloneFailedException;
import org.apache.commons.lang3.mutable.MutableInt;
import org.apache.commons.lang3.text.StrBuilder;

Operations on Object.
This class tries to handle null input gracefully. An exception will generally not be thrown for a null input. Each method documents its behavior in more detail.
#ThreadSafe#
Since:
1.0/**
 * <p>Operations on {@code Object}.</p>
 *
 * <p>This class tries to handle {@code null} input gracefully.
 * An exception will generally not be thrown for a {@code null} input.
 * Each method documents its behavior in more detail.</p>
 *
 * <p>#ThreadSafe#</p>
 * @since 1.0
 */
//@Immutable
@SuppressWarnings("deprecation") // deprecated class StrBuilder is imported
// because it is part of the signature of deprecated methods
public class ObjectUtils {

    // Null
    //-----------------------------------------------------------------------
    
Class used as a null placeholder where null has another meaning.
For example, in a HashMap the HashMap.get(Object) method returns null if the Map contains null or if there is no matching key. The Null placeholder can be used to distinguish between these two cases.
Another example is Hashtable, where null cannot be stored.
/**
     * <p>Class used as a null placeholder where {@code null}
     * has another meaning.</p>
     *
     * <p>For example, in a {@code HashMap} the
     * {@link java.util.HashMap#get(java.lang.Object)} method returns
     * {@code null} if the {@code Map} contains {@code null} or if there is
     * no matching key. The {@code Null} placeholder can be used to distinguish
     * between these two cases.</p>
     *
     * <p>Another example is {@code Hashtable}, where {@code null}
     * cannot be stored.</p>
     */
    public static class Null implements Serializable {
        
Required for serialization support. Declare serialization compatibility with Commons Lang 1.0
See Also:
Serializable/**
         * Required for serialization support. Declare serialization compatibility with Commons Lang 1.0
         *
         * @see java.io.Serializable
         */
        private static final long serialVersionUID = 7092611880189329093L;

        
Restricted constructor - singleton.
/**
         * Restricted constructor - singleton.
         */
        Null() {
            super();
        }

        
Ensure singleton.
Returns:
the singleton value/**
         * <p>Ensure singleton.</p>
         *
         * @return the singleton value
         */
        private Object readResolve() {
            return NULL;
        }
    }

    private static final char AT_SIGN = '@';

    
Singleton used as a null placeholder where null has another meaning.
For example, in a HashMap the HashMap.get(Object) method returns null if the Map contains null or if there is no matching key. The Null placeholder can be used to distinguish between these two cases.
Another example is Hashtable, where null cannot be stored.
This instance is Serializable.
/**
     * <p>Singleton used as a {@code null} placeholder where
     * {@code null} has another meaning.</p>
     *
     * <p>For example, in a {@code HashMap} the
     * {@link java.util.HashMap#get(java.lang.Object)} method returns
     * {@code null} if the {@code Map} contains {@code null} or if there
     * is no matching key. The {@code Null} placeholder can be used to
     * distinguish between these two cases.</p>
     *
     * <p>Another example is {@code Hashtable}, where {@code null}
     * cannot be stored.</p>
     *
     * <p>This instance is Serializable.</p>
     */
    public static final Null NULL = new Null();

    
Checks if all values in the given array are null. 
 If all the values are null or the array is null or empty, then true is returned, otherwise false is returned. 
ObjectUtils.allNull(*)                = false
ObjectUtils.allNull(*, null)          = false
ObjectUtils.allNull(null, *)          = false
ObjectUtils.allNull(null, null, *, *) = false
ObjectUtils.allNull(null)             = true
ObjectUtils.allNull(null, null)       = true

Params:
values –  the values to test, may be null or empty
Returns:
true if all values in the array are nulls, false if there is at least one non-null value in the array.
Since:
3.11/**
     * Checks if all values in the given array are {@code null}.
     *
     * <p>
     * If all the values are {@code null} or the array is {@code null}
     * or empty, then {@code true} is returned, otherwise {@code false} is returned.
     * </p>
     *
     * <pre>
     * ObjectUtils.allNull(*)                = false
     * ObjectUtils.allNull(*, null)          = false
     * ObjectUtils.allNull(null, *)          = false
     * ObjectUtils.allNull(null, null, *, *) = false
     * ObjectUtils.allNull(null)             = true
     * ObjectUtils.allNull(null, null)       = true
     * </pre>
     *
     * @param values  the values to test, may be {@code null} or empty
     * @return {@code true} if all values in the array are {@code null}s,
     * {@code false} if there is at least one non-null value in the array.
     * @since 3.11
     */
    public static boolean allNull(final Object... values) {
        return !anyNotNull(values);
    }

    
Checks if all values in the array are not nulls. 
 If any value is null or the array is null then false is returned. If all elements in array are not null or the array is empty (contains no elements) true is returned. 
ObjectUtils.allNotNull(*)             = true
ObjectUtils.allNotNull(*, *)          = true
ObjectUtils.allNotNull(null)          = false
ObjectUtils.allNotNull(null, null)    = false
ObjectUtils.allNotNull(null, *)       = false
ObjectUtils.allNotNull(*, null)       = false
ObjectUtils.allNotNull(*, *, null, *) = false

Params:
values –  the values to test, may be null or empty
Returns:
false if there is at least one null value in the array or the array is null, true if all values in the array are not nulls or array contains no elements.
Since:
3.5/**
     * Checks if all values in the array are not {@code nulls}.
     *
     * <p>
     * If any value is {@code null} or the array is {@code null} then
     * {@code false} is returned. If all elements in array are not
     * {@code null} or the array is empty (contains no elements) {@code true}
     * is returned.
     * </p>
     *
     * <pre>
     * ObjectUtils.allNotNull(*)             = true
     * ObjectUtils.allNotNull(*, *)          = true
     * ObjectUtils.allNotNull(null)          = false
     * ObjectUtils.allNotNull(null, null)    = false
     * ObjectUtils.allNotNull(null, *)       = false
     * ObjectUtils.allNotNull(*, null)       = false
     * ObjectUtils.allNotNull(*, *, null, *) = false
     * </pre>
     *
     * @param values  the values to test, may be {@code null} or empty
     * @return {@code false} if there is at least one {@code null} value in the array or the array is {@code null},
     * {@code true} if all values in the array are not {@code null}s or array contains no elements.
     * @since 3.5
     */
    public static boolean allNotNull(final Object... values) {
        if (values == null) {
            return false;
        }

        for (final Object val : values) {
            if (val == null) {
                return false;
            }
        }

        return true;
    }

    
Checks if any value in the given array is null. 
 If any of the values are null or the array is null, then true is returned, otherwise false is returned. 
ObjectUtils.anyNull(*)             = false
ObjectUtils.anyNull(*, *)          = false
ObjectUtils.anyNull(null)          = true
ObjectUtils.anyNull(null, null)    = true
ObjectUtils.anyNull(null, *)       = true
ObjectUtils.anyNull(*, null)       = true
ObjectUtils.anyNull(*, *, null, *) = true

Params:
values –  the values to test, may be null or empty
Returns:
true if there is at least one null value in the array, false if all the values are non-null. If the array is null or empty, true is also returned.
Since:
3.11/**
     * Checks if any value in the given array is {@code null}.
     *
     * <p>
     * If any of the values are {@code null} or the array is {@code null},
     * then {@code true} is returned, otherwise {@code false} is returned.
     * </p>
     *
     * <pre>
     * ObjectUtils.anyNull(*)             = false
     * ObjectUtils.anyNull(*, *)          = false
     * ObjectUtils.anyNull(null)          = true
     * ObjectUtils.anyNull(null, null)    = true
     * ObjectUtils.anyNull(null, *)       = true
     * ObjectUtils.anyNull(*, null)       = true
     * ObjectUtils.anyNull(*, *, null, *) = true
     * </pre>
     *
     * @param values  the values to test, may be {@code null} or empty
     * @return {@code true} if there is at least one {@code null} value in the array,
     * {@code false} if all the values are non-null.
     * If the array is {@code null} or empty, {@code true} is also returned.
     * @since 3.11
     */
    public static boolean anyNull(final Object... values) {
        return !allNotNull(values);
    }

    
Checks if any value in the given array is not null. 
 If all the values are null or the array is null or empty then false is returned. Otherwise true is returned. 
ObjectUtils.anyNotNull(*)                = true
ObjectUtils.anyNotNull(*, null)          = true
ObjectUtils.anyNotNull(null, *)          = true
ObjectUtils.anyNotNull(null, null, *, *) = true
ObjectUtils.anyNotNull(null)             = false
ObjectUtils.anyNotNull(null, null)       = false

Params:
values –  the values to test, may be null or empty
Returns:
true if there is at least one non-null value in the array, false if all values in the array are nulls. If the array is null or empty false is also returned.
Since:
3.5/**
     * Checks if any value in the given array is not {@code null}.
     *
     * <p>
     * If all the values are {@code null} or the array is {@code null}
     * or empty then {@code false} is returned. Otherwise {@code true} is returned.
     * </p>
     *
     * <pre>
     * ObjectUtils.anyNotNull(*)                = true
     * ObjectUtils.anyNotNull(*, null)          = true
     * ObjectUtils.anyNotNull(null, *)          = true
     * ObjectUtils.anyNotNull(null, null, *, *) = true
     * ObjectUtils.anyNotNull(null)             = false
     * ObjectUtils.anyNotNull(null, null)       = false
     * </pre>
     *
     * @param values  the values to test, may be {@code null} or empty
     * @return {@code true} if there is at least one non-null value in the array,
     * {@code false} if all values in the array are {@code null}s.
     * If the array is {@code null} or empty {@code false} is also returned.
     * @since 3.5
     */
    public static boolean anyNotNull(final Object... values) {
        return firstNonNull(values) != null;
    }

    // cloning
    //-----------------------------------------------------------------------
    
Clone an object.
Params:
obj –  the object to clone, null returns null
Type parameters:
<T> – the type of the object
Throws:
CloneFailedException – if the object is cloneable and the clone operation fails
Returns:
the clone if the object implements Cloneable otherwise null
Since:
3.0/**
     * <p>Clone an object.</p>
     *
     * @param <T> the type of the object
     * @param obj  the object to clone, null returns null
     * @return the clone if the object implements {@link Cloneable} otherwise {@code null}
     * @throws CloneFailedException if the object is cloneable and the clone operation fails
     * @since 3.0
     */
    public static <T> T clone(final T obj) {
        if (obj instanceof Cloneable) {
            final Object result;
            if (obj.getClass().isArray()) {
                final Class<?> componentType = obj.getClass().getComponentType();
                if (componentType.isPrimitive()) {
                    int length = Array.getLength(obj);
                    result = Array.newInstance(componentType, length);
                    while (length-- > 0) {
                        Array.set(result, length, Array.get(obj, length));
                    }
                } else {
                    result = ((Object[]) obj).clone();
                }
            } else {
                try {
                    final Method clone = obj.getClass().getMethod("clone");
                    result = clone.invoke(obj);
                } catch (final NoSuchMethodException e) {
                    throw new CloneFailedException("Cloneable type "
                        + obj.getClass().getName()
                        + " has no clone method", e);
                } catch (final IllegalAccessException e) {
                    throw new CloneFailedException("Cannot clone Cloneable type "
                        + obj.getClass().getName(), e);
                } catch (final InvocationTargetException e) {
                    throw new CloneFailedException("Exception cloning Cloneable type "
                        + obj.getClass().getName(), e.getCause());
                }
            }
            @SuppressWarnings("unchecked") // OK because input is of type T
            final T checked = (T) result;
            return checked;
        }

        return null;
    }

    
Clone an object if possible.
This method is similar to clone(Object), but will return the provided instance as the return value instead of null if the instance is not cloneable. This is more convenient if the caller uses different implementations (e.g. of a service) and some of the implementations do not allow concurrent processing or have state. In such cases the implementation can simply provide a proper clone implementation and the caller's code does not have to change.
Params:
obj –  the object to clone, null returns null
Type parameters:
<T> – the type of the object
Throws:
CloneFailedException – if the object is cloneable and the clone operation fails
Returns:
the clone if the object implements Cloneable otherwise the object itself
Since:
3.0/**
     * <p>Clone an object if possible.</p>
     *
     * <p>This method is similar to {@link #clone(Object)}, but will return the provided
     * instance as the return value instead of {@code null} if the instance
     * is not cloneable. This is more convenient if the caller uses different
     * implementations (e.g. of a service) and some of the implementations do not allow concurrent
     * processing or have state. In such cases the implementation can simply provide a proper
     * clone implementation and the caller's code does not have to change.</p>
     *
     * @param <T> the type of the object
     * @param obj  the object to clone, null returns null
     * @return the clone if the object implements {@link Cloneable} otherwise the object itself
     * @throws CloneFailedException if the object is cloneable and the clone operation fails
     * @since 3.0
     */
    public static <T> T cloneIfPossible(final T obj) {
        final T clone = clone(obj);
        return clone == null ? obj : clone;
    }

    
Null safe comparison of Comparables. null is assumed to be less than a non-null value.
Params:
c1 –  the first comparable, may be null
c2 –  the second comparable, may be null
Type parameters:
<T> – type of the values processed by this method
Returns:
a negative value if c1 < c2, zero if c1 = c2
 and a positive value if c1 > c2/**
     * <p>Null safe comparison of Comparables.
     * {@code null} is assumed to be less than a non-{@code null} value.</p>
     *
     * @param <T> type of the values processed by this method
     * @param c1  the first comparable, may be null
     * @param c2  the second comparable, may be null
     * @return a negative value if c1 &lt; c2, zero if c1 = c2
     *  and a positive value if c1 &gt; c2
     */
    public static <T extends Comparable<? super T>> int compare(final T c1, final T c2) {
        return compare(c1, c2, false);
    }

    
Null safe comparison of Comparables.
Params:
c1 –  the first comparable, may be null
c2 –  the second comparable, may be null
nullGreater – if true null is considered greater than a non-null value or if false null is considered less than a Non-null value
Type parameters:
<T> – type of the values processed by this method
See Also:
Comparator.compare(Object, Object)
Returns:
a negative value if c1 < c2, zero if c1 = c2
 and a positive value if c1 > c2/**
     * <p>Null safe comparison of Comparables.</p>
     *
     * @param <T> type of the values processed by this method
     * @param c1  the first comparable, may be null
     * @param c2  the second comparable, may be null
     * @param nullGreater if true {@code null} is considered greater
     *  than a non-{@code null} value or if false {@code null} is
     *  considered less than a Non-{@code null} value
     * @return a negative value if c1 &lt; c2, zero if c1 = c2
     *  and a positive value if c1 &gt; c2
     * @see java.util.Comparator#compare(Object, Object)
     */
    public static <T extends Comparable<? super T>> int compare(final T c1, final T c2, final boolean nullGreater) {
        if (c1 == c2) {
            return 0;
        } else if (c1 == null) {
            return nullGreater ? 1 : -1;
        } else if (c2 == null) {
            return nullGreater ? -1 : 1;
        }
        return c1.compareTo(c2);
    }

    
This method returns the provided value unchanged.
This can prevent javac from inlining a constant
field, e.g.,
    public final static boolean MAGIC_FLAG = ObjectUtils.CONST(true);

This way any jars that refer to this field do not
have to recompile themselves if the field's value
changes at some future date.
Params:
v – the boolean value to return
Returns:
the boolean v, unchanged
Since:
3.2/**
     * This method returns the provided value unchanged.
     * This can prevent javac from inlining a constant
     * field, e.g.,
     *
     * <pre>
     *     public final static boolean MAGIC_FLAG = ObjectUtils.CONST(true);
     * </pre>
     *
     * This way any jars that refer to this field do not
     * have to recompile themselves if the field's value
     * changes at some future date.
     *
     * @param v the boolean value to return
     * @return the boolean v, unchanged
     * @since 3.2
     */
    public static boolean CONST(final boolean v) {
        return v;
    }

    
This method returns the provided value unchanged.
This can prevent javac from inlining a constant
field, e.g.,
    public final static byte MAGIC_BYTE = ObjectUtils.CONST((byte) 127);

This way any jars that refer to this field do not
have to recompile themselves if the field's value
changes at some future date.
Params:
v – the byte value to return
Returns:
the byte v, unchanged
Since:
3.2/**
     * This method returns the provided value unchanged.
     * This can prevent javac from inlining a constant
     * field, e.g.,
     *
     * <pre>
     *     public final static byte MAGIC_BYTE = ObjectUtils.CONST((byte) 127);
     * </pre>
     *
     * This way any jars that refer to this field do not
     * have to recompile themselves if the field's value
     * changes at some future date.
     *
     * @param v the byte value to return
     * @return the byte v, unchanged
     * @since 3.2
     */
    public static byte CONST(final byte v) {
        return v;
    }

    
This method returns the provided value unchanged.
This can prevent javac from inlining a constant
field, e.g.,
    public final static char MAGIC_CHAR = ObjectUtils.CONST('a');

This way any jars that refer to this field do not
have to recompile themselves if the field's value
changes at some future date.
Params:
v – the char value to return
Returns:
the char v, unchanged
Since:
3.2/**
     * This method returns the provided value unchanged.
     * This can prevent javac from inlining a constant
     * field, e.g.,
     *
     * <pre>
     *     public final static char MAGIC_CHAR = ObjectUtils.CONST('a');
     * </pre>
     *
     * This way any jars that refer to this field do not
     * have to recompile themselves if the field's value
     * changes at some future date.
     *
     * @param v the char value to return
     * @return the char v, unchanged
     * @since 3.2
     */
    public static char CONST(final char v) {
        return v;
    }

    
This method returns the provided value unchanged.
This can prevent javac from inlining a constant
field, e.g.,
    public final static double MAGIC_DOUBLE = ObjectUtils.CONST(1.0);

This way any jars that refer to this field do not
have to recompile themselves if the field's value
changes at some future date.
Params:
v – the double value to return
Returns:
the double v, unchanged
Since:
3.2/**
     * This method returns the provided value unchanged.
     * This can prevent javac from inlining a constant
     * field, e.g.,
     *
     * <pre>
     *     public final static double MAGIC_DOUBLE = ObjectUtils.CONST(1.0);
     * </pre>
     *
     * This way any jars that refer to this field do not
     * have to recompile themselves if the field's value
     * changes at some future date.
     *
     * @param v the double value to return
     * @return the double v, unchanged
     * @since 3.2
     */
    public static double CONST(final double v) {
        return v;
    }

    
This method returns the provided value unchanged.
This can prevent javac from inlining a constant
field, e.g.,
    public final static float MAGIC_FLOAT = ObjectUtils.CONST(1.0f);

This way any jars that refer to this field do not
have to recompile themselves if the field's value
changes at some future date.
Params:
v – the float value to return
Returns:
the float v, unchanged
Since:
3.2/**
     * This method returns the provided value unchanged.
     * This can prevent javac from inlining a constant
     * field, e.g.,
     *
     * <pre>
     *     public final static float MAGIC_FLOAT = ObjectUtils.CONST(1.0f);
     * </pre>
     *
     * This way any jars that refer to this field do not
     * have to recompile themselves if the field's value
     * changes at some future date.
     *
     * @param v the float value to return
     * @return the float v, unchanged
     * @since 3.2
     */
    public static float CONST(final float v) {
        return v;
    }

    
This method returns the provided value unchanged.
This can prevent javac from inlining a constant
field, e.g.,
    public final static int MAGIC_INT = ObjectUtils.CONST(123);

This way any jars that refer to this field do not
have to recompile themselves if the field's value
changes at some future date.
Params:
v – the int value to return
Returns:
the int v, unchanged
Since:
3.2/**
     * This method returns the provided value unchanged.
     * This can prevent javac from inlining a constant
     * field, e.g.,
     *
     * <pre>
     *     public final static int MAGIC_INT = ObjectUtils.CONST(123);
     * </pre>
     *
     * This way any jars that refer to this field do not
     * have to recompile themselves if the field's value
     * changes at some future date.
     *
     * @param v the int value to return
     * @return the int v, unchanged
     * @since 3.2
     */
    public static int CONST(final int v) {
        return v;
    }

    
This method returns the provided value unchanged.
This can prevent javac from inlining a constant
field, e.g.,
    public final static long MAGIC_LONG = ObjectUtils.CONST(123L);

This way any jars that refer to this field do not
have to recompile themselves if the field's value
changes at some future date.
Params:
v – the long value to return
Returns:
the long v, unchanged
Since:
3.2/**
     * This method returns the provided value unchanged.
     * This can prevent javac from inlining a constant
     * field, e.g.,
     *
     * <pre>
     *     public final static long MAGIC_LONG = ObjectUtils.CONST(123L);
     * </pre>
     *
     * This way any jars that refer to this field do not
     * have to recompile themselves if the field's value
     * changes at some future date.
     *
     * @param v the long value to return
     * @return the long v, unchanged
     * @since 3.2
     */
    public static long CONST(final long v) {
        return v;
    }

    
This method returns the provided value unchanged.
This can prevent javac from inlining a constant
field, e.g.,
    public final static short MAGIC_SHORT = ObjectUtils.CONST((short) 123);

This way any jars that refer to this field do not
have to recompile themselves if the field's value
changes at some future date.
Params:
v – the short value to return
Returns:
the short v, unchanged
Since:
3.2/**
     * This method returns the provided value unchanged.
     * This can prevent javac from inlining a constant
     * field, e.g.,
     *
     * <pre>
     *     public final static short MAGIC_SHORT = ObjectUtils.CONST((short) 123);
     * </pre>
     *
     * This way any jars that refer to this field do not
     * have to recompile themselves if the field's value
     * changes at some future date.
     *
     * @param v the short value to return
     * @return the short v, unchanged
     * @since 3.2
     */
    public static short CONST(final short v) {
        return v;
    }

    
This method returns the provided value unchanged.
This can prevent javac from inlining a constant
field, e.g.,
    public final static String MAGIC_STRING = ObjectUtils.CONST("abc");

This way any jars that refer to this field do not
have to recompile themselves if the field's value
changes at some future date.
Params:
v – the genericized Object value to return (typically a String).
Type parameters:
<T> – the Object type
Returns:
the genericized Object v, unchanged (typically a String).
Since:
3.2/**
     * This method returns the provided value unchanged.
     * This can prevent javac from inlining a constant
     * field, e.g.,
     *
     * <pre>
     *     public final static String MAGIC_STRING = ObjectUtils.CONST("abc");
     * </pre>
     *
     * This way any jars that refer to this field do not
     * have to recompile themselves if the field's value
     * changes at some future date.
     *
     * @param <T> the Object type
     * @param v the genericized Object value to return (typically a String).
     * @return the genericized Object v, unchanged (typically a String).
     * @since 3.2
     */
    public static <T> T CONST(final T v) {
        return v;
    }

    
This method returns the provided value unchanged.
This can prevent javac from inlining a constant
field, e.g.,
    public final static byte MAGIC_BYTE = ObjectUtils.CONST_BYTE(127);

This way any jars that refer to this field do not
have to recompile themselves if the field's value
changes at some future date.
Params:
v – the byte literal (as an int) value to return
Throws:
IllegalArgumentException – if the value passed to v
        is larger than a byte, that is, smaller than -128 or
        larger than 127.
Returns:
the byte v, unchanged
Since:
3.2/**
     * This method returns the provided value unchanged.
     * This can prevent javac from inlining a constant
     * field, e.g.,
     *
     * <pre>
     *     public final static byte MAGIC_BYTE = ObjectUtils.CONST_BYTE(127);
     * </pre>
     *
     * This way any jars that refer to this field do not
     * have to recompile themselves if the field's value
     * changes at some future date.
     *
     * @param v the byte literal (as an int) value to return
     * @throws IllegalArgumentException if the value passed to v
     *         is larger than a byte, that is, smaller than -128 or
     *         larger than 127.
     * @return the byte v, unchanged
     * @since 3.2
     */
    public static byte CONST_BYTE(final int v) {
        if (v < Byte.MIN_VALUE || v > Byte.MAX_VALUE) {
            throw new IllegalArgumentException("Supplied value must be a valid byte literal between -128 and 127: [" + v + "]");
        }
        return (byte) v;
    }

    
This method returns the provided value unchanged.
This can prevent javac from inlining a constant
field, e.g.,
    public final static short MAGIC_SHORT = ObjectUtils.CONST_SHORT(127);

This way any jars that refer to this field do not
have to recompile themselves if the field's value
changes at some future date.
Params:
v – the short literal (as an int) value to return
Throws:
IllegalArgumentException – if the value passed to v
        is larger than a short, that is, smaller than -32768 or
        larger than 32767.
Returns:
the byte v, unchanged
Since:
3.2/**
     * This method returns the provided value unchanged.
     * This can prevent javac from inlining a constant
     * field, e.g.,
     *
     * <pre>
     *     public final static short MAGIC_SHORT = ObjectUtils.CONST_SHORT(127);
     * </pre>
     *
     * This way any jars that refer to this field do not
     * have to recompile themselves if the field's value
     * changes at some future date.
     *
     * @param v the short literal (as an int) value to return
     * @throws IllegalArgumentException if the value passed to v
     *         is larger than a short, that is, smaller than -32768 or
     *         larger than 32767.
     * @return the byte v, unchanged
     * @since 3.2
     */
    public static short CONST_SHORT(final int v) {
        if (v < Short.MIN_VALUE || v > Short.MAX_VALUE) {
            throw new IllegalArgumentException("Supplied value must be a valid byte literal between -32768 and 32767: [" + v + "]");
        }
        return (short) v;
    }

    
Returns a default value if the object passed is null.
ObjectUtils.defaultIfNull(null, null)      = null
ObjectUtils.defaultIfNull(null, "")        = ""
ObjectUtils.defaultIfNull(null, "zz")      = "zz"
ObjectUtils.defaultIfNull("abc", *)        = "abc"
ObjectUtils.defaultIfNull(Boolean.TRUE, *) = Boolean.TRUE

Params:
object –  the Object to test, may be null
defaultValue –  the default value to return, may be null
Type parameters:
<T> – the type of the object
Returns:
object if it is not null, defaultValue otherwise TODO Rename to getIfNull in 4.0/**
     * <p>Returns a default value if the object passed is {@code null}.</p>
     *
     * <pre>
     * ObjectUtils.defaultIfNull(null, null)      = null
     * ObjectUtils.defaultIfNull(null, "")        = ""
     * ObjectUtils.defaultIfNull(null, "zz")      = "zz"
     * ObjectUtils.defaultIfNull("abc", *)        = "abc"
     * ObjectUtils.defaultIfNull(Boolean.TRUE, *) = Boolean.TRUE
     * </pre>
     *
     * @param <T> the type of the object
     * @param object  the {@code Object} to test, may be {@code null}
     * @param defaultValue  the default value to return, may be {@code null}
     * @return {@code object} if it is not {@code null}, defaultValue otherwise
     * TODO Rename to getIfNull in 4.0
     */
    public static <T> T defaultIfNull(final T object, final T defaultValue) {
        return object != null ? object : defaultValue;
    }

    // Null-safe equals/hashCode
    //-----------------------------------------------------------------------
    
Compares two objects for equality, where either one or both objects may be null.
ObjectUtils.equals(null, null)                  = true
ObjectUtils.equals(null, "")                    = false
ObjectUtils.equals("", null)                    = false
ObjectUtils.equals("", "")                      = true
ObjectUtils.equals(Boolean.TRUE, null)          = false
ObjectUtils.equals(Boolean.TRUE, "true")        = false
ObjectUtils.equals(Boolean.TRUE, Boolean.TRUE)  = true
ObjectUtils.equals(Boolean.TRUE, Boolean.FALSE) = false

Params:
object1 –  the first object, may be null
object2 –  the second object, may be null
Returns:
true if the values of both objects are the same
Deprecated:
this method has been replaced by java.util.Objects.equals(Object, Object) in Java 7 and will be removed from future releases./**
     * <p>Compares two objects for equality, where either one or both
     * objects may be {@code null}.</p>
     *
     * <pre>
     * ObjectUtils.equals(null, null)                  = true
     * ObjectUtils.equals(null, "")                    = false
     * ObjectUtils.equals("", null)                    = false
     * ObjectUtils.equals("", "")                      = true
     * ObjectUtils.equals(Boolean.TRUE, null)          = false
     * ObjectUtils.equals(Boolean.TRUE, "true")        = false
     * ObjectUtils.equals(Boolean.TRUE, Boolean.TRUE)  = true
     * ObjectUtils.equals(Boolean.TRUE, Boolean.FALSE) = false
     * </pre>
     *
     * @param object1  the first object, may be {@code null}
     * @param object2  the second object, may be {@code null}
     * @return {@code true} if the values of both objects are the same
     * @deprecated this method has been replaced by {@code java.util.Objects.equals(Object, Object)} in Java 7 and will
     * be removed from future releases.
     */
    @Deprecated
    public static boolean equals(final Object object1, final Object object2) {
        if (object1 == object2) {
            return true;
        }
        if (object1 == null || object2 == null) {
            return false;
        }
        return object1.equals(object2);
    }

    
Returns the first value in the array which is not null. If all the values are null or the array is null or empty then null is returned.
ObjectUtils.firstNonNull(null, null)      = null
ObjectUtils.firstNonNull(null, "")        = ""
ObjectUtils.firstNonNull(null, null, "")  = ""
ObjectUtils.firstNonNull(null, "zz")      = "zz"
ObjectUtils.firstNonNull("abc", *)        = "abc"
ObjectUtils.firstNonNull(null, "xyz", *)  = "xyz"
ObjectUtils.firstNonNull(Boolean.TRUE, *) = Boolean.TRUE
ObjectUtils.firstNonNull()                = null

Params:
values –  the values to test, may be null or empty
Type parameters:
<T> – the component type of the array
Returns:
the first value from values which is not null, or null if there are no non-null values
Since:
3.0/**
     * <p>Returns the first value in the array which is not {@code null}.
     * If all the values are {@code null} or the array is {@code null}
     * or empty then {@code null} is returned.</p>
     *
     * <pre>
     * ObjectUtils.firstNonNull(null, null)      = null
     * ObjectUtils.firstNonNull(null, "")        = ""
     * ObjectUtils.firstNonNull(null, null, "")  = ""
     * ObjectUtils.firstNonNull(null, "zz")      = "zz"
     * ObjectUtils.firstNonNull("abc", *)        = "abc"
     * ObjectUtils.firstNonNull(null, "xyz", *)  = "xyz"
     * ObjectUtils.firstNonNull(Boolean.TRUE, *) = Boolean.TRUE
     * ObjectUtils.firstNonNull()                = null
     * </pre>
     *
     * @param <T> the component type of the array
     * @param values  the values to test, may be {@code null} or empty
     * @return the first value from {@code values} which is not {@code null},
     *  or {@code null} if there are no non-null values
     * @since 3.0
     */
    @SafeVarargs
    public static <T> T firstNonNull(final T... values) {
        if (values != null) {
            for (final T val : values) {
                if (val != null) {
                    return val;
                }
            }
        }
        return null;
    }

    
Executes the given suppliers in order and returns the first return value where a value other than null is returned. Once a non-null value is obtained, all following suppliers are not executed anymore. If all the return values are null or no suppliers are provided then null is returned.
ObjectUtils.firstNonNullLazy(null, () -> null) = null
ObjectUtils.firstNonNullLazy(() -> null, () -> "") = ""
ObjectUtils.firstNonNullLazy(() -> "", () -> throw new IllegalStateException()) = ""
ObjectUtils.firstNonNullLazy(() -> null, () -> "zz) = "zz"
ObjectUtils.firstNonNullLazy() = null

Params:
suppliers –  the suppliers returning the values to test. null values are ignored. Suppliers may return null or a value of type @{code T}
Type parameters:
<T> – the type of the return values
Returns:
the first return value from suppliers which is not null, or null if there are no non-null values
Since:
3.10/**
     * <p>Executes the given suppliers in order and returns the first return
     * value where a value other than {@code null} is returned.
     * Once a non-{@code null} value is obtained, all following suppliers are
     * not executed anymore.
     * If all the return values are {@code null} or no suppliers are provided
     * then {@code null} is returned.</p>
     *
     * <pre>
     * ObjectUtils.firstNonNullLazy(null, () -&gt; null) = null
     * ObjectUtils.firstNonNullLazy(() -&gt; null, () -&gt; "") = ""
     * ObjectUtils.firstNonNullLazy(() -&gt; "", () -&gt; throw new IllegalStateException()) = ""
     * ObjectUtils.firstNonNullLazy(() -&gt; null, () -&gt; "zz) = "zz"
     * ObjectUtils.firstNonNullLazy() = null
     * </pre>
     *
     * @param <T> the type of the return values
     * @param suppliers  the suppliers returning the values to test.
     *                   {@code null} values are ignored.
     *                   Suppliers may return {@code null} or a value of type @{code T}
     * @return the first return value from {@code suppliers} which is not {@code null},
     *  or {@code null} if there are no non-null values
     * @since 3.10
     */
    @SafeVarargs
    public static <T> T getFirstNonNull(final Supplier<T>... suppliers) {
        if (suppliers != null) {
            for (final Supplier<T> supplier : suppliers) {
                if (supplier != null) {
                    final T value = supplier.get();
                    if (value != null) {
                        return value;
                    }
                }
            }
        }
        return null;
    }

    
 Returns the given object is it is non-null, otherwise returns the Supplier's Supplier.get() value. 

The caller responsible for thread-safety and exception handling of default value supplier.

ObjectUtils.getIfNull(null, () -> null)     = null
ObjectUtils.getIfNull(null, null)              = null
ObjectUtils.getIfNull(null, () -> "")       = ""
ObjectUtils.getIfNull(null, () -> "zz")     = "zz"
ObjectUtils.getIfNull("abc", *)                = "abc"
ObjectUtils.getIfNull(Boolean.TRUE, *)         = Boolean.TRUE

Params:
object – the Object to test, may be null
defaultSupplier – the default value to return, may be null
Type parameters:
<T> – the type of the object
Returns:
object if it is not null, defaultValueSupplier.get() otherwise
Since:
3.10/**
     * <p>
     * Returns the given {@code object} is it is non-null, otherwise returns the Supplier's {@link Supplier#get()}
     * value.
     * </p>
     *
     * <p>
     * The caller responsible for thread-safety and exception handling of default value supplier.
     * </p>
     *
     * <pre>
     * ObjectUtils.getIfNull(null, () -&gt; null)     = null
     * ObjectUtils.getIfNull(null, null)              = null
     * ObjectUtils.getIfNull(null, () -&gt; "")       = ""
     * ObjectUtils.getIfNull(null, () -&gt; "zz")     = "zz"
     * ObjectUtils.getIfNull("abc", *)                = "abc"
     * ObjectUtils.getIfNull(Boolean.TRUE, *)         = Boolean.TRUE
     * </pre>
     *
     * @param <T> the type of the object
     * @param object the {@code Object} to test, may be {@code null}
     * @param defaultSupplier the default value to return, may be {@code null}
     * @return {@code object} if it is not {@code null}, {@code defaultValueSupplier.get()} otherwise
     * @since 3.10
     */
    public static <T> T getIfNull(final T object, final Supplier<T> defaultSupplier) {
        return object != null ? object : defaultSupplier == null ? null : defaultSupplier.get();
    }

    
Gets the hash code of an object returning zero when the object is null.
ObjectUtils.hashCode(null)   = 0
ObjectUtils.hashCode(obj)    = obj.hashCode()

Params:
obj –  the object to obtain the hash code of, may be null
Returns:
the hash code of the object, or zero if null
Since:
2.1
Deprecated:
this method has been replaced by java.util.Objects.hashCode(Object) in Java 7 and will be removed in future releases/**
     * <p>Gets the hash code of an object returning zero when the
     * object is {@code null}.</p>
     *
     * <pre>
     * ObjectUtils.hashCode(null)   = 0
     * ObjectUtils.hashCode(obj)    = obj.hashCode()
     * </pre>
     *
     * @param obj  the object to obtain the hash code of, may be {@code null}
     * @return the hash code of the object, or zero if null
     * @since 2.1
     * @deprecated this method has been replaced by {@code java.util.Objects.hashCode(Object)} in Java 7 and will be
     * removed in future releases
     */
    @Deprecated
    public static int hashCode(final Object obj) {
        // hashCode(Object) retained for performance, as hash code is often critical
        return obj == null ? 0 : obj.hashCode();
    }

    
Gets the hash code for multiple objects.
This allows a hash code to be rapidly calculated for a number of objects.
The hash code for a single object is the not same as hashCode(Object). The hash code for multiple objects is the same as that calculated by an ArrayList containing the specified objects.
ObjectUtils.hashCodeMulti()                 = 1
ObjectUtils.hashCodeMulti((Object[]) null)  = 1
ObjectUtils.hashCodeMulti(a)                = 31 + a.hashCode()
ObjectUtils.hashCodeMulti(a,b)              = (31 + a.hashCode()) * 31 + b.hashCode()
ObjectUtils.hashCodeMulti(a,b,c)            = ((31 + a.hashCode()) * 31 + b.hashCode()) * 31 + c.hashCode()

Params:
objects –  the objects to obtain the hash code of, may be null
Returns:
the hash code of the objects, or zero if null
Since:
3.0
Deprecated:
this method has been replaced by java.util.Objects.hash(Object...) in Java 7 and will be removed in future releases./**
     * <p>Gets the hash code for multiple objects.</p>
     *
     * <p>This allows a hash code to be rapidly calculated for a number of objects.
     * The hash code for a single object is the <em>not</em> same as {@link #hashCode(Object)}.
     * The hash code for multiple objects is the same as that calculated by an
     * {@code ArrayList} containing the specified objects.</p>
     *
     * <pre>
     * ObjectUtils.hashCodeMulti()                 = 1
     * ObjectUtils.hashCodeMulti((Object[]) null)  = 1
     * ObjectUtils.hashCodeMulti(a)                = 31 + a.hashCode()
     * ObjectUtils.hashCodeMulti(a,b)              = (31 + a.hashCode()) * 31 + b.hashCode()
     * ObjectUtils.hashCodeMulti(a,b,c)            = ((31 + a.hashCode()) * 31 + b.hashCode()) * 31 + c.hashCode()
     * </pre>
     *
     * @param objects  the objects to obtain the hash code of, may be {@code null}
     * @return the hash code of the objects, or zero if null
     * @since 3.0
     * @deprecated this method has been replaced by {@code java.util.Objects.hash(Object...)} in Java 7 and will be
     * removed in future releases.
     */
    @Deprecated
    public static int hashCodeMulti(final Object... objects) {
        int hash = 1;
        if (objects != null) {
            for (final Object object : objects) {
                final int tmpHash = hashCode(object);
                hash = hash * 31 + tmpHash;
            }
        }
        return hash;
    }

    
Appends the toString that would be produced by Object if a class did not override toString itself. null will throw a NullPointerException for either of the two parameters. 
ObjectUtils.identityToString(appendable, "")            = appendable.append("java.lang.String@1e23"
ObjectUtils.identityToString(appendable, Boolean.TRUE)  = appendable.append("java.lang.Boolean@7fa"
ObjectUtils.identityToString(appendable, Boolean.TRUE)  = appendable.append("java.lang.Boolean@7fa")

Params:
appendable –  the appendable to append to
object –  the object to create a toString for
Throws:
IOException – if an I/O error occurs
Since:
3.2/**
     * <p>Appends the toString that would be produced by {@code Object}
     * if a class did not override toString itself. {@code null}
     * will throw a NullPointerException for either of the two parameters. </p>
     *
     * <pre>
     * ObjectUtils.identityToString(appendable, "")            = appendable.append("java.lang.String@1e23"
     * ObjectUtils.identityToString(appendable, Boolean.TRUE)  = appendable.append("java.lang.Boolean@7fa"
     * ObjectUtils.identityToString(appendable, Boolean.TRUE)  = appendable.append("java.lang.Boolean@7fa")
     * </pre>
     *
     * @param appendable  the appendable to append to
     * @param object  the object to create a toString for
     * @throws IOException if an I/O error occurs
     * @since 3.2
     */
    public static void identityToString(final Appendable appendable, final Object object) throws IOException {
        Validate.notNull(object, "Cannot get the toString of a null object");
        appendable.append(object.getClass().getName())
              .append(AT_SIGN)
              .append(Integer.toHexString(System.identityHashCode(object)));
    }

    // Identity ToString
    //-----------------------------------------------------------------------
    
Gets the toString that would be produced by Object if a class did not override toString itself. null will return null.
ObjectUtils.identityToString(null)         = null
ObjectUtils.identityToString("")           = "java.lang.String@1e23"
ObjectUtils.identityToString(Boolean.TRUE) = "java.lang.Boolean@7fa"

Params:
object –  the object to create a toString for, may be null
Returns:
the default toString text, or null if null passed in/**
     * <p>Gets the toString that would be produced by {@code Object}
     * if a class did not override toString itself. {@code null}
     * will return {@code null}.</p>
     *
     * <pre>
     * ObjectUtils.identityToString(null)         = null
     * ObjectUtils.identityToString("")           = "java.lang.String@1e23"
     * ObjectUtils.identityToString(Boolean.TRUE) = "java.lang.Boolean@7fa"
     * </pre>
     *
     * @param object  the object to create a toString for, may be
     *  {@code null}
     * @return the default toString text, or {@code null} if
     *  {@code null} passed in
     */
    public static String identityToString(final Object object) {
        if (object == null) {
            return null;
        }
        final String name = object.getClass().getName();
        final String hexString = Integer.toHexString(System.identityHashCode(object));
        final StringBuilder builder = new StringBuilder(name.length() + 1 + hexString.length());
        // @formatter:off
        builder.append(name)
              .append(AT_SIGN)
              .append(hexString);
        // @formatter:on
        return builder.toString();
    }

    
Appends the toString that would be produced by Object if a class did not override toString itself. null will throw a NullPointerException for either of the two parameters. 
ObjectUtils.identityToString(builder, "")            = builder.append("java.lang.String@1e23"
ObjectUtils.identityToString(builder, Boolean.TRUE)  = builder.append("java.lang.Boolean@7fa"
ObjectUtils.identityToString(builder, Boolean.TRUE)  = builder.append("java.lang.Boolean@7fa")

Params:
builder –  the builder to append to
object –  the object to create a toString for
Since:
3.2
Deprecated:
as of 3.6, because StrBuilder was moved to commons-text, use one of the other identityToString methods instead/**
     * <p>Appends the toString that would be produced by {@code Object}
     * if a class did not override toString itself. {@code null}
     * will throw a NullPointerException for either of the two parameters. </p>
     *
     * <pre>
     * ObjectUtils.identityToString(builder, "")            = builder.append("java.lang.String@1e23"
     * ObjectUtils.identityToString(builder, Boolean.TRUE)  = builder.append("java.lang.Boolean@7fa"
     * ObjectUtils.identityToString(builder, Boolean.TRUE)  = builder.append("java.lang.Boolean@7fa")
     * </pre>
     *
     * @param builder  the builder to append to
     * @param object  the object to create a toString for
     * @since 3.2
     * @deprecated as of 3.6, because StrBuilder was moved to commons-text,
     *  use one of the other {@code identityToString} methods instead
     */
    @Deprecated
    public static void identityToString(final StrBuilder builder, final Object object) {
        Validate.notNull(object, "Cannot get the toString of a null object");
        final String name = object.getClass().getName();
        final String hexString = Integer.toHexString(System.identityHashCode(object));
        builder.ensureCapacity(builder.length() +  name.length() + 1 + hexString.length());
        builder.append(name)
              .append(AT_SIGN)
              .append(hexString);
    }

    
Appends the toString that would be produced by Object if a class did not override toString itself. null will throw a NullPointerException for either of the two parameters. 
ObjectUtils.identityToString(buf, "")            = buf.append("java.lang.String@1e23"
ObjectUtils.identityToString(buf, Boolean.TRUE)  = buf.append("java.lang.Boolean@7fa"
ObjectUtils.identityToString(buf, Boolean.TRUE)  = buf.append("java.lang.Boolean@7fa")

Params:
buffer –  the buffer to append to
object –  the object to create a toString for
Since:
2.4/**
     * <p>Appends the toString that would be produced by {@code Object}
     * if a class did not override toString itself. {@code null}
     * will throw a NullPointerException for either of the two parameters. </p>
     *
     * <pre>
     * ObjectUtils.identityToString(buf, "")            = buf.append("java.lang.String@1e23"
     * ObjectUtils.identityToString(buf, Boolean.TRUE)  = buf.append("java.lang.Boolean@7fa"
     * ObjectUtils.identityToString(buf, Boolean.TRUE)  = buf.append("java.lang.Boolean@7fa")
     * </pre>
     *
     * @param buffer  the buffer to append to
     * @param object  the object to create a toString for
     * @since 2.4
     */
    public static void identityToString(final StringBuffer buffer, final Object object) {
        Validate.notNull(object, "Cannot get the toString of a null object");
        final String name = object.getClass().getName();
        final String hexString = Integer.toHexString(System.identityHashCode(object));
        buffer.ensureCapacity(buffer.length() + name.length() + 1 + hexString.length());
        buffer.append(name)
              .append(AT_SIGN)
              .append(hexString);
    }

    
Appends the toString that would be produced by Object if a class did not override toString itself. null will throw a NullPointerException for either of the two parameters. 
ObjectUtils.identityToString(builder, "")            = builder.append("java.lang.String@1e23"
ObjectUtils.identityToString(builder, Boolean.TRUE)  = builder.append("java.lang.Boolean@7fa"
ObjectUtils.identityToString(builder, Boolean.TRUE)  = builder.append("java.lang.Boolean@7fa")

Params:
builder –  the builder to append to
object –  the object to create a toString for
Since:
3.2/**
     * <p>Appends the toString that would be produced by {@code Object}
     * if a class did not override toString itself. {@code null}
     * will throw a NullPointerException for either of the two parameters. </p>
     *
     * <pre>
     * ObjectUtils.identityToString(builder, "")            = builder.append("java.lang.String@1e23"
     * ObjectUtils.identityToString(builder, Boolean.TRUE)  = builder.append("java.lang.Boolean@7fa"
     * ObjectUtils.identityToString(builder, Boolean.TRUE)  = builder.append("java.lang.Boolean@7fa")
     * </pre>
     *
     * @param builder  the builder to append to
     * @param object  the object to create a toString for
     * @since 3.2
     */
    public static void identityToString(final StringBuilder builder, final Object object) {
        Validate.notNull(object, "Cannot get the toString of a null object");
        final String name = object.getClass().getName();
        final String hexString = Integer.toHexString(System.identityHashCode(object));
        builder.ensureCapacity(builder.length() +  name.length() + 1 + hexString.length());
        builder.append(name)
              .append(AT_SIGN)
              .append(hexString);
    }


    // Constants (LANG-816):
    /*
        These methods ensure constants are not inlined by javac.
        For example, typically a developer might declare a constant like so:

            public final static int MAGIC_NUMBER = 5;

        Should a different jar file refer to this, and the MAGIC_NUMBER
        is changed a later date (e.g., MAGIC_NUMBER = 6), the different jar
        file will need to recompile itself.  This is because javac
        typically inlines the primitive or String constant directly into
        the bytecode, and removes the reference to the MAGIC_NUMBER field.

        To help the other jar (so that it does not need to recompile
        when constants are changed) the original developer can declare
        their constant using one of the CONST() utility methods, instead:

            public final static int MAGIC_NUMBER = CONST(5);
     */


    // Empty checks
    //-----------------------------------------------------------------------
    
Checks if an Object is empty or null.
The following types are supported:

CharSequence: Considered empty if its length is zero.
Array: Considered empty if its length is zero.
Collection: Considered empty if it has zero elements.
Map: Considered empty if it has zero key-value mappings.

ObjectUtils.isEmpty(null)             = true
ObjectUtils.isEmpty("")               = true
ObjectUtils.isEmpty("ab")             = false
ObjectUtils.isEmpty(new int[]{})      = true
ObjectUtils.isEmpty(new int[]{1,2,3}) = false
ObjectUtils.isEmpty(1234)             = false

Params:
object –  the Object to test, may be null
Returns:
true if the object has a supported type and is empty or null, false otherwise
Since:
3.9/**
     * <p>Checks if an Object is empty or null.</p>
     *
     * The following types are supported:
     * <ul>
     * <li>{@link CharSequence}: Considered empty if its length is zero.</li>
     * <li>{@code Array}: Considered empty if its length is zero.</li>
     * <li>{@link Collection}: Considered empty if it has zero elements.</li>
     * <li>{@link Map}: Considered empty if it has zero key-value mappings.</li>
     * </ul>
     *
     * <pre>
     * ObjectUtils.isEmpty(null)             = true
     * ObjectUtils.isEmpty("")               = true
     * ObjectUtils.isEmpty("ab")             = false
     * ObjectUtils.isEmpty(new int[]{})      = true
     * ObjectUtils.isEmpty(new int[]{1,2,3}) = false
     * ObjectUtils.isEmpty(1234)             = false
     * </pre>
     *
     * @param object  the {@code Object} to test, may be {@code null}
     * @return {@code true} if the object has a supported type and is empty or null,
     * {@code false} otherwise
     * @since 3.9
     */
    public static boolean isEmpty(final Object object) {
        if (object == null) {
            return true;
        }
        if (object instanceof CharSequence) {
            return ((CharSequence) object).length() == 0;
        }
        if (object.getClass().isArray()) {
            return Array.getLength(object) == 0;
        }
        if (object instanceof Collection<?>) {
            return ((Collection<?>) object).isEmpty();
        }
        if (object instanceof Map<?, ?>) {
            return ((Map<?, ?>) object).isEmpty();
        }
        return false;
    }

    
Checks if an Object is not empty and not null.
The following types are supported:

CharSequence: Considered empty if its length is zero.
Array: Considered empty if its length is zero.
Collection: Considered empty if it has zero elements.
Map: Considered empty if it has zero key-value mappings.

ObjectUtils.isNotEmpty(null)             = false
ObjectUtils.isNotEmpty("")               = false
ObjectUtils.isNotEmpty("ab")             = true
ObjectUtils.isNotEmpty(new int[]{})      = false
ObjectUtils.isNotEmpty(new int[]{1,2,3}) = true
ObjectUtils.isNotEmpty(1234)             = true

Params:
object –  the Object to test, may be null
Returns:
true if the object has an unsupported type or is not empty and not null, false otherwise
Since:
3.9/**
     * <p>Checks if an Object is not empty and not null.</p>
     *
     * The following types are supported:
     * <ul>
     * <li>{@link CharSequence}: Considered empty if its length is zero.</li>
     * <li>{@code Array}: Considered empty if its length is zero.</li>
     * <li>{@link Collection}: Considered empty if it has zero elements.</li>
     * <li>{@link Map}: Considered empty if it has zero key-value mappings.</li>
     * </ul>
     *
     * <pre>
     * ObjectUtils.isNotEmpty(null)             = false
     * ObjectUtils.isNotEmpty("")               = false
     * ObjectUtils.isNotEmpty("ab")             = true
     * ObjectUtils.isNotEmpty(new int[]{})      = false
     * ObjectUtils.isNotEmpty(new int[]{1,2,3}) = true
     * ObjectUtils.isNotEmpty(1234)             = true
     * </pre>
     *
     * @param object  the {@code Object} to test, may be {@code null}
     * @return {@code true} if the object has an unsupported type or is not empty
     * and not null, {@code false} otherwise
     * @since 3.9
     */
    public static boolean isNotEmpty(final Object object) {
        return !isEmpty(object);
    }

    
Null safe comparison of Comparables.
Params:
values – the set of comparable values, may be null
Type parameters:
<T> – type of the values processed by this method
Returns:

 

  
If any objects are non-null and unequal, the greater object.
  
If all objects are non-null and equal, the first.
  
If any of the comparables are null, the greater of the non-null objects.
  
If all the comparables are null, null is returned.
 /**
     * <p>Null safe comparison of Comparables.</p>
     *
     * @param <T> type of the values processed by this method
     * @param values the set of comparable values, may be null
     * @return
     *  <ul>
     *   <li>If any objects are non-null and unequal, the greater object.
     *   <li>If all objects are non-null and equal, the first.
     *   <li>If any of the comparables are null, the greater of the non-null objects.
     *   <li>If all the comparables are null, null is returned.
     *  </ul>
     */
    @SafeVarargs
    public static <T extends Comparable<? super T>> T max(final T... values) {
        T result = null;
        if (values != null) {
            for (final T value : values) {
                if (compare(value, result, false) > 0) {
                    result = value;
                }
            }
        }
        return result;
    }

    
Find the "best guess" middle value among comparables. If there is an even
number of total values, the lower of the two middle values will be returned.
Params:
comparator – to use for comparisons
items – to compare
Type parameters:
<T> – type of values processed by this method
Throws:
NullPointerException – if items or comparator is null
IllegalArgumentException – if items is empty or contains null values
Returns:
T at middle position
Since:
3.0.1/**
     * Find the "best guess" middle value among comparables. If there is an even
     * number of total values, the lower of the two middle values will be returned.
     * @param <T> type of values processed by this method
     * @param comparator to use for comparisons
     * @param items to compare
     * @return T at middle position
     * @throws NullPointerException if items or comparator is {@code null}
     * @throws IllegalArgumentException if items is empty or contains {@code null} values
     * @since 3.0.1
     */
    @SafeVarargs
    public static <T> T median(final Comparator<T> comparator, final T... items) {
        Validate.notEmpty(items, "null/empty items");
        Validate.noNullElements(items);
        Validate.notNull(comparator, "null comparator");
        final TreeSet<T> sort = new TreeSet<>(comparator);
        Collections.addAll(sort, items);
        @SuppressWarnings("unchecked") //we know all items added were T instances
        final
        T result = (T) sort.toArray()[(sort.size() - 1) / 2];
        return result;
    }

    
Find the "best guess" middle value among comparables. If there is an even
number of total values, the lower of the two middle values will be returned.
Params:
items – to compare
Type parameters:
<T> – type of values processed by this method
Throws:
NullPointerException – if items is null
IllegalArgumentException – if items is empty or contains null values
Returns:
T at middle position
Since:
3.0.1/**
     * Find the "best guess" middle value among comparables. If there is an even
     * number of total values, the lower of the two middle values will be returned.
     * @param <T> type of values processed by this method
     * @param items to compare
     * @return T at middle position
     * @throws NullPointerException if items is {@code null}
     * @throws IllegalArgumentException if items is empty or contains {@code null} values
     * @since 3.0.1
     */
    @SafeVarargs
    public static <T extends Comparable<? super T>> T median(final T... items) {
        Validate.notEmpty(items);
        Validate.noNullElements(items);
        final TreeSet<T> sort = new TreeSet<>();
        Collections.addAll(sort, items);
        @SuppressWarnings("unchecked") //we know all items added were T instances
        final T result = (T) sort.toArray()[(sort.size() - 1) / 2];
        return result;
    }

    // Comparable
    //-----------------------------------------------------------------------
    
Null safe comparison of Comparables.
Params:
values – the set of comparable values, may be null
Type parameters:
<T> – type of the values processed by this method
Returns:

 

  
If any objects are non-null and unequal, the lesser object.
  
If all objects are non-null and equal, the first.
  
If any of the comparables are null, the lesser of the non-null objects.
  
If all the comparables are null, null is returned.
 /**
     * <p>Null safe comparison of Comparables.</p>
     *
     * @param <T> type of the values processed by this method
     * @param values the set of comparable values, may be null
     * @return
     *  <ul>
     *   <li>If any objects are non-null and unequal, the lesser object.
     *   <li>If all objects are non-null and equal, the first.
     *   <li>If any of the comparables are null, the lesser of the non-null objects.
     *   <li>If all the comparables are null, null is returned.
     *  </ul>
     */
    @SafeVarargs
    public static <T extends Comparable<? super T>> T min(final T... values) {
        T result = null;
        if (values != null) {
            for (final T value : values) {
                if (compare(value, result, true) < 0) {
                    result = value;
                }
            }
        }
        return result;
    }


    // Mode
    //-----------------------------------------------------------------------
    
Find the most frequently occurring item.
Params:
items – to check
Type parameters:
<T> – type of values processed by this method
Returns:
most populous T, null if non-unique or no items supplied
Since:
3.0.1/**
     * Find the most frequently occurring item.
     *
     * @param <T> type of values processed by this method
     * @param items to check
     * @return most populous T, {@code null} if non-unique or no items supplied
     * @since 3.0.1
     */
    @SafeVarargs
    public static <T> T mode(final T... items) {
        if (ArrayUtils.isNotEmpty(items)) {
            final HashMap<T, MutableInt> occurrences = new HashMap<>(items.length);
            for (final T t : items) {
                final MutableInt count = occurrences.get(t);
                if (count == null) {
                    occurrences.put(t, new MutableInt(1));
                } else {
                    count.increment();
                }
            }
            T result = null;
            int max = 0;
            for (final Map.Entry<T, MutableInt> e : occurrences.entrySet()) {
                final int cmp = e.getValue().intValue();
                if (cmp == max) {
                    result = null;
                } else if (cmp > max) {
                    max = cmp;
                    result = e.getKey();
                }
            }
            return result;
        }
        return null;
    }

    
Compares two objects for inequality, where either one or both objects may be null.
ObjectUtils.notEqual(null, null)                  = false
ObjectUtils.notEqual(null, "")                    = true
ObjectUtils.notEqual("", null)                    = true
ObjectUtils.notEqual("", "")                      = false
ObjectUtils.notEqual(Boolean.TRUE, null)          = true
ObjectUtils.notEqual(Boolean.TRUE, "true")        = true
ObjectUtils.notEqual(Boolean.TRUE, Boolean.TRUE)  = false
ObjectUtils.notEqual(Boolean.TRUE, Boolean.FALSE) = true

Params:
object1 –  the first object, may be null
object2 –  the second object, may be null
Returns:
false if the values of both objects are the same/**
     * <p>Compares two objects for inequality, where either one or both
     * objects may be {@code null}.</p>
     *
     * <pre>
     * ObjectUtils.notEqual(null, null)                  = false
     * ObjectUtils.notEqual(null, "")                    = true
     * ObjectUtils.notEqual("", null)                    = true
     * ObjectUtils.notEqual("", "")                      = false
     * ObjectUtils.notEqual(Boolean.TRUE, null)          = true
     * ObjectUtils.notEqual(Boolean.TRUE, "true")        = true
     * ObjectUtils.notEqual(Boolean.TRUE, Boolean.TRUE)  = false
     * ObjectUtils.notEqual(Boolean.TRUE, Boolean.FALSE) = true
     * </pre>
     *
     * @param object1  the first object, may be {@code null}
     * @param object2  the second object, may be {@code null}
     * @return {@code false} if the values of both objects are the same
     */
    public static boolean notEqual(final Object object1, final Object object2) {
        return !equals(object1, object2);
    }

    // ToString
    //-----------------------------------------------------------------------
    
Gets the toString of an Object returning an empty string ("") if null input.
ObjectUtils.toString(null)         = ""
ObjectUtils.toString("")           = ""
ObjectUtils.toString("bat")        = "bat"
ObjectUtils.toString(Boolean.TRUE) = "true"

Params:
obj –  the Object to toString, may be null
See Also:
StringUtils.defaultString(String)
String.valueOf(Object)
Returns:
the passed in Object's toString, or "" if null input
Since:
2.0
Deprecated:
this method has been replaced by java.util.Objects.toString(Object) in Java 7 and will be removed in future releases. Note however that said method will return "null" for null references, while this method returns an empty String. To preserve behavior use java.util.Objects.toString(myObject, "")/**
     * <p>Gets the {@code toString} of an {@code Object} returning
     * an empty string ("") if {@code null} input.</p>
     *
     * <pre>
     * ObjectUtils.toString(null)         = ""
     * ObjectUtils.toString("")           = ""
     * ObjectUtils.toString("bat")        = "bat"
     * ObjectUtils.toString(Boolean.TRUE) = "true"
     * </pre>
     *
     * @see StringUtils#defaultString(String)
     * @see String#valueOf(Object)
     * @param obj  the Object to {@code toString}, may be null
     * @return the passed in Object's toString, or {@code ""} if {@code null} input
     * @since 2.0
     * @deprecated this method has been replaced by {@code java.util.Objects.toString(Object)} in Java 7 and will be
     * removed in future releases. Note however that said method will return "null" for null references, while this
     * method returns an empty String. To preserve behavior use {@code java.util.Objects.toString(myObject, "")}
     */
    @Deprecated
    public static String toString(final Object obj) {
        return obj == null ? StringUtils.EMPTY : obj.toString();
    }

    
Gets the toString of an Object returning a specified text if null input.
ObjectUtils.toString(null, null)           = null
ObjectUtils.toString(null, "null")         = "null"
ObjectUtils.toString("", "null")           = ""
ObjectUtils.toString("bat", "null")        = "bat"
ObjectUtils.toString(Boolean.TRUE, "null") = "true"

Params:
obj –  the Object to toString, may be null
nullStr –  the String to return if null input, may be null
See Also:
StringUtils.defaultString(String, String)
String.valueOf(Object)
Returns:
the passed in Object's toString, or nullStr if null input
Since:
2.0
Deprecated:
this method has been replaced by java.util.Objects.toString(Object, String) in Java 7 and will be removed in future releases./**
     * <p>Gets the {@code toString} of an {@code Object} returning
     * a specified text if {@code null} input.</p>
     *
     * <pre>
     * ObjectUtils.toString(null, null)           = null
     * ObjectUtils.toString(null, "null")         = "null"
     * ObjectUtils.toString("", "null")           = ""
     * ObjectUtils.toString("bat", "null")        = "bat"
     * ObjectUtils.toString(Boolean.TRUE, "null") = "true"
     * </pre>
     *
     * @see StringUtils#defaultString(String,String)
     * @see String#valueOf(Object)
     * @param obj  the Object to {@code toString}, may be null
     * @param nullStr  the String to return if {@code null} input, may be null
     * @return the passed in Object's toString, or {@code nullStr} if {@code null} input
     * @since 2.0
     * @deprecated this method has been replaced by {@code java.util.Objects.toString(Object, String)} in Java 7 and
     * will be removed in future releases.
     */
    @Deprecated
    public static String toString(final Object obj, final String nullStr) {
        return obj == null ? nullStr : obj.toString();
    }

    
Gets the toString of an Object returning a specified text if null input.
ObjectUtils.toString(obj, () -> expensive())

ObjectUtils.toString(null, () -> expensive())         = result of expensive()
ObjectUtils.toString(null, () -> expensive())         = result of expensive()
ObjectUtils.toString("", () -> expensive())           = ""
ObjectUtils.toString("bat", () -> expensive())        = "bat"
ObjectUtils.toString(Boolean.TRUE, () -> expensive()) = "true"

Params:
obj –  the Object to toString, may be null
supplier –  the Supplier of String used on null input, may be null
Returns:
the passed in Object's toString, or nullStr if null input
Since:
3.11/**
     * <p>Gets the {@code toString} of an {@code Object} returning
     * a specified text if {@code null} input.</p>
     *
     * <pre>
     * ObjectUtils.toString(obj, () -&gt; expensive())
     * </pre>
     * <pre>
     * ObjectUtils.toString(null, () -&gt; expensive())         = result of expensive()
     * ObjectUtils.toString(null, () -&gt; expensive())         = result of expensive()
     * ObjectUtils.toString("", () -&gt; expensive())           = ""
     * ObjectUtils.toString("bat", () -&gt; expensive())        = "bat"
     * ObjectUtils.toString(Boolean.TRUE, () -&gt; expensive()) = "true"
     * </pre>
     *
     * @param obj  the Object to {@code toString}, may be null
     * @param supplier  the Supplier of String used on {@code null} input, may be null
     * @return the passed in Object's toString, or {@code nullStr} if {@code null} input
     * @since 3.11
     */
    public static String toString(final Object obj, final Supplier<String> supplier) {
        return obj == null ? supplier == null ? null : supplier.get() : obj.toString();
    }

    
ObjectUtils instances should NOT be constructed in standard programming. Instead, the static methods on the class should be used, such as ObjectUtils.defaultIfNull("a","b");.
This constructor is public to permit tools that require a JavaBean
instance to operate.
/**
     * <p>{@code ObjectUtils} instances should NOT be constructed in
     * standard programming. Instead, the static methods on the class should
     * be used, such as {@code ObjectUtils.defaultIfNull("a","b");}.</p>
     *
     * <p>This constructor is public to permit tools that require a JavaBean
     * instance to operate.</p>
     */
    public ObjectUtils() {
        super();
    }

}