1/*
2 *  Licensed to the Apache Software Foundation (ASF) under one or more
3 *  contributor license agreements.  See the NOTICE file distributed with
4 *  this work for additional information regarding copyright ownership.
5 *  The ASF licenses this file to You under the Apache License, Version 2.0
6 *  (the "License"); you may not use this file except in compliance with
7 *  the License.  You may obtain a copy of the License at
8 *
9 *     http://www.apache.org/licenses/LICENSE-2.0
10 *
11 *  Unless required by applicable law or agreed to in writing, software
12 *  distributed under the License is distributed on an "AS IS" BASIS,
13 *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 *  See the License for the specific language governing permissions and
15 *  limitations under the License.
16 */
17
18package java.util;
19
20
21/**
22 * SortedSet is a Set which iterates over its elements in a sorted order. The
23 * order is determined either by the elements natural ordering, or by a
24 * {@link Comparator} which is passed into a concrete implementation at
25 * construction time. All elements in this set must be mutually comparable. The
26 * ordering in this set must be consistent with {@code equals} of its elements.
27 *
28 * @see Comparator
29 * @see Comparable
30 */
31public interface SortedSet<E> extends Set<E> {
32
33    /**
34     * Returns the comparator used to compare elements in this {@code SortedSet}.
35     *
36     * @return a comparator or null if the natural ordering is used.
37     */
38    public Comparator<? super E> comparator();
39
40    /**
41     * Returns the first element in this {@code SortedSet}. The first element
42     * is the lowest element.
43     *
44     * @return the first element.
45     * @throws NoSuchElementException
46     *             when this {@code SortedSet} is empty.
47     */
48    public E first();
49
50    /**
51     * Returns a {@code SortedSet} of the specified portion of this
52     * {@code SortedSet} which contains elements less than the end element. The
53     * returned {@code SortedSet} is backed by this {@code SortedSet} so changes
54     * to one set are reflected by the other.
55     *
56     * @param end
57     *            the end element.
58     * @return a subset where the elements are less than {@code end}.
59     * @throws ClassCastException
60     *             when the class of the end element is inappropriate for this
61     *             SubSet.
62     * @throws NullPointerException
63     *             when the end element is null and this {@code SortedSet} does
64     *             not support null elements.
65     */
66    public SortedSet<E> headSet(E end);
67
68    /**
69     * Returns the last element in this {@code SortedSet}. The last element is
70     * the highest element.
71     *
72     * @return the last element.
73     * @throws NoSuchElementException
74     *             when this {@code SortedSet} is empty.
75     */
76    public E last();
77
78    /**
79     * Returns a {@code SortedSet} of the specified portion of this
80     * {@code SortedSet} which contains elements greater or equal to the start
81     * element but less than the end element. The returned {@code SortedSet} is
82     * backed by this SortedMap so changes to one set are reflected by the
83     * other.
84     *
85     * @param start
86     *            the start element.
87     * @param end
88     *            the end element.
89     * @return a subset where the elements are greater or equal to {@code start}
90     *         and less than {@code end}.
91     * @throws ClassCastException
92     *             when the class of the start or end element is inappropriate
93     *             for this SubSet.
94     * @throws NullPointerException
95     *             when the start or end element is null and this
96     *             {@code SortedSet} does not support null elements.
97     * @throws IllegalArgumentException
98     *             when the start element is greater than the end element.
99     */
100    public SortedSet<E> subSet(E start, E end);
101
102    /**
103     * Returns a {@code SortedSet} of the specified portion of this
104     * {@code SortedSet} which contains elements greater or equal to the start
105     * element. The returned {@code SortedSet} is backed by this
106     * {@code SortedSet} so changes to one set are reflected by the other.
107     *
108     * @param start
109     *            the start element.
110     * @return a subset where the elements are greater or equal to {@code start} .
111     * @throws ClassCastException
112     *             when the class of the start element is inappropriate for this
113     *             SubSet.
114     * @throws NullPointerException
115     *             when the start element is null and this {@code SortedSet}
116     *             does not support null elements.
117     */
118    public SortedSet<E> tailSet(E start);
119}
120