content: /* 
   * 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;
  
  import java.util.NoSuchElementException;
  
  /**
   * An ordered set of integers.  
   *
   * @specfield ints: set int
   * @author Emina Torlak
   */
  public interface IntSet extends IntCollection, Cloneable {
  	
  	/**
  	 * Returns the cardinality of this set.
  	 * @return #this.ints
  	 */
  	public abstract int size();
  	
  	/**
  	 * Returns true if this set has no elements; 
  	 * otherwise returns false.
  	 * @return no this.ints
  	 */
  	public abstract boolean isEmpty();
  	
  	/**
  	 * Returns true if i is in this set.
  	 * @return i in this.ints
  	 */
  	public abstract boolean contains(int i);
  
  	/**
  	 * Returns the smallest element in this set.
  	 * Throws a NoSuchElementException if this set is empty.
  	 * @return min(this.ints)
  	 * @throws java.util.NoSuchElementException  no this.ints
  	 */
  	public abstract int min();
  	
  	/**
  	 * Returns the largest element in this set.
  	 * Throws a NoSuchElementException if this set is empty.
  	 * @return max(this.ints)
  	 * @throws java.util.NoSuchElementException  no this.ints
  	 */
  	public abstract int max();
  	
  	/**
  	 * Returns the largest element in this set that 
  	 * is smaller than or equal to i.  If this is emtpy or i is less than this.min(),
  	 * NoSuchElementException is thrown.
  	 * @return {j: this.ints | j <= i && no k: this.ints - j | k > j && k <= i}
  	 * @throws NoSuchElementException  no this.ints || i < this.min()
  	 */
  	public abstract int floor(int i);
  	
  	/**
  	 * Returns the smallest element in this set that 
  	 * is greater than or equal to i.  If this is emtpy or i is greater than this.max(),
  	 * NoSuchElementException is thrown.
  	 * @return {j: this.ints | j >= i && no k: this.ints - j | k < j && k >= i}
  	 * @throws NoSuchElementException  no this.ints || i > this.max()
  	 */
  	public abstract int ceil(int i);
  	
  	/**
  	 * Returns an iterator over the integers in this set,
  	 * in the ascending element order.
  	 * @return an IntIterator over the integers in this set.
  	 */
  	public abstract IntIterator iterator();
  	
  	/**
  	 * Returns an iterator over the elements of this set that
  	 * are in the closed range [from..to].  If from < to, 
  	 * the elements are returned in the ascending order.  
  	 * Otherwise, they are returned in the descending order.
  	 * @return an iterator over the elements in this set
  	 * that are in the closed range [from..to]. 
  	 */
  	public abstract IntIterator iterator(int from, int to);
  	
  	/**
  	 * Adds the given integer to this set if not already present
  	 * and returns true.  Otherwise does nothing and returns false.
  	 * @ensures this.ints' = this.ints + i
  	 * @return i in this.ints'
  	 * @throws IllegalArgumentException  this is a bounded set
  	 * and i is out of bounds
  	 */
  	public abstract boolean add(int i);
  
  	/**
  	 * Removes the given integer from this set if already present and
  	 * returns true.  Otherwise does nothing and returns false.
  	 * @ensures this.ints' = this.ints - i
  	 * @return i !in this.ints'
  	 */
  	public abstract boolean remove(int i);
  	
  	/**
  	 * Returns true if the elements of c are a subset of this set.
  	 * @return { i: int | c.contains(i) } in this.ints
  	 * @throws NullPointerException  c = null
  	 */
  	public abstract boolean containsAll(IntCollection c);
  	
  	/**
  	 * Adds all of the elements in the specified collection to this set 
  	 * if they're not already present. 
  	 * @ensures this.ints' = this.ints + { i: int | c.contains(i) }
  	 * @return this.ints' != this.ints
  	 * @throws NullPointerException  c = null
  	 * @throws UnsupportedOperationException  this is an unmodifiable set
  	 * @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 from this set all of its elements that are contained in the 
  	 * specified set. 
  	 * @ensures this.ints' = this.ints - { i: int | c.contains(i) }
  	 * @return this.ints' != this.ints
  	 * @throws NullPointerException  s = null
  	 * @throws UnsupportedOperationException  this is an unmodifiable set
  	 */
  	public abstract boolean removeAll(IntCollection c);
  	
  	/**
  	 * Retains only the elements in this set that are contained in the 
  	 * specified set. 
  	 * @ensures this.ints' = this.ints & { i: int | c.contains(i) }
  	 * @return this.ints' != this.ints
  	 * @throws NullPointerException  s = null
  	 * @throws UnsupportedOperationException  this is an unmodifiable set
  	 */
  	public abstract boolean retainAll(IntCollection c);
  	
  	/**
  	 * Removes all elements from this set. 
  	 * @ensures no this.ints'
  	 */
  	public abstract void clear();
  	
  	/**
  	 * Returns a copy of this IntSet.  The copy is independent of this 
  	 * IntSet unless this is a singleton or an immutable set, in which case
  	 * clone() may return this.  An implementing class that does not support
  	 * cloning may throw a CloneNotSupportedException.
  	 * @return a copy of this IntSet.
  	 * @throws CloneNotSupportedException  this is not cloneable
  	 */
  	public abstract IntSet clone() throws CloneNotSupportedException;
  	
  	/**
       * Returns an array containing all of the elements in this set in the
       * ascending order.
       *
       * @return an array containing all of the elements in this set in the
       * ascending order.
       */
  	public abstract int[] toArray();
  	
  	/**
       * Copies the elements of this set into the specified array, in the ascending
       * order, provided that the array is large enough. If the array is not large enough,
       * the effect of this method is the same as calling {@linkplain #toArray()}.
       * @ensures array.length>=this.size() => all i: [0..this.size()) | array'[i] in this.ints and #{e: this.ints | e < array'[i]} = i
       * @return array.length>=this.size() => array' else this.toArray()
       * @throws NullPointerException  array = null
       */
      public abstract int[] toArray(int[] array);
      
      /**
       * Compares the specified object with this set for equality. 
       * Returns true if the specified object is also an IntSet, 
       * the two sets have the same size, and every member of the 
       * specified set is contained in this set (or equivalently, 
       * every member of this set is contained in the specified set). 
       * This definition ensures that the equals method works properly 
       * across different implementations of the IntSet interface.
       * @return o instanceof IntSet and o.size() = this.size() and this.containsAll(o)
       */
      public abstract boolean equals(Object o);
      
      /**
       * Returns the hash code value for this set. The hash code of a set is 
       * defined to be the {@link Ints#superFastHash(int[])} of the elements in the set, 
       * taken in the ascending order of values.  
       * This ensures that s1.equals(s2) implies that s1.hashCode()==s2.hashCode() 
       * for any two IntSets s1 and s2, as required by the general contract of the Object.hashCode method.
       * @return Ints.superFastHash(this.toArray())
       */
      public abstract int hashCode();
  }