com.ccg.util
Class CompareStrings

java.lang.Object
  com.ccg.util.CompareStrings

All Implemented Interfaces:

Comparator

public class CompareStrings
extends Object
implements Comparator

Base class to help build comparators.

This class can be used as a standard string comparator, however, it is intended to serve more as a base for building custom comparators. It provides the following functionality:

• Methods to safely compare strings and objects taking into account the possibility that the objects may be null.
• The ability to control whether the comparison should result in a ascending or descending sort.
• This ability to be used directly to compare the string representation of objects and produce either a ascending or descending output.

Refer to the CStrings.java example program to see how to use this class directly.

If you extend this class (as it is intended to be), you will want to implement a custom compare method, be sure to pass your comparison results through the adjustCompare method before returning the final value (this will handle the ascending/desceding option for you). This looks something like the following:

 public int compare(Object o1, Object o2) {
   int rc = 0;          // assume objects will be equal

   ...                  // insert your custom code to compare

   return adjustCompare(rc);   // allow your comparison value to be adjusted
 }
 

Since:

1.0

Version:

$Revision: 1.1.1.1 $

Author:

$Author: pkb $

See Also:

Arrays, Comparator, CString.java

Constructor Summary

CompareStrings()

Method Summary

protected int	adjustCompare(int cv) Adjust the "compare value" computed.
int	compare(Object o1, Object o2) Compare the String representations of two objects.
static int	compareObjects(Object o1, Object o2) Compare two the String values of two objects (allow for null).
static int	compareStrings(String s1, String s2) Compare two String objects where one or more could be null.
boolean	isDescending() Is a descending sort to be generated set?
void	setDescending(boolean val) Set whether a descending sort should be generated.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface java.util.Comparator

equals

Constructor Detail

CompareStrings

public CompareStrings()

Method Detail

compare

public int compare(Object o1,
                   Object o2)
            throws ClassCastException

Compare the String representations of two objects.

This is the method that all Comparator's must implement. It determines if one object (o1) is less than, equal to or greater than another object (o2).

This method is likely to be overridden by derived classes. This implementation uses the following approach:

• It uses the compareObjects method to get an initial compare value for the two objects passed (which tries to look at the string representation of the objects when possible).
• It then feeds this preliminary value through the adjustCompare(int) method, which may negate the result if this object has been configured to do a descending sort.

Specified by:

compare in interface Comparator

Parameters:

o1 - Object to compare against.

o2 - Object to compare against o1.

Returns:

0 if equal, less than 0 if o1 < o2, greater than 0 if o1 > o2.

Throws:

ClassCastException

Since:

1.0

See Also:

setDescending(boolean)

compareStrings

public static final int compareStrings(String s1,
                                       String s2)

Compare two String objects where one or more could be null. This method compares to strings to determine which is less than or equal to the other. It is similar to compareTo method in the String class, except that it allows one to pass null values (null values are considered to be less than non-null values). If both values passed are not null, then the results returned will be the same as if one did: o1.compareTo(o2).

Parameters:

o1 - String to compare against (null is OK).

o2 - String to compare against o1 (null is OK).

Returns:

0 if equal, less than 0 if o1 < o2, greater than 0 if o1 > o2. null is condsidered less than non-null.

Since:

1.0

See Also:

compareObjects(java.lang.Object, java.lang.Object)

compareObjects

public static final int compareObjects(Object o1,
                                       Object o2)

Compare two the String values of two objects (allow for null).

This method compares to objects to determine which is less than or equal to the other. It allows one to pass null values (null values are considered to be less than non-null values). If both values passed are not null, then the string values of the two objects will be retrieved and processed by the compareStrings(java.lang.String, java.lang.String) method.

Parameters:

o1 - Object to compare against (null is OK).

o2 - Object to compare against o1 (null is OK).

Returns:

0 if equal, less than 0 if o1 < o2, greater than 0 if o1 > o2. null is condsidered less than non-null.

Since:

1.0

See Also:

compareStrings(java.lang.String, java.lang.String)

setDescending

public void setDescending(boolean val)

Set whether a descending sort should be generated.

This method can be used to control whether the comparator is to be used for a ascending or descending sort. At the time of construction, a ascending sort is assumed ("a", "b", "c", ...). If you pass true to this method, you'll get a descending sort ("z", "y", "x", ...).

Parameters:

val - false for standard ascending compare, true to reverse the sort to create a descending compare.

See Also:

isDescending()

isDescending

public boolean isDescending()

Is a descending sort to be generated set?

Returns:

Current boolean value assigned.

See Also:

setDescending(boolean)

adjustCompare

protected int adjustCompare(int cv)

Adjust the "compare value" computed.

This method should be used by all derived classes when they implement the compare method. It will make any last minute adjustments to the value returned. It's main purpose is to automatically handle the ascending/descending option for all derived classes.

Parameters:

cv - Standard integer "compare value" as described in the compare method.

Returns:

Will return the value passed if an ascending sort, or the negative value of what was passed if this is a decending sort.

Since:

1.0

See Also:

setDescending(boolean)