jdk/src/share/classes/java/util/NavigableSet.java
author dl
Thu, 07 Apr 2011 15:06:32 +0100
changeset 9242 ef138d47df58
parent 5506 202f599c92aa
child 18818 a9ceff754226
permissions -rw-r--r--
7034657: Update Creative Commons license URL in legal notices Reviewed-by: chegar
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
     1
/*
90ce3da70b43 Initial load
duke
parents:
diff changeset
     2
 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
90ce3da70b43 Initial load
duke
parents:
diff changeset
     3
 *
90ce3da70b43 Initial load
duke
parents:
diff changeset
     4
 * This code is free software; you can redistribute it and/or modify it
90ce3da70b43 Initial load
duke
parents:
diff changeset
     5
 * under the terms of the GNU General Public License version 2 only, as
5506
202f599c92aa 6943119: Rebrand source copyright notices
ohair
parents: 4670
diff changeset
     6
 * published by the Free Software Foundation.  Oracle designates this
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
     7
 * particular file as subject to the "Classpath" exception as provided
5506
202f599c92aa 6943119: Rebrand source copyright notices
ohair
parents: 4670
diff changeset
     8
 * by Oracle in the LICENSE file that accompanied this code.
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
     9
 *
90ce3da70b43 Initial load
duke
parents:
diff changeset
    10
 * This code is distributed in the hope that it will be useful, but WITHOUT
90ce3da70b43 Initial load
duke
parents:
diff changeset
    11
 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
90ce3da70b43 Initial load
duke
parents:
diff changeset
    12
 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
90ce3da70b43 Initial load
duke
parents:
diff changeset
    13
 * version 2 for more details (a copy is included in the LICENSE file that
90ce3da70b43 Initial load
duke
parents:
diff changeset
    14
 * accompanied this code).
90ce3da70b43 Initial load
duke
parents:
diff changeset
    15
 *
90ce3da70b43 Initial load
duke
parents:
diff changeset
    16
 * You should have received a copy of the GNU General Public License version
90ce3da70b43 Initial load
duke
parents:
diff changeset
    17
 * 2 along with this work; if not, write to the Free Software Foundation,
90ce3da70b43 Initial load
duke
parents:
diff changeset
    18
 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
90ce3da70b43 Initial load
duke
parents:
diff changeset
    19
 *
5506
202f599c92aa 6943119: Rebrand source copyright notices
ohair
parents: 4670
diff changeset
    20
 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
202f599c92aa 6943119: Rebrand source copyright notices
ohair
parents: 4670
diff changeset
    21
 * or visit www.oracle.com if you need additional information or have any
202f599c92aa 6943119: Rebrand source copyright notices
ohair
parents: 4670
diff changeset
    22
 * questions.
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
    23
 */
90ce3da70b43 Initial load
duke
parents:
diff changeset
    24
90ce3da70b43 Initial load
duke
parents:
diff changeset
    25
/*
90ce3da70b43 Initial load
duke
parents:
diff changeset
    26
 * This file is available under and governed by the GNU General Public
90ce3da70b43 Initial load
duke
parents:
diff changeset
    27
 * License version 2 only, as published by the Free Software Foundation.
90ce3da70b43 Initial load
duke
parents:
diff changeset
    28
 * However, the following notice accompanied the original version of this
90ce3da70b43 Initial load
duke
parents:
diff changeset
    29
 * file:
90ce3da70b43 Initial load
duke
parents:
diff changeset
    30
 *
90ce3da70b43 Initial load
duke
parents:
diff changeset
    31
 * Written by Doug Lea and Josh Bloch with assistance from members of JCP
90ce3da70b43 Initial load
duke
parents:
diff changeset
    32
 * JSR-166 Expert Group and released to the public domain, as explained at
9242
ef138d47df58 7034657: Update Creative Commons license URL in legal notices
dl
parents: 5506
diff changeset
    33
 * http://creativecommons.org/publicdomain/zero/1.0/
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
    34
 */
90ce3da70b43 Initial load
duke
parents:
diff changeset
    35
90ce3da70b43 Initial load
duke
parents:
diff changeset
    36
package java.util;
90ce3da70b43 Initial load
duke
parents:
diff changeset
    37
90ce3da70b43 Initial load
duke
parents:
diff changeset
    38
/**
90ce3da70b43 Initial load
duke
parents:
diff changeset
    39
 * A {@link SortedSet} extended with navigation methods reporting
90ce3da70b43 Initial load
duke
parents:
diff changeset
    40
 * closest matches for given search targets. Methods {@code lower},
90ce3da70b43 Initial load
duke
parents:
diff changeset
    41
 * {@code floor}, {@code ceiling}, and {@code higher} return elements
90ce3da70b43 Initial load
duke
parents:
diff changeset
    42
 * respectively less than, less than or equal, greater than or equal,
90ce3da70b43 Initial load
duke
parents:
diff changeset
    43
 * and greater than a given element, returning {@code null} if there
90ce3da70b43 Initial load
duke
parents:
diff changeset
    44
 * is no such element.  A {@code NavigableSet} may be accessed and
90ce3da70b43 Initial load
duke
parents:
diff changeset
    45
 * traversed in either ascending or descending order.  The {@code
90ce3da70b43 Initial load
duke
parents:
diff changeset
    46
 * descendingSet} method returns a view of the set with the senses of
90ce3da70b43 Initial load
duke
parents:
diff changeset
    47
 * all relational and directional methods inverted. The performance of
90ce3da70b43 Initial load
duke
parents:
diff changeset
    48
 * ascending operations and views is likely to be faster than that of
90ce3da70b43 Initial load
duke
parents:
diff changeset
    49
 * descending ones.  This interface additionally defines methods
90ce3da70b43 Initial load
duke
parents:
diff changeset
    50
 * {@code pollFirst} and {@code pollLast} that return and remove the
90ce3da70b43 Initial load
duke
parents:
diff changeset
    51
 * lowest and highest element, if one exists, else returning {@code
90ce3da70b43 Initial load
duke
parents:
diff changeset
    52
 * null}.  Methods {@code subSet}, {@code headSet},
90ce3da70b43 Initial load
duke
parents:
diff changeset
    53
 * and {@code tailSet} differ from the like-named {@code
90ce3da70b43 Initial load
duke
parents:
diff changeset
    54
 * SortedSet} methods in accepting additional arguments describing
90ce3da70b43 Initial load
duke
parents:
diff changeset
    55
 * whether lower and upper bounds are inclusive versus exclusive.
90ce3da70b43 Initial load
duke
parents:
diff changeset
    56
 * Subsets of any {@code NavigableSet} must implement the {@code
90ce3da70b43 Initial load
duke
parents:
diff changeset
    57
 * NavigableSet} interface.
90ce3da70b43 Initial load
duke
parents:
diff changeset
    58
 *
90ce3da70b43 Initial load
duke
parents:
diff changeset
    59
 * <p> The return values of navigation methods may be ambiguous in
90ce3da70b43 Initial load
duke
parents:
diff changeset
    60
 * implementations that permit {@code null} elements. However, even
90ce3da70b43 Initial load
duke
parents:
diff changeset
    61
 * in this case the result can be disambiguated by checking
90ce3da70b43 Initial load
duke
parents:
diff changeset
    62
 * {@code contains(null)}. To avoid such issues, implementations of
90ce3da70b43 Initial load
duke
parents:
diff changeset
    63
 * this interface are encouraged to <em>not</em> permit insertion of
90ce3da70b43 Initial load
duke
parents:
diff changeset
    64
 * {@code null} elements. (Note that sorted sets of {@link
90ce3da70b43 Initial load
duke
parents:
diff changeset
    65
 * Comparable} elements intrinsically do not permit {@code null}.)
90ce3da70b43 Initial load
duke
parents:
diff changeset
    66
 *
90ce3da70b43 Initial load
duke
parents:
diff changeset
    67
 * <p>Methods
90ce3da70b43 Initial load
duke
parents:
diff changeset
    68
 * {@link #subSet(Object, Object) subSet(E, E)},
90ce3da70b43 Initial load
duke
parents:
diff changeset
    69
 * {@link #headSet(Object) headSet(E)}, and
90ce3da70b43 Initial load
duke
parents:
diff changeset
    70
 * {@link #tailSet(Object) tailSet(E)}
90ce3da70b43 Initial load
duke
parents:
diff changeset
    71
 * are specified to return {@code SortedSet} to allow existing
90ce3da70b43 Initial load
duke
parents:
diff changeset
    72
 * implementations of {@code SortedSet} to be compatibly retrofitted to
90ce3da70b43 Initial load
duke
parents:
diff changeset
    73
 * implement {@code NavigableSet}, but extensions and implementations
90ce3da70b43 Initial load
duke
parents:
diff changeset
    74
 * of this interface are encouraged to override these methods to return
90ce3da70b43 Initial load
duke
parents:
diff changeset
    75
 * {@code NavigableSet}.
90ce3da70b43 Initial load
duke
parents:
diff changeset
    76
 *
90ce3da70b43 Initial load
duke
parents:
diff changeset
    77
 * <p>This interface is a member of the
90ce3da70b43 Initial load
duke
parents:
diff changeset
    78
 * <a href="{@docRoot}/../technotes/guides/collections/index.html">
90ce3da70b43 Initial load
duke
parents:
diff changeset
    79
 * Java Collections Framework</a>.
90ce3da70b43 Initial load
duke
parents:
diff changeset
    80
 *
90ce3da70b43 Initial load
duke
parents:
diff changeset
    81
 * @author Doug Lea
90ce3da70b43 Initial load
duke
parents:
diff changeset
    82
 * @author Josh Bloch
90ce3da70b43 Initial load
duke
parents:
diff changeset
    83
 * @param <E> the type of elements maintained by this set
90ce3da70b43 Initial load
duke
parents:
diff changeset
    84
 * @since 1.6
90ce3da70b43 Initial load
duke
parents:
diff changeset
    85
 */
90ce3da70b43 Initial load
duke
parents:
diff changeset
    86
public interface NavigableSet<E> extends SortedSet<E> {
90ce3da70b43 Initial load
duke
parents:
diff changeset
    87
    /**
90ce3da70b43 Initial load
duke
parents:
diff changeset
    88
     * Returns the greatest element in this set strictly less than the
90ce3da70b43 Initial load
duke
parents:
diff changeset
    89
     * given element, or {@code null} if there is no such element.
90ce3da70b43 Initial load
duke
parents:
diff changeset
    90
     *
90ce3da70b43 Initial load
duke
parents:
diff changeset
    91
     * @param e the value to match
90ce3da70b43 Initial load
duke
parents:
diff changeset
    92
     * @return the greatest element less than {@code e},
90ce3da70b43 Initial load
duke
parents:
diff changeset
    93
     *         or {@code null} if there is no such element
90ce3da70b43 Initial load
duke
parents:
diff changeset
    94
     * @throws ClassCastException if the specified element cannot be
90ce3da70b43 Initial load
duke
parents:
diff changeset
    95
     *         compared with the elements currently in the set
90ce3da70b43 Initial load
duke
parents:
diff changeset
    96
     * @throws NullPointerException if the specified element is null
90ce3da70b43 Initial load
duke
parents:
diff changeset
    97
     *         and this set does not permit null elements
90ce3da70b43 Initial load
duke
parents:
diff changeset
    98
     */
90ce3da70b43 Initial load
duke
parents:
diff changeset
    99
    E lower(E e);
90ce3da70b43 Initial load
duke
parents:
diff changeset
   100
90ce3da70b43 Initial load
duke
parents:
diff changeset
   101
    /**
90ce3da70b43 Initial load
duke
parents:
diff changeset
   102
     * Returns the greatest element in this set less than or equal to
90ce3da70b43 Initial load
duke
parents:
diff changeset
   103
     * the given element, or {@code null} if there is no such element.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   104
     *
90ce3da70b43 Initial load
duke
parents:
diff changeset
   105
     * @param e the value to match
90ce3da70b43 Initial load
duke
parents:
diff changeset
   106
     * @return the greatest element less than or equal to {@code e},
90ce3da70b43 Initial load
duke
parents:
diff changeset
   107
     *         or {@code null} if there is no such element
90ce3da70b43 Initial load
duke
parents:
diff changeset
   108
     * @throws ClassCastException if the specified element cannot be
90ce3da70b43 Initial load
duke
parents:
diff changeset
   109
     *         compared with the elements currently in the set
90ce3da70b43 Initial load
duke
parents:
diff changeset
   110
     * @throws NullPointerException if the specified element is null
90ce3da70b43 Initial load
duke
parents:
diff changeset
   111
     *         and this set does not permit null elements
90ce3da70b43 Initial load
duke
parents:
diff changeset
   112
     */
90ce3da70b43 Initial load
duke
parents:
diff changeset
   113
    E floor(E e);
90ce3da70b43 Initial load
duke
parents:
diff changeset
   114
90ce3da70b43 Initial load
duke
parents:
diff changeset
   115
    /**
90ce3da70b43 Initial load
duke
parents:
diff changeset
   116
     * Returns the least element in this set greater than or equal to
90ce3da70b43 Initial load
duke
parents:
diff changeset
   117
     * the given element, or {@code null} if there is no such element.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   118
     *
90ce3da70b43 Initial load
duke
parents:
diff changeset
   119
     * @param e the value to match
90ce3da70b43 Initial load
duke
parents:
diff changeset
   120
     * @return the least element greater than or equal to {@code e},
90ce3da70b43 Initial load
duke
parents:
diff changeset
   121
     *         or {@code null} if there is no such element
90ce3da70b43 Initial load
duke
parents:
diff changeset
   122
     * @throws ClassCastException if the specified element cannot be
90ce3da70b43 Initial load
duke
parents:
diff changeset
   123
     *         compared with the elements currently in the set
90ce3da70b43 Initial load
duke
parents:
diff changeset
   124
     * @throws NullPointerException if the specified element is null
90ce3da70b43 Initial load
duke
parents:
diff changeset
   125
     *         and this set does not permit null elements
90ce3da70b43 Initial load
duke
parents:
diff changeset
   126
     */
90ce3da70b43 Initial load
duke
parents:
diff changeset
   127
    E ceiling(E e);
90ce3da70b43 Initial load
duke
parents:
diff changeset
   128
90ce3da70b43 Initial load
duke
parents:
diff changeset
   129
    /**
90ce3da70b43 Initial load
duke
parents:
diff changeset
   130
     * Returns the least element in this set strictly greater than the
90ce3da70b43 Initial load
duke
parents:
diff changeset
   131
     * given element, or {@code null} if there is no such element.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   132
     *
90ce3da70b43 Initial load
duke
parents:
diff changeset
   133
     * @param e the value to match
90ce3da70b43 Initial load
duke
parents:
diff changeset
   134
     * @return the least element greater than {@code e},
90ce3da70b43 Initial load
duke
parents:
diff changeset
   135
     *         or {@code null} if there is no such element
90ce3da70b43 Initial load
duke
parents:
diff changeset
   136
     * @throws ClassCastException if the specified element cannot be
90ce3da70b43 Initial load
duke
parents:
diff changeset
   137
     *         compared with the elements currently in the set
90ce3da70b43 Initial load
duke
parents:
diff changeset
   138
     * @throws NullPointerException if the specified element is null
90ce3da70b43 Initial load
duke
parents:
diff changeset
   139
     *         and this set does not permit null elements
90ce3da70b43 Initial load
duke
parents:
diff changeset
   140
     */
90ce3da70b43 Initial load
duke
parents:
diff changeset
   141
    E higher(E e);
90ce3da70b43 Initial load
duke
parents:
diff changeset
   142
90ce3da70b43 Initial load
duke
parents:
diff changeset
   143
    /**
90ce3da70b43 Initial load
duke
parents:
diff changeset
   144
     * Retrieves and removes the first (lowest) element,
90ce3da70b43 Initial load
duke
parents:
diff changeset
   145
     * or returns {@code null} if this set is empty.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   146
     *
90ce3da70b43 Initial load
duke
parents:
diff changeset
   147
     * @return the first element, or {@code null} if this set is empty
90ce3da70b43 Initial load
duke
parents:
diff changeset
   148
     */
90ce3da70b43 Initial load
duke
parents:
diff changeset
   149
    E pollFirst();
90ce3da70b43 Initial load
duke
parents:
diff changeset
   150
90ce3da70b43 Initial load
duke
parents:
diff changeset
   151
    /**
90ce3da70b43 Initial load
duke
parents:
diff changeset
   152
     * Retrieves and removes the last (highest) element,
90ce3da70b43 Initial load
duke
parents:
diff changeset
   153
     * or returns {@code null} if this set is empty.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   154
     *
90ce3da70b43 Initial load
duke
parents:
diff changeset
   155
     * @return the last element, or {@code null} if this set is empty
90ce3da70b43 Initial load
duke
parents:
diff changeset
   156
     */
90ce3da70b43 Initial load
duke
parents:
diff changeset
   157
    E pollLast();
90ce3da70b43 Initial load
duke
parents:
diff changeset
   158
90ce3da70b43 Initial load
duke
parents:
diff changeset
   159
    /**
90ce3da70b43 Initial load
duke
parents:
diff changeset
   160
     * Returns an iterator over the elements in this set, in ascending order.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   161
     *
90ce3da70b43 Initial load
duke
parents:
diff changeset
   162
     * @return an iterator over the elements in this set, in ascending order
90ce3da70b43 Initial load
duke
parents:
diff changeset
   163
     */
90ce3da70b43 Initial load
duke
parents:
diff changeset
   164
    Iterator<E> iterator();
90ce3da70b43 Initial load
duke
parents:
diff changeset
   165
90ce3da70b43 Initial load
duke
parents:
diff changeset
   166
    /**
90ce3da70b43 Initial load
duke
parents:
diff changeset
   167
     * Returns a reverse order view of the elements contained in this set.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   168
     * The descending set is backed by this set, so changes to the set are
90ce3da70b43 Initial load
duke
parents:
diff changeset
   169
     * reflected in the descending set, and vice-versa.  If either set is
90ce3da70b43 Initial load
duke
parents:
diff changeset
   170
     * modified while an iteration over either set is in progress (except
90ce3da70b43 Initial load
duke
parents:
diff changeset
   171
     * through the iterator's own {@code remove} operation), the results of
90ce3da70b43 Initial load
duke
parents:
diff changeset
   172
     * the iteration are undefined.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   173
     *
90ce3da70b43 Initial load
duke
parents:
diff changeset
   174
     * <p>The returned set has an ordering equivalent to
90ce3da70b43 Initial load
duke
parents:
diff changeset
   175
     * <tt>{@link Collections#reverseOrder(Comparator) Collections.reverseOrder}(comparator())</tt>.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   176
     * The expression {@code s.descendingSet().descendingSet()} returns a
90ce3da70b43 Initial load
duke
parents:
diff changeset
   177
     * view of {@code s} essentially equivalent to {@code s}.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   178
     *
90ce3da70b43 Initial load
duke
parents:
diff changeset
   179
     * @return a reverse order view of this set
90ce3da70b43 Initial load
duke
parents:
diff changeset
   180
     */
90ce3da70b43 Initial load
duke
parents:
diff changeset
   181
    NavigableSet<E> descendingSet();
90ce3da70b43 Initial load
duke
parents:
diff changeset
   182
90ce3da70b43 Initial load
duke
parents:
diff changeset
   183
    /**
90ce3da70b43 Initial load
duke
parents:
diff changeset
   184
     * Returns an iterator over the elements in this set, in descending order.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   185
     * Equivalent in effect to {@code descendingSet().iterator()}.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   186
     *
90ce3da70b43 Initial load
duke
parents:
diff changeset
   187
     * @return an iterator over the elements in this set, in descending order
90ce3da70b43 Initial load
duke
parents:
diff changeset
   188
     */
90ce3da70b43 Initial load
duke
parents:
diff changeset
   189
    Iterator<E> descendingIterator();
90ce3da70b43 Initial load
duke
parents:
diff changeset
   190
90ce3da70b43 Initial load
duke
parents:
diff changeset
   191
    /**
90ce3da70b43 Initial load
duke
parents:
diff changeset
   192
     * Returns a view of the portion of this set whose elements range from
90ce3da70b43 Initial load
duke
parents:
diff changeset
   193
     * {@code fromElement} to {@code toElement}.  If {@code fromElement} and
90ce3da70b43 Initial load
duke
parents:
diff changeset
   194
     * {@code toElement} are equal, the returned set is empty unless {@code
4670
fb58a0e847a6 6828204: NavigableSet.subSet() documentation refers to nonexistent parameters
darcy
parents: 2
diff changeset
   195
     * fromInclusive} and {@code toInclusive} are both true.  The returned set
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
   196
     * is backed by this set, so changes in the returned set are reflected in
90ce3da70b43 Initial load
duke
parents:
diff changeset
   197
     * this set, and vice-versa.  The returned set supports all optional set
90ce3da70b43 Initial load
duke
parents:
diff changeset
   198
     * operations that this set supports.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   199
     *
90ce3da70b43 Initial load
duke
parents:
diff changeset
   200
     * <p>The returned set will throw an {@code IllegalArgumentException}
90ce3da70b43 Initial load
duke
parents:
diff changeset
   201
     * on an attempt to insert an element outside its range.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   202
     *
90ce3da70b43 Initial load
duke
parents:
diff changeset
   203
     * @param fromElement low endpoint of the returned set
90ce3da70b43 Initial load
duke
parents:
diff changeset
   204
     * @param fromInclusive {@code true} if the low endpoint
90ce3da70b43 Initial load
duke
parents:
diff changeset
   205
     *        is to be included in the returned view
90ce3da70b43 Initial load
duke
parents:
diff changeset
   206
     * @param toElement high endpoint of the returned set
90ce3da70b43 Initial load
duke
parents:
diff changeset
   207
     * @param toInclusive {@code true} if the high endpoint
90ce3da70b43 Initial load
duke
parents:
diff changeset
   208
     *        is to be included in the returned view
90ce3da70b43 Initial load
duke
parents:
diff changeset
   209
     * @return a view of the portion of this set whose elements range from
90ce3da70b43 Initial load
duke
parents:
diff changeset
   210
     *         {@code fromElement}, inclusive, to {@code toElement}, exclusive
90ce3da70b43 Initial load
duke
parents:
diff changeset
   211
     * @throws ClassCastException if {@code fromElement} and
90ce3da70b43 Initial load
duke
parents:
diff changeset
   212
     *         {@code toElement} cannot be compared to one another using this
90ce3da70b43 Initial load
duke
parents:
diff changeset
   213
     *         set's comparator (or, if the set has no comparator, using
90ce3da70b43 Initial load
duke
parents:
diff changeset
   214
     *         natural ordering).  Implementations may, but are not required
90ce3da70b43 Initial load
duke
parents:
diff changeset
   215
     *         to, throw this exception if {@code fromElement} or
90ce3da70b43 Initial load
duke
parents:
diff changeset
   216
     *         {@code toElement} cannot be compared to elements currently in
90ce3da70b43 Initial load
duke
parents:
diff changeset
   217
     *         the set.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   218
     * @throws NullPointerException if {@code fromElement} or
90ce3da70b43 Initial load
duke
parents:
diff changeset
   219
     *         {@code toElement} is null and this set does
90ce3da70b43 Initial load
duke
parents:
diff changeset
   220
     *         not permit null elements
90ce3da70b43 Initial load
duke
parents:
diff changeset
   221
     * @throws IllegalArgumentException if {@code fromElement} is
90ce3da70b43 Initial load
duke
parents:
diff changeset
   222
     *         greater than {@code toElement}; or if this set itself
90ce3da70b43 Initial load
duke
parents:
diff changeset
   223
     *         has a restricted range, and {@code fromElement} or
90ce3da70b43 Initial load
duke
parents:
diff changeset
   224
     *         {@code toElement} lies outside the bounds of the range.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   225
     */
90ce3da70b43 Initial load
duke
parents:
diff changeset
   226
    NavigableSet<E> subSet(E fromElement, boolean fromInclusive,
90ce3da70b43 Initial load
duke
parents:
diff changeset
   227
                           E toElement,   boolean toInclusive);
90ce3da70b43 Initial load
duke
parents:
diff changeset
   228
90ce3da70b43 Initial load
duke
parents:
diff changeset
   229
    /**
90ce3da70b43 Initial load
duke
parents:
diff changeset
   230
     * Returns a view of the portion of this set whose elements are less than
90ce3da70b43 Initial load
duke
parents:
diff changeset
   231
     * (or equal to, if {@code inclusive} is true) {@code toElement}.  The
90ce3da70b43 Initial load
duke
parents:
diff changeset
   232
     * returned set is backed by this set, so changes in the returned set are
90ce3da70b43 Initial load
duke
parents:
diff changeset
   233
     * reflected in this set, and vice-versa.  The returned set supports all
90ce3da70b43 Initial load
duke
parents:
diff changeset
   234
     * optional set operations that this set supports.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   235
     *
90ce3da70b43 Initial load
duke
parents:
diff changeset
   236
     * <p>The returned set will throw an {@code IllegalArgumentException}
90ce3da70b43 Initial load
duke
parents:
diff changeset
   237
     * on an attempt to insert an element outside its range.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   238
     *
90ce3da70b43 Initial load
duke
parents:
diff changeset
   239
     * @param toElement high endpoint of the returned set
90ce3da70b43 Initial load
duke
parents:
diff changeset
   240
     * @param inclusive {@code true} if the high endpoint
90ce3da70b43 Initial load
duke
parents:
diff changeset
   241
     *        is to be included in the returned view
90ce3da70b43 Initial load
duke
parents:
diff changeset
   242
     * @return a view of the portion of this set whose elements are less than
90ce3da70b43 Initial load
duke
parents:
diff changeset
   243
     *         (or equal to, if {@code inclusive} is true) {@code toElement}
90ce3da70b43 Initial load
duke
parents:
diff changeset
   244
     * @throws ClassCastException if {@code toElement} is not compatible
90ce3da70b43 Initial load
duke
parents:
diff changeset
   245
     *         with this set's comparator (or, if the set has no comparator,
90ce3da70b43 Initial load
duke
parents:
diff changeset
   246
     *         if {@code toElement} does not implement {@link Comparable}).
90ce3da70b43 Initial load
duke
parents:
diff changeset
   247
     *         Implementations may, but are not required to, throw this
90ce3da70b43 Initial load
duke
parents:
diff changeset
   248
     *         exception if {@code toElement} cannot be compared to elements
90ce3da70b43 Initial load
duke
parents:
diff changeset
   249
     *         currently in the set.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   250
     * @throws NullPointerException if {@code toElement} is null and
90ce3da70b43 Initial load
duke
parents:
diff changeset
   251
     *         this set does not permit null elements
90ce3da70b43 Initial load
duke
parents:
diff changeset
   252
     * @throws IllegalArgumentException if this set itself has a
90ce3da70b43 Initial load
duke
parents:
diff changeset
   253
     *         restricted range, and {@code toElement} lies outside the
90ce3da70b43 Initial load
duke
parents:
diff changeset
   254
     *         bounds of the range
90ce3da70b43 Initial load
duke
parents:
diff changeset
   255
     */
90ce3da70b43 Initial load
duke
parents:
diff changeset
   256
    NavigableSet<E> headSet(E toElement, boolean inclusive);
90ce3da70b43 Initial load
duke
parents:
diff changeset
   257
90ce3da70b43 Initial load
duke
parents:
diff changeset
   258
    /**
90ce3da70b43 Initial load
duke
parents:
diff changeset
   259
     * Returns a view of the portion of this set whose elements are greater
90ce3da70b43 Initial load
duke
parents:
diff changeset
   260
     * than (or equal to, if {@code inclusive} is true) {@code fromElement}.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   261
     * The returned set is backed by this set, so changes in the returned set
90ce3da70b43 Initial load
duke
parents:
diff changeset
   262
     * are reflected in this set, and vice-versa.  The returned set supports
90ce3da70b43 Initial load
duke
parents:
diff changeset
   263
     * all optional set operations that this set supports.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   264
     *
90ce3da70b43 Initial load
duke
parents:
diff changeset
   265
     * <p>The returned set will throw an {@code IllegalArgumentException}
90ce3da70b43 Initial load
duke
parents:
diff changeset
   266
     * on an attempt to insert an element outside its range.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   267
     *
90ce3da70b43 Initial load
duke
parents:
diff changeset
   268
     * @param fromElement low endpoint of the returned set
90ce3da70b43 Initial load
duke
parents:
diff changeset
   269
     * @param inclusive {@code true} if the low endpoint
90ce3da70b43 Initial load
duke
parents:
diff changeset
   270
     *        is to be included in the returned view
90ce3da70b43 Initial load
duke
parents:
diff changeset
   271
     * @return a view of the portion of this set whose elements are greater
90ce3da70b43 Initial load
duke
parents:
diff changeset
   272
     *         than or equal to {@code fromElement}
90ce3da70b43 Initial load
duke
parents:
diff changeset
   273
     * @throws ClassCastException if {@code fromElement} is not compatible
90ce3da70b43 Initial load
duke
parents:
diff changeset
   274
     *         with this set's comparator (or, if the set has no comparator,
90ce3da70b43 Initial load
duke
parents:
diff changeset
   275
     *         if {@code fromElement} does not implement {@link Comparable}).
90ce3da70b43 Initial load
duke
parents:
diff changeset
   276
     *         Implementations may, but are not required to, throw this
90ce3da70b43 Initial load
duke
parents:
diff changeset
   277
     *         exception if {@code fromElement} cannot be compared to elements
90ce3da70b43 Initial load
duke
parents:
diff changeset
   278
     *         currently in the set.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   279
     * @throws NullPointerException if {@code fromElement} is null
90ce3da70b43 Initial load
duke
parents:
diff changeset
   280
     *         and this set does not permit null elements
90ce3da70b43 Initial load
duke
parents:
diff changeset
   281
     * @throws IllegalArgumentException if this set itself has a
90ce3da70b43 Initial load
duke
parents:
diff changeset
   282
     *         restricted range, and {@code fromElement} lies outside the
90ce3da70b43 Initial load
duke
parents:
diff changeset
   283
     *         bounds of the range
90ce3da70b43 Initial load
duke
parents:
diff changeset
   284
     */
90ce3da70b43 Initial load
duke
parents:
diff changeset
   285
    NavigableSet<E> tailSet(E fromElement, boolean inclusive);
90ce3da70b43 Initial load
duke
parents:
diff changeset
   286
90ce3da70b43 Initial load
duke
parents:
diff changeset
   287
    /**
90ce3da70b43 Initial load
duke
parents:
diff changeset
   288
     * {@inheritDoc}
90ce3da70b43 Initial load
duke
parents:
diff changeset
   289
     *
90ce3da70b43 Initial load
duke
parents:
diff changeset
   290
     * <p>Equivalent to {@code subSet(fromElement, true, toElement, false)}.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   291
     *
90ce3da70b43 Initial load
duke
parents:
diff changeset
   292
     * @throws ClassCastException       {@inheritDoc}
90ce3da70b43 Initial load
duke
parents:
diff changeset
   293
     * @throws NullPointerException     {@inheritDoc}
90ce3da70b43 Initial load
duke
parents:
diff changeset
   294
     * @throws IllegalArgumentException {@inheritDoc}
90ce3da70b43 Initial load
duke
parents:
diff changeset
   295
     */
90ce3da70b43 Initial load
duke
parents:
diff changeset
   296
    SortedSet<E> subSet(E fromElement, E toElement);
90ce3da70b43 Initial load
duke
parents:
diff changeset
   297
90ce3da70b43 Initial load
duke
parents:
diff changeset
   298
    /**
90ce3da70b43 Initial load
duke
parents:
diff changeset
   299
     * {@inheritDoc}
90ce3da70b43 Initial load
duke
parents:
diff changeset
   300
     *
90ce3da70b43 Initial load
duke
parents:
diff changeset
   301
     * <p>Equivalent to {@code headSet(toElement, false)}.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   302
     *
90ce3da70b43 Initial load
duke
parents:
diff changeset
   303
     * @throws ClassCastException       {@inheritDoc}
90ce3da70b43 Initial load
duke
parents:
diff changeset
   304
     * @throws NullPointerException     {@inheritDoc}
90ce3da70b43 Initial load
duke
parents:
diff changeset
   305
     * @throws IllegalArgumentException {@inheritDoc}
90ce3da70b43 Initial load
duke
parents:
diff changeset
   306
na     */
90ce3da70b43 Initial load
duke
parents:
diff changeset
   307
    SortedSet<E> headSet(E toElement);
90ce3da70b43 Initial load
duke
parents:
diff changeset
   308
90ce3da70b43 Initial load
duke
parents:
diff changeset
   309
    /**
90ce3da70b43 Initial load
duke
parents:
diff changeset
   310
     * {@inheritDoc}
90ce3da70b43 Initial load
duke
parents:
diff changeset
   311
     *
90ce3da70b43 Initial load
duke
parents:
diff changeset
   312
     * <p>Equivalent to {@code tailSet(fromElement, true)}.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   313
     *
90ce3da70b43 Initial load
duke
parents:
diff changeset
   314
     * @throws ClassCastException       {@inheritDoc}
90ce3da70b43 Initial load
duke
parents:
diff changeset
   315
     * @throws NullPointerException     {@inheritDoc}
90ce3da70b43 Initial load
duke
parents:
diff changeset
   316
     * @throws IllegalArgumentException {@inheritDoc}
90ce3da70b43 Initial load
duke
parents:
diff changeset
   317
     */
90ce3da70b43 Initial load
duke
parents:
diff changeset
   318
    SortedSet<E> tailSet(E fromElement);
90ce3da70b43 Initial load
duke
parents:
diff changeset
   319
}