Oracle® Fusion Middleware C++ API Reference for Oracle Coherence
12c (12.2.1.1.0)

E69640-01

coherence/util/List.hpp

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