/*
 * Copyright (c) 1997, 2018, 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 Torello.Java.ReadOnly;

import Torello.Java.Additional.RemoveUnsupportedIterator;

import java.util.Spliterators;
import java.util.Spliterator;
import java.util.Collection;

import java.util.function.IntFunction;

import java.util.stream.Stream;
import java.util.stream.StreamSupport;

/**
 * Immutable variant of  Java Collections Framework interface
 * <CODE>java&#46;util&#46;Collection&lt;E&gt;</CODE>.
 * 
 * <EMBED CLASS='external-html' DATA-JDK=ReadOnlyCollection DATA-FILE-ID=INTERFACES>
 * 
 * @param <E> the type of elements in this collection
 */
@Torello.JavaDoc.JDHeaderBackgroundImg(EmbedTagFileID="JDHBI_INTERFACE")
public interface ReadOnlyCollection<E> extends Iterable<E>
{
    // ********************************************************************************************
    // ********************************************************************************************
    // Query Operations
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * Returns the number of elements in this collection.  If this collection
     * contains more than {@code Integer.MAX_VALUE} elements, returns
     * {@code Integer.MAX_VALUE}.
     *
     * @return the number of elements in this collection
     */
    int size();

    /**
     * Returns {@code TRUE} if this collection contains no elements.
     * @return {@code TRUE} if this collection contains no elements
     */
    boolean isEmpty();

    /**
     * Returns {@code TRUE} if this collection contains the specified element.  More formally,
     * returns {@code TRUE} if and only if this collection contains at least one element {@code e}
     * such that {@code Objects.equals(o, e)}.
     *
     * @param o element whose presence in this collection is to be tested
     * 
     * @return {@code TRUE} if this collection contains the specifiedelement
     * 
     * @throws ClassCastException if the type of the specified element is incompatible with this
     * collection (<A HREF='#optional-restrictions'>optional-restrictions</A>)
     * 
     * @throws NullPointerException if the specified element is null and this collection does not
     * permit null elements (<A HREF='#optional-restrictions'>optional-restrictions</A>)
     */
    boolean contains(Object o);

    /**
     * Returns an iterator over the elements in this collection.  There are no guarantees
     * concerning the order in which the elements are returned (unless this collection is an
     * instance of some class that provides a guarantee).
     *
     * @return an {@code Iterator} over the elements in this collection
     */
    RemoveUnsupportedIterator<E> iterator();

    /**
     * Returns an array containing all of the elements in this collection.  If this collection
     * makes any guarantees as to what order its elements are returned by its iterator, this method
     * must return the elements in the same order. The returned array's
     * {@code Class.getComponentType (runtime component type)} is {@code Object}.
     *
     * <BR /><BR />The returned array will be "safe" in that no references to it are maintained by
     * this collection.  (In other words, this method must allocate a new array even if this
     * collection is backed by an array).  The caller is thus free to modify the returned array.
     *
     * @apiNote
     * This method acts as a bridge between array-based and collection-based APIs.  It returns an
     * array whose runtime type is {@code Object[]}.  Use {@link #toArray(Object[]) toArray(T[])}
     * to reuse an existing array, or use {@link #toArray(IntFunction)} to control the runtime type
     * of the array.
     *
     * @return an array, whose {@linkplain Class#getComponentType runtime component type} is
     * {@code Object}, containing all of the elements in this collection
     */
    Object[] toArray();

    /**
     * Returns an array containing all of the elements in this collection; the runtime type of the
     * returned array is that of the specified array.  If the collection fits in the specified
     * array, it is returned therein.  Otherwise, a new array is allocated with the runtime type of
     * the specified array and the size of this collection.
     *
     * <BR /><BR />If this collection fits in the specified array with room to spare (i.e., the
     * array has more elements than this collection), the element in the array immediately
     * following the end of the collection is set to {@code null}.  (This is useful in determining
     * the length of this collection <i>only</i> if the caller knows that this collection does not
     * contain any {@code null} elements.)
     *
     * <BR /><BR />If this collection makes any guarantees as to what order its elements are
     * returned by its iterator, this method must return the elements in the same order.
     *
     * @apiNote
     * This method acts as a bridge between array-based and collection-based APIs.  It allows an
     * existing array to be reused under certain circumstances.  Use {@link #toArray()} to create
     * an array whose runtime type is {@code Object[]}, or use {@link #toArray(IntFunction)} to
     * control the runtime type of the array.
     *
     * <BR /><BR />Suppose {@code x} is a collection known to contain only strings.  The following
     * code can be used to dump the collection into a previously allocated {@code String} array:
     * 
     * <BR /><DIV CLASS=SNIP>{@code
     * String[] y = new String[SIZE];
     * ...
     * y = x.toArray(y);
     * }</DIV>
     *
     * <BR /><BR />The return value is reassigned to the variable {@code y}, because a new array
     * will be allocated and returned if the collection {@code x} has too many elements to fit into
     * the existing array {@code y}.
     * 
     * <BR /><BR />Note that {@code toArray(new Object[0])} is identical in function to
     * {@code toArray()}.
     *
     * @param <T> the component type of the array to contain the collection
     * 
     * @param a the array into which the elements of this collection are to be stored, if it is big
     * enough; otherwise, a new array of the same runtime type is allocated for this purpose.
     * 
     * @return an array containing all of the elements in this collection
     * 
     * @throws ArrayStoreException if the runtime type of any element in this collection is not
     * assignable to the {@linkplain Class#getComponentType runtime component type} of the
     * specified array
     * 
     * @throws NullPointerException if the specified array is null
     */
    <T> T[] toArray(T[] a);

    /**
     * Returns an array containing all of the elements in this collection, using the provided
     * {@code generator} function to allocate the returned array.
     *
     * <BR /><BR />If this collection makes any guarantees as to what order its elements are
     * returned by its iterator, this method must return the elements in the same order.
     * 
     * @apiNote
     * This method acts as a bridge between array-based and collection-based APIs.  It allows
     * creation of an array of a particular runtime type. Use {@link #toArray()} to create an array
     * whose runtime type is {@code Object[]}, or use {@link #toArray(Object[]) toArray(T[])} to
     * reuse an existing array.
     *
     * <BR /><BR />Suppose {@code x} is a collection known to contain only strings.  The following
     * code can be used to dump the collection into a newly allocated array of {@code String}:
     *
     * <BR /><DIV CLASS=SNIP>{@code
     * String[] y = x.toArray(String[]::new);
     * }</DIV>
     *
     * <BR /><BR />The default implementation calls the generator function with zero and then
     * passes the resulting array to {@link #toArray(Object[]) toArray(T[])}.
     *
     * @param <T> the component type of the array to contain the collection
     * 
     * @param generator a function which produces a new array of the desired type and the provided
     * length
     * 
     * @return an array containing all of the elements in this collection
     * 
     * @throws ArrayStoreException if the runtime type of any element in this collection is not
     * assignable to the {@linkplain Class#getComponentType runtime component type} of the
     * generated array
     * 
     * @throws NullPointerException if the generator function is null
     */
    default <T> T[] toArray(IntFunction<T[]> generator)
    { return toArray(generator.apply(0)); }

    /**
     * Simply copies the contents of {@code 'this'} instance of {@code ReadOnlyCollection} into
     * the user-provided {@code 'collection'} data-structure.
     * 
     * @param collection Any Java Collection instance.  This collection's {@code 'add(E e)'} method
     * will be utilized for performing the coying.
     */
    default void copyIntoCollection(Collection<? super E> collection)
    { for (E e : this) collection.add(e); }


    // ********************************************************************************************
    // ********************************************************************************************
    // Bulk Operations
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * Returns {@code TRUE} if this collection contains all of the elements in the specified
     * collection.
     *
     * @param c collection to be checked for containment in this collection
     * 
     * @return {@code TRUE} if this collection contains all of the elements in the specified
     * collection
     * 
     * @throws ClassCastException if the types of one or more elements in the specified collection
     * are incompatible with this collection
     * (<A HREF='#optional-restrictions'>optional-restrictions</A>)
     * 
     * @throws NullPointerException if the specified collection contains one or more null elements
     * and this collection does not permit null elements
     * (<A HREF='#optional-restrictions'>optional-restrictions</A>),
     * or if the specified collection is null.
     * 
     * @see #contains(Object)
     */
    boolean containsAll(Collection<?> c);


    // ********************************************************************************************
    // ********************************************************************************************
    // contains - using Var-Args Arrays
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * Checks to ensure that {@code 'this'} instance of {@code ReadOnlyCollection}
     * <B STYLE='color: red;'>contains every one of the elements</B> in Var-Args Parameter
     * {@code 'elements'}
     * 
     * @param elements a list of elements
     * 
     * @return {@code TRUE} If and only if {@code 'this'} instance contains every element in
     * {@code 'elements'}
     */
    default boolean containsAND(Object... elements)
    {
        for (Object elem : elements) if (! this.contains(elem)) return false;
        return true;
    }

    /**
     * Checks to ensure that {@code 'this'} instance of {@code ReadOnlyCollection}
     * <B STYLE='color: red;'>does not contain any of the elements</B> in Var-Args Parameter
     * {@code 'elements'}
     * 
     * @param elements a list of elements
     * 
     * @return {@code TRUE} If and only if {@code 'this'} instance contains none of the elements in
     * {@code 'elements'}
     */
    default boolean containsNAND(Object... elements)
    {
        for (Object elem : elements) if (this.contains(elem)) return false;
        return true;
    }

    /**
     * Checks to ensure that {@code 'this'} instance of {@code ReadOnlyCollection}
     * <B STYLE='color: red;'>contains at least one of the elements</B> in Var-Args Parameter
     * {@code 'elements'}
     * 
     * @param elements a list of elements
     * 
     * @return {@code TRUE} If and only if {@code 'this'} instance contains one or more of the
     * elements in {@code 'elements'}
     */
    default boolean containsOR(Object... elements)
    {
        for (Object elem : elements) if (this.contains(elem)) return true;
        return false;
    }

    /**
     * Checks to ensure that {@code 'this'} instance of {@code ReadOnlyCollection}
     * <B STYLE='color: red;'>contains precisely one of the elements</B> in Var-Args Parameter
     * {@code 'elements'}
     * 
     * @param elements a list of elements
     * 
     * @return {@code TRUE} If and only if {@code 'this'} instance has exactly one element that is
     * also in {@code 'elements'}
     */
    default boolean containsXOR(Object... elements)
    {
        boolean found = false;

        for (Object elem : elements)

            if (this.contains(elem))
            {
                if (found) return false;
                else found = true;
            }

        return found;
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // contains - using java.lang.Iterable
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * Checks to ensure that {@code 'this'} instance of {@code ReadOnlyCollection}
     * <B STYLE='color: red;'>contains every one of the elements</B> in {@code Iterable} parameter
     * {@code 'i'}
     * 
     * @param i any Java {@code Iterable}
     * 
     * @return {@code TRUE} If and only if {@code 'this'} instance contains every element in
     * {@code 'i'}
     */
    default boolean containsAND(Iterable<?> i)
    {
        for (Object o: i) if (! this.contains(o)) return false;
        return true;
    }

    /**
     * Checks to ensure that {@code 'this'} instance of {@code ReadOnlyCollection}
     * <B STYLE='color: red;'>does not contain any of the elements</B> in {@code Iterable}
     * parameter {@code 'i'}
     * 
     * @param i any Java {@code Iterable}
     * 
     * @return {@code TRUE} If and only if {@code 'this'} instance contains none of the elements in
     * {@code 'i'}
     */
    default boolean containsNAND(Iterable<?> i)
    {
        for (Object o: i) if (this.contains(o)) return false;
        return true;
    }

    /**
     * Checks to ensure that {@code 'this'} instance of {@code ReadOnlyCollection}
     * <B STYLE='color: red;'>contains at least one of the elements</B> in {@code Iterable}
     * parameter {@code 'i'}
     * 
     * @param i any Java {@code Iterable}
     * 
     * @return {@code TRUE} If and only if {@code 'this'} instance contains one or more of the
     * elements in {@code 'i'}
     */
    default boolean containsOR(Iterable<?> i)
    {
        for (Object o: i) if (this.contains(o)) return true;
        return false;
    }

    /**
     * Checks to ensure that {@code 'this'} instance of {@code ReadOnlyCollection}
     * <B STYLE='color: red;'>contains precisely one of the elements</B> in {@code Iterable}
     * parameter {@code 'i'}
     *
     * @param i any Java {@code Iterable}
     * 
     * @return {@code TRUE} If and only if {@code 'this'} instance has exactly one element that is
     * also in {@code 'i'}
     */
    default boolean containsXOR(Iterable<?> i)
    {
        boolean found = false;

        for (Object o: i)

            if (this.contains(o))
            {
                if (found) return false;
                else found = true;
            }

        return found;
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // Comparison and Hashing
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * Compares the specified object with this collection for equality.
     * 
     * <BR /><BR />While the {@code ReadOnlyCollection} interface adds no stipulations to the
     * general contract for the {@code Object.equals}, programmers who implement the
     * {@code ReadOnlyCollection} interface "directly" (in other words, create a class that is a
     * {@code ReadOnlyCollection} but is not a {@code ReadOnlySet} or a {@code ReadOnlyList}) must
     * exercise care if they choose to override the {@code Object.equals}.  It is not necessary to
     * do so, and the simplest course of action is to rely on {@code Object}'s implementation, but
     * the implementor may wish to implement a "value comparison" in place of the default
     * "reference comparison."  (The {@code ReadOnlyList} and {@code ReadOnlySet} interfaces
     * mandate such value comparisons.)
     * 
     * <BR /><BR />The general contract for the {@code Object.equals} method states that equals
     * must be symmetric (in other words, {@code a.equals(b)} if and only if {@code b.equals(a)}).
     * The contracts for {@code ReadOnlyList.equals} and {@code ReadOnlySet.equals} state that
     * lists are only equal to other lists, and sets to other sets.  Thus, a custom {@code equals}
     * method for a collection class that implements neither the {@code ReadOnlyList} nor
     * {@code ReadOnlySet} interface must return {@code FALSE} when this collection is compared to
     * any list or set.  (By the same logic, it is not possible to write a class that correctly
     * implements both the {@code ReadOnlySet} and {@code ReadOnlyList} interfaces.)
     *
     * @param o object to be compared for equality with this collection
     * 
     * @return {@code TRUE} if the specified object is equal to this collection
     *
     * @see Object#equals(Object)
     * @see ReadOnlySet#equals(Object)
     * @see ReadOnlyList#equals(Object)
     */
    boolean equals(Object o);

    /**
     * Returns the hash code value for this collection.  While the {@code Collection} interface
     * adds no stipulations to the general contract for the {@code Object.hashCode} method,
     * programmers should take note that any class that overrides the {@code Object.equals} method
     * must also override the {@code Object.hashCode} method in order to satisfy the general
     * contract for the {@code Object.hashCode} method.  In particular, {@code c1.equals(c2)}
     * implies that {@code c1.hashCode()==c2.hashCode()}.
     *
     * @return the hash code value for this collection
     *
     * @see Object#hashCode()
     * @see Object#equals(Object)
     */
    int hashCode();

    /**
     * Creates a {@link Spliterator} over the elements in this collection.
     * 
     * <BR /><BR />Implementations should document characteristic values reported by the
     * spliterator.  Such characteristic values are not required to be reported if the spliterator
     * reports {@code Spliterator.SIZED} and this collection contains no elements.
     * 
     * <BR /><BR />The default implementation should be overridden by subclasses that can return a
     * more efficient spliterator.  In order to preserve expected laziness behavior for the
     * {@link #stream()} and {@link #parallelStream()} methods, spliterators should either have the
     * characteristic of {@code IMMUTABLE} or {@code CONCURRENT}, or be
     * <em><a href="Spliterator.html#binding">late-binding</a></em>.  If none of these is
     * practical, the overriding class should describe the spliterator's documented policy of
     * binding and structural interference, and should override the {@link #stream()} and
     * {@link #parallelStream()} methods to create streams using a {@code Supplier} of the
     * spliterator, as in:
     * 
     * <BR /><DIV CLASS=SNIP>{@code
     * Stream<E> s = StreamSupport.stream(() -> spliterator(), spliteratorCharacteristics)
     * }</DIV>
     * 
     * <BR /><BR />These requirements ensure that streams produced by the {@link #stream()} and
     * {@link #parallelStream()} methods will reflect the contents of the collection as of
     * initiation of the terminal stream operation.
     *
     * <BR /><BR />The default implementation creates a <em><a href="Spliterator.html#binding">
     * late-binding</a></em> spliterator from the collection's {@code Iterator}.
     * 
     * <BR /><BR />The created {@code Spliterator} reports {@code Spliterator.SIZED}.
     * 
     * @implNote
     * The created {@code Spliterator} additionally reports {@code Spliterator.SUBSIZED}.
     * 
     * <BR /><BR />If a spliterator covers no elements then the reporting of additional
     * characteristic values, beyond that of {@code SIZED} and {@code SUBSIZED}, does not aid
     * clients to control, specialize or simplify computation.  However, this does enable shared
     * use of an immutable and empty spliterator instance (see
     * {@code Spliterators.emptySpliterator()}) for empty collections, and enables clients to
     * determine if such a spliterator covers no elements. 
     * 
     * @return a {@code Spliterator} over the elements in this collection
     */
    @Override
    default Spliterator<E> spliterator()
    { return Spliterators.spliterator(this.iterator(), this.size(), 0); }

    /**
     * Returns a sequential {@code Stream} with this collection as its source.
     * 
     * <BR /><BR />This method should be overridden when the {@link #spliterator()} method cannot
     * return a spliterator that is {@code IMMUTABLE}, {@code CONCURRENT}, or
     * <em>late-binding</em>. (See {@link #spliterator()} for details.)
     * 
     * <BR /><BR />The default implementation creates a sequential {@code Stream} from the
     * collection's {@code Spliterator}.
     * 
     * @return a sequential {@code Stream} over the elements in this collection
     */
    default Stream<E> stream()
    { return StreamSupport.stream(spliterator(), false); }

    /**
     * Returns a possibly parallel {@code Stream} with this collection as its source.  It is
     * allowable for this method to return a sequential stream.
     *
     * <BR /><BR />This method should be overridden when the {@link #spliterator()} method cannot
     * return a spliterator that is {@code IMMUTABLE}, {@code CONCURRENT}, or
     * <em>late-binding</em>. (See {@link #spliterator()} for details.)
     *
     * @implSpec
     * The default implementation creates a parallel {@code Stream} from the collection's
     * {@code Spliterator}.
     *
     * @return a possibly parallel {@code Stream} over the elements in this collection
     */
    default Stream<E> parallelStream()
    { return StreamSupport.stream(spliterator(), true); }
}