com.sas.util
Class StringComparator

com.sas.util.StringComparator

All Implemented Interfaces:

com.sas.beans.PropertyChangeSource, com.sas.beans.VetoableChangeSource, com.sas.ComponentInterface, com.sas.LinkPropertiesInterface, com.sas.ModelInterface, com.sas.PublicClonable, com.sas.ViewInterface, MultipleValueEventSourceInterface, java.beans.PropertyChangeListener, java.io.ObjectInputValidation, java.io.Serializable, java.lang.Cloneable, java.util.Comparator, java.util.EventListener

Direct Known Subclasses:

TransformingComparator

public class StringComparator
implements com.sas.util.Comparator, com.sas.PublicClonable, java.io.Serializable, java.util.Comparator

StringComparator is used to compare two string values. This is most often done when sorting collections of stringss. You can also use StringComparator for non-string items; it invokes the toString() method of objects and compares using the resulting strings.

StringComparator provides a bit of extra smarts: you can specify that the comparison start at a character offset in the strings, instead of a default 0, or that case be ignored (although this is not always appropriate for some character sets).

See Also:

OrderedCollection, StringCollection, Serialized Form

Field Summary

static StringComparator

defaultInstance If you wish to use a default StringComparator, you can use defaultInstance to avoid creating a new instance.

Fields inherited from interface com.sas.util.Comparator

EQUALS, GREATER_THAN, INCOMPARABLE, LESS_THAN

Constructor Summary

StringComparator()
Default constructor.

StringComparator(boolean ascending)
Construct a string based comparator.

StringComparator(boolean ascending, boolean caseSensitive)
Construct a string based comparator.

StringComparator(boolean ascending, boolean caseSensitive, int startChar)
Construct a string based comparator.

StringComparator(java.text.Collator collator)
Construct a StringComparator which uses a Collator to perform the comparison.

Method Summary

java.lang.Object	clone() Clone this StringComparator
int	compare(java.lang.Object first, java.lang.Object second) Compare two values.
java.text.Collator	getCollator() Return the collator used to compare the strings.
int	getStartChar() Return the character at which string comparison begins.
boolean	isAscending() Return true if this StringComparator is performing an ascending comparison.
boolean	isCaseSensitive() Indicate if the comparison is case sensitive or not.
void	setAscending(boolean ascending) Set the StringComparator to an ascending sort comparison (the default).
void	setCaseSensitive(boolean caseSensitive) Set the case sensitivity of the StringComparator.
void	setCollator(java.text.Collator newCollator) Set the collator used to compare strings.
void	setStartChar(int startChar) Set the character at which string comparisons are performed.
java.lang.String	toString() Return a string representation of the comparator

Field Detail

defaultInstance

public static final StringComparator defaultInstance

If you wish to use a default StringComparator, you can use defaultInstance to avoid creating a new instance. It is initialized to new StringComparator() and thus compares strings in ascending order, honoring case, starting at character 0. Note: Java does not provide a means to define const objects, so nothing prevents you from calling one of the below set methods on defaultInstance, but doing so is highly discouraged, as other packages may be relying on defaultInstance to have the default behavior.

Constructor Detail

StringComparator

public StringComparator()

Default constructor. This comparator will perform an ascending comparison of two objects using their String representation.

StringComparator

public StringComparator(java.text.Collator collator)

Construct a StringComparator which uses a Collator to perform the comparison.

Parameters:

collator - a collator. You can use Collator.getInstance() to construct the default Collator for the current Locale.

StringComparator

public StringComparator(boolean ascending)

Construct a string based comparator. This comparator will perform an ascending or descending comparison of two objects using their String representation.

Parameters:

ascending - if false, negate the default comparison.

StringComparator

public StringComparator(boolean ascending,
                        boolean caseSensitive)

Construct a string based comparator. This comparator will perform an ascending or descending comparison of two objects using their String representation, optionally ignoring case differences.

Parameters:

ascending - if false, negate the default comparison.

caseSensitive - if true, the comparison ignores case. Warning: case insensitive string comparisons are not possible or correct in all languages/character encodings.

StringComparator

public StringComparator(boolean ascending,
                        boolean caseSensitive,
                        int startChar)

Construct a string based comparator. This comparator will perform an ascending or descending comparison of two objects using their String representation.

Parameters:

ascending - if false, negate the default comparison.

caseSensitive - if true, the comparison ignores case. Warning: case insensitive string comparisons are not possible or correct in all languages/character encodings.

startChar - the starting character for comparisons. characters before the startChar are ignored.

Method Detail

isAscending

public boolean isAscending()

Return true if this StringComparator is performing an ascending comparison.

Returns:

true if compare("A", "B") will return LESS_THAN

setAscending

public void setAscending(boolean ascending)

Set the StringComparator to an ascending sort comparison (the default).

Parameters:

ascending - true if you want an ascending string {"A", "B", "C"}; false if you want a descending sort {"C", "B", "A"}, for example.

isCaseSensitive

public boolean isCaseSensitive()

Indicate if the comparison is case sensitive or not.

Returns:

true if the comparison ignores case by comparing only the String.toLowerCase() version of strings.

setCaseSensitive

public void setCaseSensitive(boolean caseSensitive)

Set the case sensitivity of the StringComparator.

Parameters:

caseSensitive - if true, the comparator will honor the case of the strings; if false, comparisons are done on the toLowerCase() results. If the StringComparator was constructed with a Collator, this method will set the collator's strength to Collator.TERTIARY if caseSensitive is true, and Collator.PRIMARY if false. If you need finer granularity, you can modify the collator directly.

setCollator

public void setCollator(java.text.Collator newCollator)

Set the collator used to compare strings.

Parameters:

newCollator - the new value for the collator property. If null, then simple string comparison is used.

getCollator

public java.text.Collator getCollator()

Return the collator used to compare the strings. This may be null if no collator exists, in which case the StringComparator uses default string comparison.

Returns:

the string collator used to compare strings

getStartChar

public int getStartChar()

Return the character at which string comparison begins.

Returns:

the start character. The default is 0, which means the entire string is considered when comparing.

setStartChar

public void setStartChar(int startChar)

Set the character at which string comparisons are performed. The default is 0.

Parameters:

startChar - the character index where comparison begins; characters before this are ignored. If a string is less than startChar characters long, it is compared as an empty string; i.e. less than other strings in an ascending sort.

compare

public int compare(java.lang.Object first,
                   java.lang.Object second)

Compare two values. If the StringComparator is constructed with ascending == true, the compare() method returns LESS_THAN if the toString() value of the first object compares less than the toString() value of the second, else EQUALS or GREATER_THAN. A null item is sorted LESS_THAN a non-null item in an ascending comparison.

Specified by:

compare in interface java.util.Comparator

Parameters:

first - the left hand side of the comparison

second - the right hand side of the comparison

Returns:

LESS_THAN	the first object compares "less than" the second, meaning it should appear before the second in the sorted result
EQUALS	the objects are equal
GREATER_THAN	the first object compares greater than the first, meaning it should appear after the second in the sorted result

(swap results if ascending == false)

See Also:

Comparator.LESS_THAN, Comparator.EQUALS, Comparator.GREATER_THAN

clone

public java.lang.Object clone()
                       throws java.lang.CloneNotSupportedException

Clone this StringComparator

Specified by:

clone in interface com.sas.PublicClonable

Overrides:

clone in class com.sas.Component

Returns:

a clone of this StringComparator

Throws:

java.lang.CloneNotSupportedException - if the string comparator cannot be cloned.

toString

public java.lang.String toString()

Return a string representation of the comparator

Overrides:

toString in class java.lang.Object

Returns:

a string representation of the comparator