/* * 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 #include #include #include #include #include #include #include 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 class DECAF_API List : public virtual decaf::util::Collection { public: // Un-hide any methods from Collection that the declarations in this interface hid. using decaf::util::Collection::add; using decaf::util::Collection::addAll; using decaf::util::Collection::remove; public: List() {} virtual ~List() {} /** * @return a list iterator over the elements in this list (in proper sequence). */ virtual ListIterator* listIterator() = 0; virtual ListIterator* 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* listIterator( int index ) = 0; virtual ListIterator* 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& 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_*/