/*

 * Copyright (c) 2013, Oracle and/or its affiliates. All rights reserved.

 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.

 *

 * This code is free software; you can redistribute it and/or modify it

 * under the terms of the GNU General Public License version 2 only, as

 * published by the Free Software Foundation.  Oracle designates this

 * particular file as subject to the "Classpath" exception as provided

 * by Oracle in the LICENSE file that accompanied this code.

 *

 * This code is distributed in the hope that it will be useful, but WITHOUT

 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or

 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License

 * version 2 for more details (a copy is included in the LICENSE file that

 * accompanied this code).

 *

 * You should have received a copy of the GNU General Public License version

 * 2 along with this work; if not, write to the Free Software Foundation,

 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.

 *

 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA

 * or visit www.oracle.com if you need additional information or have any

 * questions.

 */

package java.util;

import java.util.function.Consumer;

import java.util.function.DoubleConsumer;

import java.util.function.IntConsumer;

import java.util.function.LongConsumer;

/**

 * Static classes and methods for operating on or creating instances of

 * {@link Spliterator} and its primitive specializations

 * {@link Spliterator.OfInt}, {@link Spliterator.OfLong}, and

 * {@link Spliterator.OfDouble}.

 *

 * @see Spliterator

 * @since 1.8

 */

public final class Spliterators {

    // Suppresses default constructor, ensuring non-instantiability.

    private Spliterators() {}

    // Empty spliterators

    /**

     * Creates an empty {@code Spliterator}

     *

     * <p>The empty spliterator reports {@link Spliterator#SIZED} and

     * {@link Spliterator#SUBSIZED}.  Calls to

     * {@link java.util.Spliterator#trySplit()} always return {@code null}.

     *

     * @param <T> Type of elements

     * @return An empty spliterator

     */

    @SuppressWarnings("unchecked")

    public static <T> Spliterator<T> emptySpliterator() {

        return (Spliterator<T>) EMPTY_SPLITERATOR;

    }

    private static final Spliterator<Object> EMPTY_SPLITERATOR =

            new EmptySpliterator.OfRef<>();

    /**

     * Creates an empty {@code Spliterator.OfInt}

     *

     * <p>The empty spliterator reports {@link Spliterator#SIZED} and

     * {@link Spliterator#SUBSIZED}.  Calls to

     * {@link java.util.Spliterator#trySplit()} always return {@code null}.

     *

     * @return An empty spliterator

     */

    public static Spliterator.OfInt emptyIntSpliterator() {

        return EMPTY_INT_SPLITERATOR;

    }

    private static final Spliterator.OfInt EMPTY_INT_SPLITERATOR =

            new EmptySpliterator.OfInt();

    /**

     * Creates an empty {@code Spliterator.OfLong}

     *

     * <p>The empty spliterator reports {@link Spliterator#SIZED} and

     * {@link Spliterator#SUBSIZED}.  Calls to

     * {@link java.util.Spliterator#trySplit()} always return {@code null}.

     *

     * @return An empty spliterator

     */

    public static Spliterator.OfLong emptyLongSpliterator() {

        return EMPTY_LONG_SPLITERATOR;

    }

    private static final Spliterator.OfLong EMPTY_LONG_SPLITERATOR =

            new EmptySpliterator.OfLong();

    /**

     * Creates an empty {@code Spliterator.OfDouble}

     *

     * <p>The empty spliterator reports {@link Spliterator#SIZED} and

     * {@link Spliterator#SUBSIZED}.  Calls to

     * {@link java.util.Spliterator#trySplit()} always return {@code null}.

     *

     * @return An empty spliterator

     */

    public static Spliterator.OfDouble emptyDoubleSpliterator() {

        return EMPTY_DOUBLE_SPLITERATOR;

    }

    private static final Spliterator.OfDouble EMPTY_DOUBLE_SPLITERATOR =

            new EmptySpliterator.OfDouble();

    // Array-based spliterators

    /**

     * Creates a {@code Spliterator} covering the elements of a given array,

     * using a customized set of spliterator characteristics.

     *

     * <p>This method is provided as an implementation convenience for

     * Spliterators which store portions of their elements in arrays, and need

     * fine control over Spliterator characteristics.  Most other situations in

     * which a Spliterator for an array is needed should use

     * {@link Arrays#spliterator(Object[])}.

     *

     * <p>The returned spliterator always reports the characteristics

     * {@code SIZED} and {@code SUBSIZED}.  The caller may provide additional

     * characteristics for the spliterator to report; it is common to

     * additionally specify {@code IMMUTABLE} and {@code ORDERED}.

     *

     * @param <T> Type of elements

     * @param array The array, assumed to be unmodified during use

     * @param additionalCharacteristics Additional spliterator characteristics

     *        of this spliterator's source or elements beyond {@code SIZED} and

     *        {@code SUBSIZED} which are are always reported

     * @return A spliterator for an array

     * @throws NullPointerException if the given array is {@code null}

     * @see Arrays#spliterator(Object[])

     */

    public static <T> Spliterator<T> spliterator(Object[] array,

                                                 int additionalCharacteristics) {

        return new ArraySpliterator<>(Objects.requireNonNull(array),

                                      additionalCharacteristics);

    }

    /**

     * Creates a {@code Spliterator} covering a range of elements of a given

     * array, using a customized set of spliterator characteristics.

     *

     * <p>This method is provided as an implementation convenience for

     * Spliterators which store portions of their elements in arrays, and need

     * fine control over Spliterator characteristics.  Most other situations in

     * which a Spliterator for an array is needed should use

     * {@link Arrays#spliterator(Object[])}.

     *

     * <p>The returned spliterator always reports the characteristics

     * {@code SIZED} and {@code SUBSIZED}.  The caller may provide additional

     * characteristics for the spliterator to report; it is common to

     * additionally specify {@code IMMUTABLE} and {@code ORDERED}.

     *

     * @param <T> Type of elements

     * @param array The array, assumed to be unmodified during use

     * @param fromIndex The least index (inclusive) to cover

     * @param toIndex One past the greatest index to cover

     * @param additionalCharacteristics Additional spliterator characteristics

     *        of this spliterator's source or elements beyond {@code SIZED} and

     *        {@code SUBSIZED} which are are always reported

     * @return A spliterator for an array

     * @throws NullPointerException if the given array is {@code null}

     * @throws ArrayIndexOutOfBoundsException if {@code fromIndex} is negative,

     *         {@code toIndex} is less than {@code fromIndex}, or

     *         {@code toIndex} is greater than the array size

     * @see Arrays#spliterator(Object[], int, int)

     */

    public static <T> Spliterator<T> spliterator(Object[] array, int fromIndex, int toIndex,

                                                 int additionalCharacteristics) {

        checkFromToBounds(Objects.requireNonNull(array).length, fromIndex, toIndex);

        return new ArraySpliterator<>(array, fromIndex, toIndex, additionalCharacteristics);

    }

    /**

     * Creates a {@code Spliterator.OfInt} covering the elements of a given array,

     * using a customized set of spliterator characteristics.

     *

     * <p>This method is provided as an implementation convenience for

     * Spliterators which store portions of their elements in arrays, and need

     * fine control over Spliterator characteristics.  Most other situations in

     * which a Spliterator for an array is needed should use

     * {@link Arrays#spliterator(int[])}.

     *

     * <p>The returned spliterator always reports the characteristics

     * {@code SIZED} and {@code SUBSIZED}.  The caller may provide additional

     * characteristics for the spliterator to report; it is common to

     * additionally specify {@code IMMUTABLE} and {@code ORDERED}.

     *

     * @param array The array, assumed to be unmodified during use

     * @param additionalCharacteristics Additional spliterator characteristics

     *        of this spliterator's source or elements beyond {@code SIZED} and

     *        {@code SUBSIZED} which are are always reported

     * @return A spliterator for an array

     * @throws NullPointerException if the given array is {@code null}

     * @see Arrays#spliterator(int[])

     */

    public static Spliterator.OfInt spliterator(int[] array,

                                                int additionalCharacteristics) {

        return new IntArraySpliterator(Objects.requireNonNull(array), additionalCharacteristics);

    }

    /**

     * Creates a {@code Spliterator.OfInt} covering a range of elements of a

     * given array, using a customized set of spliterator characteristics.

     *

     * <p>This method is provided as an implementation convenience for

     * Spliterators which store portions of their elements in arrays, and need

     * fine control over Spliterator characteristics.  Most other situations in

     * which a Spliterator for an array is needed should use

     * {@link Arrays#spliterator(int[], int, int)}.

     *

     * <p>The returned spliterator always reports the characteristics

     * {@code SIZED} and {@code SUBSIZED}.  The caller may provide additional

     * characteristics for the spliterator to report; it is common to

     * additionally specify {@code IMMUTABLE} and {@code ORDERED}.

     *

     * @param array The array, assumed to be unmodified during use

     * @param fromIndex The least index (inclusive) to cover

     * @param toIndex One past the greatest index to cover

     * @param additionalCharacteristics Additional spliterator characteristics

     *        of this spliterator's source or elements beyond {@code SIZED} and

     *        {@code SUBSIZED} which are are always reported

     * @return A spliterator for an array

     * @throws NullPointerException if the given array is {@code null}

     * @throws ArrayIndexOutOfBoundsException if {@code fromIndex} is negative,

     *         {@code toIndex} is less than {@code fromIndex}, or

     *         {@code toIndex} is greater than the array size

     * @see Arrays#spliterator(int[], int, int)

     */

    public static Spliterator.OfInt spliterator(int[] array, int fromIndex, int toIndex,

                                                int additionalCharacteristics) {

        checkFromToBounds(Objects.requireNonNull(array).length, fromIndex, toIndex);

        return new IntArraySpliterator(array, fromIndex, toIndex, additionalCharacteristics);

    }

    /**

     * Creates a {@code Spliterator.OfLong} covering the elements of a given array,

     * using a customized set of spliterator characteristics.

     *

     * <p>This method is provided as an implementation convenience for

     * Spliterators which store portions of their elements in arrays, and need

     * fine control over Spliterator characteristics.  Most other situations in

     * which a Spliterator for an array is needed should use

     * {@link Arrays#spliterator(long[])}.

     *

     * <p>The returned spliterator always reports the characteristics

     * {@code SIZED} and {@code SUBSIZED}.  The caller may provide additional

     * characteristics for the spliterator to report; it is common to

     * additionally specify {@code IMMUTABLE} and {@code ORDERED}.

     *

     * @param array The array, assumed to be unmodified during use

     * @param additionalCharacteristics Additional spliterator characteristics

     *        of this spliterator's source or elements beyond {@code SIZED} and

     *        {@code SUBSIZED} which are are always reported

     * @return A spliterator for an array

     * @throws NullPointerException if the given array is {@code null}

     * @see Arrays#spliterator(long[])

     */

    public static Spliterator.OfLong spliterator(long[] array,

                                                 int additionalCharacteristics) {

        return new LongArraySpliterator(Objects.requireNonNull(array), additionalCharacteristics);

    }

    /**

     * Creates a {@code Spliterator.OfLong} covering a range of elements of a

     * given array, using a customized set of spliterator characteristics.

     *

     * <p>This method is provided as an implementation convenience for

     * Spliterators which store portions of their elements in arrays, and need

     * fine control over Spliterator characteristics.  Most other situations in

     * which a Spliterator for an array is needed should use

     * {@link Arrays#spliterator(long[], int, int)}.

     *

     * <p>The returned spliterator always reports the characteristics

     * {@code SIZED} and {@code SUBSIZED}.  The caller may provide additional

     * characteristics for the spliterator to report.  (For example, if it is

     * known the array will not be further modified, specify {@code IMMUTABLE};

     * if the array data is considered to have an an encounter order, specify

     * {@code ORDERED}).  The method {@link Arrays#spliterator(long[], int, int)} can

     * often be used instead, which returns a spliterator that reports

     * {@code SIZED}, {@code SUBSIZED}, {@code IMMUTABLE}, and {@code ORDERED}.

     *

     * @param array The array, assumed to be unmodified during use

     * @param fromIndex The least index (inclusive) to cover

     * @param toIndex One past the greatest index to cover

     * @param additionalCharacteristics Additional spliterator characteristics

     *        of this spliterator's source or elements beyond {@code SIZED} and

     *        {@code SUBSIZED} which are are always reported

     * @return A spliterator for an array

     * @throws NullPointerException if the given array is {@code null}

     * @throws ArrayIndexOutOfBoundsException if {@code fromIndex} is negative,

     *         {@code toIndex} is less than {@code fromIndex}, or

     *         {@code toIndex} is greater than the array size

     * @see Arrays#spliterator(long[], int, int)

     */

    public static Spliterator.OfLong spliterator(long[] array, int fromIndex, int toIndex,

                                                 int additionalCharacteristics) {

        checkFromToBounds(Objects.requireNonNull(array).length, fromIndex, toIndex);

        return new LongArraySpliterator(array, fromIndex, toIndex, additionalCharacteristics);

    }

    /**

     * Creates a {@code Spliterator.OfDouble} covering the elements of a given array,

     * using a customized set of spliterator characteristics.

     *

     * <p>This method is provided as an implementation convenience for

     * Spliterators which store portions of their elements in arrays, and need

     * fine control over Spliterator characteristics.  Most other situations in

     * which a Spliterator for an array is needed should use

     * {@link Arrays#spliterator(double[])}.

     *

     * <p>The returned spliterator always reports the characteristics

     * {@code SIZED} and {@code SUBSIZED}.  The caller may provide additional

     * characteristics for the spliterator to report; it is common to

     * additionally specify {@code IMMUTABLE} and {@code ORDERED}.

     *

     * @param array The array, assumed to be unmodified during use

     * @param additionalCharacteristics Additional spliterator characteristics

     *        of this spliterator's source or elements beyond {@code SIZED} and

     *        {@code SUBSIZED} which are are always reported

     * @return A spliterator for an array

     * @throws NullPointerException if the given array is {@code null}

     * @see Arrays#spliterator(double[])

     */

    public static Spliterator.OfDouble spliterator(double[] array,

                                                   int additionalCharacteristics) {

        return new DoubleArraySpliterator(Objects.requireNonNull(array), additionalCharacteristics);

    }

    /**

     * Creates a {@code Spliterator.OfDouble} covering a range of elements of a

     * given array, using a customized set of spliterator characteristics.

     *

     * <p>This method is provided as an implementation convenience for

     * Spliterators which store portions of their elements in arrays, and need

     * fine control over Spliterator characteristics.  Most other situations in

     * which a Spliterator for an array is needed should use

     * {@link Arrays#spliterator(double[], int, int)}.

     *

     * <p>The returned spliterator always reports the characteristics

     * {@code SIZED} and {@code SUBSIZED}.  The caller may provide additional

     * characteristics for the spliterator to report.  (For example, if it is

     * known the array will not be further modified, specify {@code IMMUTABLE};

     * if the array data is considered to have an an encounter order, specify

     * {@code ORDERED}).  The method {@link Arrays#spliterator(long[], int, int)} can

     * often be used instead, which returns a spliterator that reports

     * {@code SIZED}, {@code SUBSIZED}, {@code IMMUTABLE}, and {@code ORDERED}.

     *

     * @param array The array, assumed to be unmodified during use

     * @param fromIndex The least index (inclusive) to cover

     * @param toIndex One past the greatest index to cover

     * @param additionalCharacteristics Additional spliterator characteristics

     *        of this spliterator's source or elements beyond {@code SIZED} and

     *        {@code SUBSIZED} which are are always reported

     * @return A spliterator for an array

     * @throws NullPointerException if the given array is {@code null}

     * @throws ArrayIndexOutOfBoundsException if {@code fromIndex} is negative,

     *         {@code toIndex} is less than {@code fromIndex}, or

     *         {@code toIndex} is greater than the array size

     * @see Arrays#spliterator(double[], int, int)

     */

    public static Spliterator.OfDouble spliterator(double[] array, int fromIndex, int toIndex,

                                                   int additionalCharacteristics) {

        checkFromToBounds(Objects.requireNonNull(array).length, fromIndex, toIndex);

        return new DoubleArraySpliterator(array, fromIndex, toIndex, additionalCharacteristics);

    }

    /**

     * Validate inclusive start index and exclusive end index against the length

     * of an array.

     * @param arrayLength The length of the array

     * @param origin The inclusive start index

     * @param fence The exclusive end index

     * @throws ArrayIndexOutOfBoundsException if the start index is greater than

     * the end index, if the start index is negative, or the end index is

     * greater than the array length

     */

    private static void checkFromToBounds(int arrayLength, int origin, int fence) {

        if (origin > fence) {

            throw new IllegalArgumentException(

                    "origin(" + origin + ") > fence(" + fence + ")");

        }

        if (origin < 0) {

            throw new ArrayIndexOutOfBoundsException(origin);

        }

        if (fence > arrayLength) {

            throw new ArrayIndexOutOfBoundsException(fence);

        }

    }

    // Iterator-based spliterators

    /**

     * Creates a {@code Spliterator} using the given collection's

     * {@link java.util.Collection#iterator()} as the source of elements, and

     * reporting its {@link java.util.Collection#size()} as its initial size.

     *

     * <p>The spliterator is

     * <em><a href="Spliterator.html#binding">late-binding</a></em>, inherits

     * the <em>fail-fast</em> properties of the collection's iterator, and

     * implements {@code trySplit} to permit limited parallelism.

     *

     * @param <T> Type of elements

     * @param c The collection

     * @param additionalCharacteristics Additional spliterator characteristics

     *        of this spliterator's source or elements beyond {@code SIZED} and

     *        {@code SUBSIZED} which are are always reported

     * @return A spliterator from an iterator

     * @throws NullPointerException if the given collection is {@code null}

     */

    public static <T> Spliterator<T> spliterator(Collection<? extends T> c,

                                                 int additionalCharacteristics) {

        return new IteratorSpliterator<>(Objects.requireNonNull(c),

                                         additionalCharacteristics);

    }

    /**

     * Creates a {@code Spliterator} using a given {@code Iterator}

     * as the source of elements, and with a given initially reported size.

     *

     * <p>The spliterator is not

     * <em><a href="Spliterator.html#binding">late-binding</a></em>, inherits

     * the <em>fail-fast</em> properties of the iterator, and implements

     * {@code trySplit} to permit limited parallelism.

     *

     * <p>Traversal of elements should be accomplished through the spliterator.

     * The behaviour of splitting and traversal is undefined if the iterator is

     * operated on after the spliterator is returned, or the initially reported

     * size is not equal to the actual number of elements in the source.

     *

     * @param <T> Type of elements

     * @param iterator The iterator for the source

     * @param size The number of elements in the source, to be reported as

     *        initial {@code estimateSize}

     * @param additionalCharacteristics Additional spliterator characteristics

     *        of this spliterator's source or elements beyond {@code SIZED} and

     *        {@code SUBSIZED} which are are always reported

     * @return A spliterator from an iterator

     * @throws NullPointerException if the given iterator is {@code null}

     */

    public static <T> Spliterator<T> spliterator(Iterator<? extends T> iterator,

                                                 long size,

                                                 int additionalCharacteristics) {

        return new IteratorSpliterator<>(Objects.requireNonNull(iterator), size,

                                         additionalCharacteristics);

    }

    /**

     * Creates a {@code Spliterator} using a given {@code Iterator}

     * as the source of elements, with no initial size estimate.

     *

     * <p>The spliterator is not

     * <em><a href="Spliterator.html#binding">late-binding</a></em>, inherits

     * the <em>fail-fast</em> properties of the iterator, and implements

     * {@code trySplit} to permit limited parallelism.

     *

     * <p>Traversal of elements should be accomplished through the spliterator.

     * The behaviour of splitting and traversal is undefined if the iterator is

     * operated on after the spliterator is returned.

     *

     * @param <T> Type of elements

     * @param iterator The iterator for the source

     * @param characteristics Properties of this spliterator's source

     *        or elements ({@code SIZED} and {@code SUBSIZED}, if supplied, are

     *        ignored and are not reported.)

     * @return A spliterator from an iterator

     * @throws NullPointerException if the given iterator is {@code null}

     */

    public static <T> Spliterator<T> spliteratorUnknownSize(Iterator<? extends T> iterator,

                                                            int characteristics) {

        return new IteratorSpliterator<>(Objects.requireNonNull(iterator), characteristics);

    }

    /**

     * Creates a {@code Spliterator.OfInt} using a given

     * {@code IntStream.IntIterator} as the source of elements, and with a given

     * initially reported size.

     *

     * <p>The spliterator is not

     * <em><a href="Spliterator.html#binding">late-binding</a></em>, inherits

     * the <em>fail-fast</em> properties of the iterator, and implements

     * {@code trySplit} to permit limited parallelism.

     *

     * <p>Traversal of elements should be accomplished through the spliterator.

     * The behaviour of splitting and traversal is undefined if the iterator is

     * operated on after the spliterator is returned, or the initially reported

     * size is not equal to the actual number of elements in the source.

     *

     * @param iterator The iterator for the source

     * @param size The number of elements in the source, to be reported as

     *        initial {@code estimateSize}.

     * @param additionalCharacteristics Additional spliterator characteristics

     *        of this spliterator's source or elements beyond {@code SIZED} and

     *        {@code SUBSIZED} which are are always reported

     * @return A spliterator from an iterator

     * @throws NullPointerException if the given iterator is {@code null}

     */

    public static Spliterator.OfInt spliterator(PrimitiveIterator.OfInt iterator,

                                                long size,

                                                int additionalCharacteristics) {

        return new IntIteratorSpliterator(Objects.requireNonNull(iterator),

                                          size, additionalCharacteristics);

    }

    /**

     * Creates a {@code Spliterator.OfInt} using a given

     * {@code IntStream.IntIterator} as the source of elements, with no initial

     * size estimate.

     *

     * <p>The spliterator is not

     * <em><a href="Spliterator.html#binding">late-binding</a></em>, inherits

     * the <em>fail-fast</em> properties of the iterator, and implements

     * {@code trySplit} to permit limited parallelism.

     *

     * <p>Traversal of elements should be accomplished through the spliterator.

     * The behaviour of splitting and traversal is undefined if the iterator is

     * operated on after the spliterator is returned.

     *

     * @param iterator The iterator for the source

     * @param characteristics Properties of this spliterator's source

     *        or elements ({@code SIZED} and {@code SUBSIZED}, if supplied, are

     *        ignored and are not reported.)