You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@commons.apache.org by ps...@apache.org on 2003/10/16 08:04:56 UTC
cvs commit: jakarta-commons/collections/src/java/org/apache/commons/collections ComparatorUtils.java
psteitz 2003/10/15 23:04:56
Modified: collections/src/java/org/apache/commons/collections
ComparatorUtils.java
Log:
javadoc
Revision Changes Path
1.10 +27 -31 jakarta-commons/collections/src/java/org/apache/commons/collections/ComparatorUtils.java
Index: ComparatorUtils.java
===================================================================
RCS file: /home/cvs/jakarta-commons/collections/src/java/org/apache/commons/collections/ComparatorUtils.java,v
retrieving revision 1.9
retrieving revision 1.10
diff -u -r1.9 -r1.10
--- ComparatorUtils.java 5 Sep 2003 03:35:06 -0000 1.9
+++ ComparatorUtils.java 16 Oct 2003 06:04:56 -0000 1.10
@@ -71,14 +71,10 @@
* Provides convenient static utility methods for <Code>Comparator</Code>
* objects.
* <p>
- * Most of the utility in this class can also be found in the
+ * Most of the functionality in this class can also be found in the
* <code>comparators</code> package. This class merely provides a
* convenient central place if you have use for more than one class
* in the <code>comparators</code> subpackage.
- * <p>
- * Note that <i>every</i> method in this class allows you to specify
- * <code>null</code> instead of a comparator, in which case
- * {@link #NATURAL_COMPARATOR} will be used.
*
* @since Commons Collections 2.1
* @version $Revision$ $Date$
@@ -89,7 +85,7 @@
public class ComparatorUtils {
/**
- * ComparatorUtils should not normally be constructed.
+ * ComparatorUtils should not normally be instantiated.
*/
public ComparatorUtils() {
}
@@ -113,27 +109,26 @@
/**
* Gets a comparator that compares using two {@link Comparator}s.
* <p>
- * The second comparator is used if the first comparator returns
- * that equal.
+ * The second comparator is used if the first comparator returns equal.
*
* @param comparator1 the first comparator to use, not null
* @param comparator2 the first comparator to use, not null
- * @return a combination comparator over the comparators
+ * @return a {@link ComparatorChain} formed from the two comparators
* @throws NullPointerException if either comparator is null
+ * @see ComparatorChain
*/
public static Comparator chainedComparator(Comparator comparator1, Comparator comparator2) {
return chainedComparator(new Comparator[] {comparator1, comparator2});
}
/**
- * Gets a comparator that compares using an array of {@link Comparator}s.
- * <p>
- * The second comparator is used if the first comparator returns
- * that equal and so on.
+ * Gets a comparator that compares using an array of {@link Comparator}s, applied
+ * in sequence until one returns not equal or the array is exhausted.
*
- * @param comparators the comparators to use, not null or empty or contain nulls
- * @return a combination comparator over the comparators
+ * @param comparators the comparators to use, not null or empty or containing nulls
+ * @return a {@link ComparatorChain} formed from the input comparators
* @throws NullPointerException if comparators array is null or contains a null
+ * @see ComparatorChain
*/
public static Comparator chainedComparator(Comparator[] comparators) {
ComparatorChain chain = new ComparatorChain();
@@ -147,15 +142,15 @@
}
/**
- * Gets a comparator that compares using a collection of {@link Comparator}s.
- * <p>
- * The second comparator is used if the first comparator returns
- * that equal and so on.
+ * Gets a comparator that compares using a collection of {@link Comparator}s,
+ * applied in (default iterator) sequence until one returns not equal or the
+ * collection is exhausted.
*
- * @param comparators the comparators to use, not null or empty or contain nulls
- * @return a combination comparator over the comparators
+ * @param comparators the comparators to use, not null or empty or containing nulls
+ * @return a {@link ComparatorChain} formed from the input comparators
* @throws NullPointerException if comparators collection is null or contains a null
* @throws ClassCastException if the comparators collection contains the wrong object type
+ * @see ComparatorChain
*/
public static Comparator chainedComparator(Collection comparators) {
return chainedComparator(
@@ -164,11 +159,10 @@
}
/**
- * Gets a comparator that reverses the order of the given
- * comparator.
+ * Gets a comparator that reverses the order of the given comparator.
*
- * @param comparator the comparator whose order to reverse
- * @return a comparator who reverses that order
+ * @param comparator the comparator to reverse
+ * @return a comparator that reverses the order of the input comparator
* @see ReverseComparator
*/
public static Comparator reversedComparator(Comparator comparator) {
@@ -199,7 +193,7 @@
* <p>
* The returned comparator will consider a null value to be less than
* any nonnull value, and equal to any other null value. Two nonnull
- * values will be evaluated with the given comparator.<P>
+ * values will be evaluated with the given comparator.
*
* @param comparator the comparator that wants to allow nulls
* @return a version of that comparator that allows nulls
@@ -217,7 +211,7 @@
* <p>
* The returned comparator will consider a null value to be greater than
* any nonnull value, and equal to any other null value. Two nonnull
- * values will be evaluated with the given comparator.<P>
+ * values will be evaluated with the given comparator.
*
* @param comparator the comparator that wants to allow nulls
* @return a version of that comparator that allows nulls
@@ -251,7 +245,8 @@
/**
* Returns the smaller of the given objects according to the given
- * comparator.
+ * comparator, returning the second object if the comparator
+ * returns equal.
*
* @param o1 the first object to compare
* @param o2 the second object to compare
@@ -267,13 +262,14 @@
}
/**
- * Returns the smaller of the given objects according to the given
- * comparator.
+ * Returns the larger of the given objects according to the given
+ * comparator, returning the second object if the comparator
+ * returns equal.
*
* @param o1 the first object to compare
* @param o2 the second object to compare
* @param comparator the sort order to use
- * @return the smaller of the two objects
+ * @return the larger of the two objects
*/
public static Object max(Object o1, Object o2, Comparator comparator) {
if (comparator == null) {
---------------------------------------------------------------------
To unsubscribe, e-mail: commons-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: commons-dev-help@jakarta.apache.org