| public interface Bag<E extends Base<?>> extends Collection<E> {
|
|
|
| /** |
| * Returns the number of occurrences (cardinality) of the given |
| * object currently in the bag. If the object does not exist in the |
| * bag, return 0. |
| * |
| * @param object the object to search for |
| * @return the number of occurrences of the object, zero if not found |
| */
|
| Long getCount(E e);
|
|
|
| /** |
| * <i>(Violation)</i> |
| * Adds one copy the specified object to the Bag. |
| * <p> |
| * If the object is already in the {@link #uniqueSet()} then increment its |
| * count as reported by {@link #getCount(Object)}. Otherwise add it to the |
| * {@link #uniqueSet()} and report its count as 1. |
| * <p> |
| * Since this method always increases the size of the bag, |
| * according to the {@link Collection#add(Object)} contract, it |
| * should always return <code>true</code>. Since it sometimes returns |
| * <code>false</code>, this method violates the contract. |
| * |
| * @param object the object to add |
| * @return <code>true</code> if the object was not already in the <code>uniqueSet</code> |
| */
|
| boolean add(E object);
|
|
|
| /** |
| * Adds <code>nCopies</code> copies of the specified object to the Bag. |
| * <p> |
| * If the object is already in the {@link #uniqueSet()} then increment its |
| * count as reported by {@link #getCount(Object)}. Otherwise add it to the |
| * {@link #uniqueSet()} and report its count as <code>nCopies</code>. |
| * |
| * @param object the object to add |
| * @param nCopies the number of copies to add |
| * @return <code>true</code> if the object was not already in the <code>uniqueSet</code> |
| */
|
| boolean add(E object, int nCopies);
|
|
|
| /** |
| * <i>(Violation)</i> |
| * Removes all occurrences of the given object from the bag. |
| * <p> |
| * This will also remove the object from the {@link #uniqueSet()}. |
| * <p> |
| * According to the {@link Collection#remove(Object)} method, |
| * this method should only remove the <i>first</i> occurrence of the |
| * given object, not <i>all</i> occurrences. |
| * |
| * @param object the object to remove |
| * @return <code>true</code> if this call changed the collection |
| */
|
| boolean remove(E E);
|
|
|
| /** |
| * Removes <code>nCopies</code> copies of the specified object from the Bag. |
| * <p> |
| * If the number of copies to remove is greater than the actual number of |
| * copies in the Bag, no error is thrown. |
| * |
| * @param object the object to remove |
| * @param nCopies the number of copies to remove |
| * @return <code>true</code> if this call changed the collection |
| */
|
| boolean remove(E E, int nCopies);
|
|
|
| /** |
| * Returns a {@link Set} of unique elements in the Bag. |
| * <p> |
| * Uniqueness constraints are the same as those in {@link java.util.Set}. |
| * |
| * @return the Set of unique Bag elements |
| */
|
| Set<E> uniqueSet();
|
|
|
| /** |
| * Returns the total number of items in the bag across all types. |
| * |
| * @return the total size of the Bag |
| */
|
| int size();
|
|
|
| /** |
| * <i>(Violation)</i> |
| * Returns <code>true</code> if the bag contains all elements in |
| * the given collection, respecting cardinality. That is, if the |
| * given collection <code>coll</code> contains <code>n</code> copies |
| * of a given object, calling {@link #getCount(Object)} on that object must |
| * be <code>>= n</code> for all <code>n</code> in <code>coll</code>. |
| * <p> |
| * The {@link Collection#containsAll(Collection)} method specifies |
| * that cardinality should <i>not</i> be respected; this method should |
| * return true if the bag contains at least one of every object contained |
| * in the given collection. |
| * |
| * @param coll the collection to check against |
| * @return <code>true</code> if the Bag contains all the collection |
| */
|
| boolean containsAll(Collection<?> coll);
|
|
|
| /** |
| * <i>(Violation)</i> |
| * Remove all elements represented in the given collection, |
| * respecting cardinality. That is, if the given collection |
| * <code>coll</code> contains <code>n</code> copies of a given object, |
| * the bag will have <code>n</code> fewer copies, assuming the bag |
| * had at least <code>n</code> copies to begin with. |
| * |
| * <p>The {@link Collection#removeAll(Collection)} method specifies |
| * that cardinality should <i>not</i> be respected; this method should |
| * remove <i>all</i> occurrences of every object contained in the |
| * given collection. |
| * |
| * @param coll the collection to remove |
| * @return <code>true</code> if this call changed the collection |
| */
|
| boolean removeAll(Collection<?> coll);
|
|
|
| /** |
| * <i>(Violation)</i> |
| * Remove any members of the bag that are not in the given |
| * collection, respecting cardinality. That is, if the given |
| * collection <code>coll</code> contains <code>n</code> copies of a |
| * given object and the bag has <code>m > n</code> copies, then |
| * delete <code>m - n</code> copies from the bag. In addition, if |
| * <code>e</code> is an object in the bag but |
| * <code>!coll.contains(e)</code>, then remove <code>e</code> and any |
| * of its copies. |
| * |
| * <p>The {@link Collection#retainAll(Collection)} method specifies |
| * that cardinality should <i>not</i> be respected; this method should |
| * keep <i>all</i> occurrences of every object contained in the |
| * given collection. |
| * |
| * @param coll the collection to retain |
| * @return <code>true</code> if this call changed the collection |
| */
|
| boolean retainAll(Collection<?> coll);
|
|
|
| /** |
| * Returns an {@link Iterator} over the entire set of members, |
| * including copies due to cardinality. This iterator is fail-fast |
| * and will not tolerate concurrent modifications. |
| * |
| * @return iterator over all elements in the Bag |
| */
|
| Iterator<E> iterator();
|
|
|
| // The following is not part of the formal Bag interface, however where possible
|
| // Bag implementations should follow these comments.
|
| // /**
|
| // * Compares this Bag to another.
|
| // * This Bag equals another Bag if it contains the same number of occurrences of
|
| // * the same elements.
|
| // * This equals definition is compatible with the Set interface.
|
| // *
|
| // * @param obj the Bag to compare to
|
| // * @return true if equal
|
| // */
|
| // boolean equals(Object obj);
|
| //
|
| // /**
|
| // * Gets a hash code for the Bag compatible with the definition of equals.
|
| // * The hash code is defined as the sum total of a hash code for each element.
|
| // * The per element hash code is defined as
|
| // * <code>(e==null ? 0 : e.hashCode()) ^ noOccurances)</code>.
|
| // * This hash code definition is compatible with the Set interface.
|
| // *
|
| // * @return the hash code of the Bag
|
| // */
|
| // int hashCode();
|
|
|
| } |
