WebObjects 5.2

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:

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

Last updated Fri Feb 21 13:15:00 PST 2003.

Copyright © 2003 Apple Computer, Inc.