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