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 * @since Android 1.0
31 */
32public interface SortedSet<E> extends Set<E> {
33
34    /**
35     * Returns the comparator used to compare elements in this {@code SortedSet}.
36     *
37     * @return a comparator or null if the natural ordering is used.
38     * @since Android 1.0
39     */
40    public Comparator<? super E> comparator();
41
42    /**
43     * Returns the first element in this {@code SortedSet}. The first element
44     * is the lowest element.
45     *
46     * @return the first element.
47     * @throws NoSuchElementException
48     *             when this {@code SortedSet} is empty.
49     * @since Android 1.0
50     */
51    public E first();
52
53    /**
54     * Returns a {@code SortedSet} of the specified portion of this
55     * {@code SortedSet} which contains elements less than the end element. The
56     * returned {@code SortedSet} is backed by this {@code SortedSet} so changes
57     * to one set are reflected by the other.
58     *
59     * @param end
60     *            the end element.
61     * @return a subset where the elements are less than {@code end}.
62     * @throws ClassCastException
63     *             when the class of the end element is inappropriate for this
64     *             SubSet.
65     * @throws NullPointerException
66     *             when the end element is null and this {@code SortedSet} does
67     *             not support null elements.
68     * @since Android 1.0
69     */
70    public SortedSet<E> headSet(E end);
71
72    /**
73     * Returns the last element in this {@code SortedSet}. The last element is
74     * the highest element.
75     *
76     * @return the last element.
77     * @throws NoSuchElementException
78     *             when this {@code SortedSet} is empty.
79     * @since Android 1.0
80     */
81    public E last();
82
83    /**
84     * Returns a {@code SortedSet} of the specified portion of this
85     * {@code SortedSet} which contains elements greater or equal to the start
86     * element but less than the end element. The returned {@code SortedSet} is
87     * backed by this SortedMap so changes to one set are reflected by the
88     * other.
89     *
90     * @param start
91     *            the start element.
92     * @param end
93     *            the end element.
94     * @return a subset where the elements are greater or equal to {@code start}
95     *         and less than {@code end}.
96     * @throws ClassCastException
97     *             when the class of the start or end element is inappropriate
98     *             for this SubSet.
99     * @throws NullPointerException
100     *             when the start or end element is null and this
101     *             {@code SortedSet} does not support null elements.
102     * @throws IllegalArgumentException
103     *             when the start element is greater than the end element.
104     * @since Android 1.0
105     */
106    public SortedSet<E> subSet(E start, E end);
107
108    /**
109     * Returns a {@code SortedSet} of the specified portion of this
110     * {@code SortedSet} which contains elements greater or equal to the start
111     * element. The returned {@code SortedSet} is backed by this
112     * {@code SortedSet} so changes to one set are reflected by the other.
113     *
114     * @param start
115     *            the start element.
116     * @return a subset where the elements are greater or equal to {@code start} .
117     * @throws ClassCastException
118     *             when the class of the start element is inappropriate for this
119     *             SubSet.
120     * @throws NullPointerException
121     *             when the start element is null and this {@code SortedSet}
122     *             does not support null elements.
123     * @since Android 1.0
124     */
125    public SortedSet<E> tailSet(E start);
126}
127