commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From pste...@apache.org
Subject cvs commit: jakarta-commons/collections/src/java/org/apache/commons/collections ComparatorUtils.java
Date Thu, 16 Oct 2003 06:04:56 GMT
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


Mime
View raw message