• Home
• com.landawn
• abacus-common
• 5.8.8
• source code
• Iterables.java

×

Project download

Many resources are needed to download a project. Please understand that we have to compensate our server costs. Thank you in advance.
Project price only 1 $

You can buy this project and download/modify it how often you want.

com.landawn.abacus.util.Iterables Maven / Gradle / Ivy

/*
 * Copyright (c) 2018, Haiyang Li.
 *
 * Licensed 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
 *
 * https://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 com.landawn.abacus.util;

import java.math.BigDecimal;
import java.math.BigInteger;
import java.util.AbstractCollection;
import java.util.AbstractList;
import java.util.AbstractSet;
import java.util.ArrayList;
import java.util.Arrays;
import java.util.Collection;
import java.util.Collections;
import java.util.Comparator;
import java.util.HashSet;
import java.util.Iterator;
import java.util.LinkedHashMap;
import java.util.List;
import java.util.ListIterator;
import java.util.Map;
import java.util.NavigableSet;
import java.util.NoSuchElementException;
import java.util.RandomAccess;
import java.util.Set;
import java.util.TreeSet;
import java.util.function.Function;
import java.util.function.IntFunction;
import java.util.function.Predicate;
import java.util.function.Supplier;
import java.util.function.ToDoubleFunction;
import java.util.function.ToIntFunction;
import java.util.function.ToLongFunction;
import java.util.function.UnaryOperator;

import com.landawn.abacus.annotation.Beta;
import com.landawn.abacus.annotation.SuppressFBWarnings;
import com.landawn.abacus.util.Range.BoundType;
import com.landawn.abacus.util.u.Nullable;
import com.landawn.abacus.util.u.Optional;
import com.landawn.abacus.util.u.OptionalByte;
import com.landawn.abacus.util.u.OptionalChar;
import com.landawn.abacus.util.u.OptionalDouble;
import com.landawn.abacus.util.u.OptionalFloat;
import com.landawn.abacus.util.u.OptionalInt;
import com.landawn.abacus.util.u.OptionalLong;
import com.landawn.abacus.util.u.OptionalShort;

/**
 * 

 * Note: This class includes codes copied from Apache Commons Lang, Google Guava and other open source projects under the Apache License 2.0.
 * The methods copied from other libraries/frameworks/projects may be modified in this class.
 * 
 *
 *
 * 

 * When to throw exception? It's designed to avoid throwing any unnecessary
 * exception if the contract defined by method is not broken. For example, if
 * user tries to reverse a {@code null} or empty String. The input String will be
 * returned. But exception will be thrown if try to add an element to a {@code null} Object array or collection.
 *
 * 

 * An empty String/Array/Collection/Map/Iterator/Iterable/InputStream/Reader will always be a preferred choice than a {@code null} for the return value of a method.
 *
 * 

 * The methods in this class should only read the input {@code Collection/Array/Iterator} parameters, not modify them.
 *
 * 

 * The input parameters of most methods in this class should be {@code Iterable/Array}, instead of {@code Collection/Array}.
 * The returned type of most methods in this class should be a type of {@code Optional}, instead of element type of the input {@code Collection/Array}.
 * This class is a utility class, which is designed to extend the methods in {@code CommonUtil/N} class for handling empty input {@code Collection/Array/Iterator/Iterable} parameters or result.
 * 
 *
 * @see com.landawn.abacus.util.Comparators
 * @see com.landawn.abacus.util.Fn
 * @see com.landawn.abacus.util.Fn.Fnn
 * @see com.landawn.abacus.util.Array
 * @see com.landawn.abacus.util.CommonUtil
 * @see com.landawn.abacus.util.N
 * @see com.landawn.abacus.util.Iterators
 * @see com.landawn.abacus.util.Index
 * @see com.landawn.abacus.util.Median
 * @see com.landawn.abacus.util.Maps
 * @see com.landawn.abacus.util.Strings
 * @see com.landawn.abacus.util.Numbers
 * @see com.landawn.abacus.util.IOUtil
 * @see java.lang.reflect.Array
 * @see java.util.Arrays
 * @see java.util.Collections
 */
public final class Iterables {

    private Iterables() {
        // Utility class.
    }

    /**
     * Returns the minimum value from the provided array of characters.
     * If the array is {@code null} or empty, it returns an empty {@code OptionalChar}.
     *
     * @param a the array of characters to evaluate
     * @return an {@code OptionalChar} containing the minimum value if the array is not {@code null} or empty, otherwise an empty {@code OptionalChar}
     * @see N#min(char...)
     */
    public static OptionalChar min(final char... a) {
        return a == null || a.length == 0 ? OptionalChar.empty() : OptionalChar.of(N.min(a));
    }

    /**
     * Returns the minimum value from the provided array of bytes.
     * If the array is {@code null} or empty, it returns an empty {@code OptionalByte}.
     *
     * @param a the array of bytes to evaluate
     * @return an {@code OptionalByte} containing the minimum value if the array is not {@code null} or empty, otherwise an empty {@code OptionalByte}
     * @see N#min(byte...)
     */
    public static OptionalByte min(final byte... a) {
        return a == null || a.length == 0 ? OptionalByte.empty() : OptionalByte.of(N.min(a));
    }

    /**
     * Returns the minimum value from the provided array of shorts.
     * If the array is {@code null} or empty, it returns an empty {@code OptionalShort}.
     *
     * @param a the array of shorts to evaluate
     * @return an {@code OptionalShort} containing the minimum value if the array is not {@code null} or empty, otherwise an empty {@code OptionalShort}
     * @see N#min(short...)
     */
    public static OptionalShort min(final short... a) {
        return a == null || a.length == 0 ? OptionalShort.empty() : OptionalShort.of(N.min(a));
    }

    /**
     * Returns the minimum value from the provided array of integers.
     * If the array is {@code null} or empty, it returns an empty {@code OptionalInt}.
     *
     * @param a the array of integers to evaluate
     * @return an  {@code OptionalInt} containing the minimum value if the array is not {@code null} or empty, otherwise an empty {@code OptionalInt}
     * @see N#min(int...)
     */
    public static OptionalInt min(final int... a) {
        return a == null || a.length == 0 ? OptionalInt.empty() : OptionalInt.of(N.min(a));
    }

    /**
     * Returns the minimum value from the provided array of longs.
     * If the array is {@code null} or empty, it returns an empty {@code OptionalLong}.
     *
     * @param a the array of longs to evaluate
     * @return an {@code OptionalLong} containing the minimum value if the array is not {@code null} or empty, otherwise an empty {@code OptionalLong}
     * @see N#min(long...)
     */
    public static OptionalLong min(final long... a) {
        return a == null || a.length == 0 ? OptionalLong.empty() : OptionalLong.of(N.min(a));
    }

    /**
     * Returns the minimum value from the provided array of floats.
     * If the array is {@code null} or empty, it returns an empty {@code OptionalFloat}.
     *
     * @param a the array of floats to evaluate
     * @return an {@code OptionalFloat} containing the minimum value if the array is not {@code null} or empty, otherwise an empty {@code OptionalFloat}
     * @see N#min(float...)
     */
    public static OptionalFloat min(final float... a) {
        return a == null || a.length == 0 ? OptionalFloat.empty() : OptionalFloat.of(N.min(a));
    }

    /**
     * Returns the minimum value from the provided array of doubles.
     * If the array is {@code null} or empty, it returns an empty {@code OptionalDouble}.
     *
     * @param a the array of doubles to evaluate
     * @return an {@code OptionalDouble} containing the minimum value if the array is not {@code null} or empty, otherwise an empty {@code OptionalDouble}
     * @see N#min(double...)
     */
    public static OptionalDouble min(final double... a) {
        return a == null || a.length == 0 ? OptionalDouble.empty() : OptionalDouble.of(N.min(a));
    }

    /**
     * Returns the minimum value from the provided array of elements based on their natural ordering.
     * Null values are considered to be maximum value.
     * If the array is {@code null} or empty, it returns an empty {@code Nullable}.
     *
     * @param a the array of elements to evaluate
     * @return a {@code Nullable} containing the minimum value if the array is not {@code null} or empty, otherwise an empty {@code Nullable}
     * @see N#min(Comparable...)
     */
    public static > Nullable min(final T[] a) {
        return N.isEmpty(a) ? Nullable.empty() : Nullable.of(N.min(a));
    }

    /**
     * Returns the minimum value from the provided array of elements according to the provided comparator.
     * If the array is {@code null} or empty, it returns an empty {@code Nullable}.
     *
     * @param a the array of elements to evaluate
     * @param cmp the comparator to determine the order of the elements
     * @return a {@code Nullable} containing the minimum value if the array is not {@code null} or empty, otherwise an empty {@code Nullable}
     * @see N#min(Object[], Comparator)
     */
    public static  Nullable min(final T[] a, final Comparator cmp) {
        return N.isEmpty(a) ? Nullable.empty() : Nullable.of(N.min(a, cmp));
    }

    /**
     * Returns the minimum value from the provided iterable of elements based on their natural ordering.
     * Null values are considered to be maximum value.
     * If the iterable is {@code null} or empty, it returns an empty {@code Nullable}.
     *
     * @param c the iterable of elements to evaluate
     * @return a {@code Nullable} containing the minimum value if the iterable is not {@code null} or empty, otherwise an empty {@code Nullable}
     * @see N#min(Iterable)
     */
    public static > Nullable min(final Iterable c) {
        return min(c, N.NULL_MAX_COMPARATOR);
    }

    /**
     * Returns the minimum value from the provided iterable of elements according to the provided comparator.
     * If the iterable is {@code null} or empty, it returns an empty {@code Nullable}.
     *
     * @param c the iterable of elements to
     * @param cmp the comparator to determine the order of the elements
     * @return a {@code Nullable} containing the minimum value if the iterable is not {@code null} or empty, otherwise an empty {@code Nullable}
     * @see N#min(Iterable, Comparator)
     */
    public static  Nullable min(final Iterable c, final Comparator cmp) {
        return c == null ? Nullable.empty() : min(c.iterator(), cmp);
    }

    /**
     * Returns the minimum value from the provided iterator of elements based on their natural ordering.
     * Null values are considered to be maximum value.
     * If the iterator is {@code null} or empty, it returns an empty {@code Nullable}.
     *
     * @param iter the iterator of elements to evaluate
     * @return a {@code Nullable} containing the minimum value if the iterator is not {@code null} or empty, otherwise an empty {@code Nullable}
     * @see N#min(Iterator)
     */
    public static > Nullable min(final Iterator iter) {
        return min(iter, N.NULL_MAX_COMPARATOR);
    }

    /**
     * Returns the minimum value from the provided iterator of elements according to the provided comparator.
     * If the iterator is {@code null} or empty, it returns an empty {@code Nullable}.
     *
     * @param iter the iterator of elements to evaluate
     * @param cmp the comparator to determine the order of the elements
     * @return a {@code Nullable} containing the minimum value if the iterator is not {@code null} or empty, otherwise an empty {@code Nullable}
     * @see N#min(Iterator, Comparator)
     */
    @SuppressFBWarnings("NP_LOAD_OF_KNOWN_NULL_VALUE")
    public static  Nullable min(final Iterator iter, Comparator cmp) {
        cmp = cmp == null ? (Comparator) N.NULL_MAX_COMPARATOR : cmp;
        final boolean isNullMinComparator = cmp == N.NULL_MIN_COMPARATOR;

        if (iter == null || !iter.hasNext()) {
            return Nullable.empty();
        }

        T candidate = null;
        T next = null;

        do {
            next = iter.next();

            if (isNullMinComparator && next == null) { // NOSONAR
                //noinspection ConstantValue
                return Nullable.of(next);
            } else if (cmp.compare(next, candidate) < 0) {
                candidate = next;
            }
        } while (iter.hasNext());

        return Nullable.of(candidate);
    }

    /**
     * Returns the minimum value from the provided array of elements according to the key extracted by the {@code keyExtractor} function.
     * Null values are considered to be maximum value.
     * If the array is {@code null} or empty, it returns an empty {@code Nullable}.
     *
     * @param a the array of elements to evaluate
     * @param keyExtractor the function to transform the elements into a comparable type for comparison
     * @return a {@code Nullable} containing the minimum value if the array is not {@code null} or empty, otherwise an empty {@code Nullable}
     * @see N#min(Object[], Comparator)
     */
    @SuppressWarnings("rawtypes")
    public static  Nullable minBy(final T[] a, final Function keyExtractor) {
        return min(a, Comparators.nullsLastBy(keyExtractor));
    }

    /**
     * Returns the minimum value from the provided array of elements according to the key extracted by the {@code keyExtractor} function.
     * Null values are considered to be maximum value.
     * If the iterable is {@code null} or empty, it returns an empty {@code Nullable}.
     *
     * @param c the iterable of elements to evaluate
     * @param keyExtractor the function to transform the elements into a comparable type for comparison
     * @return a {@code Nullable} containing the minimum value if the iterable is not {@code null} or empty, otherwise an empty {@code Nullable}
     * @see N#min(Iterable, Comparator)
     */
    @SuppressWarnings("rawtypes")
    public static  Nullable minBy(final Iterable c, final Function keyExtractor) {
        return min(c, Comparators.nullsLastBy(keyExtractor));
    }

    /**
     * Returns the minimum value from the provided array of elements according to the key extracted by the {@code keyExtractor} function.
     * Null values are considered to be maximum value.
     * If the iterator is {@code null} or empty, it returns an empty {@code Nullable}.
     *
     * @param iter the iterator of elements to evaluate
     * @param keyExtractor the function to transform the elements into a comparable type for comparison
     * @return a {@code Nullable} containing the minimum value if the iterator is not {@code null} or empty, otherwise an empty {@code Nullable}
     * @see N#min(Iterator, Comparator)
     */
    @SuppressWarnings("rawtypes")
    public static  Nullable minBy(final Iterator iter, final Function keyExtractor) {
        return min(iter, Comparators.nullsLastBy(keyExtractor));
    }

    /**
     * Returns the minimum integer value extracted from the elements in the provided array by the input {@code valueExtractor} function.
     * If the array is {@code null} or empty, it returns an empty {@code OptionalInt}.
     *
     * @param  the type of the elements in the array
     * @param a the array of elements to evaluate
     * @param valueExtractor the function to extract an integer value from each element
     * @return an {@code OptionalInt} containing the minimum value if the array is not {@code null} or empty, otherwise an empty {@code OptionalInt}
     * @see N#minIntOrDefaultIfEmpty(Object[], ToIntFunction, int)
     */
    @Beta
    public static  OptionalInt minInt(final T[] a, final ToIntFunction valueExtractor) {
        if (N.isEmpty(a)) {
            return OptionalInt.empty();
        }

        int candidate = valueExtractor.applyAsInt(a[0]);
        int next = 0;

        for (int i = 1, len = a.length; i < len; i++) {
            next = valueExtractor.applyAsInt(a[i]);

            if (next < candidate) {
                candidate = next;
            }
        }

        return OptionalInt.of(candidate);
    }

    /**
     * Returns the minimum integer value extracted from the elements in the provided iterable by the input {@code valueExtractor} function.
     * If the iterable is {@code null} or empty, it returns an empty {@code OptionalInt}.
     *
     * @param  the type of the elements in the iterable
     * @param c the iterable of elements to evaluate
     * @param valueExtractor the function to extract an integer value from each element
     * @return an {@code OptionalInt} containing the minimum value if the iterable is not {@code null} or empty, otherwise an empty {@code OptionalInt}
     * @see N#minIntOrDefaultIfEmpty(Iterable, ToIntFunction, int)
     */
    @Beta
    public static  OptionalInt minInt(final Iterable c, final ToIntFunction valueExtractor) {
        if (c == null) {
            return OptionalInt.empty();
        }

        return minInt(c.iterator(), valueExtractor);
    }

    /**
     * Returns the minimum integer value extracted from the elements in the provided iterator by the input {@code valueExtractor} function.
     * If the iterator is {@code null} or empty, it returns an empty {@code OptionalInt}.
     *
     * @param  the type of the elements in the iterator
     * @param iter the iterator of elements to evaluate
     * @param valueExtractor the function to extract an integer value from each element
     * @return an {@code OptionalInt} containing the minimum value if the iterator is not {@code null} or empty, otherwise an empty {@code OptionalInt}
     * @see N#minIntOrDefaultIfEmpty(Iterator, ToIntFunction, int)
     */
    @Beta
    public static  OptionalInt minInt(final Iterator iter, final ToIntFunction valueExtractor) {
        if (iter == null || !iter.hasNext()) {
            return OptionalInt.empty();
        }

        int candidate = valueExtractor.applyAsInt(iter.next());
        int next = 0;

        while (iter.hasNext()) {
            next = valueExtractor.applyAsInt(iter.next());

            if (next < candidate) {
                candidate = next;
            }
        }

        return OptionalInt.of(candidate);
    }

    /**
     * Returns the minimum long value extracted from the elements in the provided array by the input {@code valueExtractor} function.
     * If the array is {@code null} or empty, it returns an empty {@code OptionalLong}.
     *
     * @param  the type of the elements in the array
     * @param a the array of elements to evaluate
     * @param valueExtractor the function to extract a long value from each element
     * @return an {@code OptionalLong} containing the minimum value if the array is not {@code null} or empty, otherwise an empty {@code OptionalLong}
     * @see N#minLongOrDefaultIfEmpty(Object[], ToLongFunction, long)
     */
    @Beta
    public static  OptionalLong minLong(final T[] a, final ToLongFunction valueExtractor) {
        if (N.isEmpty(a)) {
            return OptionalLong.empty();
        }

        long candidate = valueExtractor.applyAsLong(a[0]);
        long next = 0;

        for (int i = 1, len = a.length; i < len; i++) {
            next = valueExtractor.applyAsLong(a[i]);

            if (next < candidate) {
                candidate = next;
            }
        }

        return OptionalLong.of(candidate);
    }

    /**
     * Returns the minimum long value extracted from the elements in the provided iterable by the input {@code valueExtractor} function.
     * If the iterable is {@code null} or empty, it returns an empty {@code OptionalLong}.
     *
     * @param  the type of the elements in the iterable
     * @param c the iterable of elements to evaluate
     * @param valueExtractor the function to extract a long value from each element
     * @return an {@code OptionalLong} containing the minimum value if the iterable is not {@code null} or empty, otherwise an empty {@code OptionalLong}
     * @see N#minLongOrDefaultIfEmpty(Iterable, ToLongFunction, long)
     */
    @Beta
    public static  OptionalLong minLong(final Iterable c, final ToLongFunction valueExtractor) {
        if (c == null) {
            return OptionalLong.empty();
        }

        return minLong(c.iterator(), valueExtractor);
    }

    /**
     * Returns the minimum long value extracted from the elements in the provided iterator by the input {@code valueExtractor} function.
     * If the iterator is {@code null} or empty, it returns an empty {@code OptionalLong}.
     *
     * @param  the type of the elements in the iterator
     * @param iter the iterator of elements to evaluate
     * @param valueExtractor the function to extract a long value from each element
     * @return an {@code OptionalLong} containing the minimum value if the iterator is not {@code null} or empty, otherwise an empty {@code OptionalLong}
     * @see N#minLongOrDefaultIfEmpty(Iterator, ToLongFunction, long)
     */
    @Beta
    public static  OptionalLong minLong(final Iterator iter, final ToLongFunction valueExtractor) {
        if (iter == null || !iter.hasNext()) {
            return OptionalLong.empty();
        }

        long candidate = valueExtractor.applyAsLong(iter.next());
        long next = 0;

        while (iter.hasNext()) {
            next = valueExtractor.applyAsLong(iter.next());

            if (next < candidate) {
                candidate = next;
            }
        }

        return OptionalLong.of(candidate);
    }

    /**
     * Returns the minimum double value extracted from the elements in the provided array by the input {@code valueExtractor} function.
     * If the array is {@code null} or empty, it returns an empty {@code OptionalDouble}.
     *
     * @param  the type of the elements in the array
     * @param a the array of elements to evaluate
     * @param valueExtractor the function to extract a double value from each element
     * @return an {@code OptionalDouble} containing the minimum value if the array is not {@code null} or empty, otherwise an empty {@code OptionalDouble}
     * @see N#minDoubleOrDefaultIfEmpty(Object[], ToDoubleFunction, double)
     */
    @Beta
    public static  OptionalDouble minDouble(final T[] a, final ToDoubleFunction valueExtractor) {
        if (N.isEmpty(a)) {
            return OptionalDouble.empty();
        }

        double candidate = valueExtractor.applyAsDouble(a[0]);
        double next = 0;

        for (int i = 1, len = a.length; i < len; i++) {
            next = valueExtractor.applyAsDouble(a[i]);

            if (N.compare(next, candidate) < 0) {
                candidate = next;
            }
        }

        return OptionalDouble.of(candidate);
    }

    /**
     * Returns the minimum double value extracted from the elements in the provided iterable by the input {@code valueExtractor} function.
     * If the iterable is {@code null} or empty, it returns an empty {@code OptionalDouble}.
     *
     * @param  the type of the elements in the iterable
     * @param c the iterable of elements to evaluate
     * @param valueExtractor the function to extract a double value from each element
     * @return an {@code OptionalDouble} containing the minimum value if the iterable is not {@code null} or empty, otherwise an empty {@code OptionalDouble}
     * @see N#minDoubleOrDefaultIfEmpty(Iterable, ToDoubleFunction, double)
     */
    @Beta
    public static  OptionalDouble minDouble(final Iterable c, final ToDoubleFunction valueExtractor) {
        if (c == null) {
            return OptionalDouble.empty();
        }

        return minDouble(c.iterator(), valueExtractor);
    }

    /**
     * Returns the minimum double value extracted from the elements in the provided iterator by the input {@code valueExtractor} function.
     * If the iterator is {@code null} or empty, it returns an empty {@code OptionalDouble}.
     *
     * @param  the type of the elements in the iterator
     * @param iter the iterator of elements to evaluate
     * @param valueExtractor the function to extract a double value from each element
     * @return an {@code OptionalDouble} containing the minimum value if the iterator is not {@code null} or empty, otherwise an empty {@code OptionalDouble}
     * @see N#minDoubleOrDefaultIfEmpty(Iterator, ToDoubleFunction, double)
     */
    @Beta
    public static  OptionalDouble minDouble(final Iterator iter, final ToDoubleFunction valueExtractor) {
        if (iter == null || !iter.hasNext()) {
            return OptionalDouble.empty();
        }

        double candidate = valueExtractor.applyAsDouble(iter.next());
        double next = 0;

        while (iter.hasNext()) {
            next = valueExtractor.applyAsDouble(iter.next());

            if (N.compare(next, candidate) < 0) {
                candidate = next;
            }
        }

        return OptionalDouble.of(candidate);
    }

    /**
     * Returns the maximum value from the provided array of characters.
     * If the array is {@code null} or empty, it returns an empty {@code OptionalChar}.
     *
     * @param a the array of characters to evaluate
     * @return an {@code OptionalChar} containing the maximum value if the array is not {@code null} or empty, otherwise an empty {@code OptionalChar}
     * @see N#max(char...)
     */
    public static OptionalChar max(final char... a) {
        return a == null || a.length == 0 ? OptionalChar.empty() : OptionalChar.of(N.max(a));
    }

    /**
     * Returns the maximum value from the provided array of bytes.
     * If the array is {@code null} or empty, it returns an empty {@code OptionalByte}.
     *
     * @param a the array of bytes to evaluate
     * @return an {@code OptionalByte} containing the maximum value if the array is not {@code null} or empty, otherwise an empty {@code OptionalByte}
     * @see N#max(byte...)
     */
    public static OptionalByte max(final byte... a) {
        return a == null || a.length == 0 ? OptionalByte.empty() : OptionalByte.of(N.max(a));
    }

    /**
     * Returns the maximum value from the provided array of shorts.
     * If the array is {@code null} or empty, it returns an empty {@code OptionalShort}.
     *
     * @param a the array of shorts to evaluate
     * @return an {@code OptionalShort} containing the maximum value if the array is not {@code null} or empty, otherwise an empty {@code OptionalShort}
     * @see N#max(short...)
     */
    public static OptionalShort max(final short... a) {
        return a == null || a.length == 0 ? OptionalShort.empty() : OptionalShort.of(N.max(a));
    }

    /**
     * Returns the maximum value from the provided array of integers.
     * If the array is {@code null} or empty, it returns an empty {@code OptionalInt}.
     *
     * @param a the array of integers to evaluate
     * @return an  {@code OptionalInt} containing the maximum value if the array is not {@code null} or empty, otherwise an empty {@code OptionalInt}
     * @see N#max(int...)
     */
    public static OptionalInt max(final int... a) {
        return a == null || a.length == 0 ? OptionalInt.empty() : OptionalInt.of(N.max(a));
    }

    /**
     * Returns the maximum value from the provided array of longs.
     * If the array is {@code null} or empty, it returns an empty {@code OptionalLong}.
     *
     * @param a the array of longs to evaluate
     * @return an {@code OptionalLong} containing the maximum value if the array is not {@code null} or empty, otherwise an empty {@code OptionalLong}
     * @see N#max(long...)
     */
    public static OptionalLong max(final long... a) {
        return a == null || a.length == 0 ? OptionalLong.empty() : OptionalLong.of(N.max(a));
    }

    /**
     * Returns the maximum value from the provided array of floats.
     * If the array is {@code null} or empty, it returns an empty {@code OptionalFloat}.
     *
     * @param a the array of floats to evaluate
     * @return an {@code OptionalFloat} containing the maximum value if the array is not {@code null} or empty, otherwise an empty {@code OptionalFloat}
     * @see N#max(float...)
     */
    public static OptionalFloat max(final float... a) {
        return a == null || a.length == 0 ? OptionalFloat.empty() : OptionalFloat.of(N.max(a));
    }

    /**
     * Returns the maximum value from the provided array of doubles.
     * If the array is {@code null} or empty, it returns an empty {@code OptionalDouble}.
     *
     * @param a the array of doubles to evaluate
     * @return an {@code OptionalDouble} containing the maximum value if the array is not {@code null} or empty, otherwise an empty {@code OptionalDouble}
     * @see N#max(double...)
     */
    public static OptionalDouble max(final double... a) {
        return a == null || a.length == 0 ? OptionalDouble.empty() : OptionalDouble.of(N.max(a));
    }

    /**
     * Returns the maximum value from the provided array of elements based on their natural ordering.
     * Null values are considered to be minimum
     * If the array is {@code null} or empty, it returns an empty {@code Nullable}.
     *
     * @param a the array of elements to evaluate
     * @return a {@code Nullable} containing the maximum value if the array is not {@code null} or empty, otherwise an empty {@code Nullable}
     * @see N#max(Comparable...)
     */
    public static > Nullable max(final T[] a) {
        return N.isEmpty(a) ? Nullable.empty() : Nullable.of(N.max(a));
    }

    /**
     * Returns the maximum value from the provided array of elements according to the provided comparator.
     * If the array is {@code null} or empty, it returns an empty {@code Nullable}.
     *
     * @param a the array of elements to evaluate
     * @param cmp the comparator to determine the order of the elements
     * @return a {@code Nullable} containing the maximum value if the array is not {@code null} or empty, otherwise an empty {@code Nullable}
     * @see N#max(Object[], Comparator)
     */
    public static  Nullable max(final T[] a, final Comparator cmp) {
        return N.isEmpty(a) ? Nullable.empty() : Nullable.of(N.max(a, cmp));
    }

    /**
     * Returns the maximum value from the provided iterable of elements based on their natural ordering.
     * Null values are considered to be minimum
     * If the iterable is {@code null} or empty, it returns an empty {@code Nullable}.
     *
     * @param c the iterable of elements to evaluate
     * @return a {@code Nullable} containing the maximum value if the iterable is not {@code null} or empty, otherwise an empty {@code Nullable}
     * @see N#max(Iterable)
     */
    public static > Nullable max(final Iterable c) {
        return max(c, N.NULL_MIN_COMPARATOR);
    }

    /**
     * Returns the maximum value from the provided iterable of elements according to the provided comparator.
     * If the iterable is {@code null} or empty, it returns an empty {@code Nullable}.
     *
     * @param c the iterable of elements to
     * @param cmp the comparator to determine the order of the elements
     * @return a {@code Nullable} containing the maximum value if the iterable is not {@code null} or empty, otherwise an empty {@code Nullable}
     * @see N#max(Iterable, Comparator)
     */
    public static  Nullable max(final Iterable c, final Comparator cmp) {
        return c == null ? Nullable.empty() : max(c.iterator(), cmp);
    }

    /**
     * Returns the maximum value from the provided iterator of elements based on their natural ordering.
     * Null values are considered to be minimum
     * If the iterator is {@code null} or empty, it returns an empty {@code Nullable}.
     *
     * @param iter the iterator of elements to evaluate
     * @return a {@code Nullable} containing the maximum value if the iterator is not {@code null} or empty, otherwise an empty {@code Nullable}
     * @see N#max(Iterator)
     */
    public static > Nullable max(final Iterator iter) {
        return max(iter, N.NULL_MIN_COMPARATOR);
    }

    /**
     * Returns the maximum value from the provided iterator of elements according to the provided comparator.
     * If the iterator is {@code null} or empty, it returns an empty {@code Nullable}.
     *
     * @param iter the iterator of elements to evaluate
     * @param cmp the comparator to determine the order of the elements
     * @return a {@code Nullable} containing the maximum value if the iterator is not {@code null} or empty, otherwise an empty {@code Nullable}
     * @see N#max(Iterator, Comparator)
     */
    @SuppressFBWarnings("NP_LOAD_OF_KNOWN_NULL_VALUE")
    public static  Nullable max(final Iterator iter, Comparator cmp) {
        cmp = cmp == null ? (Comparator) N.NULL_MIN_COMPARATOR : cmp;
        final boolean isNullMaxComparator = cmp == N.NULL_MAX_COMPARATOR;

        if (iter == null || !iter.hasNext()) {
            return Nullable.empty();
        }

        T candidate = null;
        T next = null;

        do {
            next = iter.next();

            if (isNullMaxComparator && next == null) { // NOSONAR
                //noinspection ConstantValue
                return Nullable.of(next);
            } else if (cmp.compare(next, candidate) > 0) {
                candidate = next;
            }
        } while (iter.hasNext());

        return Nullable.of(candidate);
    }

    /**
     * Returns the maximum value from the provided array of elements according to the key extracted by the {@code keyExtractor} function.
     * Null values are considered to be minimum
     * If the array is {@code null} or empty, it returns an empty {@code Nullable}.
     *
     * @param a the array of elements to evaluate
     * @param keyExtractor the function to transform the elements into a comparable type for comparison
     * @return a {@code Nullable} containing the maximum value if the array is not {@code null} or empty, otherwise an empty {@code Nullable}
     * @see N#max(Object[], Comparator)
     */
    @SuppressWarnings("rawtypes")
    public static  Nullable maxBy(final T[] a, final Function keyExtractor) {
        return max(a, Comparators.nullsFirstBy(keyExtractor));
    }

    /**
     * Returns the maximum value from the provided array of elements according to the key extracted by the {@code keyExtractor} function.
     * Null values are considered to be minimum
     * If the iterable is {@code null} or empty, it returns an empty {@code Nullable}.
     *
     * @param c the iterable of elements to evaluate
     * @param keyExtractor the function to transform the elements into a comparable type for comparison
     * @return a {@code Nullable} containing the maximum value if the iterable is not {@code null} or empty, otherwise an empty {@code Nullable}
     * @see N#max(Iterable, Comparator)
     */
    @SuppressWarnings("rawtypes")
    public static  Nullable maxBy(final Iterable c, final Function keyExtractor) {
        return max(c, Comparators.nullsFirstBy(keyExtractor));
    }

    /**
     * Returns the maximum value from the provided array of elements according to the key extracted by the {@code keyExtractor} function.
     * Null values are considered to be minimum
     * If the iterator is {@code null} or empty, it returns an empty {@code Nullable}.
     *
     * @param iter the iterator of elements to evaluate
     * @param keyExtractor the function to transform the elements into a comparable type for comparison
     * @return a {@code Nullable} containing the maximum value if the iterator is not {@code null} or empty, otherwise an empty {@code Nullable}
     * @see N#max(Iterator, Comparator)
     */
    @SuppressWarnings("rawtypes")
    public static  Nullable maxBy(final Iterator iter, final Function keyExtractor) {
        return max(iter, Comparators.nullsFirstBy(keyExtractor));
    }

    /**
     * Returns the maximum integer value extracted from the elements in the provided array by the input {@code valueExtractor} function.
     * If the array is {@code null} or empty, it returns an empty {@code OptionalInt}.
     *
     * @param  the type of the elements in the array
     * @param a the array of elements to evaluate
     * @param valueExtractor the function to extract an integer value from each element
     * @return an {@code OptionalInt} containing the maximum value if the array is not {@code null} or empty, otherwise an empty {@code OptionalInt}
     * @see N#maxIntOrDefaultIfEmpty(Object[], ToIntFunction, int)
     */
    @Beta
    public static  OptionalInt maxInt(final T[] a, final ToIntFunction valueExtractor) {
        if (N.isEmpty(a)) {
            return OptionalInt.empty();
        }

        int candidate = valueExtractor.applyAsInt(a[0]);
        int next = 0;

        for (int i = 1, len = a.length; i < len; i++) {
            next = valueExtractor.applyAsInt(a[i]);

            if (next > candidate) {
                candidate = next;
            }
        }

        return OptionalInt.of(candidate);
    }

    /**
     * Returns the maximum integer value extracted from the elements in the provided iterable by the input {@code valueExtractor} function.
     * If the iterable is {@code null} or empty, it returns an empty {@code OptionalInt}.
     *
     * @param  the type of the elements in the iterable
     * @param c the iterable of elements to evaluate
     * @param valueExtractor the function to extract an integer value from each element
     * @return an {@code OptionalInt} containing the maximum value if the iterable is not {@code null} or empty, otherwise an empty {@code OptionalInt}
     * @see N#maxIntOrDefaultIfEmpty(Iterable, ToIntFunction, int)
     */
    @Beta
    public static  OptionalInt maxInt(final Iterable c, final ToIntFunction valueExtractor) {
        if (c == null) {
            return OptionalInt.empty();
        }

        return maxInt(c.iterator(), valueExtractor);
    }

    /**
     * Returns the maximum integer value extracted from the elements in the provided iterator by the input {@code valueExtractor} function.
     * If the iterator is {@code null} or empty, it returns an empty {@code OptionalInt}.
     *
     * @param  the type of the elements in the iterator
     * @param iter the iterator of elements to evaluate
     * @param valueExtractor the function to extract an integer value from each element
     * @return an {@code OptionalInt} containing the maximum value if the iterator is not {@code null} or empty, otherwise an empty {@code OptionalInt}
     * @see N#maxIntOrDefaultIfEmpty(Iterator, ToIntFunction, int)
     */
    @Beta
    public static  OptionalInt maxInt(final Iterator iter, final ToIntFunction valueExtractor) {
        if (iter == null || !iter.hasNext()) {
            return OptionalInt.empty();
        }

        int candidate = valueExtractor.applyAsInt(iter.next());
        int next = 0;

        while (iter.hasNext()) {
            next = valueExtractor.applyAsInt(iter.next());

            if (next > candidate) {
                candidate = next;
            }
        }

        return OptionalInt.of(candidate);
    }

    /**
     * Returns the maximum long value extracted from the elements in the provided array by the input {@code valueExtractor} function.
     * If the array is {@code null} or empty, it returns an empty {@code OptionalLong}.
     *
     * @param  the type of the elements in the array
     * @param a the array of elements to evaluate
     * @param valueExtractor the function to extract a long value from each element
     * @return an {@code OptionalLong} containing the maximum value if the array is not {@code null} or empty, otherwise an empty {@code OptionalLong}
     * @see N#maxLongOrDefaultIfEmpty(Object[], ToLongFunction, long)
     */
    @Beta
    public static  OptionalLong maxLong(final T[] a, final ToLongFunction valueExtractor) {
        if (N.isEmpty(a)) {
            return OptionalLong.empty();
        }

        long candidate = valueExtractor.applyAsLong(a[0]);
        long next = 0;

        for (int i = 1, len = a.length; i < len; i++) {
            next = valueExtractor.applyAsLong(a[i]);

            if (next > candidate) {
                candidate = next;
            }
        }

        return OptionalLong.of(candidate);
    }

    /**
     * Returns the maximum long value extracted from the elements in the provided iterable by the input {@code valueExtractor} function.
     * If the iterable is {@code null} or empty, it returns an empty {@code OptionalLong}.
     *
     * @param  the type of the elements in the iterable
     * @param c the iterable of elements to evaluate
     * @param valueExtractor the function to extract a long value from each element
     * @return an {@code OptionalLong} containing the maximum value if the iterable is not {@code null} or empty, otherwise an empty {@code OptionalLong}
     * @see N#maxLongOrDefaultIfEmpty(Iterable, ToLongFunction, long)
     */
    @Beta
    public static  OptionalLong maxLong(final Iterable c, final ToLongFunction valueExtractor) {
        if (c == null) {
            return OptionalLong.empty();
        }

        return maxLong(c.iterator(), valueExtractor);
    }

    /**
     * Returns the maximum long value extracted from the elements in the provided iterator by the input {@code valueExtractor} function.
     * If the iterator is {@code null} or empty, it returns an empty {@code OptionalLong}.
     *
     * @param  the type of the elements in the iterator
     * @param iter the iterator of elements to evaluate
     * @param valueExtractor the function to extract a long value from each element
     * @return an {@code OptionalLong} containing the maximum value if the iterator is not {@code null} or empty, otherwise an empty {@code OptionalLong}
     * @see N#maxLongOrDefaultIfEmpty(Iterator, ToLongFunction, long)
     */
    @Beta
    public static  OptionalLong maxLong(final Iterator iter, final ToLongFunction valueExtractor) {
        if (iter == null || !iter.hasNext()) {
            return OptionalLong.empty();
        }

        long candidate = valueExtractor.applyAsLong(iter.next());
        long next = 0;

        while (iter.hasNext()) {
            next = valueExtractor.applyAsLong(iter.next());

            if (next > candidate) {
                candidate = next;
            }
        }

        return OptionalLong.of(candidate);
    }

    /**
     * Returns the maximum double value extracted from the elements in the provided array by the input {@code valueExtractor} function.
     * If the array is {@code null} or empty, it returns an empty {@code OptionalDouble}.
     *
     * @param  the type of the elements in the array
     * @param a the array of elements to evaluate
     * @param valueExtractor the function to extract a double value from each element
     * @return an {@code OptionalDouble} containing the maximum value if the array is not {@code null} or empty, otherwise an empty {@code OptionalDouble}
     * @see N#maxDoubleOrDefaultIfEmpty(Object[], ToDoubleFunction, double)
     */
    @Beta
    public static  OptionalDouble maxDouble(final T[] a, final ToDoubleFunction valueExtractor) {
        if (N.isEmpty(a)) {
            return OptionalDouble.empty();
        }

        double candidate = valueExtractor.applyAsDouble(a[0]);
        double next = 0;

        for (int i = 1, len = a.length; i < len; i++) {
            next = valueExtractor.applyAsDouble(a[i]);

            if (N.compare(next, candidate) > 0) {
                candidate = next;
            }
        }

        return OptionalDouble.of(candidate);
    }

    /**
     * Returns the maximum double value extracted from the elements in the provided iterable by the input {@code valueExtractor} function.
     * If the iterable is {@code null} or empty, it returns an empty {@code OptionalDouble}.
     *
     * @param  the type of the elements in the iterable
     * @param c the iterable of elements to evaluate
     * @param valueExtractor the function to extract a double value from each element
     * @return an {@code OptionalDouble} containing the maximum value if the iterable is not {@code null} or empty, otherwise an empty {@code OptionalDouble}
     * @see N#maxDoubleOrDefaultIfEmpty(Iterable, ToDoubleFunction, double)
     */
    @Beta
    public static  OptionalDouble maxDouble(final Iterable c, final ToDoubleFunction valueExtractor) {
        if (c == null) {
            return OptionalDouble.empty();
        }

        return maxDouble(c.iterator(), valueExtractor);
    }

    /**
     * Returns the maximum double value extracted from the elements in the provided iterator by the input {@code valueExtractor} function.
     * If the iterator is {@code null} or empty, it returns an empty {@code OptionalDouble}.
     *
     * @param  the type of the elements in the iterator
     * @param iter the iterator of elements to evaluate
     * @param valueExtractor the function to extract a double value from each element
     * @return an {@code OptionalDouble} containing the maximum value if the iterator is not {@code null} or empty, otherwise an empty {@code OptionalDouble}
     * @see N#maxDoubleOrDefaultIfEmpty(Iterator, ToDoubleFunction, double)
     */
    @Beta
    public static  OptionalDouble maxDouble(final Iterator iter, final ToDoubleFunction valueExtractor) {
        if (iter == null || !iter.hasNext()) {
            return OptionalDouble.empty();
        }

        double candidate = valueExtractor.applyAsDouble(iter.next());
        double next = 0;

        while (iter.hasNext()) {
            next = valueExtractor.applyAsDouble(iter.next());

            if (N.compare(next, candidate) > 0) {
                candidate = next;
            }
        }

        return OptionalDouble.of(candidate);
    }

    /**
     * Returns the minimum and maximum values from the provided array of elements based on their natural ordering.
     * The result is wrapped in an Optional Pair, where the first element is the minimum and the second is the maximum.
     * If the array is {@code null} or empty, it returns an empty Optional.
     *
     * @param a the array of elements to evaluate
     * @return an Optional Pair containing the minimum and maximum values if the array is not {@code null} or empty, otherwise an empty Optional
     * @see N#minMax(Comparable...)
     */
    public static > Optional> minMax(final T[] a) {
        return N.isEmpty(a) ? Optional.empty() : Optional.of(N.minMax(a));
    }

    /**
     * Returns the minimum and maximum values from the provided array of elements according to the provided comparator.
     * The result is wrapped in an Optional Pair, where the first element is the minimum and the second is the maximum.
     * If the array is {@code null} or empty, it returns an empty Optional.
     *
     * @param  the type of the elements in the array
     * @param a the array of elements to evaluate
     * @param cmp the comparator to determine the order of the elements
     * @return an Optional Pair containing the minimum and maximum values if the array is not {@code null} or empty, otherwise an empty Optional
     * @see N#minMax(Object[], Comparator)
     */
    public static  Optional> minMax(final T[] a, final Comparator cmp) {
        return N.isEmpty(a) ? Optional.empty() : Optional.of(N.minMax(a, cmp));
    }

    /**
     * Returns the minimum and maximum values from the provided iterable of elements based on their natural ordering.
     * The result is wrapped in an Optional Pair, where the first element is the minimum and the second is the maximum.
     * If the iterable is {@code null} or empty, it returns an empty Optional.
     *
     * @param c the iterable of elements to evaluate
     * @return an Optional Pair containing the minimum and maximum values if the iterable is not {@code null} or empty, otherwise an empty Optional
     * @see N#minMax(Iterable)
     */
    public static > Optional> minMax(final Iterable c) {
        final Iterator iter = c == null ? null : c.iterator();

        return iter == null || !iter.hasNext() ? Optional.empty() : Optional.of(N.minMax(iter));
    }

    /**
     * Returns the minimum and maximum values from the provided iterable of elements, according to the provided comparator.
     * The result is wrapped in an Optional Pair, where the first element is the minimum and the second is the maximum.
     * If the iterable is {@code null} or empty, it returns an empty Optional.
     *
     * @param c the iterable of elements to evaluate
     * @param cmp the comparator to determine the order of the elements
     * @return an Optional Pair containing the minimum and maximum values if the iterable is not {@code null} or empty, otherwise an empty Optional
     * @see N#minMax(Iterable, Comparator)
     */
    public static  Optional> minMax(final Iterable c, final Comparator cmp) {
        final Iterator iter = c == null ? null : c.iterator();

        return iter == null || !iter.hasNext() ? Optional.empty() : Optional.of(N.minMax(iter, cmp));
    }

    /**
     * Returns the minimum and maximum values from the provided iterator of elements based on their natural ordering.
     * The result is wrapped in an Optional Pair, where the first element is the minimum and the second is the maximum.
     * If the iterator is {@code null} or empty, it returns an empty Optional.
     *
     * @param iter the iterator of elements to evaluate
     * @return an Optional Pair containing the minimum and maximum values if the iterator is not {@code null} or empty, otherwise an empty Optional
     * @see N#minMax(Iterator)
     */
    public static > Optional> minMax(final Iterator iter) {
        return iter == null || !iter.hasNext() ? Optional.empty() : Optional.of(N.minMax(iter));
    }

    /**
     * Returns the minimum and maximum values from the provided iterator of elements, according to the provided comparator.
     * The result is wrapped in an Optional Pair, where the first element is the minimum and the second is the maximum.
     * If the iterator is {@code null} or empty, it returns an empty Optional.
     *
     * @param iter the iterator of elements to evaluate
     * @param cmp the comparator to determine the order of the elements
     * @return an Optional Pair containing the minimum and maximum values if the iterator is not {@code null} or empty, otherwise an empty Optional
     * @see N#minMax(Iterator, Comparator)
     */
    public static  Optional> minMax(final Iterator iter, final Comparator cmp) {
        return iter == null || !iter.hasNext() ? Optional.empty() : Optional.of(N.minMax(iter, cmp));
    }

    /**
     * Returns the length / 2 + 1 largest value in the specified array based on their natural ordering.
     * The result is wrapped in a {@code Nullable}. If the array is {@code null} or empty, it returns an empty {@code Nullable}.
     *
     * @param  the type of the elements in the array, which must be a subtype of Comparable
     * @param a the array of elements to evaluate
     * @return a {@code Nullable} containing the median value if the array is not {@code null} or empty, otherwise an empty {@code Nullable}
     * @see N#median(Comparable...)
     * @see Median#of(Comparable[])
     * @see Median#of(Object[], Comparator)
     */
    public static > Nullable median(final T[] a) {
        return N.isEmpty(a) ? Nullable.empty() : Nullable.of(N.median(a));
    }

    /**
     * Returns the length / 2 + 1 largest value in the specified array, according to the provided comparator.
     * The result is wrapped in a {@code Nullable}. If the array is {@code null} or empty, it returns an empty {@code Nullable}.
     *
     * @param  the type of the elements in the array, which must be a subtype of Comparable
     * @param a the array of elements to evaluate
     * @param cmp the comparator to determine the order of the elements
     * @return a {@code Nullable} containing the median value if the array is not {@code null} or empty, otherwise an empty {@code Nullable}
     * @see N#median(Object[], Comparator)
     * @see Median#of(Comparable[])
     * @see Median#of(Object[], Comparator)
     */
    public static  Nullable median(final T[] a, final Comparator cmp) {
        return N.isEmpty(a) ? Nullable.empty() : Nullable.of(N.median(a, cmp));
    }

    /**
     * Returns the length / 2 + 1 largest value in the specified collection based on their natural ordering.
     * The result is wrapped in a {@code Nullable}. If the collection is {@code null} or empty, it returns an empty {@code Nullable}.
     *
     * @param  the type of the elements in the collection, which must be a subtype of Comparable
     * @param c the collection of elements to evaluate
     * @return a {@code Nullable} containing the median value if the collection is not {@code null} or empty, otherwise an empty {@code Nullable}
     * @see N#median(Collection)
     * @see Median#of(Collection)
     * @see Median#of(Collection, Comparator)
     */
    public static > Nullable median(final Collection c) {
        return N.isEmpty(c) ? Nullable.empty() : Nullable.of(N.median(c));
    }

    /**
     * Returns the length / 2 + 1 largest value in the specified collection, according to the provided comparator.
     * The result is wrapped in a {@code Nullable}. If the collection is {@code null} or empty, it returns an empty {@code Nullable}.
     *
     * @param  the type of the elements in the collection, which must be a subtype of Comparable
     * @param c the collection of elements to evaluate
     * @param cmp the comparator to determine the order of the elements
     * @return a {@code Nullable} containing the median value if the collection is not {@code null} or empty, otherwise an empty {@code Nullable}
     * @see N#median(Collection, Comparator)
     * @see Median#of(Collection)
     * @see Median#of(Collection, Comparator)
     */
    public static  Nullable median(final Collection c, final Comparator cmp) {
        return N.isEmpty(c) ? Nullable.empty() : Nullable.of(N.median(c, cmp));
    }

    //    /**
    //     * Returns {@code Nullable.empty()} if the specified {@code Array/Collection} is {@code null} or empty.
    //     *
    //     * @param 
    //     * @param a
    //     * @param keyExtractor
    //     * @return
    //     * @deprecated
    //     * @see Comparators#comparingBy(Function)
    //     */
    //    @Deprecated
    //    @Beta
    //    @SuppressWarnings("rawtypes")
    //    public static  Nullable medianBy(final T[] a, final Function keyExtractor) {
    //        return median(a, Comparators.comparingBy(keyExtractor));
    //    }
    //
    //    /**
    //     * Returns {@code Nullable.empty()} if the specified {@code Array/Collection} is {@code null} or empty.
    //     *
    //     * @param 
    //     * @param c
    //     * @param keyExtractor
    //     * @return
    //     * @deprecated
    //     * @see Comparators#comparingBy(Function)
    //     */
    //    @Deprecated
    //    @Beta
    //    @SuppressWarnings("rawtypes")
    //    public static  Nullable medianBy(final Collection c, final Function keyExtractor) {
    //        return median(c, Comparators.comparingBy(keyExtractor));
    //    }

    /**
     * Returns the k-th largest element from the provided array based on their natural ordering.
     * If the array is {@code null}, empty, or its length is less than {@code k}, it returns an empty {@code Nullable}.
     *
     * @param  the type of the elements in the array, which must be a subtype of Comparable
     * @param a the array of elements to evaluate
     * @param k the position of the largest element to find (1-based index)
     * @return a {@code Nullable} containing the k-th largest value if the array is not {@code null}, not empty, and its length is greater or equal to {@code k}, otherwise an empty {@code Nullable}
     * @see N#kthLargest(Comparable[], int)
     */
    public static > Nullable kthLargest(final T[] a, final int k) {
        return N.isEmpty(a) || a.length < k ? Nullable.empty() : Nullable.of(N.kthLargest(a, k));
    }

    /**
     * Returns the k-th largest element from the provided array according to the provided comparator.
     * If the array is {@code null}, empty, or its length is less than {@code k}, it returns an empty {@code Nullable}.
     *
     * @param  the type of the elements in the array
     * @param a the array of elements to evaluate
     * @param k the position of the largest element to find (1-based index)
     * @param cmp the comparator to determine the order of the elements
     * @return a {@code Nullable} containing the k-th largest value if the array is not {@code null}, not empty, and its length is greater or equal to {@code k}, otherwise an empty {@code Nullable}
     * @see N#kthLargest(Object[], int, Comparator)
     */
    public static  Nullable kthLargest(final T[] a, final int k, final Comparator cmp) {
        return N.isEmpty(a) || a.length < k ? Nullable.empty() : Nullable.of(N.kthLargest(a, k, cmp));
    }

    /**
     * Returns the k-th largest element from the provided collection based on their natural ordering.
     * If the collection is {@code null}, empty, or its size is less than {@code k}, it returns an empty {@code Nullable}.
     *
     * @param  the type of the elements in the collection, which must be a subtype of Comparable
     * @param c the collection of elements to evaluate
     * @param k the position of the largest element to find (1-based index)
     * @return a {@code Nullable} containing the k-th largest value if the collection is not {@code null}, not empty, and its size is greater or equal to {@code k}, otherwise an empty {@code Nullable}
     * @see N#kthLargest(Collection, int)
     */
    public static > Nullable kthLargest(final Collection c, final int k) {
        return N.isEmpty(c) || c.size() < k ? Nullable.empty() : Nullable.of(N.kthLargest(c, k));
    }

    /**
     * Returns the k-th largest element from the provided collection based on the provided comparator.
     * If the collection is {@code null}, empty, or its size is less than k, a {@code Nullable}.empty() is returned.
     *
     * @param  The type of elements in the collection.
     * @param c The collection from which to find the k-th largest element.
     * @param k The position from the end of a sorted list of the collection's elements (1-based index).
     * @param cmp The comparator used to determine the order of the collection's elements.
     * @return A {@code Nullable} containing the k-th largest element if it exists, otherwise {@code Nullable}.empty().
     * @see N#kthLargest(Collection, int, Comparator)
     */
    public static  Nullable kthLargest(final Collection c, final int k, final Comparator cmp) {
        return N.isEmpty(c) || c.size() < k ? Nullable.empty() : Nullable.of(N.kthLargest(c, k, cmp));
    }

    /**
     * Returns the sum of the integer value of provided numbers as an {@code OptionalInt}.
     * If the iterable is {@code null} or empty, it returns an empty {@code OptionalInt}.
     *
     * @param  the type of the elements in the iterable, which must be a subtype of Number
     * @param c the iterable of elements to evaluate
     * @return an {@code OptionalInt} containing the sum if the iterable is not {@code null} or empty, otherwise an empty {@code OptionalInt}
     * @see N#sumInt(Iterable)
     */
    public static  OptionalInt sumInt(final Iterable c) {
        return sumInt(c, Fn.numToInt());
    }

    /**
     * Returns the sum of the integer values extracted from the elements in the provided iterable by the input {@code func} function.
     * If the iterable is {@code null} or empty, it returns an empty {@code OptionalInt}.
     *
     * @param  the type of the elements in the iterable
     * @param c the iterable of elements to evaluate
     * @param func the function to extract an integer value from each element
     * @return an {@code OptionalInt} containing the sum if the iterable is not {@code null} or empty, otherwise an empty {@code OptionalInt}
     * @see N#sumInt(Iterable, ToIntFunction)
     */
    public static  OptionalInt sumInt(final Iterable c, final ToIntFunction func) {
        final Iterator iter = c == null ? ObjIterator.empty() : c.iterator();

        if (!iter.hasNext()) {
            return OptionalInt.empty();
        }

        return OptionalInt.of(N.sumInt(c, func));
    }

    /**
     * Returns the sum of the integer values of the provided numbers as an {@code OptionalLong}.
     * If the iterable is {@code null} or empty, it returns an empty {@code OptionalLong}.
     *
     * @param  the type of the elements in the iterable, which must be a subtype of Number
     * @param c the iterable of elements to evaluate
     * @return an {@code OptionalLong} containing the sum if the iterable is not {@code null} or empty, otherwise an empty {@code OptionalLong}
     * @see N#sumIntToLong(Iterable)
     */
    public static  OptionalLong sumIntToLong(final Iterable c) {
        return sumIntToLong(c, Fn.numToInt());
    }

    /**
     * Returns the sum of the integer values extracted from the elements in the provided iterable by the input {@code func} function as an {@code OptionalLong}.
     * If the iterable is {@code null} or empty, it returns an empty {@code OptionalLong}.
     *
     * @param  the type of the elements in the iterable
     * @param c the iterable of elements to evaluate
     * @param func the function to extract an integer value from each element
     * @return an {@code OptionalLong} containing the sum if the iterable is not {@code null} or empty, otherwise an empty {@code OptionalLong}
     * @see N#sumIntToLong(Iterable, ToIntFunction)
     */
    public static  OptionalLong sumIntToLong(final Iterable c, final ToIntFunction func) {
        final Iterator iter = c == null ? ObjIterator.empty() : c.iterator();

        if (!iter.hasNext()) {
            return OptionalLong.empty();
        }

        return OptionalLong.of(N.sumIntToLong(c, func));
    }

    /**
     * Returns the sum of the long values of the provided numbers as an {@code OptionalLong}.
     * If the iterable is {@code null} or empty, it returns an empty {@code OptionalLong}.
     *
     * @param  the type of the elements in the iterable, which must be a subtype of Number
     * @param c the iterable of elements to evaluate
     * @return an {@code OptionalLong} containing the sum if the iterable is not {@code null} or empty, otherwise an empty {@code OptionalLong}
     * @see N#sumLong(Iterable)
     */
    public static  OptionalLong sumLong(final Iterable c) {
        return sumLong(c, Fn.numToLong());
    }

    /**
     * Returns the sum of the long values extracted from the elements in the provided iterable by the input {@code func} function.
     * If the iterable is {@code null} or empty, it returns an empty {@code OptionalLong}.
     *
     * @param  the type of the elements in the iterable
     * @param c the iterable of elements to evaluate
     * @param func the function to extract a long value from each element
     * @return an {@code OptionalLong} containing the sum if the iterable is not {@code null} or empty, otherwise an empty {@code OptionalLong}
     * @see N#sumLong(Iterable, ToLongFunction)
     */
    public static  OptionalLong sumLong(final Iterable c, final ToLongFunction func) {
        final Iterator iter = c == null ? ObjIterator.empty() : c.iterator();

        if (!iter.hasNext()) {
            return OptionalLong.empty();
        }

        return OptionalLong.of(N.sumLong(c, func));
    }

    /**
     * Returns the sum of the double values of the provided numbers as an {@code OptionalDouble}.
     * If the iterable is {@code null} or empty, it returns an empty {@code OptionalDouble}.
     *
     * @param  the type of the elements in the iterable, which must be a subtype of Number
     * @param c the iterable of elements to evaluate
     * @return an {@code OptionalDouble} containing the sum if the iterable is not {@code null} or empty, otherwise an empty {@code OptionalDouble}
     * @see N#sumDouble(Iterable)
     */
    public static  OptionalDouble sumDouble(final Iterable c) {
        return sumDouble(c, Fn.numToDouble());
    }

    /**
     * Returns the sum of the double values extracted from the elements in the provided iterable by the input {@code func} function.
     * If the iterable is {@code null} or empty, it returns an empty {@code OptionalDouble}.
     *
     * @param  the type of the elements in the iterable
     * @param c the iterable of elements to evaluate
     * @param func the function to extract a double value from each element
     * @return an {@code OptionalDouble} containing the sum if the iterable is not {@code null} or empty, otherwise an empty {@code OptionalDouble}
     * @see N#sumDouble(Iterable, ToDoubleFunction)
     */
    public static  OptionalDouble sumDouble(final Iterable c, final ToDoubleFunction func) {
        final Iterator iter = c == null ? ObjIterator.empty() : c.iterator();

        if (!iter.hasNext()) {
            return OptionalDouble.empty();
        }

        return OptionalDouble.of(N.sumDouble(c, func));
    }

    /**
     * Returns the sum of the BigInteger values in the provided iterable.
     * If the iterable is {@code null} or empty, it returns an empty {@code Optional}.
     *
     * @param c the iterable of BigInteger elements to evaluate
     * @return an {@code Optional} containing the sum if the iterable is not {@code null} or empty, otherwise an empty {@code Optional}
     * @see N#sumBigInteger(Iterable)
     */
    public static Optional sumBigInteger(final Iterable c) {
        return sumBigInteger(c, Fn.identity());
    }

    /**
     * Returns the sum of the BigInteger values extracted from the elements in the provided iterable by the input {@code func} function.
     * If the iterable is {@code null} or empty, it returns an empty {@code Optional}.
     *
     * @param  the type of the elements in the iterable
     * @param c the iterable of elements to evaluate
     * @param func the function to extract a BigInteger value from each element
     * @return an {@code Optional} containing the sum if the iterable is not {@code null} or empty, otherwise an empty {@code Optional}
     * @see N#sumBigInteger(Iterable, Function)
     */
    public static  Optional sumBigInteger(final Iterable c, final Function func) {
        final Iterator iter = c == null ? ObjIterator.empty() : c.iterator();

        if (!iter.hasNext()) {
            return Optional.empty();
        }

        return Optional.of(N.sumBigInteger(c, func));
    }

    /**
     * Returns the sum of the BigDecimal values in the provided iterable.
     * If the iterable is {@code null} or empty, it returns an empty {@code Optional}.
     *
     * @param c the iterable of BigDecimal elements to evaluate
     * @return an {@code Optional} containing the sum if the iterable is not {@code null} or empty, otherwise an empty {@code Optional}
     * @see N#sumBigDecimal(Iterable)
     */
    public static Optional sumBigDecimal(final Iterable c) {
        return sumBigDecimal(c, Fn.identity());
    }

    /**
     * Returns the sum of the BigDecimal values extracted from the elements in the provided iterable by the input {@code func} function.
     * If the iterable is {@code null} or empty, it returns an empty {@code Optional}.
     *
     * @param  the type of the elements in the iterable
     * @param c the iterable of elements to evaluate
     * @param func the function to extract a BigDecimal value from each element
     * @return an {@code Optional} containing the sum if the iterable is not {@code null} or empty, otherwise an empty {@code Optional}
     * @see N#sumBigDecimal(Iterable, Function)
     */
    public static  Optional sumBigDecimal(final Iterable c, final Function func) {
        final Iterator iter = c == null ? ObjIterator.empty() : c.iterator();

        if (!iter.hasNext()) {
            return Optional.empty();
        }

        return Optional.of(N.sumBigDecimal(c, func));
    }

    /**
     * Returns the average of the integer values of the provided numbers as an {@code OptionalDouble}.
     * If the array is {@code null} or empty, it returns an empty {@code OptionalDouble}.
     *
     * @param  the type of the elements in the array, which must be a subtype of Number
     * @param a the array of elements to evaluate
     * @return the average of the integer values if the array is not {@code null} or empty, otherwise an empty {@code OptionalDouble}
     * @see N#averageInt(Number[])
     */
    public static  OptionalDouble averageInt(final T[] a) {
        return averageInt(a, Fn.numToInt());
    }

    /**
     * Returns the average of the integer values of the provided numbers in the specified range as an {@code OptionalDouble}.
     * If the specified range is empty ({@code fromIndex == toIndex}, it returns an empty {@code OptionalDouble}.
     *
     * @param  the type of the elements in the array, which must be a subtype of Number
     * @param a the array of elements to evaluate
     * @param fromIndex the start index of the range, inclusive
     * @param toIndex the end index of the range, exclusive
     * @return the average of the integer values of the provided numbers in the specified range as an {@code OptionalDouble} if the ranger is not empty, otherwise an empty {@code OptionalDouble}
     * @throws IndexOutOfBoundsException if the range is invalid: ({@code fromIndex < 0 || fromIndex > toIndex || toIndex > a.length})
     * @see N#averageInt(Number[], int, int)
     */
    public static  OptionalDouble averageInt(final T[] a, final int fromIndex, final int toIndex) throws IndexOutOfBoundsException {
        return averageInt(a, fromIndex, toIndex, Fn.numToInt());
    }

    /**
     * Returns the average of the integer values extracted from the elements in the provided array by the input {@code func} function as an {@code OptionalDouble}.
     * If the array is {@code null} or empty, it returns an empty {@code OptionalDouble}.
     *
     * @param  the type of the elements in the array
     * @param a the array of elements to evaluate
     * @param func the function to extract an integer value from each element
     * @return the average of the integer values if the array is not {@code null} or empty, otherwise an empty {@code OptionalDouble}
     * @see N#averageInt(Object[], ToIntFunction)
     */
    public static  OptionalDouble averageInt(final T[] a, final ToIntFunction func) {
        if (N.isEmpty(a)) {
            return OptionalDouble.empty();
        }

        return averageInt(a, 0, a.length, func);
    }

    /**
     * Returns the average of the integer values extracted from the elements in the specified range by the input {@code func} function as an {@code OptionalDouble}.
     * If the specified range is empty ({@code fromIndex == toIndex}, it returns an empty {@code OptionalDouble}.
     *
     * @param  the type of the elements in the array
     * @param a the array of elements to evaluate
     * @param fromIndex the start index of the range, inclusive
     * @param toIndex the end index of the range, exclusive
     * @param func the function to extract an integer value from each element
     * @return the average of the integer values of the provided numbers in the specified range as an {@code OptionalDouble} if the ranger is not empty, otherwise an empty {@code OptionalDouble}
     * @throws IndexOutOfBoundsException if the range is invalid: ({@code fromIndex < 0 || fromIndex > toIndex || toIndex > a.length})
     * @see N#averageInt(Object[], int, int, ToIntFunction)
     */
    public static  OptionalDouble averageInt(final T[] a, final int fromIndex, final int toIndex, final ToIntFunction func)
            throws IndexOutOfBoundsException {
        N.checkFromToIndex(fromIndex, toIndex, N.len(a));

        if (fromIndex == toIndex) {
            return OptionalDouble.empty();
        }

        return OptionalDouble.of(N.averageInt(a, fromIndex, toIndex, func));
    }

    /**
     * Returns the average of the integer values of the provided numbers in the specified range as an {@code OptionalDouble}.
     * If the specified range is empty ({@code fromIndex == toIndex}, it returns an empty {@code OptionalDouble}.
     *
     * @param  the type of the elements in the collection, which must be a subtype of Number
     * @param c the collection of elements to evaluate
     * @param fromIndex the start index of the range, inclusive
     * @param toIndex the end index of the range, exclusive
     * @return the average of the integer values of the provided numbers in the specified range as an {@code OptionalDouble} if the ranger is not empty, otherwise an empty {@code OptionalDouble}
     * @throws IndexOutOfBoundsException if the range is invalid: ({@code fromIndex < 0 || fromIndex > toIndex || toIndex > a.length})
     * @see N#averageInt(Collection, int, int)
     */
    public static  OptionalDouble averageInt(final Collection c, final int fromIndex, final int toIndex)
            throws IndexOutOfBoundsException {
        return averageInt(c, fromIndex, toIndex, Fn.numToInt());
    }

    /**
     * Returns the average of the integer values extracted from the elements in the specified range by the input {@code func} function as an {@code OptionalDouble}.
     * If the specified range is empty ({@code fromIndex == toIndex}, it returns an empty {@code OptionalDouble}.
     *
     * @param  the type of the elements in the collection
     * @param c the collection of elements to evaluate
     * @param fromIndex the start index of the range, inclusive
     * @param toIndex the end index of the range, exclusive
     * @param func the function to extract an integer value from each element
     * @return the average of the integer values of the provided numbers in the specified range as an {@code OptionalDouble} if the ranger is not empty, otherwise an empty {@code OptionalDouble}
     * @throws IndexOutOfBoundsException if the range is invalid: ({@code fromIndex < 0 || fromIndex > toIndex || toIndex > a.length})
     * @see N#averageInt(Collection, int, int, ToIntFunction)
     */
    public static  OptionalDouble averageInt(final Collection c, final int fromIndex, final int toIndex, final ToIntFunction func)
            throws IndexOutOfBoundsException {
        N.checkFromToIndex(fromIndex, toIndex, N.size(c));

        if (fromIndex == toIndex) {
            return OptionalDouble.empty();
        }

        return OptionalDouble.of(N.averageInt(c, fromIndex, toIndex, func));
    }

    /**
     * Returns the average of the integer values of the provided numbers as an {@code OptionalDouble}.
     * If the iterable is {@code null} or empty, it returns an empty {@code OptionalDouble}.
     *
     * @param  the type of the elements in the iterable, which must be a subtype of Number
     * @param c the iterable of elements to evaluate
     * @return the average of the integer values if the iterable is not {@code null} or empty, otherwise an empty {@code OptionalDouble}
     * @see N#averageInt(Iterable)
     */
    public static  OptionalDouble averageInt(final Iterable c) {
        return averageInt(c, Fn.numToInt());
    }

    /**
     * Returns the average of the integer values extracted from the elements in the provided iterable by the input {@code func} function as an {@code OptionalDouble}.
     * If the iterable is {@code null} or empty, it returns an empty {@code OptionalDouble}.
     *
     * @param  the type of the elements in the iterable
     * @param c the iterable of elements to evaluate
     * @param func the function to extract an integer value from each element
     * @return the average of the integer values if the iterable is not {@code null} or empty, otherwise an empty {@code OptionalDouble}
     * @see N#averageInt(Iterable, ToIntFunction)
     */
    public static  OptionalDouble averageInt(final Iterable c, final ToIntFunction func) {
        final Iterator iter = c == null ? ObjIterator.empty() : c.iterator();

        if (!iter.hasNext()) {
            return OptionalDouble.empty();
        }

        return OptionalDouble.of(N.averageInt(c, func));
    }

    /**
     * Returns the average of the long values of the provided numbers as an {@code OptionalDouble}.
     * If the array is {@code null} or empty, it returns an empty {@code OptionalDouble}.
     *
     * @param  the type of the elements in the array, which must be a subtype of Number
     * @param a the array of elements to evaluate
     * @return the average of the long values if the array is not {@code null} or empty, otherwise an empty {@code OptionalDouble}
     * @see N#averageLong(Number[])
     */
    public static  OptionalDouble averageLong(final T[] a) {
        return averageLong(a, Fn.numToLong());
    }

    /**
     * Returns the average of the long values of the provided numbers in the specified range as an {@code OptionalDouble}.
     * If the specified range is empty ({@code fromIndex == toIndex}, it returns an empty {@code OptionalDouble}.
     *
     * @param  the type of the elements in the array, which must be a subtype of Number
     * @param a the array of elements to evaluate
     * @param fromIndex the start index of the range, inclusive
     * @param toIndex the end index of the range, exclusive
     * @return the average of the long values of the provided numbers in the specified range as an {@code OptionalDouble} if the ranger is not empty, otherwise an empty {@code OptionalDouble}
     * @throws IndexOutOfBoundsException if the range is invalid: ({@code fromIndex < 0 || fromIndex > toIndex || toIndex > a.length})
     * @see N#averageLong(Number[], int, int)
     */
    public static  OptionalDouble averageLong(final T[] a, final int fromIndex, final int toIndex) throws IndexOutOfBoundsException {
        return averageLong(a, fromIndex, toIndex, Fn.numToLong());
    }

    /**
     * Returns the average of the long values extracted from the elements in the provided array by the input {@code func} function as an {@code OptionalDouble}.
     * If the array is {@code null} or empty, it returns an empty {@code OptionalDouble}.
     *
     * @param  the type of the elements in the array
     * @param a the array of elements to evaluate
     * @param func the function to extract a long value from each element
     * @return the average of the long values if the array is not {@code null} or empty, otherwise an empty {@code OptionalDouble}
     * @see N#averageLong(Object[], ToLongFunction)
     */
    public static  OptionalDouble averageLong(final T[] a, final ToLongFunction func) {
        if (N.isEmpty(a)) {
            return OptionalDouble.empty();
        }

        return averageLong(a, 0, a.length, func);
    }

    /**
     * Returns the average of the long values extracted from the elements in the specified range by the input {@code func} function as an {@code OptionalDouble}.
     * If the specified range is empty ({@code fromIndex == toIndex}, it returns an empty {@code OptionalDouble}.
     *
     * @param  the type of the elements in the array
     * @param a the array of elements to evaluate
     * @param fromIndex the start index of the range, inclusive
     * @param toIndex the end index of the range, exclusive
     * @param func the function to extract a long value from each element
     * @return the average of the long values of the provided numbers in the specified range as an {@code OptionalDouble} if the ranger is not empty, otherwise an empty {@code OptionalDouble}
     * @throws IndexOutOfBoundsException if the range is invalid: ({@code fromIndex < 0 || fromIndex > toIndex || toIndex > a.length})
     * @see N#averageLong(Object[], int, int, ToLongFunction)
     */
    public static  OptionalDouble averageLong(final T[] a, final int fromIndex, final int toIndex, final ToLongFunction func)
            throws IndexOutOfBoundsException {
        N.checkFromToIndex(fromIndex, toIndex, N.len(a));

        if (fromIndex == toIndex) {
            return OptionalDouble.empty();
        }

        return OptionalDouble.of(N.averageLong(a, fromIndex, toIndex, func));
    }

    /**
     * Returns the average of the long values of the provided numbers in the specified range as an {@code OptionalDouble}.
     * If the specified range is empty ({@code fromIndex == toIndex}, it returns an empty {@code OptionalDouble}.
     *
     * @param  the type of the elements in the collection, which must be a subtype of Number
     * @param c the collection of elements to evaluate
     * @param fromIndex the start index of the range, inclusive
     * @param toIndex the end index of the range, exclusive
     * @return the average of the long values of the provided numbers in the specified range as an {@code OptionalDouble} if the ranger is not empty, otherwise an empty {@code OptionalDouble}
     * @throws IndexOutOfBoundsException if the range is invalid: ({@code fromIndex < 0 || fromIndex > toIndex || toIndex > a.length})
     * @see N#averageLong(Collection, int, int)
     */
    public static  OptionalDouble averageLong(final Collection c, final int fromIndex, final int toIndex)
            throws IndexOutOfBoundsException {
        return averageLong(c, fromIndex, toIndex, Fn.numToLong());
    }

    /**
     * Returns the average of the integer values extracted from the elements in the specified range by the input {@code func} function as an {@code OptionalDouble}.
     * If the specified range is empty ({@code fromIndex == toIndex}, it returns an empty {@code OptionalDouble}.
     *
     * @param  the type of the elements in the array
     * @param c the collection of elements to evaluate
     * @param fromIndex the start index of the range, inclusive
     * @param toIndex the end index of the range, exclusive
     * @param func the function to extract an integer value from each element
     * @return the average of the integer values of the provided numbers in the specified range as an {@code OptionalDouble} if the ranger is not empty, otherwise an empty {@code OptionalDouble}
     * @throws IndexOutOfBoundsException if the range is invalid: ({@code fromIndex < 0 || fromIndex > toIndex || toIndex > a.length})
     * @see N#averageLong(Object[], int, int, ToLongFunction)
     */
    public static  OptionalDouble averageLong(final Collection c, final int fromIndex, final int toIndex, final ToLongFunction func)
            throws IndexOutOfBoundsException {
        N.checkFromToIndex(fromIndex, toIndex, N.size(c));

        if (fromIndex == toIndex) {
            return OptionalDouble.empty();
        }

        return OptionalDouble.of(N.averageLong(c, fromIndex, toIndex, func));
    }

    /**
     * Returns the average of the long values of the provided numbers as an {@code OptionalDouble}.
     * If the iterable is {@code null} or empty, it returns an empty {@code OptionalDouble}.
     *
     * @param  the type of the elements in the iterable, which must be a subtype of Number
     * @param c the iterable of elements to evaluate
     * @return the average of the long values if the iterable is not {@code null} or empty, otherwise an empty {@code OptionalDouble}
     * @see N#averageLong(Iterable)
     */
    public static  OptionalDouble averageLong(final Iterable c) {
        return averageLong(c, Fn.numToLong());
    }

    /**
     * Returns the average of the long values extracted from the elements in the provided iterable by the input {@code func} function as an {@code OptionalDouble}.
     * If the iterable is {@code null} or empty, it returns an empty {@code OptionalDouble}.
     *
     * @param  the type of the elements in the iterable
     * @param c the iterable of elements to evaluate
     * @param func the function to extract a long value from each element
     * @return the average of the long values if the iterable is not {@code null} or empty, otherwise an empty {@code OptionalDouble}
     * @see N#averageLong(Iterable, ToLongFunction)
     */
    public static  OptionalDouble averageLong(final Iterable c, final ToLongFunction func) {
        final Iterator iter = c == null ? ObjIterator.empty() : c.iterator();

        if (!iter.hasNext()) {
            return OptionalDouble.empty();
        }

        return OptionalDouble.of(N.averageLong(c, func));
    }

    /**
     * Returns the average of the double values of the provided numbers as an {@code OptionalDouble}.
     * If the array is {@code null} or empty, it returns an empty {@code OptionalDouble}.
     *
     * @param  the type of the elements in the array, which must be a subtype of Number
     * @param a the array of elements to evaluate
     * @return the average of the double values if the array is not {@code null} or empty, otherwise an empty {@code OptionalDouble}
     * @see N#averageDouble(Number[])
     */
    public static  OptionalDouble averageDouble(final T[] a) {
        return averageDouble(a, Fn.numToDouble());
    }

    /**
     * Returns the average of the double values of the provided numbers in the specified range as an {@code OptionalDouble}.
     * If the specified range is empty ({@code fromIndex == toIndex}, it returns an empty {@code OptionalDouble}.
     *
     * @param  the type of the elements in the array, which must be a subtype of Number
     * @param a the array of elements to evaluate
     * @param fromIndex the start index of the range, inclusive
     * @param toIndex the end index of the range, exclusive
     * @return the average of the double values of the provided numbers in the specified range as an {@code OptionalDouble} if the ranger is not empty, otherwise an empty {@code OptionalDouble}
     * @throws IndexOutOfBoundsException if the range is invalid: ({@code fromIndex < 0 || fromIndex > toIndex || toIndex > a.length})
     * @see N#averageDouble(Number[], int, int)
     */
    public static  OptionalDouble averageDouble(final T[] a, final int fromIndex, final int toIndex) throws IndexOutOfBoundsException {
        return averageDouble(a, fromIndex, toIndex, Fn.numToDouble());
    }

    /**
     * Returns the average of the double values extracted from the elements in the provided array by the input {@code func} function as an {@code OptionalDouble}.
     * If the array is {@code null} or empty, it returns an empty {@code OptionalDouble}.
     *
     * @param  the type of the elements in the array
     * @param a the array of elements to evaluate
     * @param func the function to extract a double value from each element
     * @return the average of the double values if the array is not {@code null} or empty, otherwise an empty {@code OptionalDouble}
     * @see N#averageDouble(Object[], ToDoubleFunction)
     */
    public static  OptionalDouble averageDouble(final T[] a, final ToDoubleFunction func) {
        if (N.isEmpty(a)) {
            return OptionalDouble.empty();
        }

        return averageDouble(a, 0, a.length, func);
    }

    /**
     * Returns the average of the double values extracted from the elements in the specified range by the input {@code func} function as an {@code OptionalDouble}.
     * If the specified range is empty ({@code fromIndex == toIndex}, it returns an empty {@code OptionalDouble}.
     *
     * @param  the type of the elements in the array
     * @param a the array of elements to evaluate
     * @param fromIndex the start index of the range, inclusive
     * @param toIndex the end index of the range, exclusive
     * @param func the function to extract a double value from each element
     * @return the average of the double values of the provided numbers in the specified range as an {@code OptionalDouble} if the ranger is not empty, otherwise an empty {@code OptionalDouble}
     * @throws IndexOutOfBoundsException if the range is invalid: ({@code fromIndex < 0 || fromIndex > toIndex || toIndex > a.length})
     * @see N#averageDouble(Object[], int, int, ToDoubleFunction)
     */
    public static  OptionalDouble averageDouble(final T[] a, final int fromIndex, final int toIndex, final ToDoubleFunction func)
            throws IndexOutOfBoundsException {
        N.checkFromToIndex(fromIndex, toIndex, N.len(a));

        if (fromIndex == toIndex) {
            return OptionalDouble.empty();
        }

        final KahanSummation summation = new KahanSummation();

        for (int i = fromIndex; i < toIndex; i++) {
            summation.add(func.applyAsDouble(a[i]));
        }

        return summation.average();
    }

    /**
     * Returns the average of the double values of the provided numbers in the specified range as an {@code OptionalDouble}.
     * If the specified range is empty ({@code fromIndex == toIndex}, it returns an empty {@code OptionalDouble}.
     *
     * @param  the type of the elements in the collection, which must be a subtype of Number
     * @param c the collection of elements to evaluate
     * @param fromIndex the start index of the range, inclusive
     * @param toIndex the end index of the range, exclusive
     * @return the average of the double values of the provided numbers in the specified range as an {@code OptionalDouble} if the ranger is not empty, otherwise an empty {@code OptionalDouble}
     * @throws IndexOutOfBoundsException if the range is invalid: ({@code fromIndex < 0 || fromIndex > toIndex || toIndex > a.length})
     * @see N#averageDouble(Collection, int, int)
     */
    public static  OptionalDouble averageDouble(final Collection c, final int fromIndex, final int toIndex)
            throws IndexOutOfBoundsException {
        return averageDouble(c, fromIndex, toIndex, Fn.numToDouble());
    }

    /**
     * Returns the average of the double values extracted from the elements in the specified range by the input {@code func} function as an {@code OptionalDouble}.
     * If the specified range is empty ({@code fromIndex == toIndex}, it returns an empty {@code OptionalDouble}.
     *
     * @param  the type of the elements in the collection
     * @param c the collection of elements to evaluate
     * @param fromIndex the start index of the range, inclusive
     * @param toIndex the end index of the range, exclusive
     * @param func the function to extract a double value from each element
     * @return the average of the double values of the provided numbers in the specified range as an {@code OptionalDouble} if the ranger is not empty, otherwise an empty {@code OptionalDouble}
     * @throws IndexOutOfBoundsException if the range is invalid: ({@code fromIndex < 0 || fromIndex > toIndex || toIndex > a.length})
     * @see N#averageDouble(Object[], int, int, ToDoubleFunction)
     */
    public static  OptionalDouble averageDouble(final Collection c, final int fromIndex, final int toIndex,
            final ToDoubleFunction func) throws IndexOutOfBoundsException {
        N.checkFromToIndex(fromIndex, toIndex, N.size(c));

        if (fromIndex == toIndex) {
            return OptionalDouble.empty();
        }

        final KahanSummation summation = new KahanSummation();

        if (c instanceof List && c instanceof RandomAccess) {
            final List list = (List) c;

            for (int i = fromIndex; i < toIndex; i++) {
                summation.add(func.applyAsDouble(list.get(i)));
            }
        } else {
            int idx = 0;

            for (final T e : c) {
                if (idx++ < fromIndex) {
                    continue;
                }

                summation.add(func.applyAsDouble(e));

                if (idx >= toIndex) {
                    break;
                }
            }
        }

        return summation.average();
    }

    /**
     * Returns the average of the double values of the provided numbers as an {@code OptionalDouble}.
     * If the iterable is {@code null} or empty, it returns an empty {@code OptionalDouble}.
     *
     * @param  the type of the elements in the iterable, which must be a subtype of Number
     * @param c the iterable of elements to evaluate
     * @return the average of the double values if the iterable is not {@code null} or empty, otherwise an empty {@code OptionalDouble}
     * @see N#averageDouble(Iterable)
     */
    public static  OptionalDouble averageDouble(final Iterable c) {
        return averageDouble(c, Fn.numToDouble());
    }

    /**
     * Returns the average of the double values extracted from the elements in the provided iterable by the input {@code func} function as an {@code OptionalDouble}.
     * If the iterable is {@code null} or empty, it returns an empty {@code OptionalDouble}.
     *
     * @param  the type of the elements in the iterable
     * @param c the iterable of elements to evaluate
     * @param func the function to extract a double value from each element
     * @return the average of the double values if the iterable is not {@code null} or empty, otherwise an empty {@code OptionalDouble}
     * @see N#averageDouble(Iterable, ToDoubleFunction)
     */
    public static  OptionalDouble averageDouble(final Iterable c, final ToDoubleFunction func) {
        if (c == null) {
            return OptionalDouble.empty();
        }

        final KahanSummation summation = new KahanSummation();

        for (final T e : c) {
            summation.add(func.applyAsDouble(e));
        }

        return summation.average();
    }

    /**
     * Returns the average of the BigInteger values of the provided numbers as an {@code Optional}.
     * If the iterable is {@code null} or empty, it returns an empty {@code Optional}.
     *
     * @param c the iterable of elements to evaluate
     * @return the average of the BigInteger values if the iterable is not {@code null} or empty, otherwise an empty {@code Optional}
     * @see N#averageBigInteger(Iterable)
     */
    public static Optional averageBigInteger(final Iterable c) {
        return averageBigInteger(c, Fn.identity());
    }

    /**
     * Returns the average of the BigInteger values extracted from the elements in the provided iterable by the input {@code func} function as an {@code Optional}.
     * If the iterable is {@code null} or empty, it returns an empty {@code Optional}.
     *
     * @param  the type of the elements in the iterable
     * @param c the iterable of elements to evaluate
     * @param func the function to extract a BigInteger value from each element
     * @return the average of the BigInteger values if the iterable is not {@code null} or empty, otherwise an empty {@code Optional}
     * @see N#averageBigInteger(Iterable, Function)
     */
    public static  Optional averageBigInteger(final Iterable c, final Function func) {
        final Iterator iter = c == null ? ObjIterator.empty() : c.iterator();

        if (!iter.hasNext()) {
            return Optional.empty();
        }

        return Optional.of(N.averageBigInteger(c, func));
    }

    /**
     * Returns the average of the BigDecimal values of the provided numbers as an {@code Optional}.
     * If the iterable is {@code null} or empty, it returns an empty {@code Optional}.
     *
     * @param c the iterable of elements to evaluate
     * @return the average of the BigDecimal values if the iterable is not {@code null} or empty, otherwise an empty {@code Optional}
     * @see N#averageBigDecimal(Iterable)
     */
    public static Optional averageBigDecimal(final Iterable c) {
        return averageBigDecimal(c, Fn.identity());
    }

    /**
     * Returns the average of the BigDecimal values extracted from the elements in the provided iterable by the input {@code func} function as an {@code Optional}.
     * If the iterable is {@code null} or empty, it returns an empty {@code Optional}.
     *
     * @param  the type of the elements in the iterable
     * @param c the iterable of elements to evaluate
     * @param func the function to extract a BigDecimal value from each element
     * @return the average of the BigDecimal values if the iterable is not {@code null} or empty, otherwise an empty {@code Optional}
     * @see N#averageBigDecimal(Iterable, Function)
     */
    public static  Optional averageBigDecimal(final Iterable c, final Function func) {
        final Iterator iter = c == null ? ObjIterator.empty() : c.iterator();

        if (!iter.hasNext()) {
            return Optional.empty();
        }

        return Optional.of(N.averageBigDecimal(c, func));
    }

    /**
     * Returns the index of the first occurrence of the specified value in the provided array as an {@code OptionalInt}.
     * If the array is {@code null} or doesn't contain the specified value, it returns an empty {@code OptionalInt}.
     *
     * @param a the array to search
     * @param valueToFind the value to find in the array
     * @return an {@code OptionalInt} containing the index of the first occurrence of the specified value if found, otherwise an empty {@code OptionalInt}
     * @see N#indexOf(Object[], Object)
     * @see Index#of(Object[], Object)
     */
    public static OptionalInt indexOf(final Object[] a, final Object valueToFind) {
        return Index.of(a, valueToFind);
    }

    /**
     * Returns the index of the first occurrence of the specified value in the provided collection as an {@code OptionalInt}.
     * If the collection is {@code null} or doesn't contain the specified value, it returns an empty {@code OptionalInt}.
     *
     * @param c the collection to search
     * @param valueToFind the value to find in the collection
     * @return an {@code OptionalInt} containing the index of the first occurrence of the specified value if found, otherwise an empty {@code OptionalInt}
     * @see N#indexOf(Collection, Object)
     * @see Index#of(Collection, Object)
     */
    public static OptionalInt indexOf(final Collection c, final Object valueToFind) {
        return Index.of(c, valueToFind);
    }

    /**
     * Returns the index of the last occurrence of the specified value in the provided array as an {@code OptionalInt}.
     * If the array is {@code null} or doesn't contain the specified value, it returns an empty {@code OptionalInt}.
     *
     * @param a the array to search
     * @param valueToFind the value to find in the array
     * @return an {@code OptionalInt} containing the index of the last occurrence of the specified value if found, otherwise an empty {@code OptionalInt}
     * @see N#lastIndexOf(Object[], Object)
     * @see Index#last(Object[], Object)
     */
    public static OptionalInt lastIndexOf(final Object[] a, final Object valueToFind) {
        return Index.last(a, valueToFind);
    }

    /**
     * Returns the index of the last occurrence of the specified value in the provided collection as an {@code OptionalInt}.
     * If the collection is {@code null} or doesn't contain the specified value, it returns an empty {@code OptionalInt}.
     *
     * @param c the collection to search
     * @param valueToFind the value to find in the collection
     * @return an {@code OptionalInt} containing the index of the last occurrence of the specified value if found, otherwise an empty {@code OptionalInt}
     * @see N#lastIndexOf(Collection, Object)
     * @see Index#last(Collection, Object)
     */
    public static OptionalInt lastIndexOf(final Collection c, final Object valueToFind) {
        return Index.last(c, valueToFind);
    }

    /**
     * Returns the first element in the provided array that satisfies the given {@code predicateForFirst},
     * or if no such element is found, returns the last element that satisfies the {@code predicateForLast}.
     * If the array is {@code null} or doesn't contain any element that satisfies the predicates, it returns an empty {@code Nullable}.
     *
     * @param  the type of the elements in the array
     * @param a the array to search
     * @param predicateForFirst the predicate to test for the first element
     * @param predicateForLast the predicate to test for the last element
     * @return a {@code Nullable} containing the first element satisfying {@code predicateForFirst} if found,
     *         otherwise the last element satisfying {@code predicateForLast} if found, otherwise an empty {@code Nullable}
     * @see N#findFirst(Object[], Predicate)
     * @see N#findLast(Object[], Predicate)
     */
    public static  Nullable findFirstOrLast(final T[] a, final Predicate predicateForFirst, final Predicate predicateForLast) {
        if (N.isEmpty(a)) {
            return Nullable.empty();
        }

        final Nullable res = N.findFirst(a, predicateForFirst);

        return res.isPresent() ? res : N.findLast(a, predicateForLast);
    }

    /**
     * Returns the first element in the provided collection that satisfies the given {@code predicateForFirst},
     * or if no such element is found, returns the last element that satisfies the {@code predicateForLast}.
     * If the collection is {@code null} or doesn't contain any element that satisfies the predicates, it returns an empty {@code Nullable}.
     *
     * @param  the type of the elements in the collection
     * @param c the collection to search
     * @param predicateForFirst the predicate to test for the first element
     * @param predicateForLast the predicate to test for the last element
     * @return a {@code Nullable} containing the first element satisfying {@code predicateForFirst} if found,
     *         otherwise the last element satisfying {@code predicateForLast} if found, otherwise an empty {@code Nullable}
     * @see N#findFirst(Iterable, Predicate)
     * @see N#findLast(Iterable, Predicate)
     */
    public static  Nullable findFirstOrLast(final Collection c, final Predicate predicateForFirst,
            final Predicate predicateForLast) {
        if (N.isEmpty(c)) {
            return Nullable.empty();
        }

        final Nullable res = N.findFirst(c, predicateForFirst);

        return res.isPresent() ? res : N.findLast(c, predicateForLast);
    }

    /**
     * Returns the index of the first element in the provided array that satisfies the given {@code predicateForFirst},
     * or if no such element is found, returns the index of the last element that satisfies the {@code predicateForLast}.
     * If the array is {@code null} or doesn't contain any element that satisfies the predicates, it returns an empty {@code OptionalInt}.
     *
     * @param  the type of the elements in the array
     * @param a the array to search
     * @param predicateForFirst the predicate to test for the first element
     * @param predicateForLast the predicate to test for the last element
     * @return an {@code OptionalInt} containing the index of the first element satisfying {@code predicateForFirst} if found,
     *         otherwise the index of the last element satisfying {@code predicateForLast} if found, otherwise an empty {@code OptionalInt}
     * @see N#findFirstIndex(Object[], Predicate)
     * @see N#findLastIndex(Object[], Predicate)
     */
    public static  OptionalInt findFirstOrLastIndex(final T[] a, final Predicate predicateForFirst, final Predicate predicateForLast) {
        if (N.isEmpty(a)) {
            return OptionalInt.empty();
        }

        final OptionalInt res = N.findFirstIndex(a, predicateForFirst);

        return res.isPresent() ? res : N.findLastIndex(a, predicateForLast);
    }

    /**
     * Returns the index of the first element in the provided collection that satisfies the given {@code predicateForFirst},
     * or if no such element is found, returns the index of the last element that satisfies the {@code predicateForLast}.
     * If the collection is {@code null} or doesn't contain any element that satisfies the predicates, it returns an empty {@code OptionalInt}.
     *
     * @param  the type of the elements in the collection
     * @param c the collection to search
     * @param predicateForFirst the predicate to test for the first element
     * @param predicateForLast the predicate to test for the last element
     * @return an {@code OptionalInt} containing the index of the first element satisfying {@code predicateForFirst} if found,
     *         otherwise the index of the last element satisfying {@code predicateForLast} if found, otherwise an empty {@code OptionalInt}
     * @see N#findFirstIndex(Collection, Predicate)
     * @see N#findLastIndex(Collection, Predicate)
     */
    public static  OptionalInt findFirstOrLastIndex(final Collection c, final Predicate predicateForFirst,
            final Predicate predicateForLast) {
        if (N.isEmpty(c)) {
            return OptionalInt.empty();
        }

        final OptionalInt res = N.findFirstIndex(c, predicateForFirst);

        return res.isPresent() ? res : N.findLastIndex(c, predicateForLast);
    }

    /**
     * Returns a pair of {@code Nullable} objects containing the first and last elements in the provided array that satisfy the given {@code predicate}.
     * If the array is {@code null} or doesn't contain any element that satisfies the predicate, it returns a pair of empty {@code Nullable} objects.
     *
     * @param  the type of the elements in the array
     * @param a the array to search
     * @param predicate the predicate to test for the first and last elements
     * @return a {@code Pair} containing a {@code Nullable} for the first element satisfying {@code predicate} if found and a {@code Nullable} for the last element satisfying {@code predicate} if found,
     *         otherwise a {@code Pair} of empty {@code Nullable} objects
     * @see #findFirstAndLast(Object[], Predicate, Predicate)
     * @see #findFirstOrLast(Object[], Predicate, Predicate)
     * @see N#findFirst(Object[], Predicate)
     * @see N#findLast(Object[], Predicate)
     */
    public static  Pair, Nullable> findFirstAndLast(final T[] a, final Predicate predicate) {
        return findFirstAndLast(a, predicate, predicate);
    }

    /**
     * Returns a pair of {@code Nullable} objects containing the first and last elements in the provided array that satisfy the given predicates.
     * If the array is {@code null} or doesn't contain any element that satisfies the predicates, it returns a pair of empty {@code Nullable} objects.
     *
     * @param  the type of the elements in the array
     * @param a the array to search
     * @param predicateForFirst the predicate to test for the first element
     * @param predicateForLast the predicate to test for the last element
     * @return a {@code Pair} containing a {@code Nullable} for the first element satisfying {@code predicateForFirst} if found and a {@code Nullable} for the last element satisfying {@code predicateForLast} if found,
     *         otherwise a {@code Pair} of empty {@code Nullable} objects
     * @see #findFirstAndLast(Object[], Predicate)
     * @see #findFirstOrLast(Object[], Predicate, Predicate)
     * @see N#findFirst(Object[], Predicate)
     * @see N#findLast(Object[], Predicate)
     */
    public static  Pair, Nullable> findFirstAndLast(final T[] a, final Predicate predicateForFirst,
            final Predicate predicateForLast) {
        if (N.isEmpty(a)) {
            return Pair.of(Nullable.empty(), Nullable.empty());
        }

        return Pair.of(N.findFirst(a, predicateForFirst), N.findLast(a, predicateForLast));
    }

    /**
     * Returns a pair of {@code Nullable} objects containing the first and last elements in the provided collection that satisfy the given {@code predicate}.
     * If the collection is {@code null} or doesn't contain any element that satisfies the predicate, it returns a pair of empty {@code Nullable} objects.
     *
     * @param  the type of the elements in the collection
     * @param c the collection to search
     * @param predicate the predicate to test for the first and last elements
     * @return a {@code Pair} containing a {@code Nullable} for the first element satisfying {@code predicate} if found and a {@code Nullable} for the last element satisfying {@code predicate} if found,
     *         otherwise a {@code Pair} of empty {@code Nullable} objects
     * @see #findFirstAndLast(Collection, Predicate, Predicate)
     * @see #findFirstOrLast(Collection, Predicate, Predicate)
     * @see N#findFirst(Iterable, Predicate)
     * @see N#findLast(Iterable, Predicate)
     */
    public static  Pair, Nullable> findFirstAndLast(final Collection c, final Predicate predicate) {
        return findFirstAndLast(c, predicate, predicate);
    }

    /**
     * Returns a pair of {@code Nullable} objects containing the first and last elements in the provided collection that satisfy the given predicates.
     * If the collection is {@code null} or doesn't contain any element that satisfies the predicates, it returns a pair of empty {@code Nullable} objects.
     *
     * @param  the type of the elements in the collection
     * @param c the collection to search
     * @param predicateForFirst the predicate to test for the first element
     * @param predicateForLast the predicate to test for the last element
     * @return a {@code Pair} containing a {@code Nullable} for the first element satisfying {@code predicateForFirst} if found and a {@code Nullable} for the last element satisfying {@code predicateForLast} if found,
     *         otherwise a {@code Pair} of empty {@code Nullable} objects
     * @see #findFirstAndLast(Collection, Predicate)
     * @see #findFirstOrLast(Collection, Predicate, Predicate)
     * @see N#findFirst(Iterable, Predicate)
     * @see N#findLast(Iterable, Predicate)
     */
    public static  Pair, Nullable> findFirstAndLast(final Collection c, final Predicate predicateForFirst,
            final Predicate predicateForLast) {
        if (N.isEmpty(c)) {
            return Pair.of(Nullable.empty(), Nullable.empty());
        }

        return Pair.of(N.findFirst(c, predicateForFirst), N.findLast(c, predicateForLast));
    }

    /**
     * Returns a pair of OptionalInt objects containing the indices of the first and last elements in the provided array that satisfy the given {@code predicate}.
     * If the array is {@code null} or doesn't contain any element that satisfies the predicate, it returns a pair of empty {@code OptionalInt} objects.
     *
     * @param  the type of the elements in the array
     * @param a the array to search
     * @param predicate the predicate to test for the first and last elements
     * @return a {@code Pair} containing an {@code OptionalInt} for the index of the first element satisfying {@code predicate} if found and an {@code OptionalInt} for the index of the last element satisfying {@code predicate} if found,
     *         otherwise a {@code Pair} of empty {@code OptionalInt} objects
     * @see #findFirstAndLastIndex(Object[], Predicate, Predicate)
     * @see #findFirstOrLastIndex(Object[], Predicate, Predicate)
     * @see N#findFirstIndex(Object[], Predicate)
     * @see N#findLastIndex(Object[], Predicate)
     */
    public static  Pair findFirstAndLastIndex(final T[] a, final Predicate predicate) {
        return findFirstAndLastIndex(a, predicate, predicate);
    }

    /**
     * Returns a pair of OptionalInt objects containing the indices of the first and last elements in the provided array that satisfy the given predicates.
     * If the array is {@code null} or doesn't contain any element that satisfies the predicates, it returns a pair of empty {@code OptionalInt} objects.
     *
     * @param  the type of the elements in the array
     * @param a the array to search
     * @param predicateForFirst the predicate to test for the first element
     * @param predicateForLast the predicate to test for the last element
     * @return a {@code Pair} containing an {@code OptionalInt} for the index of the first element satisfying {@code predicateForFirst} if found and an {@code OptionalInt} for the index of the last element satisfying {@code predicateForLast} if found,
     *         otherwise a {@code Pair} of empty {@code OptionalInt} objects
     * @see #findFirstAndLastIndex(Object[], Predicate)
     * @see #findFirstOrLastIndex(Object[], Predicate, Predicate)
     * @see N#findFirstIndex(Object[], Predicate)
     * @see N#findLastIndex(Object[], Predicate)
     */
    public static  Pair findFirstAndLastIndex(final T[] a, final Predicate predicateForFirst,
            final Predicate predicateForLast) {
        if (N.isEmpty(a)) {
            return Pair.of(OptionalInt.empty(), OptionalInt.empty());
        }

        return Pair.of(N.findFirstIndex(a, predicateForFirst), N.findLastIndex(a, predicateForLast));
    }

    /**
     * Returns a pair of OptionalInt objects containing the indices of the first and last elements in the provided collection that satisfy the given {@code predicate}.
     * If the collection is {@code null} or doesn't contain any element that satisfies the predicate, it returns a pair of empty {@code OptionalInt} objects.
     *
     * @param  the type of the elements in the collection
     * @param c the collection to search
     * @param predicate the predicate to test for the first and last elements
     * @return a {@code Pair} containing an {@code OptionalInt} for the index of the first element satisfying {@code predicate} if found and an {@code OptionalInt} for the index of the last element satisfying {@code predicate} if found,
     *         otherwise a {@code Pair} of empty {@code OptionalInt} objects
     * @see #findFirstAndLastIndex(Collection, Predicate, Predicate)
     * @see #findFirstOrLastIndex(Collection, Predicate, Predicate)
     * @see N#findFirstIndex(Collection, Predicate)
     * @see N#findLastIndex(Collection, Predicate)
     */
    public static  Pair findFirstAndLastIndex(final Collection c, final Predicate predicate) {
        return findFirstAndLastIndex(c, predicate, predicate);
    }

    /**
     * Returns a pair of OptionalInt objects containing the indices of the first and last elements in the provided collection that satisfy the given predicates.
     * If the collection is {@code null} or doesn't contain any element that satisfies the predicates, it returns a pair of empty {@code OptionalInt} objects.
     *
     * @param  the type of the elements in the collection
     * @param c the collection to search
     * @param predicateForFirst the predicate to test for the first element
     * @param predicateForLast the predicate to test for the last element
     * @return a {@code Pair} containing an {@code OptionalInt} for the index of the first element satisfying {@code predicateForFirst} if found and an {@code OptionalInt} for the index of the last element satisfying {@code predicateForLast} if found,
     *         otherwise a {@code Pair} of empty {@code OptionalInt} objects
     * @see #findFirstAndLastIndex(Collection, Predicate)
     * @see #findFirstOrLastIndex(Collection, Predicate, Predicate)
     * @see N#findFirstIndex(Collection, Predicate)
     * @see N#findLastIndex(Collection, Predicate)
     */
    public static  Pair findFirstAndLastIndex(final Collection c, final Predicate predicateForFirst,
            final Predicate predicateForLast) {
        if (N.isEmpty(c)) {
            return Pair.of(OptionalInt.empty(), OptionalInt.empty());
        }

        return Pair.of(N.findFirstIndex(c, predicateForFirst), N.findLastIndex(c, predicateForLast));
    }

    /**
     * Fills the specified Object array with the values provided by the specified supplier.
     *
     * @param a the Object array to be filled
     * @param supplier provider of the value to fill the array with
     * @see Arrays#fill(Object[], Object)
     * @see N#setAll(Object[], IntFunction)
     * @see N#replaceAll(Object[], UnaryOperator) 
     * @see N#fill(Object[], Object)
     * @see N#fill(Object[], int, int, Object)
     */
    @Beta
    public static  void fill(final T[] a, final Supplier supplier) {
        if (N.isEmpty(a)) {
            return;
        }

        for (int i = 0, len = a.length; i < len; i++) {
            a[i] = supplier.get();
        }
    }

    /**
     * Fills the specified Object array with the values provided by the specified supplier from the specified fromIndex (inclusive) to the specified toIndex (exclusive).
     *
     * @param a the Object array to be filled
     * @param fromIndex the index to start filling (inclusive)
     * @param toIndex the index to stop filling (exclusive)
     * @param supplier provider of the value to fill the array with
     * @throws IndexOutOfBoundsException if the fromIndex or toIndex is out of bounds
     * @see Arrays#fill(Object[], int, int, Object)
     * @see N#fill(Object[], Object)
     * @see N#fill(Object[], int, int, Object)
     */
    @Beta
    public static  void fill(final T[] a, final int fromIndex, final int toIndex, final Supplier supplier) {
        N.checkFromToIndex(fromIndex, toIndex, N.len(a));

        if (fromIndex == toIndex) {
            return;
        }

        for (int i = fromIndex; i < toIndex; i++) {
            a[i] = supplier.get();
        }
    }

    /**
     * Fills the specified list with values provided by the specified supplier.
     *
     * @param  the type of elements in the list
     * @param list the list to be filled
     * @param supplier provider of the value to fill the list with
     * @throws IllegalArgumentException if the specified list is null
     * @see N#fill(List, Object)
     * @see N#fill(List, int, int, Object)
     * @see N#setAll(List, java.util.function.IntFunction)
     * @see N#replaceAll(List, java.util.function.UnaryOperator) 
     * @see N#padLeft(List, int, Object)
     * @see N#padRight(Collection, int, Object)
     */
    @Beta
    public static  void fill(final List list, final Supplier supplier) throws IllegalArgumentException {
        N.checkArgNotNull(list, cs.list);

        fill(list, 0, list.size(), supplier);
    }

    /**
     * Fills the specified list with the specified with values provided by the specified supplier from the specified start index to the specified end index.
     * The list will be extended automatically if the size of the list is less than the specified toIndex.
     *
     * @param  the type of elements in the list
     * @param list the list to be filled
     * @param fromIndex the starting index (inclusive) to begin filling
     * @param toIndex the ending index (exclusive) to stop filling
     * @param supplier provider of the value to fill the list with
     * @throws IllegalArgumentException if the specified list is null
     * @throws IndexOutOfBoundsException if the specified indices are out of range
     * @see N#fill(List, Object)
     * @see N#fill(List, int, int, Object)
     * @see N#setAll(List, java.util.function.IntFunction)
     * @see N#replaceAll(List, java.util.function.UnaryOperator)
     * @see N#padLeft(List, int, Object)
     * @see N#padRight(Collection, int, Object)
     */
    @Beta
    public static  void fill(final List list, final int fromIndex, final int toIndex, final Supplier supplier)
            throws IllegalArgumentException, IndexOutOfBoundsException {
        N.checkArgNotNull(list, cs.list);
        N.checkFromToIndex(fromIndex, toIndex, Integer.MAX_VALUE);

        final int size = list.size();

        if (size < toIndex) {
            if (fromIndex < size) {
                for (int i = fromIndex; i < size; i++) {
                    list.set(i, supplier.get());
                }
            } else {
                for (int i = size; i < fromIndex; i++) {
                    list.add(null);
                }
            }

            for (int i = 0, len = toIndex - list.size(); i < len; i++) {
                list.add(supplier.get());
            }
        } else {
            if (toIndex - fromIndex < CommonUtil.FILL_THRESHOLD || list instanceof RandomAccess) {
                for (int i = fromIndex; i < toIndex; i++) {
                    list.set(i, supplier.get());
                }
            } else {
                final ListIterator itr = list.listIterator(fromIndex);

                for (int i = fromIndex; i < toIndex; i++) {
                    itr.next();

                    itr.set(supplier.get());
                }
            }
        }
    }

    /**
     * 
Copied from Google Guava under Apache License v2.0 and may be modified.
     *
     * Returns a reversed view of the specified list. For example, {@code
     * reverse(Arrays.asList(1, 2, 3))} returns a list containing {@code 3, 2, 1}. The returned
     * list is backed by this list, so changes in the returned list are reflected in this list, and
     * vice versa. The returned list supports all the optional list operations supported by this
     * list.
     *
     * 
The returned list is random-access if the specified list is random access.
     *
     * @param  the type of elements in the list
     * @param list the list to be reversed
     * @return a reversed view of the specified list
     * @see N#reverse(List)
     * @see N#reverse(Collection)
     * @see N#reverseToList(Collection)
     */
    public static  List reverse(final List list) {
        if (list instanceof ImmutableList) {
            // Avoid nullness warnings.
            final List reversed = ((ImmutableList) list).reverse();
            return (List) reversed;
        } else if (list instanceof ReverseList) {
            return ((ReverseList) list).getForwardList();
        } else if (list instanceof RandomAccess) {
            return new RandomAccessReverseList<>(list);
        } else {
            return new ReverseList<>(list);
        }
    }

    // Copied from Google Guava under Apache License v2.0 and may be modified.
    private static sealed class ReverseList extends AbstractList permits RandomAccessReverseList {
        private final List forwardList;

        ReverseList(final List forwardList) {
            this.forwardList = N.checkArgNotNull(forwardList);
        }

        List getForwardList() {
            return forwardList;
        }

        private int reverseIndex(final int index) {
            final int size = size();
            N.checkElementIndex(index, size);
            return (size - 1) - index;
        }

        private int reversePosition(final int index) {
            final int size = size();
            N.checkPositionIndex(index, size);
            return size - index;
        }

        @Override
        public void add(final int index, final T element) {
            forwardList.add(reversePosition(index), element);
        }

        @Override
        public void clear() {
            forwardList.clear();
        }

        @Override
        public T remove(final int index) {
            return forwardList.remove(reverseIndex(index));
        }

        @Override
        protected void removeRange(final int fromIndex, final int toIndex) {
            subList(fromIndex, toIndex).clear();
        }

        @Override
        public T set(final int index, final T element) {
            return forwardList.set(reverseIndex(index), element);
        }

        @Override
        public T get(final int index) {
            return forwardList.get(reverseIndex(index));
        }

        @Override
        public int size() {
            return forwardList.size();
        }

        @Override
        public List subList(final int fromIndex, final int toIndex) {
            N.checkFromToIndex(fromIndex, toIndex, size());
            return reverse(forwardList.subList(reversePosition(toIndex), reversePosition(fromIndex)));
        }

        @Override
        public Iterator iterator() {
            return listIterator();
        }

        @Override
        public ListIterator listIterator(final int index) {
            final int start = reversePosition(index);
            final ListIterator forwardIterator = forwardList.listIterator(start);

            return new ListIterator<>() {
                boolean canRemoveOrSet;

                @Override
                public void add(final T e) {
                    forwardIterator.add(e);
                    forwardIterator.previous();
                    canRemoveOrSet = false;
                }

                @Override
                public boolean hasNext() {
                    return forwardIterator.hasPrevious();
                }

                @Override
                public boolean hasPrevious() {
                    return forwardIterator.hasNext();
                }

                @Override
                public T next() {
                    if (!hasNext()) {
                        throw new NoSuchElementException();
                    }

                    canRemoveOrSet = true;
                    return forwardIterator.previous();
                }

                @Override
                public int nextIndex() {
                    return reversePosition(forwardIterator.nextIndex());
                }

                @Override
                public T previous() {
                    if (!hasPrevious()) {
                        throw new NoSuchElementException();
                    }

                    canRemoveOrSet = true;

                    return forwardIterator.next();
                }

                @Override
                public int previousIndex() {
                    return nextIndex() - 1;
                }

                @Override
                public void remove() {
                    checkRemove(canRemoveOrSet);
                    forwardIterator.remove();
                    canRemoveOrSet = false;
                }

                @Override
                public void set(final T e) {
                    N.checkState(canRemoveOrSet);
                    forwardIterator.set(e);
                }
            };
        }
    }

    // Copied from Google Guava under Apache License v2.0 and may be modified.
    private static final class RandomAccessReverseList extends ReverseList implements RandomAccess {
        RandomAccessReverseList(final List forwardList) {
            super(forwardList);
        }
    }

    static void checkRemove(final boolean canRemove) {
        N.checkState(canRemove, "no calls to next() since the last call to remove()");
    }

    public abstract static class SetView extends ImmutableSet {
        SetView(final Set set) {
            super(set);
        }

        /**
         *
         * @param 
         * @param set
         * @return
         */
        public > S copyInto(final S set) {
            set.addAll(this);
            return set;
        }
    }

    /**
     * Returns an unmodifiable view of the union of two sets. The returned set contains all
     * elements that are contained in either backing set. Iterating over the returned set iterates
     * first over all the elements of {@code set1}, then over each element of {@code set2}, in order,
     * that is not contained in {@code set1}.
     *
     * 
Results are undefined if {@code set1} and {@code set2} are sets based on different
     * equivalence relations (as {@link HashSet}, {@link TreeSet}, and the {@link Map#keySet} of an
     * {@code IdentityHashMap} all are).
     *
     * @param 
     * @param set1
     * @param set2
     * @return
     * @throws IllegalArgumentException
     */
    public static  SetView union(final Set set1, final Set set2) throws IllegalArgumentException {
        // N.checkArgNotNull(set1, "set1");
        // N.checkArgNotNull(set2, "set2");

        Set tmp = null;

        if (N.isEmpty(set1)) {
            tmp = N.isEmpty(set2) ? N.emptySet() : set2;
        } else if (N.isEmpty(set2)) {
            tmp = set1;
        } else {
            tmp = new AbstractSet<>() {
                @Override
                public ObjIterator iterator() {
                    return new ObjIterator<>() {
                        private final Iterator iter1 = set1.iterator();
                        private final Iterator iter2 = set2.iterator();
                        private final E NONE = (E) N.NULL_MASK; //NOSONAR
                        private E next = NONE;
                        private E tmp = null;

                        @Override
                        public boolean hasNext() {
                            if (iter1.hasNext() || next != NONE) {
                                return true;
                            }

                            while (iter2.hasNext()) {
                                next = iter2.next();

                                if (!set1.contains(next)) {
                                    return true;
                                }
                            }

                            next = NONE;

                            return false;
                        }

                        @Override
                        public E next() {
                            if (!hasNext()) {
                                throw new NoSuchElementException(InternalUtil.ERROR_MSG_FOR_NO_SUCH_EX);
                            }

                            if (iter1.hasNext()) {
                                return iter1.next();
                            } else {
                                tmp = next;
                                next = NONE;
                                return tmp;
                            }
                        }
                    };
                }

                @Override
                public boolean contains(final Object object) {
                    return set1.contains(object) || set2.contains(object);
                }

                @Override
                public int size() {
                    int size = set1.size();

                    for (final E e : set2) {
                        if (!set1.contains(e)) {
                            size++;
                        }
                    }

                    return size;
                }

                @Override
                public boolean isEmpty() {
                    return set1.isEmpty() && set2.isEmpty();
                }
            };
        }

        return new SetView<>(tmp) {
            @Override
            public > S copyInto(final S set) {
                set.addAll(set1);
                set.addAll(set2);
                return set;
            }
        };
    }

    /**
     * Returns an unmodifiable view of the intersection of two sets. The returned set contains
     * all elements that are contained by both backing sets. The iteration order of the returned set
     * matches that of {@code set1}.
     *
     * 
Results are undefined if {@code set1} and {@code set2} are sets based on different
     * equivalence relations (as {@code HashSet}, {@code TreeSet}, and the keySet of an {@code
     * IdentityHashMap} all are).
     *
     * 
Note: The returned view performs slightly better when {@code set1} is the smaller of
     * the two sets. If you have reason to believe one of your sets will generally be smaller than the
     * other, pass it first. Unfortunately, since this method sets the generic type of the returned
     * set based on the type of the first set passed, this could in rare cases force you to make a
     * cast, for example:
     *
     * 
{@code
     * Set