| /* |
| * Licensed to the Apache Software Foundation (ASF) under one or more |
| * contributor license agreements. See the NOTICE file distributed with |
| * this work for additional information regarding copyright ownership. |
| * The ASF licenses this file to You under the Apache License, Version 2.0 |
| * (the "License"); you may not use this file except in compliance with |
| * the License. You may obtain a copy of the License at |
| * |
| * http://www.apache.org/licenses/LICENSE-2.0 |
| * |
| * Unless required by applicable law or agreed to in writing, software |
| * distributed under the License is distributed on an "AS IS" BASIS, |
| * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| * See the License for the specific language governing permissions and |
| * limitations under the License. |
| */ |
| |
| #ifndef _DECAF_UTIL_LIST_H_ |
| #define _DECAF_UTIL_LIST_H_ |
| |
| #include <decaf/util/NoSuchElementException.h> |
| #include <decaf/lang/exceptions/IndexOutOfBoundsException.h> |
| #include <decaf/util/concurrent/Synchronizable.h> |
| #include <decaf/util/Config.h> |
| #include <decaf/util/Iterator.h> |
| #include <decaf/util/Collection.h> |
| #include <decaf/util/AbstractCollection.h> |
| #include <decaf/util/ListIterator.h> |
| |
| namespace decaf{ |
| namespace util{ |
| |
| /** |
| * An ordered collection (also known as a sequence). The user of this interface has |
| * precise control over where in the list each element is inserted. The user can |
| * access elements by their integer index (position in the list), and search for |
| * elements in the list. |
| * |
| * Unlike sets, lists typically allow duplicate elements. More formally, lists |
| * typically allow pairs of elements e1 and e2 such that e1.equals(e2), and they |
| * typically allow multiple null elements if they allow null elements at all. |
| * It is not inconceivable that someone might wish to implement a list that |
| * prohibits duplicates, by throwing runtime exceptions when the user attempts |
| * to insert them, but we expect this usage to be rare. |
| */ |
| template <typename E> |
| class DECAF_API List : public virtual decaf::util::Collection<E> { |
| public: |
| |
| // Un-hide any methods from Collection that the declarations in this interface hid. |
| using decaf::util::Collection<E>::add; |
| using decaf::util::Collection<E>::addAll; |
| using decaf::util::Collection<E>::remove; |
| |
| public: |
| |
| List() {} |
| |
| virtual ~List() {} |
| |
| /** |
| * @return a list iterator over the elements in this list (in proper sequence). |
| */ |
| virtual ListIterator<E>* listIterator() = 0; |
| virtual ListIterator<E>* listIterator() const = 0; |
| |
| /** |
| * @param index index of first element to be returned from the list iterator |
| * (by a call to the next method). |
| * |
| * @return a list iterator of the elements in this list (in proper sequence), |
| * starting at the specified position in this list. The specified index |
| * indicates the first element that would be returned by an initial call |
| * to next. An initial call to previous would return the element with the |
| * specified index minus one. |
| * |
| * @throws IndexOutOfBoundsException if the index is out of range |
| * (index < 0 || index > size()) |
| */ |
| virtual ListIterator<E>* listIterator(int index) = 0; |
| virtual ListIterator<E>* listIterator(int index) const = 0; |
| |
| /** |
| * Returns the index of the first occurrence of the specified element in |
| * this list, or -1 if this list does not contain the element. More |
| * formally, returns the lowest index i such that get(i) == value, or |
| * -1 if there is no such index. |
| * |
| * @param value |
| * The element to search for in this List. |
| * |
| * @return the index of the first occurrence of the specified element in this list, |
| * |
| * @throws NullPointerException if the Collection is a container of pointers |
| * and does not allow NULL values. |
| */ |
| virtual int indexOf(const E& value) const = 0; |
| |
| /** |
| * Returns the index of the last occurrence of the specified element in |
| * this list, or -1 if this list does not contain the element. More |
| * formally, returns the highest index i such that get(i) == value |
| * or -1 if there is no such index. |
| * |
| * @param value |
| * The element to search for in this List. |
| * |
| * @return the index of the last occurrence of the specified element in this list. |
| * |
| * @throws NullPointerException if the Collection is a container of pointers |
| * and does not allow NULL values. |
| */ |
| virtual int lastIndexOf(const E& value) const = 0; |
| |
| /** |
| * Gets the element contained at position passed. |
| * |
| * @param index |
| * The position to get. |
| * |
| * @return value at index specified. |
| * |
| * @throws IndexOutOfBoundsException if the index given is less than zero |
| * or greater than the List size. |
| */ |
| virtual E get(int index) const = 0; |
| |
| /** |
| * Replaces the element at the specified position in this list with the |
| * specified element. |
| * |
| * @param index |
| * The index of the element to replace. |
| * @param element |
| * The element to be stored at the specified position. |
| * |
| * @return the element previously at the specified position. |
| * |
| * @throws IndexOutOfBoundsException if the index given is less than zero |
| * or greater than the List size. |
| * @throws UnsupportedOperationExceptio if this is an unmodifiable collection. |
| * @throws NullPointerException if the Collection is a container of pointers |
| * and does not allow NULL values. |
| * @throws IllegalArgumentException if some property of the element prevents it |
| * from being added to this collection |
| * @throws IllegalStateException if the element cannot be added at this time due |
| * to insertion restrictions. |
| */ |
| virtual E set(int index, const E& element) = 0; |
| |
| /** |
| * Inserts the specified element at the specified position in this list. |
| * Shifts the element currently at that position (if any) and any |
| * subsequent elements to the right (adds one to their indices). |
| * |
| * @param index |
| * The index at which the specified element is to be inserted. |
| * @param element |
| * The element to be inserted in this List. |
| * |
| * @throws IndexOutOfBoundsException if the index is greater than size of the List. |
| * @throws UnsupportedOperationExceptio if this is an unmodifiable collection. |
| * @throws NullPointerException if the Collection is a container of pointers |
| * and does not allow NULL values. |
| * @throws IllegalArgumentException if some property of the element prevents it |
| * from being added to this collection |
| * @throws IllegalStateException if the element cannot be added at this time due |
| * to insertion restrictions. |
| */ |
| virtual void add(int index, const E& element) = 0; |
| |
| /** |
| * Inserts all of the elements in the specified collection into this list at |
| * the specified position (optional operation). Shifts the element currently at |
| * that position (if any) and any subsequent elements to the right (increases |
| * their indices). The new elements will appear in this list in the order that |
| * they are returned by the specified collection's iterator. The behavior of this |
| * operation is undefined if the specified collection is modified while the |
| * operation is in progress. (Note that this will occur if the specified collection |
| * is this list, and it's nonempty.) |
| * |
| * @param index |
| * The index at which to insert the first element from the specified collection |
| * @param source |
| * The Collection containing elements to be added to this list |
| * |
| * @return true if this list changed as a result of the call |
| * |
| * @throws IndexOutOfBoundsException if the index given is less than zero |
| * or greater than the List size. |
| * @throws UnsupportedOperationExceptio if this is an unmodifiable collection. |
| * @throws NullPointerException if the Collection is a container of pointers |
| * and does not allow NULL values. |
| * @throws IllegalArgumentException if some property of the element prevents it |
| * from being added to this collection |
| * @throws IllegalStateException if the element cannot be added at this time due |
| * to insertion restrictions. |
| */ |
| virtual bool addAll(int index, const Collection<E>& source) = 0; |
| |
| /** |
| * Removes the element at the specified position in this list. |
| * Shifts any subsequent elements to the left (subtracts one from their |
| * indices). Returns the element that was removed from the list. |
| * |
| * @param index - the index of the element to be removed. |
| * |
| * @return the element previously at the specified position. |
| * |
| * @throws IndexOutOfBoundsException if the index given is less than zero |
| * or greater than the List size. |
| * @throws UnsupportedOperationExceptio if this is an unmodifiable collection. |
| */ |
| virtual E removeAt(int index) = 0; |
| |
| }; |
| |
| }} |
| |
| #endif /*_DECAF_UTIL_LIST_H_*/ |