001/* 002 * Copyright (c) 1998, 2023, Oracle and/or its affiliates. All rights reserved. 003 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 004 * 005 * This code is free software; you can redistribute it and/or modify it 006 * under the terms of the GNU General Public License version 2 only, as 007 * published by the Free Software Foundation. Oracle designates this 008 * particular file as subject to the "Classpath" exception as provided 009 * by Oracle in the LICENSE file that accompanied this code. 010 * 011 * This code is distributed in the hope that it will be useful, but WITHOUT 012 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 013 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 014 * version 2 for more details (a copy is included in the LICENSE file that 015 * accompanied this code). 016 * 017 * You should have received a copy of the GNU General Public License version 018 * 2 along with this work; if not, write to the Free Software Foundation, 019 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 020 * 021 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 022 * or visit www.oracle.com if you need additional information or have any 023 * questions. 024 */ 025package Torello.Java.ReadOnly; 026 027import Torello.Java.Additional.RemoveUnsupportedIterator; 028 029import java.util.Collection; 030import java.util.SortedSet; 031import java.util.Spliterator; 032import java.util.Spliterators; 033import java.util.Comparator; 034 035/** 036 * Immutable variant of Java Collections Framework interface 037 * <CODE>java.util.SortedSet<E></CODE>. 038 * 039 * <EMBED CLASS='external-html' DATA-JDK=ReadOnlySortedSet DATA-FILE-ID=INTERFACES> 040 * 041 * @param <E> the type of elements maintained by this set 042 */ 043@Torello.JavaDoc.JDHeaderBackgroundImg(EmbedTagFileID="JDHBI_INTERFACE") 044public interface ReadOnlySortedSet<E> extends ReadOnlySet<E>, ReadOnlySequencedSet<E> 045{ 046 // ******************************************************************************************** 047 // ******************************************************************************************** 048 // Original JDK Interface Methods 049 // ******************************************************************************************** 050 // ******************************************************************************************** 051 052 053 /** 054 * Returns the comparator used to order the elements in this set, or {@code null} if this set 055 * uses the {@linkplain Comparable natural ordering} of its elements. 056 * 057 * @return the comparator used to order the elements in this set, or {@code null} if this set 058 * uses the natural ordering of its elements 059 */ 060 Comparator<? super E> comparator(); 061 062 /** 063 * Returns a view of the portion of this set whose elements range from {@code fromElement}, 064 * inclusive, to {@code toElement}, exclusive. (If {@code fromElement} and {@code toElement} 065 * are equal, the returned set is empty.) The returned set supports all optional set 066 * operations that this set supports. 067 * 068 * @param fromElement low endpoint (inclusive) of the returned set 069 * @param toElement high endpoint (exclusive) of the returned set 070 * 071 * @return a view of the portion of this set whose elements range from {@code fromElement}, 072 * inclusive, to {@code toElement}, exclusive 073 * 074 * @throws ClassCastException if {@code fromElement} and {@code toElement} cannot be compared 075 * to one another using this set's comparator (or, if the set has no comparator, using natural 076 * ordering). Implementations may, but are not required to, throw this exception if 077 * {@code fromElement} or {@code toElement} cannot be compared to elements currently in the 078 * set. 079 * 080 * @throws NullPointerException if {@code fromElement} or {@code toElement} is null and this 081 * set does not permit null elements 082 * 083 * @throws IllegalArgumentException if {@code fromElement} is greater than {@code toElement}; 084 * or if this set itself has a restricted range, and {@code fromElement} or {@code toElement} 085 * lies outside the bounds of the range 086 */ 087 ReadOnlySortedSet<E> subSet(E fromElement, E toElement); 088 089 /** 090 * Returns a view of the portion of this set whose elements are strictly less than 091 * {@code toElement}. The returned set supports all optional set operations that this set 092 * supports. 093 * 094 * @param toElement high endpoint (exclusive) of the returned set 095 * 096 * @return a view of the portion of this set whose elements are strictly less than 097 * {@code toElement} 098 * 099 * @throws ClassCastException if {@code toElement} is not compatible with this set's comparator 100 * (or, if the set has no comparator, if {@code toElement} does not implement 101 * {@code Comparable}). Implementations may, but are not required to, throw this exception if 102 * {@code toElement} cannot be compared to elements currently in the set. 103 * 104 * @throws NullPointerException if {@code toElement} is null and this set does not permit null 105 * elements 106 * 107 * @throws IllegalArgumentException if this set itself has a restricted range, and 108 * {@code toElement} lies outside the bounds of the range 109 */ 110 ReadOnlySortedSet<E> headSet(E toElement); 111 112 /** 113 * Returns a view of the portion of this set whose elements are greater than or equal to 114 * {@code fromElement}. The returned set supports all optional set operations that this set 115 * supports. 116 * 117 * @param fromElement low endpoint (inclusive) of the returned set 118 * 119 * @return a view of the portion of this set whose elements are greater than or equal to 120 * {@code fromElement} 121 * 122 * @throws ClassCastException if {@code fromElement} is not compatible with this set's 123 * comparator (or, if the set has no comparator, if {@code fromElement} does not implement 124 * {@code Comparable}). Implementations may, but are not required to, throw this exception if 125 * {@code fromElement} cannot be compared to elements currently in the set. 126 * 127 * @throws NullPointerException if {@code fromElement} is null and this set does not permit 128 * null elements 129 * 130 * @throws IllegalArgumentException if this set itself has a restricted range, and 131 * {@code fromElement} lies outside the bounds of the range 132 */ 133 ReadOnlySortedSet<E> tailSet(E fromElement); 134 135 /** 136 * Returns the first (lowest) element currently in this set. 137 * 138 * @return the first (lowest) element currently in this set 139 * @throws NoSuchElementException if this set is empty 140 */ 141 E first(); 142 143 /** 144 * Returns the last (highest) element currently in this set. 145 * @return the last (highest) element currently in this set 146 * @throws NoSuchElementException if this set is empty 147 */ 148 E last(); 149 150 /** 151 * Creates a {@code Spliterator} over the elements in this sorted set. 152 * 153 * <BR /><BR />The {@code Spliterator} reports {@code Spliterator.DISTINCT}, 154 * {@code Spliterator.SORTED}}. Implementations should document the reporting of additional 155 * characteristic values. 156 * 157 * <BR /><BR />The spliterator's comparator (see 158 * {@link java.util.Spliterator#getComparator()}) must be {@code null} if 159 * the sorted set's comparator (see {@link #comparator()}) is {@code null}. 160 * Otherwise, the spliterator's comparator must be the same as or impose the 161 * same total ordering as the sorted set's comparator. 162 * 163 * @implSpec 164 * The default implementation creates a 165 * <em><code>late-binding</code></em> spliterator 166 * from the sorted set's {@code Iterator}. The spliterator inherits the 167 * <em>fail-fast</em> properties of the set's iterator. The 168 * spliterator's comparator is the same as the sorted set's comparator. 169 * 170 * <BR /><BR />The created {@code Spliterator} additionally reports {@code Spliterator.SIZED}. 171 * 172 * @implNote 173 * The created {@code Spliterator} additionally reports {@code Spliterator.SUBSIZED}. 174 * 175 * @return a {@code Spliterator} over the elements in this sorted set 176 */ 177 @Override 178 default Spliterator<E> spliterator() 179 { 180 // *** Java-HTML: Some Spliterators Code was copied into this package 181 return new Iterator_Spliterator<E> 182 (this, Spliterator.DISTINCT | Spliterator.SORTED | Spliterator.ORDERED) 183 { 184 @Override 185 public Comparator<? super E> getComparator() 186 { return ReadOnlySortedSet.this.comparator(); } 187 }; 188 } 189 190 191 // ******************************************************************************************** 192 // ******************************************************************************************** 193 // Original JDK Interface Methods: SEQUENCED-COLLECTION (New JDK21 Thing) 194 // ******************************************************************************************** 195 // ******************************************************************************************** 196 197 198 /** 199 * {@inheritDoc} 200 * 201 * @implSpec 202 * The implementation in this interface returns the result of calling the {@code first} method. 203 * 204 * @throws NoSuchElementException {@inheritDoc} 205 */ 206 default E getFirst() { return this.first(); } 207 208 /** 209 * {@inheritDoc} 210 * 211 * @implSpec 212 * The implementation in this interface returns the result of calling the {@code last} method. 213 * 214 * @throws NoSuchElementException {@inheritDoc} 215 */ 216 default E getLast() { return this.last(); } 217 218 /** 219 * {@inheritDoc} 220 * 221 * @implSpec 222 * The implementation in this interface returns a reverse-ordered {@code ReadOnlySortedSet} 223 * view. The {@code reversed()} method of the view returns a reference to this 224 * {@code ReadOnlySortedSet}. Other operations on the view are implemented via calls to public 225 * methods on this {@code ReadOnlySortedSet}. The exact relationship between calls on the view 226 * and calls on this {@code ReadOnlySortedSet} is unspecified. However, order-sensitive 227 * operations generally delegate to the appropriate method with the opposite orientation. For 228 * example, calling {@code getFirst} on the view results in a call to {@code getLast} on this 229 * {@code ReadOnlySortedSet}. 230 * 231 * @return a reverse-ordered view of this collection, as a {@code ReadOnlySortedSet} 232 */ 233 default ReadOnlySortedSet<E> reversed() 234 { 235 // *** Java-HTML: This is the use of the ReverseOrderedSortedSetView 236 // This was copied out of "Package-Private" stuff for the JDK 21 237 // from the OpenJDK class on Git-Hub 238 239 return JDKReverseOrderSortedSetView.of(this); 240 } 241}