org.apache.commons.collections4.MultiSet Maven / Gradle / Ivy
Show all versions of commons-collections4 Show documentation
/*
* 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.
*/
package org.apache.commons.collections4;
import java.util.Collection;
import java.util.Iterator;
import java.util.Set;
/**
* Defines a collection that counts the number of times an object appears in
* the collection.
*
* Suppose you have a MultiSet that contains {a, a, b, c}.
* Calling {@link #getCount(Object)} on a would return 2, while
* calling {@link #uniqueSet()} would return {a, b, c}.
*
* @param the type held in the multiset
* @since 4.1
*/
public interface MultiSet extends Collection {
/**
* Returns the number of occurrences of the given object currently
* in the MultiSet. If the object does not exist in the multiset,
* return 0.
*
* @param object the object to search for
* @return the number of occurrences of the object, zero if not found
*/
int getCount(Object object);
/**
* Sets the number of occurrences of the specified object in the MultiSet
* to the given count.
*
* If the provided count is zero, the object will be removed from the
* {@link #uniqueSet()}.
*
* @param object the object to update
* @param count the number of occurrences of the object
* @return the number of occurrences of the object before this operation, zero
* if the object was not contained in the multiset
* @throws IllegalArgumentException if count is negative
*/
int setCount(E object, int count);
/**
* Adds one copy of the specified object to the MultiSet.
*
* 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.
*
* @param object the object to add
* @return true always, as the size of the MultiSet is increased
* in any case
*/
@Override
boolean add(E object);
/**
* Adds a number of occurrences of the specified object to the MultiSet.
*
* 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 occurrences.
*
* @param object the object to add
* @param occurrences the number of occurrences to add, may be zero,
* in which case no change is made to the multiset
* @return the number of occurrences of the object in the multiset before
* this operation; possibly zero
* @throws IllegalArgumentException if occurrences is negative
*/
int add(E object, int occurrences);
/**
* Removes one occurrence of the given object from the MultiSet.
*
* If the number of occurrences after this operations is reduced
* to zero, the object will be removed from the {@link #uniqueSet()}.
*
* @param object the object to remove
* @return true if this call changed the collection
*/
@Override
boolean remove(Object object);
/**
* Removes a number of occurrences of the specified object from the MultiSet.
*
* If the number of occurrences to remove is greater than the actual number of
* occurrences in the multiset, the object will be removed from the multiset.
*
* @param object the object to remove
* @param occurrences the number of occurrences to remove, may be zero,
* in which case no change is made to the multiset
* @return the number of occurrences of the object in the multiset
* before the operation; possibly zero
* @throws IllegalArgumentException if occurrences is negative
*/
int remove(Object object, int occurrences);
/**
* Returns a {@link Set} of unique elements in the MultiSet.
*
* Uniqueness constraints are the same as those in {@link java.util.Set}.
*
* The returned set is backed by this multiset, so any change to either
* is immediately reflected in the other. Only removal operations are
* supported, in which case all occurrences of the element are removed
* from the backing multiset.
*
* @return the Set of unique MultiSet elements
*/
Set uniqueSet();
/**
* Returns a {@link Set} of all entries contained in the MultiSet.
*
* The returned set is backed by this multiset, so any change to either
* is immediately reflected in the other.
*
* @return the Set of MultiSet entries
*/
Set> entrySet();
/**
* 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 MultiSet
*/
@Override
Iterator iterator();
/**
* Returns the total number of items in the MultiSet.
*
* @return the total size of the multiset
*/
@Override
int size();
/**
* Returns true if the MultiSet contains at least one
* occurrence for each element contained in the given collection.
*
* @param coll the collection to check against
* @return true if the MultiSet contains all the collection
*/
@Override
boolean containsAll(Collection coll);
/**
* Remove all occurrences of all elements from this MultiSet represented
* in the given collection.
*
* @param coll the collection of elements to remove
* @return true if this call changed the multiset
*/
@Override
boolean removeAll(Collection coll);
/**
* Remove any elements of this MultiSet that are not contained in the
* given collection.
*
* @param coll the collection of elements to retain
* @return true if this call changed the multiset
*/
@Override
boolean retainAll(Collection coll);
/**
* Compares this MultiSet to another object.
*
* This MultiSet equals another object if it is also a MultiSet
* that contains the same number of occurrences of the same elements.
*
* @param obj the object to compare to
* @return true if equal
*/
@Override
boolean equals(Object obj);
/**
* Gets a hash code for the MultiSet 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
* (e==null ? 0 : e.hashCode()) ^ noOccurances).
*
* @return the hash code of the MultiSet
*/
@Override
int hashCode();
/**
* An unmodifiable entry for an element and its occurrence as contained in a MultiSet.
*
* The {@link MultiSet#entrySet()} method returns a view of the multiset whose elements
* implements this interface.
*
* @param the element type
*/
interface Entry {
/**
* Returns the element corresponding to this entry.
*
* @return the element corresponding to this entry
*/
E getElement();
/**
* Returns the number of occurrences for the element of this entry.
*
* @return the number of occurrences of the element
*/
int getCount();
/**
* Compares the specified object with this entry for equality.
* Returns true if the given object is also a multiset entry
* and the two entries represent the same element with the same
* number of occurrences.
*
* More formally, two entries e1 and e2 represent
* the same mapping if
*
* (e1.getElement()==null ? e2.getElement()==null
* : e1.getElement().equals(e2.getElement())) &&
* (e1.getCount()==e2.getCount())
*
*
* @param o object to be compared for equality with this multiset entry
* @return true if the specified object is equal to this multiset entry
*/
@Override
boolean equals(Object o);
/**
* Returns the hash code value for this multiset entry.
*
* The hash code of a multiset entry e is defined to be:
*
* (e==null ? 0 : e.hashCode()) ^ noOccurances)
*
*
* @return the hash code value for this multiset entry
*/
@Override
int hashCode();
}
}