package org.apache.commons.collections;


import java.util.Comparator;
import org.apache.commons.collections.comparators.ComparableComparator;
import org.apache.commons.collections.comparators.ReverseComparator;
import org.apache.commons.collections.comparators.NullComparator;
import org.apache.commons.collections.comparators.TransformingComparator;


/**
 *  Provides convenient static utility methods for <Code>Comparator</Code>
 *  objects.<P>
 *
 *  Most of the utility 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} will be used.
 *
 *  @author Paul Jack
 *  @version $Id$
 */
public class ComparatorUtils {


    /**
     *  Comparator for natural sort order.
     *
     *  @see ComparableComparator#getInstance
     */
    final public static Comparator NATURAL = 
      ComparableComparator.getInstance();


    /**
     *  Returns 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
     *  @see ReverseComparator
     */
    public static Comparator reverse(Comparator comparator) {
        if (comparator == null) comparator = NATURAL;
        return new ReverseComparator(comparator);
    }


    /**
     *  Allows the given comparator to compare <Code>null</Code> values.<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>
     *
     *  @param comparator the comparator that wants to allow nulls
     *  @return  a version of that comparator that allows nulls
     *  @see NullComparator
     */
    public static Comparator nullFirst(Comparator comparator) {
        if (comparator == null) comparator = NATURAL;
        return new NullComparator(comparator, false);
    }


    /**
     *  Allows the given comparator to compare <Code>null</Code> values.<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>
     *
     *  @param comparator the comparator that wants to allow nulls
     *  @return  a version of that comparator that allows nulls
     *  @see NullComparator
     */
    public static Comparator nullLast(Comparator comparator) {
        if (comparator == null) comparator = NATURAL;
        return new NullComparator(comparator, true);
    }


    
    /**
     *  Passes transformed objects to the given comparator.<P>
     *
     *  Objects passed to the returned comparator will first be transformed
     *  by the given transformer before they are compared by the given
     *  comparator.<P>
     *
     *  @param comparator  the sort order to use
     *  @param t  the transformer to use
     *  @return  a comparator that transforms its input objects before 
     *    comparing them
     *  @see  TransformingComparator
     */
    public static Comparator transform(Comparator comparator, Transformer t) {
        if (comparator == null) comparator = NATURAL;
        return new TransformingComparator(t, comparator);
    }


    /**
     *  Returns the smaller of the given objects according to the given 
     *  comparator.
     * 
     *  @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
     */
    public static Object min(Object o1, Object o2, Comparator comparator) {
        if (comparator == null) comparator = NATURAL;
        int c = comparator.compare(o1, o2);
        return (c < 0) ? o1 : o2;        
    }


    /**
     *  Returns the smaller of the given objects according to the given 
     *  comparator.
     * 
     *  @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
     */
    public static Object max(Object o1, Object o2, Comparator comparator) {
        if (comparator == null) comparator = NATURAL;
        int c = comparator.compare(o1, o2);
        return (c > 0) ? o1 : o2;        
    }


}

--
To unsubscribe, e-mail:   <mailto:commons-dev-unsubscribe@jakarta.apache.org>
For additional commands, e-mail: <mailto:commons-dev-help@jakarta.apache.org>