00001 /* 00002 * SortedSet.hpp 00003 * 00004 * Copyright (c) 2000, 2017, Oracle and/or its affiliates. All rights reserved. 00005 * 00006 * Oracle is a registered trademarks of Oracle Corporation and/or its 00007 * affiliates. 00008 * 00009 * This software is the confidential and proprietary information of Oracle 00010 * Corporation. You shall not disclose such confidential and proprietary 00011 * information and shall use it only in accordance with the terms of the 00012 * license agreement you entered into with Oracle. 00013 * 00014 * This notice may not be removed or altered. 00015 */ 00016 #ifndef COH_SORTED_SET_HPP 00017 #define COH_SORTED_SET_HPP 00018 00019 #include "coherence/lang.ns" 00020 00021 #include "coherence/util/Comparator.hpp" 00022 #include "coherence/util/Map.hpp" 00023 #include "coherence/util/Set.hpp" 00024 00025 COH_OPEN_NAMESPACE2(coherence,util) 00026 00027 /** 00028 * A Set that further provides a <i>total ordering</i> on its elements. 00029 * The elements are ordered using their Comparable natural 00030 * ordering, or by a Comparator typically provided at sorted 00031 * set creation time. The set's iterator will traverse the set in 00032 * ascending element order. Several additional operations are provided 00033 * to take advantage of the ordering. (This interface is the set 00034 * analogue of SortedMap.) 00035 * 00036 * @see Set 00037 * @see TreeSet 00038 * @see TreeMap 00039 * 00040 * @author hr 2011.09.07 00041 * 00042 * @since Coherence 12.1.2 00043 */ 00044 class COH_EXPORT SortedSet 00045 : public interface_spec<SortedSet, 00046 implements<Set> > 00047 { 00048 00049 // ----- SortedSet interface -------------------------------------------- 00050 00051 public: 00052 /** 00053 * Returns the comparator used in sorting this set, or NULL if it is 00054 * the keys' natural ordering. 00055 * 00056 * @return the sorting comparator 00057 */ 00058 virtual Comparator::View comparator() const = 0; 00059 00060 /** 00061 * Returns a handle of the portion of the set greater than or equal to 00062 * vFromElement, and strictly less than vToElement. The handle is 00063 * backed by this set, so changes in one show up in the other. 00064 * 00065 * @param vFromElement the inclusive lower range of the sub-set 00066 * @param vToElement the exclusive upper range of the sub-set 00067 * 00068 * @return the sub-set 00069 * 00070 * @throws ClassCastException if vFromElement or vToElement is not 00071 * comparable to the set's contents 00072 * @throws IllegalArgumentException if this is a sub-set, and 00073 * vFromElement or or vToElement is out of range 00074 * @throws NullPointerException if vFromElement or vToElement is NULL 00075 * but the map does not allow NULL elements 00076 */ 00077 virtual SortedSet::Handle subSet(Object::View vFromElement, 00078 Object::View vToElement) = 0; 00079 00080 /** 00081 * Returns a view of the portion of the set greater than or equal to 00082 * vFromElement, and strictly less than vToElement. 00083 * 00084 * @param vFromElement the inclusive lower range of the sub-set 00085 * @param vToElement the exclusive upper range of the sub-set 00086 * 00087 * @return the sub-set 00088 * 00089 * @throws ClassCastException if vFromElement or vToElement is not 00090 * comparable to the set's contents 00091 * @throws IllegalArgumentException if this is a sub-set, and 00092 * vFromElement or vToElement is out of range 00093 * @throws NullPointerException if vFromElement or vToElement is NULL 00094 * but the set does not allow NULL elements 00095 */ 00096 virtual SortedSet::View subSet(Object::View vFromElement, 00097 Object::View vToElement) const = 0; 00098 00099 /** 00100 * Returns a handle of the portion of the set strictly less than 00101 * vToElement. The handle is backed by this set, so changes in one show 00102 * up in the other. The sub-set supports all optional operations of 00103 * the original. 00104 * 00105 * @param vToElement the exclusive upper range of the sub-set 00106 * 00107 * @return the sub-set 00108 * 00109 * @throws ClassCastException if vToElement is not comparable to the 00110 * set contents 00111 * @throws IllegalArgumentException if this is a sub-set, and 00112 * vToElement is out of range 00113 * @throws NullPointerException if vToElement is NULL but the set does 00114 * not allow NULL elements 00115 */ 00116 virtual SortedSet::Handle headSet(Object::View vToElement) = 0; 00117 00118 /** 00119 * Returns a view of the portion of the set strictly less than 00120 * vToElement. 00121 * 00122 * @param vToElement the exclusive upper range of the sub-set 00123 * 00124 * @return the sub-set 00125 * 00126 * @throws ClassCastException if vToElement is not comparable to the 00127 * set contents 00128 * @throws IllegalArgumentException if this is a sub-set, and 00129 * vToElement is out of range 00130 * @throws NullPointerException if vToElement is NULL but the set does 00131 * not allow NULL elements 00132 */ 00133 virtual SortedSet::View headSet(Object::View vToElement) const = 0; 00134 00135 /** 00136 * Returns a handle of the portion of the set greater than or equal to 00137 * vFromElement. The handle is backed by this set, so changes in one 00138 * show up in the other. The sub-set supports all optional operations 00139 * of the original. 00140 * 00141 * @param vFromElement the inclusive lower range of the sub-set 00142 * 00143 * @return the sub-set 00144 * 00145 * @throws ClassCastException if vFromElement is not comparable to the 00146 * set contents 00147 * @throws IllegalArgumentException if this is a sub-set, and 00148 * vFromElement is out of range 00149 * @throws NullPointerException if vFromElement is NULL but the set 00150 * does not allow NULL elements 00151 */ 00152 virtual SortedSet::Handle tailSet(Object::View vFromElement) = 0; 00153 00154 /** 00155 * Returns a view of the portion of the set greater than or equal to 00156 * vFromElement. 00157 * 00158 * @param vFromElement the inclusive lower range of the sub-set 00159 * 00160 * @return the sub-set 00161 * 00162 * @throws ClassCastException if vFromElement is not comparable to the 00163 * set contents 00164 * @throws IllegalArgumentException if this is a sub-set, and 00165 * vFromElement is out of range 00166 * @throws NullPointerException if vFromElement is NULL but the set 00167 * does not allow NULL elements 00168 */ 00169 virtual SortedSet::View tailSet(Object::View vFromElement) const = 0; 00170 00171 /** 00172 * Returns the first (lowest sorted) element in the set. 00173 * 00174 * @return the first element 00175 * 00176 * @throws NoSuchElementException if this set is empty. 00177 */ 00178 virtual Object::View first() const = 0; 00179 00180 /** 00181 * Returns the last (highest sorted) element in the set. 00182 * 00183 * @return the last element 00184 * 00185 * @throws NoSuchElementException if this set is empty. 00186 */ 00187 virtual Object::View last() const = 0; 00188 }; 00189 00190 COH_CLOSE_NAMESPACE2 00191 00192 #endif // COH_SORTED_SET_HPP