/*
 * Copyright (c) 1997, 2020, 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.function.UnaryOperator;

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


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


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

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

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

    /**
     * Returns an iterator over the elements in this list in proper sequence.
     * @return an iterator over the elements in this list in proper sequence
     */
    RemoveUnsupportedIterator<E> iterator();

    /**
     * Returns an array containing all of the elements in this list in proper sequence (from first
     * to last element).
     *
     * <BR /><BR />The returned array will be "safe" in that no references to it are maintained by
     * this list.  (In other words, this method must allocate a new array even if this list is
     * backed by an array).  The caller is thus free to modify the returned array.
     *
     * <BR /><BR />This method acts as bridge between array-based and collection-based APIs.
     *
     * @return an array containing all of the elements in this list in proper sequence
     */
    Object[] toArray();

    /**
     * Returns an array containing all of the elements in this list in proper sequence (from first
     * to last element); the runtime type of the returned array is that of the specified array.  If
     * the list 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 list.
     *
     * <BR /><BR />If the list fits in the specified array with room to spare (i.e., the array has
     * more elements than the list), the element in the array immediately following the end of the
     * list is set to {@code null}.  (This is useful in determining the length of the list
     * <i>only</i> if the caller knows that the list does not contain any null elements.)
     *
     * <BR /><BR />Like the {@link #toArray()} method, this method acts as bridge between
     * array-based and collection-based APIs.  Further, this method allows precise control over the
     * runtime type of the output array, and may, under certain circumstances, be used to save
     * allocation costs.
     *
     * <BR /><BR />Suppose {@code x} is a list known to contain only strings.  The following code
     * can be used to dump the list into a newly allocated array of {@code String}:
     *
     * <BR /><DIV CLASS=SNIP>{@code
     * String[] y = x.toArray(new String[0]);
     * }</DIV>
     *
     * <BR /><BR />Note that {@code toArray(new Object[0])} is identical in function to
     * {@code toArray()}.
     *
     * @param a the array into which the elements of this list 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 the elements of this list
     * 
     * @throws ArrayStoreException if the runtime type of the specified array is not a supertype of
     * the runtime type of every element in this list
     * 
     * @throws NullPointerException if the specified array is null
     */
    <T> T[] toArray(T[] a);

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


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


    /**
     * Compares the specified object with this list for equality.  Returns {@code TRUE} if and only
     * if the specified object is also a list, both lists have the same size, and all corresponding
     * pairs of elements in the two lists are <i>equal</i>.  (Two elements {@code e1} and
     * {@code e2} are <i>equal</i> if {@code Objects.equals(e1, e2)}.)  In other words, two lists
     * are defined to be equal if they contain the same elements in the same order.  This
     * definition ensures that the equals method works properly across different implementations of
     * the {@code ReadOnlyList} interface.
     *
     * @param o the object to be compared for equality with this list
     * @return {@code TRUE} if the specified object is equal to this list
     */
    boolean equals(Object o);

    /**
     * Returns the hash code value for this list.  The hash code of a list is defined to be the
     * result of the following calculation:
     * 
     * <BR /><DIV CLASS=SNIP>{@code
     * int hashCode = 1;
     * for (E e : list) hashCode = 31*hashCode + (e==null ? 0 : e.hashCode());
     * }</DIV>
     * 
     * <BR /><BR />This ensures that {@code list1.equals(list2)} implies that
     * {@code list1.hashCode()==list2.hashCode()} for any two lists, {@code list1} and
     * {@code list2}, as required by the general contract of {@code Object.hashCode}.
     *
     * @return the hash code value for this list
     * 
     * @see Object#equals(Object)
     * @see #equals(Object)
     */
    int hashCode();


    // ********************************************************************************************
    // ********************************************************************************************
    // Positional Access Operations
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * Returns the element at the specified position in this list.
     * @param index index of the element to return
     * @return the element at the specified position in this list
     * 
     * @throws IndexOutOfBoundsException if the index is out of range
     * ({@code index < 0 || index >= size()})
     */
    E get(int index);


    // ********************************************************************************************
    // ********************************************************************************************
    // Search Operations
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * Returns the index of the first occurrence of the specified element in this list, or -1 if
     * this list does not contain the element.  More formally, returns the lowest index {@code i}
     * such that {@code Objects.equals(o, get(i))}, or -1 if there is no such index.
     *
     * @param o element to search for
     * 
     * @return the index of the first occurrence of the specified element in this list, or -1 if
     * this list does not contain the element
     * 
     * @throws ClassCastException if the type of the specified element is incompatible with this
     * list (<a href="Collection.html#optional-restrictions">optional</a>)
     * 
     * @throws NullPointerException if the specified element is null and this list does not permit
     * null elements (<a href="Collection.html#optional-restrictions">optional</a>)
     */
    int indexOf(Object o);

    /**
     * Returns the index of the last occurrence of the specified element in this list, or -1 if
     * this list does not contain the element.  More formally, returns the highest index {@code i}
     * such that {@code Objects.equals(o, get(i))}, or -1 if there is no such index.
     *
     * @param o element to search for
     * 
     * @return the index of the last occurrence of the specified element in this list, or -1 if
     * this list does not contain the element
     * 
     * @throws ClassCastException if the type of the specified element is incompatible with this
     * list (<a href="Collection.html#optional-restrictions">optional</a>)
     * 
     * @throws NullPointerException if the specified element is null and this list does not permit
     * null elements (<a href="Collection.html#optional-restrictions">optional</a>)
     */
    int lastIndexOf(Object o);


    // ********************************************************************************************
    // ********************************************************************************************
    // List Iterators
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * Returns a list iterator over the elements in this list (in proper sequence).
     * @return a list iterator over the elements in this list (in proper sequence)
     */
    ReadOnlyListIterator<E> listIterator();

    /**
     * Returns a list iterator over the elements in this list (in proper sequence), starting at the
     * specified position in the list.  The specified index indicates the first element that would
     * be returned by an initial call to {@link ReadOnlyListIterator#next}.  An initial call to
     * {@link ReadOnlyListIterator#previous} would return the element with the specified index
     * minus one.
     *
     * @param index index of the first element to be returned from the list iterator (by a call to
     * {@link ReadOnlyListIterator#next next})
     * 
     * @return a list iterator over the elements in this list (in proper sequence), starting at the
     * specified position in the list
     * 
     * @throws IndexOutOfBoundsException if the index is out of range
     * ({@code index < 0 || index > size()})
     */
    ReadOnlyListIterator<E> listIterator(int index);


    // ********************************************************************************************
    // ********************************************************************************************
    // View
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * Returns a view of the portion of this list between the specified {@code fromIndex},
     * inclusive, and {@code toIndex}, exclusive.  (If {@code fromIndex} and {@code toIndex} are
     * equal, the returned list is empty.)  The returned list is backed by this list, so
     * non-structural changes in the returned list are reflected in this list, and vice-versa.  The
     * returned list supports all of the optional list operations supported by this list.
     * 
     * <BR /><BR />This method eliminates the need for explicit range operations (of the sort that
     * commonly exist for arrays).  Any operation that expects a list can be used as a range
     * operation by passing a subList view instead of a whole list.  For example, the following
     * idiom removes a range of elements from a list:
     * 
     * <BR /><DIV CLASS=SNIP>{@code
     * list.subList(from, to).clear();
     * }</DIV>
     * 
     * <BR /><BR />Similar idioms may be constructed for {@code indexOf} and {@code lastIndexOf},
     * and all of the algorithms in the {@code Collections} class can be applied to a subList.
     * 
     * <BR /><BR />The semantics of the list returned by this method become undefined if the
     * backing list (i.e., this list) is <i>structurally modified</i> in any way other than via the
     * returned list.  (Structural modifications are those that change the size of this list, or
     * otherwise perturb it in such a fashion that iterations in progress may yield incorrect
     * results.)
     *
     * @param fromIndex low endpoint (inclusive) of the subList
     * 
     * @param toIndex high endpoint (exclusive) of the subList
     * 
     * @return a view of the specified range within this list
     * 
     * @throws IndexOutOfBoundsException for an illegal endpoint index value
     * ({@code fromIndex < 0 || toIndex > size || fromIndex > toIndex})
     */
    ReadOnlyList<E> subList(int fromIndex, int toIndex);

    /*
     * Creates a {@link Spliterator} over the elements in this list.
     *
     * <BR /><BR />The {@code Spliterator} reports {@code Spliterator.SIZED} and
     * {@code Spliterator.ORDERED}.  Implementations should document the
     * reporting of additional characteristic values.
     * 
     * <BR /><BR />The default implementation creates a
     * <em><a href="Spliterator.html#binding">late-binding</a></em>
     * spliterator as follows:
     * 
     * <UL CLASS=JDUL>
     * 
     * <LI> If the list is an instance of {@code RandomAccess} then the default implementation
     *      creates a spliterator that traverses elements by invoking the method
     *      {@link ReadOnlyList#get}.
     *      </LI>
     * 
     * <LI> Otherwise, the default implementation creates a spliterator from the list's
     *      {@code Iterator}.
     *      </LI>
     * 
     * </UL>
     *
     * <BR /><BR />The created {@code Spliterator} additionally reports
     * {@code Spliterator.SUBSIZED}.
     *
     * @return a {@code Spliterator} over the elements in this list
     */
    @Override
    default Spliterator<E> spliterator()
    {
        return (this instanceof RandomAccess)
            ? new AbstractReadOnlyList.RandomAccessSpliterator<>(this)
            : Spliterators.spliterator(this.iterator(), this.size(), Spliterator.ORDERED);
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // Static Builder Methods
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * Returns an unmodifiable list containing zero elements.
     * @param <E> the {@code List}'s element type
     * @return an empty {@code List}
     */
    static <E> ReadOnlyList<E> of()
    { return InterfaceBuilder.toReadOnlyList(java.util.List.of()); }

    /**
     * Returns an unmodifiable list containing one element.
     * @param <E> the {@code List}'s element type
     * @param e1 the single element
     * @return a {@code List} containing the specified element
     * @throws NullPointerException if the element is {@code null}
     */
    static <E> ReadOnlyList<E> of(E e1)
    { return InterfaceBuilder.toReadOnlyList(java.util.List.of(e1)); }

    /**
     * Returns an unmodifiable list containing two elements.
     * @param <E> the {@code List}'s element type
     * @param e1 the first element
     * @param e2 the second element
     * @return a {@code List} containing the specified elements
     * @throws NullPointerException if an element is {@code null}
     */
    static <E> ReadOnlyList<E> of(E e1, E e2)
    { return InterfaceBuilder.toReadOnlyList(java.util.List.of(e1, e2)); }

    /**
     * Returns an unmodifiable list containing three elements.
     * @param <E> the {@code List}'s element type
     * 
     * @param e1 the first element
     * @param e2 the second element
     * @param e3 the third element
     * 
     * @return a {@code List} containing the specified elements
     * @throws NullPointerException if an element is {@code null}
     */
    static <E> ReadOnlyList<E> of(E e1, E e2, E e3)
    { return InterfaceBuilder.toReadOnlyList(java.util.List.of(e1, e2, e3)); }

    /**
     * Returns an unmodifiable list containing four elements.
     * @param <E> the {@code List}'s element type
     * 
     * @param e1 the first element
     * @param e2 the second element
     * @param e3 the third element
     * @param e4 the fourth element
     * 
     * @return a {@code List} containing the specified elements
     * @throws NullPointerException if an element is {@code null}
     */
    static <E> ReadOnlyList<E> of(E e1, E e2, E e3, E e4)
    { return InterfaceBuilder.toReadOnlyList(java.util.List.of(e1, e2, e3, e4)); }

    /**
     * Returns an unmodifiable list containing five elements.
     * @param <E> the {@code List}'s element type
     * 
     * @param e1 the first element
     * @param e2 the second element
     * @param e3 the third element
     * @param e4 the fourth element
     * @param e5 the fifth element
     * 
     * @return a {@code List} containing the specified elements
     * @throws NullPointerException if an element is {@code null}
     */
    static <E> ReadOnlyList<E> of(E e1, E e2, E e3, E e4, E e5)
    { return InterfaceBuilder.toReadOnlyList(java.util.List.of(e1, e2, e3, e4, e5)); }

    /**
     * Returns an unmodifiable list containing six elements.
     * @param <E> the {@code List}'s element type
     * 
     * @param e1 the first element
     * @param e2 the second element
     * @param e3 the third element
     * @param e4 the fourth element
     * @param e5 the fifth element
     * @param e6 the sixth element
     * 
     * @return a {@code List} containing the specified elements
     * @throws NullPointerException if an element is {@code null}
     */
    static <E> ReadOnlyList<E> of(E e1, E e2, E e3, E e4, E e5, E e6)
    { return InterfaceBuilder.toReadOnlyList(java.util.List.of(e1, e2, e3, e4, e5, e6)); }

    /**
     * Returns an unmodifiable list containing seven elements.
     * @param <E> the {@code List}'s element type
     * 
     * @param e1 the first element
     * @param e2 the second element
     * @param e3 the third element
     * @param e4 the fourth element
     * @param e5 the fifth element
     * @param e6 the sixth element
     * @param e7 the seventh element
     * 
     * @return a {@code List} containing the specified elements
     * @throws NullPointerException if an element is {@code null}
     */
    static <E> ReadOnlyList<E> of(E e1, E e2, E e3, E e4, E e5, E e6, E e7)
    { return InterfaceBuilder.toReadOnlyList(java.util.List.of(e1, e2, e3, e4, e5, e6, e7)); }

    /**
     * Returns an unmodifiable list containing eight elements.
     * @param <E> the {@code List}'s element type
     * 
     * @param e1 the first element
     * @param e2 the second element
     * @param e3 the third element
     * @param e4 the fourth element
     * @param e5 the fifth element
     * @param e6 the sixth element
     * @param e7 the seventh element
     * @param e8 the eighth element
     * 
     * @return a {@code List} containing the specified elements
     * @throws NullPointerException if an element is {@code null}
     */
    static <E> ReadOnlyList<E> of(E e1, E e2, E e3, E e4, E e5, E e6, E e7, E e8)
    { return InterfaceBuilder.toReadOnlyList(java.util.List.of(e1, e2, e3, e4, e5, e6, e7, e8)); }

    /**
     * Returns an unmodifiable list containing nine elements.
     * @param <E> the {@code List}'s element type
     * 
     * @param e1 the first element
     * @param e2 the second element
     * @param e3 the third element
     * @param e4 the fourth element
     * @param e5 the fifth element
     * @param e6 the sixth element
     * @param e7 the seventh element
     * @param e8 the eighth element
     * @param e9 the ninth element
     * 
     * @return a {@code List} containing the specified elements
     * @throws NullPointerException if an element is {@code null}
     */
    static <E> ReadOnlyList<E> of(E e1, E e2, E e3, E e4, E e5, E e6, E e7, E e8, E e9)
    {
        return InterfaceBuilder.toReadOnlyList
            (java.util.List.of(e1, e2, e3, e4, e5, e6, e7, e8, e9));
    }

    /**
     * Returns an unmodifiable list containing ten elements.
     * @param <E> the {@code List}'s element type
     * 
     * @param e1 the first element
     * @param e2 the second element
     * @param e3 the third element
     * @param e4 the fourth element
     * @param e5 the fifth element
     * @param e6 the sixth element
     * @param e7 the seventh element
     * @param e8 the eighth element
     * @param e9 the ninth element
     * @param e10 the tenth element
     * 
     * @return a {@code List} containing the specified elements
     * @throws NullPointerException if an element is {@code null}
     */
    static <E> ReadOnlyList<E> of(E e1, E e2, E e3, E e4, E e5, E e6, E e7, E e8, E e9, E e10)
    {
        return InterfaceBuilder.toReadOnlyList
            (java.util.List.of(e1, e2, e3, e4, e5, e6, e7, e8, e9, e10));
    }

    /**
     * Returns an unmodifiable list containing an arbitrary number of elements.
     * 
     * @apiNote
     * This method also accepts a single array as an argument. The element type of the resulting
     * list will be the component type of the array, and the size of the list will be equal to the
     * length of the array. To create a list with a single element that is an array, do the
     * following:
     * 
     * <BR /><DIV CLASS=SNIP>{@code
     * String[] array = ... ;
     * ReadOnlyList<String[]> list = ReadOnlyList.<String[]>of(array);
     * }</DIV>
     * 
     * <BR /><BR />This will cause the {@link ReadOnlyList#of(Object) ReadOnlyList.of(E)} method to
     * be invoked instead.
     * 
     * @param <E> the {@code List}'s element type
     * @param elements the elements to be contained in the list
     * @return a {@code List} containing the specified elements
     * @throws NullPointerException if an element is {@code null} or if the array is {@code null}
     */
    @SafeVarargs
    @SuppressWarnings("varargs")
    static <E> ReadOnlyList<E> of(E... elements)
    { return InterfaceBuilder.toReadOnlyList(java.util.List.of(elements)); }

    /**
     * Returns a {@code ReadOnlyList} containing the elements of the given
     * {@code ReadOnlyCollection}, in its iteration order. The given {@code Collection} must not be
     * null, and it must not contain any null elements. If the given {@code Collection} is
     * subsequently modified, the returned {@code ReadOnlyList} will not reflect such modifications
     *
     * @param <E> the {@code ReadOnlyList}'s element type
     * @param coll a {@code ReadOnlyCollection} from which elements are drawn, must be non-null
     * @return a {@code ReadOnlyList} containing the elements of the given {@code Collection}
     * @throws NullPointerException if coll is null, or if it contains any nulls
     */
    @SuppressWarnings("unchecked")
    static <E> ReadOnlyList<E> copyOf(ReadOnlyCollection<? extends E> coll)
    {
        return (ReadOnlyList.class.isAssignableFrom(coll.getClass()))
            ? (ReadOnlyList<E>) coll
            : new ReadOnlyArrayList<E>((ReadOnlyCollection<E>) coll, coll.size());
    }
}