home *** CD-ROM | disk | FTP | other *** search
/ Java 1.2 How-To / JavaHowTo.iso / 3rdParty / jbuilder / unsupported / JDK1.2beta3 / SOURCE / SRC.ZIP / java / util / Set.java < prev    next >
Encoding:
Java Source  |  1998-03-20  |  8.9 KB  |  247 lines
  1. /*
  2.  * @(#)Set.java    1.14 98/03/18
  3.  *
  4.  * Copyright 1997 by Sun Microsystems, Inc.,
  5.  * 901 San Antonio Road, Palo Alto, California, 94303, U.S.A.
  6.  * All rights reserved.
  7.  *
  8.  * This software is the confidential and proprietary information
  9.  * of Sun Microsystems, Inc. ("Confidential Information").  You
  10.  * shall not disclose such Confidential Information and shall use
  11.  * it only in accordance with the terms of the license agreement
  12.  * you entered into with Sun.
  13.  */
  14.  
  15. package java.util;
  16.  
  17. /**
  18.  * A Collection that contains no duplicate elements.  More formally, Sets
  19.  * contain no pair of elements <code>e1</code> and <code>e2</code> such that
  20.  * <code>e1.equals(e2)</code>, and at most one null element.  As implied by
  21.  * its name, this interface models the mathematical <i>set</i> abstraction.
  22.  * <p>
  23.  * The Set interface places additional stipulations, beyond those inherited
  24.  * from the Collection interface, on the contracts of all constructors and of
  25.  * the add, equals and hashCode methods.  Declarations for other inherited
  26.  * methods are also included here for convenience.  (The specifications
  27.  * accompanying these declarations have been tailored to Set, but they do not
  28.  * contain any additional stipulations.)
  29.  * <p>
  30.  * The additional stipulation on constructors is, not surprisingly,
  31.  * that all constructors must create a Set that contain no duplicate elements
  32.  * (as defined above).
  33.  * <p>
  34.  * Implemented by HashSet, ArraySet.
  35.  *
  36.  * @author  Josh Bloch
  37.  * @version 1.14 03/18/98
  38.  * @see Collection
  39.  * @see List
  40.  * @see HashSet
  41.  * @see ArraySet
  42.  * @see AbstractSet
  43.  * @since JDK1.2
  44.  */
  45.  
  46. public interface Set extends Collection {
  47.     // Query Operations
  48.  
  49.     /**
  50.      * Returns the number of elements in this Set (its cardinality).
  51.      *
  52.      * @since JDK1.2
  53.      */
  54.     int size();
  55.  
  56.     /**
  57.      * Returns true if this Set contains no elements.
  58.      *
  59.      * @since JDK1.2
  60.      */
  61.     boolean isEmpty();
  62.  
  63.     /**
  64.      * Returns true if this Set contains the specified element.  More
  65.      * formally, returns true if and only if this Set contains an element
  66.      * <code>e</code> such that <code>(o==null ? e==null : o.equals(e))</code>.
  67.      *
  68.      * @since JDK1.2
  69.      */
  70.     boolean contains(Object o);
  71.  
  72.     /**
  73.      * Returns an Iterator over the elements in this Set.  The elements are
  74.      * returned in no particular order (unless the Set is an instance of some
  75.      * class that provides a guarantee).
  76.      *
  77.      * @since JDK1.2
  78.      */
  79.     Iterator iterator();
  80.  
  81.     /**
  82.      * Returns an array containing all of the elements in this Set.
  83.      * Obeys the general contract of Collection.toArray.
  84.      *
  85.      * @since JDK1.2
  86.      */
  87.     Object[] toArray();
  88.  
  89.  
  90.     // Modification Operations
  91.  
  92.     /**
  93.      * Adds the specified element to this Set if it is not already present
  94.      * (optional operation).  More formally, adds the specified element,
  95.      * <code>o</code>, to the Set if the Set contains no element
  96.      * <code>e</code> such that <code>(o==null ? e==null :
  97.      * o.equals(e))</code>.  If the Set already contains the specified
  98.      * element, the call leaves the Set unchanged (and returns false).  In
  99.      * combination with the restriction on constructors, this ensures that
  100.      * Sets never contain duplicate elements.
  101.      * <p>
  102.      * This stipulation should not be construed to imply that Sets must
  103.      * accept all elements; Sets have the option of refusing to add any
  104.      * particular element, including null, and throwing an exception, as
  105.      * described in the specification for Collection.add.  Individual
  106.      * Set implementations should clearly document any restrictions on the
  107.      * the elements that they may contain.
  108.      *
  109.      * @param o element to be added to this Set.
  110.      * @return true if the Set did not already contain the specified element.
  111.      * @exception UnsupportedOperationException add is not supported
  112.      *           by this Set.
  113.      * @exception ClassCastException class of the specified element
  114.      *           prevents it from being added to this Set.
  115.      * @exception IllegalArgumentException some aspect of this element prevents
  116.      *          it from being added to this Set.
  117.      * @since JDK1.2
  118.      */
  119.     boolean add(Object o);
  120.  
  121.  
  122.     /**
  123.      * Removes the given element from this Set if it is present (optional
  124.      * operation).  More formally, removes an element <code>e</code> such
  125.      * that <code>(o==null ?  e==null : o.equals(e))</code>, if the Set
  126.      * contains such an element.  Returns true if the Set contained the
  127.      * specified element (or equivalently, if the Set changed as a result of
  128.      * the call).  (The Set will not contain the specified element once the
  129.      * call returns.)
  130.      *
  131.      * @param o object to be removed from this Set, if present.
  132.      * @return true if the Set contained the specified element.
  133.      * @exception UnsupportedOperationException remove is not supported
  134.      *          by this Set.
  135.      * @since JDK1.2
  136.      */
  137.     boolean remove(Object o);
  138.  
  139.  
  140.     // Bulk Operations
  141.  
  142.     /**
  143.      * Returns true if this Set contains all of the elements of the
  144.      * specified Collection.  If the specified Collection is also a Set,
  145.      * this method returns true if it is a <i>subset</i> of this Set.
  146.      *
  147.      * @since JDK1.2
  148.      */
  149.     boolean containsAll(Collection c);
  150.  
  151.     /**
  152.      * Adds all of the elements in the specified Collection to this Set if
  153.      * they're not already present (optional operation).  If the specified
  154.      * Collection is also a Set, this operation effectively modifies this Set
  155.      * so that its value is the <em>union</em> of the two Sets.  The behavior
  156.      * of this operation is unspecified if the specified Collection is
  157.      * modified while the operation is in progress.
  158.      *
  159.      * @return true if this Set changed as a result of the call.
  160.      * @exception UnsupportedOperationException addAll is not supported
  161.      *           by this Set.
  162.      * @exception ClassCastException class of some element of the specified
  163.      *           Collection prevents it from being added to this Set.
  164.      * @exception IllegalArgumentException some aspect of some element of the
  165.      *          specified Collection prevents it from being added to this
  166.      *          Set.
  167.      * @see #add(Object)
  168.      * @since JDK1.2
  169.      */
  170.     boolean addAll(Collection c);
  171.  
  172.     /**
  173.      * Retains only the elements in this Set that are contained in the
  174.      * specified Collection (optional operation).  In other words, removes
  175.      * from this Set all of its elements that are not contained in the
  176.      * specified Collection.  If the specified Collection is also a Set, this
  177.      * operation effectively modifies this Set so that its value is the
  178.      * <em>intersection</em> of the two Sets.
  179.      *
  180.      * @return true if this Collection changed as a result of the call.
  181.      * @exception UnsupportedOperationException retainAll is not supported
  182.      *           by this Collection.
  183.      * @see #remove(Object)
  184.      * @since JDK1.2
  185.      */
  186.     boolean retainAll(Collection c);
  187.  
  188.  
  189.     /**
  190.      * Removes from this Set all of its elements that are contained in the
  191.      * specified Collection (optional operation).  If the specified
  192.      * Collection is also a Set, this operation effectively modifies this Set
  193.      * so that its value is the <em>asymmetric set difference</em> of the two
  194.      * Sets.
  195.      *
  196.      * @return true if this Set changed as a result of the call.
  197.      * @exception UnsupportedOperationException removeAll is not supported
  198.      *           by this Collection.
  199.      * @see #remove(Object)
  200.      * @since JDK1.2
  201.      */
  202.     boolean removeAll(Collection c);
  203.  
  204.     /**
  205.      * Removes all of the elements from this Set (optional operation).  The
  206.      * Set will be empty after this call returns (unless it throws an
  207.      * exception).
  208.      *
  209.      * @exception UnsupportedOperationException clear is not supported
  210.      *           by this Set.
  211.      * @since JDK1.2
  212.      */
  213.     void clear();
  214.  
  215.  
  216.     // Comparison and hashing
  217.  
  218.     /**
  219.      * Compares the specified Object with this Set for equality.
  220.      * Returns true if the given object is also a Set, the two Sets have the
  221.      * same size, and every member of the given Set is contained in this Set.
  222.      * This ensures that the equals method works properly across different
  223.      * implementations of the Set interface.
  224.      *
  225.      * @param o Object to be compared for equality with this Set.
  226.      * @return true if the specified Object is equal to this Set.
  227.      * @since JDK1.2
  228.      */
  229.     boolean equals(Object o);
  230.  
  231.     /**
  232.      * Returns the hash code value for this Set.  The hash code of a Set is
  233.      * defined to be the sum of the hashCodes of the elements in the Set,
  234.      * where the hashcode of a null element is defined to be zero.  This
  235.      * ensures that <code>s1.equals(s2)</code> implies that
  236.      * <code>s1.hashCode()==s2.hashCode()</code> for any two Sets
  237.      * <code>s1</code> and <code>s2</code>, as required by the general
  238.      * contract of Object.hashCode.
  239.      *
  240.      * @see Object#hashCode()
  241.      * @see Object#equals(Object)
  242.      * @see Set#equals(Object)
  243.      * @since JDK1.2 
  244.      */
  245.     int hashCode();
  246. }
  247.