This is an automated email from the ASF dual-hosted git repository.
garydgregory pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/commons-collections.git
The following commit(s) were added to refs/heads/master by this push:
new c119c75f6 Javadoc
c119c75f6 is described below
commit c119c75f6ae460ec152ea30ed2d1cffa09bfe738
Author: Gary Gregory <[email protected]>
AuthorDate: Thu Jul 2 22:00:33 2026 +0000
Javadoc
---
.../org/apache/commons/collections4/MultiSet.java | 164 +++++++++------------
1 file changed, 68 insertions(+), 96 deletions(-)
diff --git a/src/main/java/org/apache/commons/collections4/MultiSet.java
b/src/main/java/org/apache/commons/collections4/MultiSet.java
index 797923e76..73a90991b 100644
--- a/src/main/java/org/apache/commons/collections4/MultiSet.java
+++ b/src/main/java/org/apache/commons/collections4/MultiSet.java
@@ -14,6 +14,7 @@
* See the License for the specific language governing permissions and
* limitations under the License.
*/
+
package org.apache.commons.collections4;
import java.util.Collection;
@@ -21,12 +22,10 @@ import java.util.Iterator;
import java.util.Set;
/**
- * Defines a collection that counts the number of times an object appears in
- * the collection.
+ * Defines a collection that counts the number of times an object appears in
the collection.
* <p>
- * Suppose you have a MultiSet that contains {@code {a, a, b, c}}.
- * Calling {@link #getCount(Object)} on {@code a} would return 2, while
- * calling {@link #uniqueSet()} would return {@code {a, b, c}}.
+ * Suppose you have a MultiSet that contains {@code {a, a, b, c}}. Calling
{@link #getCount(Object)} on {@code a} would return 2, while calling
+ * {@link #uniqueSet()} would return {@code {a, b, c}}.
* </p>
*
* @param <E> The type held in the multiset
@@ -37,31 +36,26 @@ public interface MultiSet<E> extends Collection<E> {
/**
* An unmodifiable entry for an element and its occurrence as contained in
a MultiSet.
* <p>
- * The {@link MultiSet#entrySet()} method returns a view of the multiset
whose elements
- * implement this interface.
+ * The {@link MultiSet#entrySet()} method returns a view of the multiset
whose elements implement this interface.
* </p>
*
- * @param <E> the element type
+ * @param <E> the element type
*/
interface Entry<E> {
/**
- * 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.
+ * 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.
* <p>
- * More formally, two entries {@code e1} and {@code e2} represent
- * the same mapping if
+ * More formally, two entries {@code e1} and {@code e2} represent the
same mapping if
* </p>
+ *
* <pre>
- * (e1.getElement()==null ? e2.getElement()==null
- * :
e1.getElement().equals(e2.getElement())) &&
- * (e1.getCount()==e2.getCount())
+ * (e1.getElement() == null ? e2.getElement() == null :
e1.getElement().equals(e2.getElement())) && (e1.getCount() ==
e2.getCount())
* </pre>
*
- * @param o object to be compared for equality with this multiset entry
- * @return true if the specified object is equal to this multiset entry
+ * @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);
@@ -69,14 +63,14 @@ public interface MultiSet<E> extends Collection<E> {
/**
* Gets the number of occurrences for the element of this entry.
*
- * @return the number of occurrences of the element
+ * @return the number of occurrences of the element.
*/
int getCount();
/**
* Gets the element corresponding to this entry.
*
- * @return the element corresponding to this entry
+ * @return the element corresponding to this entry.
*/
E getElement();
@@ -84,11 +78,13 @@ public interface MultiSet<E> extends Collection<E> {
* Returns the hash code value for this multiset entry.
* <p>
* The hash code of a multiset entry {@code e} is defined to be:
+ * </p>
+ *
* <pre>
* (e==null ? 0 : e.hashCode()) ^ noOccurrences)
* </pre>
*
- * @return the hash code value for this multiset entry
+ * @return the hash code value for this multiset entry.
*/
@Override
int hashCode();
@@ -97,14 +93,12 @@ public interface MultiSet<E> extends Collection<E> {
/**
* Adds one copy of the specified object to the MultiSet.
* <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
+ * 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>
*
- * @param object the object to add
- * @return {@code true} always, as the size of the MultiSet is increased
- * in any case
+ * @param object the object to add.
+ * @return {@code true} always, as the size of the MultiSet is increased
in any case.
*/
@Override
boolean add(E object);
@@ -112,26 +106,22 @@ public interface MultiSet<E> extends Collection<E> {
/**
* Adds a number of occurrences of the specified object to the MultiSet.
* <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
+ * 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 occurrences}.
* </p>
*
- * @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
+ * @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);
/**
- * Returns {@code true} if the MultiSet contains at least one
- * occurrence for each element contained in the given collection.
+ * Returns {@code 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 {@code true} if the MultiSet contains all the collection
+ * @param coll the collection to check against.
+ * @return {@code true} if the MultiSet contains all the collection.
*/
@Override
boolean containsAll(Collection<?> coll);
@@ -139,54 +129,47 @@ public interface MultiSet<E> extends Collection<E> {
/**
* Returns a {@link Set} of all entries contained in the MultiSet.
* <p>
- * The returned set is backed by this multiset, so any change to either
- * is immediately reflected in the other.
+ * The returned set is backed by this multiset, so any change to either is
immediately reflected in the other.
* </p>
*
- * @return the Set of MultiSet entries
+ * @return the Set of MultiSet entries.
*/
Set<Entry<E>> entrySet();
/**
* Compares this MultiSet to another object.
* <p>
- * This MultiSet equals another object if it is also a MultiSet
- * that contains the same number of occurrences of the same elements.
+ * This MultiSet equals another object if it is also a MultiSet that
contains the same number of occurrences of the same elements.
* </p>
*
- * @param obj the object to compare to
- * @return true if equal
+ * @param obj the object to compare to.
+ * @return true if equal.
*/
@Override
boolean equals(Object obj);
/**
- * Gets the number of occurrences of the given object currently
- * in the MultiSet. If the object does not exist in the multiset,
- * return 0.
+ * Gets 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
+ * @param object the object to search for.
+ * @return the number of occurrences of the object, zero if not found.
*/
int getCount(Object object);
/**
- * 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
- * {@code (e==null ? 0 : e.hashCode()) ^ noOccurrences)}.
+ * 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 {@code (e==null ? 0 :
e.hashCode()) ^ noOccurrences)}.
*
- * @return the hash code of the MultiSet
+ * @return the hash code of the MultiSet.
*/
@Override
int hashCode();
/**
- * 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.
+ * 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
+ * @return iterator over all elements in the MultiSet.
*/
@Override
Iterator<E> iterator();
@@ -194,11 +177,11 @@ public interface MultiSet<E> extends Collection<E> {
/**
* Removes one occurrence of the given object from the MultiSet.
* <p>
- * If the number of occurrences after this operation is reduced
- * to zero, the object will be removed from the {@link #uniqueSet()}.
+ * If the number of occurrences after this operation is reduced to zero,
the object will be removed from the {@link #uniqueSet()}.
+ * </p>
*
- * @param object the object to remove
- * @return {@code true} if this call changed the collection
+ * @param object the object to remove.
+ * @return {@code true} if this call changed the collection.
*/
@Override
boolean remove(Object object);
@@ -206,59 +189,51 @@ public interface MultiSet<E> extends Collection<E> {
/**
* Removes a number of occurrences of the specified object from the
MultiSet.
* <p>
- * 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.
+ * 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.
* </p>
*
- * @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
+ * @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);
/**
- * Remove all occurrences of all elements from this MultiSet represented
- * in the given collection.
+ * Remove all occurrences of all elements from this MultiSet represented
in the given collection.
*
- * @param coll the collection of elements to remove
- * @return {@code true} if this call changed the multiset
+ * @param coll the collection of elements to remove.
+ * @return {@code 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.
+ * Remove any elements of this MultiSet that are not contained in the
given collection.
*
- * @param coll the collection of elements to retain
- * @return {@code true} if this call changed the multiset
+ * @param coll the collection of elements to retain.
+ * @return {@code true} if this call changed the multiset.
*/
@Override
boolean retainAll(Collection<?> coll);
/**
- * Sets the number of occurrences of the specified object in the MultiSet
- * to the given count.
+ * Sets the number of occurrences of the specified object in the MultiSet
to the given count.
* <p>
- * If the provided count is zero, the object will be removed from the
- * {@link #uniqueSet()}.
+ * If the provided count is zero, the object will be removed from the
{@link #uniqueSet()}.
* </p>
*
- * @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
+ * @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);
/**
* Returns the total number of items in the MultiSet.
*
- * @return the total size of the multiset
+ * @return the total size of the multiset.
*/
@Override
int size();
@@ -269,14 +244,11 @@ public interface MultiSet<E> extends Collection<E> {
* Uniqueness constraints are the same as those in {@link java.util.Set}.
* </p>
* <p>
- * 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.
+ * 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.
* </p>
*
- * @return the Set of unique MultiSet elements
+ * @return the Set of unique MultiSet elements.
*/
Set<E> uniqueSet();
-
}
