IntCollection.java

/* 
 * Kodkod -- Copyright (c) 2005-present, Emina Torlak
 *
 * Permission is hereby granted, free of charge, to any person obtaining a copy
 * of this software and associated documentation files (the "Software"), to deal
 * in the Software without restriction, including without limitation the rights
 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 * copies of the Software, and to permit persons to whom the Software is
 * furnished to do so, subject to the following conditions:
 *
 * The above copyright notice and this permission notice shall be included in
 * all copies or substantial portions of the Software.
 *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
 * THE SOFTWARE.
 */
package kodkod.util.ints;

/**
 * The root interface in the int collection hierarchy. A collection 
 * represents a group of integers, known as its elements. Some collections 
 * allow duplicate elements and others do not. Some are ordered and others unordered.
 * Some allow all integers and others only integers in a certain range.
 * 
 * @author Emina Torlak
 */
public interface IntCollection {

	/**
	 * Returns the number of elements in this collection.
	 * @return number of elements in this collection.
	 */
	public abstract int size();
	
	/**
	 * Returns true if this collection has no elements; 
	 * otherwise returns false.
	 * @return true if this collection has no elements, 
	 * false otherwise.
	 */
	public abstract boolean isEmpty();
	
	/**
	 * 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).
	 * @return an iterator over the elements in this collection
	 */
	public abstract IntIterator iterator();
	
	/**
	 * Returns true if i is an element in this collection.
	 * @return true if i is an element in this collection.
	 */
	public abstract boolean contains(int i);
	
	/**
	 * Ensures that this collection contains the given integer, and returns true
	 * if this collection has changed as a result of the call.  
	 * @return true if this collection has changed as a result of the call
	 * @throws UnsupportedOperationException  this is an unmodifiable collection
	 * @throws IllegalArgumentException  some aspect of the element prevents it 
	 * from being added to this collection.
	 */
	public abstract boolean add(int i);

	/**
	 * Removes a single instance of the given integer from this collection,
	 * and returns true if this collection has changed as a result of the call.
	 * @return true if this collection has changed as a result of the call
	 * @throws UnsupportedOperationException  this is an unmodifiable collection
	 */
	public abstract boolean remove(int i);
	
	/**
	 * Returns true if this collection contains all of the elements in the specified collection.
	 * @return true if this collection contains all of the elements in the specified collection.
	 * @throws NullPointerException  c = null
	 */
	public abstract boolean containsAll(IntCollection c);
	
	/**
	 * Adds all of the elements in the specified collection to this collection.
	 * Returns true if this collection has changed as a result of the call.
	 * @return true if this collection has changed as a result of the call
	 * @throws NullPointerException  c = null
	 * @throws UnsupportedOperationException  this is an unmodifiable collection
	 * @throws IllegalArgumentException  some aspect of an element of the specified 
	 * collection prevents it from being added to this collection.
	 */
	public abstract boolean addAll(IntCollection c);
	
	/**
	 * Removes all of this collection's elements that are also contained in the specified 
	 * collection. After this call returns, this collection will contain no elements in 
	 * common with the specified collection. Returns true if this collection has changed as a result of the call. 
	 * @return true if this collection has changed as a result of the call
	 * @throws NullPointerException  c = null
	 * @throws UnsupportedOperationException  this is an unmodifiable collection
	 */
	public abstract boolean removeAll(IntCollection c);
	
	/**
	 * Retains only the elements in this collection that are contained in the specified 
	 * collection. In other words, removes from this collection all of its elements that 
	 * are not contained in the specified collection.  Returns true if this collection has changed as a result of the call. 
	 * @return rue if this collection has changed as a result of the call
	 * @throws NullPointerException  c = null
	 * @throws UnsupportedOperationException  this is an unmodifiable collection
	 */
	public abstract boolean retainAll(IntCollection c);
	
	/**
	 * Removes all elements from this collection. 
	 * @throws UnsupportedOperationException  this is an unmodifiable collection
	 */
	public abstract void clear();
	
	/**
     * Returns an array containing all of the elements in this collection.
     * @return an array containing all of the elements in this collection.
     */
	public abstract int[] toArray();
	
	/**
     * Copies the elements of this collection into the specified array, provided
     * that it is large enough, and returns it.  If the array is not large enough,
     * the effect of this method is the same as calling {@linkplain #toArray()}.
     * @return the given array, filled with the elements from this collection, if
     * the it is large enough; otherwise a new array containing all of the elements
     * in this collection.
     * @throws NullPointerException  array = null
     */
    public abstract int[] toArray(int[] array);
}