/*
 * 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.
 */

/*
 * This file is available under and governed by the GNU General Public
 * License version 2 only, as published by the Free Software Foundation.
 * However, the following notice accompanied the original version of this
 * file:
 *
 * Written by Doug Lea and Josh Bloch with assistance from members of JCP
 * JSR-166 Expert Group and released to the public domain, as explained at
 * http://creativecommons.org/publicdomain/zero/1.0/
 */
package Torello.Java.ReadOnly;

import Torello.Java.Additional.RemoveUnsupportedIterator;

import java.util.Collection;
import java.util.Comparator;
import java.util.NavigableSet;

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


    /**
     * Returns the greatest element in this set strictly less than the given element, or
     * {@code null} if there is no such element.
     *
     * @param e the value to match
     * 
     * @return the greatest element less than {@code e}, or {@code null} if there is no such
     * element
     * 
     * @throws ClassCastException if the specified element cannot be compared with the elements
     * currently in the set
     * 
     * @throws NullPointerException if the specified element is null and this set does not permit
     * null elements
     */
    E lower(E e);

    /**
     * Returns the greatest element in this set less than or equal to the given element, or
     * {@code null} if there is no such element.
     *
     * @param e the value to match
     * 
     * @return the greatest element less than or equal to {@code e}, or {@code null} if there is no
     * such element
     * 
     * @throws ClassCastException if the specified element cannot be compared with the elements
     * currently in the set
     * 
     * @throws NullPointerException if the specified element is null and this set does not permit
     * null elements
     */
    E floor(E e);

    /**
     * Returns the least element in this set greater than or equal to
     * the given element, or {@code null} if there is no such element.
     *
     * @param e the value to match
     * 
     * @return the least element greater than or equal to {@code e}, or {@code null} if there is no
     * such element
     * 
     * @throws ClassCastException if the specified element cannot be compared with the elements
     * currently in the set
     * 
     * @throws NullPointerException if the specified element is null and this set does not permit
     * null elements
     */
    E ceiling(E e);

    /**
     * Returns the least element in this set strictly greater than the
     * given element, or {@code null} if there is no such element.
     *
     * @param e the value to match
     * 
     * @return the least element greater than {@code e}, or {@code null} if there is no such
     * element
     * 
     * @throws ClassCastException if the specified element cannot be compared with the elements
     * currently in the set
     * 
     * @throws NullPointerException if the specified element is null and this set does not permit
     * null elements
     */
    E higher(E e);

    /**
     * Returns an iterator over the elements in this set, in ascending order.
     * @return an iterator over the elements in this set, in ascending order
     */
    RemoveUnsupportedIterator<E> iterator();

    /**
     * Returns a reverse order view of the elements contained in this set.  
     * 
     * <BR /><BR />The expression {@code s.descendingSet().descendingSet()} returns a view of
     * {@code s} essentially equivalent to {@code s}.
     *
     * @return a reverse order view of this set
     */
    ReadOnlyNavigableSet<E> descendingSet();

    /**
     * Returns an iterator over the elements in this set, in descending order.
     * Equivalent in effect to {@code descendingSet().iterator()}.
     *
     * @return an iterator over the elements in this set, in descending order
     */
    RemoveUnsupportedIterator<E> descendingIterator();

    /**
     * Returns a view of the portion of this set whose elements range from {@code fromElement} to
     * {@code toElement}.  If {@code fromElement} and {@code toElement} are equal, the returned set
     * is empty unless {@code fromInclusive} and {@code toInclusive} are both true.  The returned
     * set supports all optional set operations that this set supports.
     *
     * @param fromElement low endpoint of the returned set
     * @param fromInclusive {@code TRUE} if the low endpoint is to be included in the returned view
     * @param toElement high endpoint of the returned set
     * @param toInclusive {@code TRUE} if the high endpoint is to be included in the returned view
     * 
     * @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.
     */
    ReadOnlyNavigableSet<E> subSet(
            E fromElement, boolean fromInclusive,
            E toElement,   boolean toInclusive
        );

    /**
     * Returns a view of the portion of this set whose elements are less than (or equal to, if
     * {@code inclusive} is true) {@code toElement}.
     *
     * @param toElement high endpoint of the returned set
     * @param inclusive {@code TRUE} if the high endpoint is to be included in the returned view
     * 
     * @return a view of the portion of this set whose elements are less than (or equal to, if
     * {@code inclusive} is true) {@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
     */
    ReadOnlyNavigableSet<E> headSet(E toElement, boolean inclusive);

    /**
     * Returns a view of the portion of this set whose elements are greater than (or equal to, if
     * {@code inclusive} is true) {@code fromElement}.
     * 
     * @param fromElement low endpoint of the returned set
     * @param inclusive {@code TRUE} if the low endpoint is to be included in the returned view
     * 
     * @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
     */
    ReadOnlyNavigableSet<E> tailSet(E fromElement, boolean inclusive);

    /**
     * {@inheritDoc}
     *
     * <BR /><BR />Equivalent to {@code subSet(fromElement, true, toElement, false)}.
     *
     * @throws ClassCastException       {@inheritDoc}
     * @throws NullPointerException     {@inheritDoc}
     * @throws IllegalArgumentException {@inheritDoc}
     */
    ReadOnlySortedSet<E> subSet(E fromElement, E toElement);

    /**
     * {@inheritDoc}
     *
     * <BR /><BR />Equivalent to {@code headSet(toElement, false)}.
     *
     * @throws ClassCastException       {@inheritDoc}
     * @throws NullPointerException     {@inheritDoc}
     * @throws IllegalArgumentException {@inheritDoc}
     */
    ReadOnlySortedSet<E> headSet(E toElement);

    /**
     * {@inheritDoc}
     *
     * <BR /><BR />Equivalent to {@code tailSet(fromElement, true)}.
     *
     * @throws ClassCastException       {@inheritDoc}
     * @throws NullPointerException     {@inheritDoc}
     * @throws IllegalArgumentException {@inheritDoc}
     */
    ReadOnlySortedSet<E> tailSet(E fromElement);

    /**
     * {@inheritDoc}
     * <BR /><BR />
     * This method is equivalent to {@link #descendingSet descendingSet}.
     *
     * @implSpec
     * The implementation in this interface returns the result of calling the
     * {@code descendingSet} method.
     *
     * @return a reverse-ordered view of this collection, as a {@code NavigableSet}
     */
    default ReadOnlyNavigableSet<E> reversed()
    { return this.descendingSet(); }
}