3697 * of <tt>o</tt>
3698 * @param o the object whose frequency is to be determined
3699 * @throws NullPointerException if <tt>c</tt> is null
3700 * @since 1.5
3701 */
3702 public static int frequency(Collection<?> c, Object o) {
3703 int result = 0;
3704 if (o == null) {
3705 for (Object e : c)
3706 if (e == null)
3707 result++;
3708 } else {
3709 for (Object e : c)
3710 if (o.equals(e))
3711 result++;
3712 }
3713 return result;
3714 }
3715
3716 /**
3717 * Returns <tt>true</tt> if the two specified collections have no
3718 * elements in common.
3719 *
3720 * <p>Care must be exercised if this method is used on collections that
3721 * do not comply with the general contract for <tt>Collection</tt>.
3722 * Implementations may elect to iterate over either collection and test
3723 * for containment in the other collection (or to perform any equivalent
3724 * computation). If either collection uses a nonstandard equality test
3725 * (as does a {@link SortedSet} whose ordering is not <i>compatible with
3726 * equals</i>, or the key set of an {@link IdentityHashMap}), both
3727 * collections must use the same nonstandard equality test, or the
3728 * result of this method is undefined.
3729 *
3730 * <p>Note that it is permissible to pass the same collection in both
3731 * parameters, in which case the method will return true if and only if
3732 * the collection is empty.
3733 *
3734 * @param c1 a collection
3735 * @param c2 a collection
3736 * @throws NullPointerException if either collection is null
3737 * @since 1.5
3738 */
3739 public static boolean disjoint(Collection<?> c1, Collection<?> c2) {
3740 /*
3741 * We're going to iterate through c1 and test for inclusion in c2.
3742 * If c1 is a Set and c2 isn't, swap the collections. Otherwise,
3743 * place the shorter collection in c1. Hopefully this heuristic
3744 * will minimize the cost of the operation.
3745 */
3746 if ((c1 instanceof Set) && !(c2 instanceof Set) ||
3747 (c1.size() > c2.size())) {
3748 Collection<?> tmp = c1;
3749 c1 = c2;
3750 c2 = tmp;
3751 }
3752
3753 for (Object e : c1)
3754 if (c2.contains(e))
3755 return false;
3756 return true;
3757 }
3758
3759 /**
3760 * Adds all of the specified elements to the specified collection.
3761 * Elements to be added may be specified individually or as an array.
3762 * The behavior of this convenience method is identical to that of
3763 * <tt>c.addAll(Arrays.asList(elements))</tt>, but this method is likely
3764 * to run significantly faster under most implementations.
3765 *
3766 * <p>When elements are specified individually, this method provides a
3767 * convenient way to add a few elements to an existing collection:
3768 * <pre>
3769 * Collections.addAll(flavors, "Peaches 'n Plutonium", "Rocky Racoon");
3770 * </pre>
3771 *
3772 * @param c the collection into which <tt>elements</tt> are to be inserted
3773 * @param elements the elements to insert into <tt>c</tt>
3774 * @return <tt>true</tt> if the collection changed as a result of the call
3775 * @throws UnsupportedOperationException if <tt>c</tt> does not support
|
3697 * of <tt>o</tt>
3698 * @param o the object whose frequency is to be determined
3699 * @throws NullPointerException if <tt>c</tt> is null
3700 * @since 1.5
3701 */
3702 public static int frequency(Collection<?> c, Object o) {
3703 int result = 0;
3704 if (o == null) {
3705 for (Object e : c)
3706 if (e == null)
3707 result++;
3708 } else {
3709 for (Object e : c)
3710 if (o.equals(e))
3711 result++;
3712 }
3713 return result;
3714 }
3715
3716 /**
3717 * Returns {@code true} if the two specified collections have no
3718 * elements in common.
3719 *
3720 * <p>Care must be exercised if this method is used on collections that
3721 * do not comply with the general contract for {@code Collection}.
3722 * Implementations may elect to iterate over either collection and test
3723 * for containment in the other collection (or to perform any equivalent
3724 * computation). If either collection uses a nonstandard equality test
3725 * (as does a {@link SortedSet} whose ordering is not <em>compatible with
3726 * equals</em>, or the key set of an {@link IdentityHashMap}), both
3727 * collections must use the same nonstandard equality test, or the
3728 * result of this method is undefined.
3729 *
3730 * <p>Care must also be exercised when using collections that have
3731 * restrictions on the elements that they may contain. Collection
3732 * implementations are allowed to throw exceptions for any operation
3733 * involving elements they deem ineligible. For absolute safety the
3734 * specified collections should contain only elements which are
3735 * eligible elements for both collections.
3736 *
3737 * <p>Note that it is permissible to pass the same collection in both
3738 * parameters, in which case the method will return {@code true} if and
3739 * only if the collection is empty.
3740 *
3741 * @param c1 a collection
3742 * @param c2 a collection
3743 * @return {@code true} if the two specified collections have no
3744 * elements in common.
3745 * @throws NullPointerException if either collection is {@code null}.
3746 * @throws NullPointerException if one collection contains a {@code null}
3747 * element and {@code null} is not an eligible element for the other collection.
3748 * (optional)
3749 * @throws ClassCastException if one collection contains an element that is
3750 * of a type which is ineligible for the other collection. (optional)
3751 * @since 1.5
3752 */
3753 public static boolean disjoint(Collection<?> c1, Collection<?> c2) {
3754 // The collection to be used for contains(), Preference is given to
3755 // Sets as their contains() impl should be less than O(N/2).
3756 Collection<?> contains = c2;
3757 // The collection to be iterated. As performance of Set's contains()
3758 // should be less than O(N/2), iteration is given to the remaining
3759 // collection. For collections who's contains() are of the same
3760 // complexity then best performance is achieved by iterating the
3761 // smaller collection.
3762 Collection<?> iterate = c1;
3763
3764 // Performance optimization cases. The heuristics:
3765 // 1. Generally iterate over c1.
3766 // 2. If c1 is a Set then iterate over c2.
3767 // 3. If either collection is empty then result is always true.
3768 // 4. Iterate over the smaller Collection.
3769 if (c1 instanceof Set) {
3770 // As Set's contains() performs better (less than O(N/2))
3771 //than mere Collection's,iterate on c2.
3772 iterate = c2;
3773 contains = c1;
3774 } else if (!(c2 instanceof Set)) {
3775 // Both are mere Collections. Iterate over smaller collection.
3776 // E.g. if c1 contains 3 elements and c2 contains 50 elements and
3777 // assuming contains() requires ceiling(n/2) comparisons then
3778 // checking for all c1 elements in c2 would require 75 comparisons
3779 // vs. all c2 elements in c1 would require 100 comparisons.
3780 int c1size = c1.size();
3781 int c2size = c2.size();
3782 if (c1size == 0 || c2size == 0) {
3783 // One (or both) collections is/are empty. Nothing will match.
3784 return true;
3785 }
3786
3787 if (c1size > c2size) {
3788 iterate = c2;
3789 contains = c1;
3790 }
3791 }
3792
3793 for (Object e : iterate) {
3794 if (contains.contains(e)) {
3795 // Found a common element. Collections are not disjoint.
3796 return false;
3797 }
3798 }
3799
3800 // No common elements were found.
3801 return true;
3802 }
3803
3804 /**
3805 * Adds all of the specified elements to the specified collection.
3806 * Elements to be added may be specified individually or as an array.
3807 * The behavior of this convenience method is identical to that of
3808 * <tt>c.addAll(Arrays.asList(elements))</tt>, but this method is likely
3809 * to run significantly faster under most implementations.
3810 *
3811 * <p>When elements are specified individually, this method provides a
3812 * convenient way to add a few elements to an existing collection:
3813 * <pre>
3814 * Collections.addAll(flavors, "Peaches 'n Plutonium", "Rocky Racoon");
3815 * </pre>
3816 *
3817 * @param c the collection into which <tt>elements</tt> are to be inserted
3818 * @param elements the elements to insert into <tt>c</tt>
3819 * @return <tt>true</tt> if the collection changed as a result of the call
3820 * @throws UnsupportedOperationException if <tt>c</tt> does not support
|