NSComparator

Inherits from:
Object

Package:
com.webobjects.foundation

Class Description

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.

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 the section "Constants" (page 54).

Constants

NSComparator defines the following int constants as the possible return values for compare:

Constant	Description
`OrderedAscending`	Returned when the object arguments are in ascending order (the value of the first argument is less than the value of the second).
`OrderedSame`	Returned when the values of the object arguments are equal.
`OrderedDescending`	Returned when the object arguments are in descending order (the value of the first argument is less than the value of the second).

Additionally, NSComparator defines the following NSComparator constants to be used for comparing objects of the specified class:

Constant	Compares Objects of Class
`AscendingStringComparator`	String
`DescendingStringComparator`	String
`AscendingCaseInsensitiveStringComparator`	String
`DescendingCaseInsensitiveStringComparator`	String
`AscendingNumberComparator`	Number
`DescendingNumberComparator`	Number
`AscendingTimestampComparator`	NSTimestamp
`DescendingTimestampComparator`	NSTimestamp

Constructors

NSComparator

public NSComparator()

The no-arg constructor. Don't use this method; because NSComparator is an abstract class, you can never create an instance of it.

Instance Methods

compare

public abstract int compare( Object first, Object second) throws NSComparator.ComparisonException

Compares the values of first and second 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.

Throws an NSComparator.ComparisonException if a comparison between first and second is impossible or undefined; for example, if either argument is null.