com.webobjects.foundation
Class NSComparator

java.lang.Object
  |
  +--com.webobjects.foundation.NSComparator

public abstract class NSComparator

extends Object

NSComparator is an abstract class that defines an API for comparing two objects for the purpose of sorting them. The class defines one method, compare, which compares two parameters and returns one of OrderedAscending, OrderedSame, or OrderedDescending. This differs from java.lang.Comparable.compareTo which returns a non-specific positive or negative number.

Instead of invoking compare directly on a comparator, you typically use the NSArray method sortedArrayUsingComparator, which sorts the elements of the receiving array into a new array, or the NSMutableArray method sortUsingComparator, which sorts the elements of an array in place. NSComparator provides default comparators to use with these sorting methods.

See Also:

Comparable.compareTo(java.lang.Object), NSMutableArray.sortUsingComparator(com.webobjects.foundation.NSComparator), NSArray.sortedArrayUsingComparator(com.webobjects.foundation.NSComparator)

Inner Class Summary

static class

NSComparator.ComparisonException Instances of the NSComparator.ComparisonException class are created and thrown when an error condition is encountered during the comparison of two objects.

Field Summary

static NSComparator	AscendingCaseInsensitiveStringComparator To be used for comparing objects of the class String, ignoring case.
static NSComparator	AscendingNumberComparator To be used for comparing objects of the class Number.
static NSComparator	AscendingStringComparator To be used for comparing objects of the class String respecting case.
static NSComparator	AscendingTimestampComparator To be used for comparing objects of the class NSTimestamp.
static NSComparator	DescendingCaseInsensitiveStringComparator To be used for comparing objects of the class String, ignoring case.
static NSComparator	DescendingNumberComparator To be used for comparing objects of the class Number.
static NSComparator	DescendingStringComparator To be used for comparing objects of the class String, respecting case.
static NSComparator	DescendingTimestampComparator To be used for comparing objects of the class NSTimestamp.
static int	OrderedAscending Returned when the object arguments are in ascending order (the value of the first argument is less than the value of the second).
static int	OrderedDescending Returned when the object arguments are in descending order (the value of the first argument is greater than the value of the second).
static int	OrderedSame Returned when the values of the object arguments are equivalent.

Constructor Summary

NSComparator()

Method Summary

abstract int

compare(Object object1, Object object2) Compares the values of object1 and object2 and returns the result, one of OrderedAscending, OrderedSame, or OrderedDescending.

Methods inherited from class java.lang.Object

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

Field Detail

AscendingCaseInsensitiveStringComparator

public static final NSComparator AscendingCaseInsensitiveStringComparator

To be used for comparing objects of the class String, ignoring case.

AscendingNumberComparator

public static final NSComparator AscendingNumberComparator

To be used for comparing objects of the class Number.

AscendingStringComparator

public static final NSComparator AscendingStringComparator

To be used for comparing objects of the class String respecting case.

AscendingTimestampComparator

public static final NSComparator AscendingTimestampComparator

To be used for comparing objects of the class NSTimestamp.

DescendingCaseInsensitiveStringComparator

public static final NSComparator DescendingCaseInsensitiveStringComparator

To be used for comparing objects of the class String, ignoring case.

DescendingNumberComparator

public static final NSComparator DescendingNumberComparator

To be used for comparing objects of the class Number.

DescendingStringComparator

public static final NSComparator DescendingStringComparator

To be used for comparing objects of the class String, respecting case.

DescendingTimestampComparator

public static final NSComparator DescendingTimestampComparator

To be used for comparing objects of the class NSTimestamp.

OrderedAscending

public static final int OrderedAscending

Returned when the object arguments are in ascending order (the value of the first argument is less than the value of the second).

OrderedDescending

public static final int OrderedDescending

Returned when the object arguments are in descending order (the value of the first argument is greater than the value of the second).

OrderedSame

public static final int OrderedSame

Returned when the values of the object arguments are equivalent. For most NSComparators, this means equal as defined by the equals method.

Constructor Detail

NSComparator

public NSComparator()

Method Detail

compare

public abstract int compare(Object object1,
                            Object object2)
                     throws NSComparator.ComparisonException

Compares the values of object1 and object2 and returns the result, one of OrderedAscending, OrderedSame, or OrderedDescending. Specifically, for non-null x, y, and z:

• compare(x, x) returns OrderedSame.
• If compare(x, y) returns OrderedSame, then compare(y, x) returns OrderedSame
• If compare(x, y) returns OrderedAscending, then compare(y, x) returns OrderedDescending.
• If compare(x, y) returns OrderedDescending, then compare(y, x) returns OrderedAscending.
• If compare(x, y) returns OrderedAscending and compare(y, z) returns OrderedAscending, then compare(x, z) returns OrderedAscending.
• Exactly one of the following is true: compare(x, x) == OrderedSame, compare(x, x) == OrderedAscending, or compare(x, x) == OrderedDescending.
• The result of compare(x, y) must be the same in all invocations.

This comparison must be an immutable total ordering relation on the set of objects compared. There is no necessary relationship between compare() and equals(), since X, Y, and Z need not be of the same class. Throws an NSComparator.ComparisonException if a comparison between first and second is impossible or undefined; for example, if either argument is null.

Parameters:

object1 - the first object to be compared with

object2 - the second object to be compared with

Returns:

the result after comparing values of first and second

Throws:

an - NSComparator.ComparisonException if a comparison between first and second is impossible or undefined.

See Also:

OrderedAscending, OrderedSame, OrderedDescending, NSComparator.ComparisonException