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_LIST_HPP 00008 #define COH_LIST_HPP 00009 00010 #include "coherence/lang.ns" 00011 00012 #include "coherence/util/Collection.hpp" 00013 #include "coherence/util/ListIterator.hpp" 00014 #include "coherence/util/ListMuterator.hpp" 00015 00016 COH_OPEN_NAMESPACE2(coherence,util) 00017 00018 00019 /** 00020 * An ordered collection (also known as a sequence). 00021 * 00022 * The user of this interface has precise control over where in the list each 00023 * element is inserted. The user can access elements by their integer index 00024 * (position in the list), and search for elements in the list. Unlike sets, 00025 * lists typically allow duplicate elements. 00026 * 00027 * The List interface places additional stipulations, beyond those specified 00028 * in the Collection interface, on the contracts of the iterator, add, remove, 00029 * equals, and hashCode methods. 00030 * 00031 * @see Collection 00032 * 00033 * @author js/nsa 2008.01.03 00034 */ 00035 class COH_EXPORT List 00036 : public interface_spec<List, 00037 implements<Collection> > 00038 { 00039 // ----- constants ------------------------------------------------------ 00040 00041 public: 00042 /** 00043 * The largest possible value of type size32_t. 00044 */ 00045 static const size32_t npos = size32_t(-1); 00046 00047 00048 // ----- List interface ------------------------------------------------- 00049 00050 public: 00051 /** 00052 * Add the given element to this collection at the position specified. 00053 * If an element is already at that position it will be shifted to the 00054 * right by 1. 00055 * 00056 * @param i the position to insert the element at 00057 * @param oh the element to add 00058 * 00059 * @return true iff this list was modified as a result of this 00060 * operation 00061 * 00062 * @throw coherence::lang::IndexOutOfBoundsException if the index is 00063 * out of range 00064 */ 00065 virtual bool add(size32_t i, Object::Holder oh) = 0; 00066 00067 /** 00068 * Add all the elements from the supplied collection to this 00069 * collection at the position specified. 00070 * 00071 * @param i the index of the list to add the elements to 00072 * @param vc the collection to add to this list 00073 * 00074 * @return true iff this list was modified as a result of this 00075 * operation 00076 * 00077 * @throw coherence::lang::IndexOutOfBoundsException if the inedex 00078 * is out of range 00079 */ 00080 virtual bool addAll(size32_t i, Collection::View vc) = 0; 00081 00082 /** 00083 * Return the element from the specified position in the list. 00084 * 00085 * @param i the position of the item to return 00086 * 00087 * @return the element from the specified position in the list 00088 * 00089 * @throw coherence::lang::IndexOutOfBoundsException if the index is 00090 * out of range 00091 */ 00092 virtual Object::Holder get(size32_t i) const = 0; 00093 00094 /** 00095 * Return the element from the specified position in the list. 00096 * 00097 * @param i the position of the item to return 00098 * 00099 * @return the element from the specified position in the list 00100 * 00101 * @throw coherence::lang::IndexOutOfBoundsException if the index is 00102 * out of range 00103 */ 00104 virtual Object::Holder get(size32_t i) = 0; 00105 00106 /** 00107 * Return the position in the list of the first instance of the 00108 * specified element. 00109 * 00110 * @param v The object in the list to return the index of 00111 * 00112 * @return the position of the object if found, or List::npos 00113 */ 00114 virtual size32_t indexOf(Object::View v) const = 0; 00115 00116 /** 00117 * Return the position in this list of the last instance of the 00118 * specified element. 00119 * 00120 * @param v The element to search for in the list 00121 * 00122 * @return the position of the element if found, or List::npos 00123 */ 00124 virtual size32_t lastIndexOf(Object::View v) const = 0; 00125 00126 /** 00127 * Return a ListIterator for this list starting at index 00128 * 00129 * @param i the index to start the ListIterator at 00130 * 00131 * @return a ListIterator for this list start at index 00132 */ 00133 virtual ListIterator::Handle listIterator(size32_t i = 0) const = 0; 00134 00135 /** 00136 * Return a ListIterator for this list starting at index 00137 * 00138 * @param i the index to start the ListIterator at 00139 * 00140 * @return a ListIterator for this list start at index 00141 */ 00142 virtual ListMuterator::Handle listIterator(size32_t i = 0) = 0; 00143 00144 /** 00145 * Remove the element at the specified position in the list. 00146 * 00147 * @param i the index from which to remove an element 00148 * 00149 * @return the element at the specified position prior to this 00150 * operation 00151 * 00152 * @throw coherence::lang::IndexOutOfBoundsException if the index is 00153 * out of range 00154 */ 00155 virtual Object::Holder remove(size32_t i) = 0; 00156 00157 /** 00158 * Replace the element at the specified position in this list with the 00159 * specified element. 00160 * 00161 * @param i the position in the list to replace 00162 * @param oh the object to replace at the specified position 00163 * 00164 * @return the element at the specified position prior to this 00165 * operation 00166 * 00167 * @throw coherence::lang::IndexOutOfBoundsException if the index is 00168 * out of range 00169 */ 00170 virtual Object::Holder set(size32_t i, Object::Holder oh) = 0; 00171 00172 /** 00173 * Return a new list containing the contents of the list between the 00174 * specified fromIndex (inclusive) and toIndex (exclusive). 00175 * 00176 * @param iFrom the start position in this list to create the 00177 * sublist from (inclusive). 00178 * @param iTo the end position in this list to end the sublist 00179 * at (exclusive). 00180 * 00181 * @return the new sublist of this list 00182 */ 00183 virtual List::View subList(size32_t iFrom, size32_t iTo) const = 0; 00184 00185 /** 00186 * Return a new list containing the contents of the list between the 00187 * specified fromIndex (inclusive) and toIndex (exclusive). 00188 * 00189 * @param iFrom the start position in this list to create the 00190 * sublist from (inclusive). 00191 * @param iTo the end position in this list to end the sublist 00192 * at (exclusive). 00193 * 00194 * @return the new sublist of this list 00195 */ 00196 virtual List::Handle subList(size32_t iFrom, size32_t iTo) = 0; 00197 00198 00199 // ----- Collection interface ------------------------------------------- 00200 00201 public: 00202 /** 00203 * Add the given element to the end of this list. 00204 * 00205 * @param oh element to be added to this list 00206 * 00207 * @return true 00208 */ 00209 using Collection::add; 00210 00211 /** 00212 * {@inheritDoc} 00213 */ 00214 using Collection::addAll; 00215 00216 /** 00217 * {@inheritDoc} 00218 */ 00219 using Collection::remove; 00220 00221 00222 // ----- Object interface ----------------------------------------------- 00223 00224 public: 00225 /** 00226 * Compares the specified object with this list for equality. 00227 * 00228 * Two lists are defined to be equal iff they contain the same 00229 * elements in the same order. This definition ensures that the equals 00230 * method works properly across different implementations of the List 00231 * interface. 00232 * 00233 * @param vObj the Object to be compared for equality with this list 00234 * 00235 * @return true if the specified Object is equal to this list. 00236 */ 00237 using Object::equals; 00238 00239 /** 00240 * The hash code of a List is defined as follows: 00241 * <code> 00242 * size32_t nHash = 1; 00243 * for (Iterator::Handle hIter = list.iterator(); hIter->hasNext(); ) 00244 * { 00245 * Object::View v = hIter->next(); 00246 * nHash = 31 * nHash + Object::hashCode(v); 00247 * } 00248 * </code> This ensures that <code>l1->equals(l2)</code> implies that 00249 * <code>l1->hashCode() == l2->hashCode()</code> for any two lists 00250 * <tt>l1</tt> and <tt>l2</tt>, as required by the general contract of 00251 * Object::hashCode(). 00252 * 00253 * @return the hash code value for this list 00254 */ 00255 using Object::hashCode; 00256 }; 00257 00258 COH_CLOSE_NAMESPACE2 00259 00260 #endif // COH_LIST_HPP