/*
 * Copyright (c) 1998, 2023, 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.Collection;
import java.util.SortedSet;
import java.util.Spliterator;
import java.util.Spliterators;
import java.util.Comparator;

/**
 * Immutable variant of Java Collections Framework interface
 * <CODE>java&#46;util&#46;SortedSet&lt;E&gt;</CODE>.
 * 
 * <EMBED CLASS='external-html' DATA-JDK=ReadOnlySortedSet DATA-FILE-ID=INTERFACES>
 * 
 * @param <E> the type of elements maintained by this set
 */
@Torello.JavaDoc.JDHeaderBackgroundImg(EmbedTagFileID="JDHBI_INTERFACE")
public interface ReadOnlySortedSet<E> extends ReadOnlySet<E>, ReadOnlySequencedSet<E>
{
    // ********************************************************************************************
    // ********************************************************************************************
    // Original JDK Interface Methods
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * Returns the comparator used to order the elements in this set, or {@code null} if this set
     * uses the {@linkplain Comparable natural ordering} of its elements.
     *
     * @return the comparator used to order the elements in this set, or {@code null} if this set
     * uses the natural ordering of its elements
     */
    Comparator<? super E> comparator();

    /**
     * Returns a view of the portion of this set whose elements range from {@code fromElement},
     * inclusive, to {@code toElement}, exclusive.  (If {@code fromElement} and {@code toElement}
     * are equal, the returned set is empty.)  The returned set supports all optional set
     * operations that this set supports.
     *
     * @param fromElement low endpoint (inclusive) of the returned set
     * @param toElement high endpoint (exclusive) of the returned set
     * 
     * @return a view of the portion of this set whose elements range from {@code fromElement},
     * inclusive, to {@code toElement}, exclusive
     * 
     * @throws ClassCastException if {@code fromElement} and {@code toElement} cannot be compared
     * to one another using this set's comparator (or, if the set has no comparator, using natural
     * ordering).  Implementations may, but are not required to, throw this exception if
     * {@code fromElement} or {@code toElement} cannot be compared to elements currently in the
     * set.
     * 
     * @throws NullPointerException if {@code fromElement} or {@code toElement} is null and this
     * set does not permit null elements
     * 
     * @throws IllegalArgumentException if {@code fromElement} is greater than {@code toElement};
     * or if this set itself has a restricted range, and {@code fromElement} or {@code toElement}
     * lies outside the bounds of the range
     */
    ReadOnlySortedSet<E> subSet(E fromElement, E toElement);

    /**
     * Returns a view of the portion of this set whose elements are strictly less than
     * {@code toElement}.  The returned set supports all optional set operations that this set
     * supports.
     *
     * @param toElement high endpoint (exclusive) of the returned set
     * 
     * @return a view of the portion of this set whose elements are strictly less than
     * {@code toElement}
     * 
     * @throws ClassCastException if {@code toElement} is not compatible with this set's comparator
     * (or, if the set has no comparator, if {@code toElement} does not implement
     * {@code Comparable}).  Implementations may, but are not required to, throw this exception if
     * {@code toElement} cannot be compared to elements currently in the set.
     * 
     * @throws NullPointerException if {@code toElement} is null and this set does not permit null
     * elements
     * 
     * @throws IllegalArgumentException if this set itself has a restricted range, and
     * {@code toElement} lies outside the bounds of the range
     */
    ReadOnlySortedSet<E> headSet(E toElement);

    /**
     * Returns a view of the portion of this set whose elements are greater than or equal to
     * {@code fromElement}.  The returned set supports all optional set operations that this set
     * supports.
     * 
     * @param fromElement low endpoint (inclusive) of the returned set
     * 
     * @return a view of the portion of this set whose elements are greater than or equal to
     * {@code fromElement}
     * 
     * @throws ClassCastException if {@code fromElement} is not compatible with this set's
     * comparator (or, if the set has no comparator, if {@code fromElement} does not implement
     * {@code Comparable}).  Implementations may, but are not required to, throw this exception if
     * {@code fromElement} cannot be compared to elements currently in the set.
     * 
     * @throws NullPointerException if {@code fromElement} is null and this set does not permit
     * null elements
     * 
     * @throws IllegalArgumentException if this set itself has a restricted range, and
     * {@code fromElement} lies outside the bounds of the range
     */
    ReadOnlySortedSet<E> tailSet(E fromElement);

    /**
     * Returns the first (lowest) element currently in this set.
     *
     * @return the first (lowest) element currently in this set
     * @throws NoSuchElementException if this set is empty
     */
    E first();

    /**
     * Returns the last (highest) element currently in this set.
     * @return the last (highest) element currently in this set
     * @throws NoSuchElementException if this set is empty
     */
    E last();

    /**
     * Creates a {@code Spliterator} over the elements in this sorted set.
     *
     * <BR /><BR />The {@code Spliterator} reports {@code Spliterator.DISTINCT},
     * {@code Spliterator.SORTED}}.  Implementations should document the reporting of additional
     * characteristic values.
     *
     * <BR /><BR />The spliterator's comparator (see
     * {@link java.util.Spliterator#getComparator()}) must be {@code null} if
     * the sorted set's comparator (see {@link #comparator()}) is {@code null}.
     * Otherwise, the spliterator's comparator must be the same as or impose the
     * same total ordering as the sorted set's comparator.
     *
     * @implSpec
     * The default implementation creates a
     * <em><code>late-binding</code></em> spliterator
     * from the sorted set's {@code Iterator}.  The spliterator inherits the
     * <em>fail-fast</em> properties of the set's iterator.  The
     * spliterator's comparator is the same as the sorted set's comparator.
     * 
     * <BR /><BR />The created {@code Spliterator} additionally reports {@code Spliterator.SIZED}.
     *
     * @implNote
     * The created {@code Spliterator} additionally reports {@code Spliterator.SUBSIZED}.
     *
     * @return a {@code Spliterator} over the elements in this sorted set
     */
    @Override
    default Spliterator<E> spliterator()
    {
        // *** Java-HTML: Some Spliterators Code was copied into this package
        return new Iterator_Spliterator<E>
            (this, Spliterator.DISTINCT | Spliterator.SORTED | Spliterator.ORDERED)
        {
            @Override
            public Comparator<? super E> getComparator()
            { return ReadOnlySortedSet.this.comparator(); }
        };
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // Original JDK Interface Methods: SEQUENCED-COLLECTION (New JDK21 Thing)
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * {@inheritDoc}
     *
     * @implSpec
     * The implementation in this interface returns the result of calling the {@code first} method.
     *
     * @throws NoSuchElementException {@inheritDoc}
     */
    default E getFirst() { return this.first(); }

    /**
     * {@inheritDoc}
     *
     * @implSpec
     * The implementation in this interface returns the result of calling the {@code last} method.
     *
     * @throws NoSuchElementException {@inheritDoc}
     */
    default E getLast() { return this.last(); }

    /**
     * {@inheritDoc}
     *
     * @implSpec
     * The implementation in this interface returns a reverse-ordered {@code ReadOnlySortedSet}
     * view. The {@code reversed()} method of the view returns a reference to this
     * {@code ReadOnlySortedSet}. Other operations on the view are implemented via calls to public
     * methods on this {@code ReadOnlySortedSet}. The exact relationship between calls on the view
     * and calls on this {@code ReadOnlySortedSet} is unspecified. However, order-sensitive
     * operations generally delegate to the appropriate method with the opposite orientation. For
     * example, calling {@code getFirst} on the view results in a call to {@code getLast} on this
     * {@code ReadOnlySortedSet}.
     *
     * @return a reverse-ordered view of this collection, as a {@code ReadOnlySortedSet}
     */
    default ReadOnlySortedSet<E> reversed()
    {
        // *** Java-HTML: This is the use of the ReverseOrderedSortedSetView
        //     This was copied out of "Package-Private" stuff for the JDK 21
        //     from the OpenJDK class on Git-Hub

        return JDKReverseOrderSortedSetView.of(this);
    }
}