/* * 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_COLLECTION_H_ #define _DECAF_UTIL_COLLECTION_H_ #include #include #include #include #include namespace decaf{ namespace util{ /** * The root interface in the collection hierarchy. A collection represents * a group of objects, known as its elements. Some collections allow * duplicate elements and others do not. Some are ordered and others * unordered. This interface is typically used to pass collections * around and manipulate them where maximum generality is desired. * * All general-purpose Collection implementation classes (which typically * implement Collection indirectly through one of its subinterfaces) should * provide two "standard" constructors: a void (no arguments) constructor, * which creates an empty collection, and a constructor with a single argument * of type Collection, which creates a new collection with the same elements * as its argument. In effect, the latter constructor allows the user to copy * any collection, producing an equivalent collection of the desired * implementation type. There is no way to enforce this convention * (as interfaces cannot contain constructors) but all of the general-purpose * Collection implementations in the Decaf platform libraries comply. * * The "destructive" methods contained in this interface, that is, the methods * that modify the collection on which they operate, are specified to throw * UnsupportedOperationException if this collection does not support the * operation. If this is the case, these methods may, but are not required * to, throw an UnsupportedOperationException if the invocation would have * no effect on the collection. For example, invoking the addAll(Collection) * method on an unmodifiable collection may, but is not required to, throw * the exception if the collection to be added is empty. * * Many methods in Collections Framework interfaces are defined in terms of * the equals method. For example, the specification for the * contains(Object o) method says: "returns true if and only if this * collection contains at least one element e such that * (o==null ? e==null : o.equals(e))." * * @since 1.0 */ template< typename T > class Collection { public: virtual ~Collection() {} /** * Returns the number of elements in this collection. If this collection * contains more than Integer.MAX_VALUE elements, returns Integer.MAX_VALUE. * @returns the number of elements in this collection */ virtual int size() = 0; /** * @returns true if this collection contains no elements. */ virtual bool isEmpty() = 0; /** * Returns true if this collection contains the specified element. More * formally, returns true if and only if this collection contains at * least one element e such that (o==null ? e==null : o.equals(e)). * @param value - value to check for presence in the collection * @returns true if there is at least one of the elements in the collection * @thorws NullPointerException */ virtual bool contains( const E& value ) throw ( lang::exceptions::NullPointerException ) = 0; /** * Returns an iterator over the elements in this collection. There are * no guarantees concerning the order in which the elements are * returned (unless this collection is an instance of some class that * provides a guarantee). * @returns an Iterator over the elements in this collection */ virtual Iterator* iterator() = 0; /** * Returns an array containing all of the elements in this collection. If * the collection makes any guarantees as to what order its elements are * returned by its iterator, this method must return the elements in the * same order. * * This method acts as bridge between array-based and collection-based APIs. * @returns an array of the elements in this collection. */ virtual std::vector toArray() = 0; /** * Returns true if this collection changed as a result of the call. * (Returns false if this collection does not permit duplicates and * already contains the specified element.) * * Collections that support this operation may place limitations on * what elements may be added to this collection. In particular, * some collections will refuse to add null elements, and others * will impose restrictions on the type of elements that may be * added. Collection classes should clearly specify in their * documentation any restrictions on what elements may be added. * * If a collection refuses to add a particular element for any * reason other than that it already contains the element, it must * throw an exception (rather than returning false). This preserves * the invariant that a collection always contains the specified * element after this call returns. * * For non-pointer values, i.e. class instances or string's the object * will be copied into the collection, thus the object must support * being copied, must not hide the copy constructor and assignment * operator. * * @param value - reference to the element to add. * @returns true if the element was added * @throw UnsupportedOperationException * @throw NullPointerException * @throw IllegalArgumentException */ virtual bool add( const E& value ) throw ( lang::exceptions::UnsupportedOperationException, lang::exceptions::NullPointerException, lang::exceptions::IllegalArgumentException ) = 0; /** * Removes a single instance of the specified element from the * collection. More formally, removes an element e such that * (o==null ? e==null : o.equals(e)), if this collection contains one * or more such elements. Returns true if this collection contained * the specified element (or equivalently, if this collection changed * as a result of the call). * @param value - reference to the element to remove. * @returns true if the collection was changed * @throw UnsupportedOperationException * @throw NullPointerException */ virtual bool remove( const E& value ) throw ( lang::exceptions::UnsupportedOperationException, lang::exceptions::NullPointerException ) = 0; /** * Returns true if this collection contains all of the elements in * the specified collection. * @param source - Collection to compare to this one. * @thorw Exception */ virtual bool containsAll( const Collection& source ) throw ( lang::Exception ) = 0; /** * Adds all of the elements in the specified collection to this * collection. The behavior of this operation is undefined if the * specified collection is modified while the operation is in progress. * (This implies that the behavior of this call is undefined if the * specified collection is this collection, and this collection is * nonempty.) * @param source - Collection whose elements are added to this one. * @return true if this collection changed as a result of the call * @throw UnsupportedOperationException * @throw NullPointerException * @throw IllegalArgumentException */ virtual bool addAll( const Collection& source ) throw ( lang::exceptions::UnsupportedOperationException, lang::exceptions::NullPointerException, lang::exceptions::IllegalArgumentException ) = 0; /** * Removes all this collection's elements that are also contained in * the specified collection (optional operation). After this call returns, * this collection will contain no elements in common with the specified * collection. * @param value - The Collection whose elements are to be removed * @returns true if the collection changed as a result of this call * @throw UnsupportedOperationException * @throw NullPointerException * @throw IllegalArgumentException */ virtual bool removeAll( const Collection& value ) throw ( lang::exceptions::UnsupportedOperationException, lang::exceptions::NullPointerException, lang::exceptions::IllegalArgumentException ) = 0; /** * Retains only the elements in this collection that are contained in the * specified collection (optional operation). In other words, removes from * this collection all of its elements that are not contained in the * specified collection. * @param value - The Collection whose elements are to be retained * @returns true if the collection changed as a result of this call * @throw UnsupportedOperationException * @throw NullPointerException * @throw IllegalArgumentException */ virtual bool retainAll( const Collection value ) throw ( lang::exceptions::UnsupportedOperationException, lang::exceptions::NullPointerException, lang::exceptions::IllegalArgumentException ) = 0; /** * Removes all of the elements from this collection (optional operation). * This collection will be empty after this method returns unless it throws * an exception. * @throw UnsupportedOperationException */ virtual void clear() throw ( lang::exceptions::UnsupportedOperationException ) = 0; /** * Compares the passed collection to this one, if they contain the * same elements, i.e. all their elements are equivalent, then it * returns true. * @returns true if the Collections contain the same elements. */ virtual bool equals( const Collection& value ) = 0; }; }} #endif /*_DECAF_UTIL_COLLECTION_H_*/