---

NSSortDescriptor Class Reference

Overview

An instance of NSSortDescriptor describes a basis for ordering objects by specifying the property to use to compare the objects, the method to use to compare the properties, and whether the comparison should be ascending or descending. Instances of NSSortDescriptor are immutable.

You construct an instance of NSSortDescriptor by specifying the key path of the property to be compared, the order of the sort (ascending or descending), and (optionally) a selector to use to perform the comparison. The three-argument constructor allows you to specify other comparison selectors such as caseInsensitiveCompare: and localizedCompare:. Sorting raises an exception if the objects to be sorted do not respond to the sort descriptor’s comparison selector.

There are a number of situations in which you can use sort descriptors, for example:

• To sort an array (an instance of NSArray or NSMutableArray—see sortedArrayUsingDescriptors: and sortUsingDescriptors:)

• To directly compare two objects (see compareObject:toObject:)

• To specify how the elements in a table view should be arranged (see sortDescriptors)

• To specify how the elements managed by an array controller should be arranged (see sortDescriptors)

• If you are using Core Data, to specify the ordering of objects returned from a fetch request (see sortDescriptors)

Adopted Protocols

• – encodeWithCoder:

• – initWithCoder:

• – copyWithZone:

Tasks

Initializing a Sort Descriptor

• – initWithKey:ascending:
• – initWithKey:ascending:selector:

Getting Information About a Sort Descriptor

• – ascending
• – key
• – selector

Using Sort Descriptors

• – compareObject:toObject:
• – reversedSortDescriptor

Instance Methods

ascending

Returns a Boolean value that indicates whether the receiver specifies sorting in ascending order.

- (BOOL)ascending

Return Value

YES if the receiver specifies sorting in ascending order, otherwise NO.

Availability

• Available in Mac OS X v10.3 and later.

Declared In

NSSortDescriptor.h

compareObject:toObject:

Returns an NSComparisonResult value that indicates the ordering of two given objects.

- (NSComparisonResult)compareObject:(id)object1 toObject:(id)object2

Parameters

object1

The object to compare with object2. This object must have a property accessible using the key-path specified by key.

This value must not be nil. If the value is nil, the behavior is undefined and may change in future versions of Mac OS X.

object2

The object to compare with object1. This object must have a property accessible using the key-path specified by key.

This value must not be nil. If the value is nil, the behavior is undefined and may change in future versions of Mac OS X.

Return Value

NSOrderedAscending if object1 is less than object2, NSOrderedDescending if object1 is greater than object2, or NSOrderedSame if object1 is equal to object2.

Discussion

The ordering is determined by comparing, using the selector specified selector, the values of the properties specified by key of object1 and object2.

Availability

• Available in Mac OS X v10.3 and later.

Declared In

NSSortDescriptor.h

initWithKey:ascending:

Returns an NSSortDescriptor object initialized with a given property key path and sort order, and with the default comparison selector.

- (id)initWithKey:(NSString *)keyPath ascending:(BOOL)ascending

Parameters

keyPath

The property key to use when performing a comparison. In the comparison, the property is accessed using key-value coding (see Key-Value Coding Programming Guide).

ascending

YES if the receiver specifies sorting in ascending order, otherwise NO.

Return Value

An NSSortDescriptor object initialized with the property key path specified by keyPath, sort order specified by ascending, and the default comparison selector (compare:).

Availability

• Available in Mac OS X v10.3 and later.

See Also

• – initWithKey:ascending:selector:

Related Sample Code

• CoreRecipes
• Departments and Employees
• NSOperationSample
• SimpleCalendar
• SpotlightFortunes

Declared In

NSSortDescriptor.h

initWithKey:ascending:selector:

Returns an NSSortDescriptor object initialized with a given property key path, sort order, and comparison selector.

- (id)initWithKey:(NSString *)keyPath ascending:(BOOL)ascending selector:(SEL)selector

Parameters

keyPath

The property key to use when performing a comparison. In the comparison, the property is accessed using key-value coding (see Key-Value Coding Programming Guide).

ascending

YES if the receiver specifies sorting in ascending order, otherwise NO.

selector

The method to use when comparing the properties of objects, for example caseInsensitiveCompare: or localizedCompare:. The selector must specify a method implemented by the value of the property identified by keyPath. The selector used for the comparison is passed a single parameter, the object to compare against self, and must return the appropriate NSComparisonResult constant. The selector must have the same method signature as:

- (NSComparisonResult)localizedCompare:(NSString *)aString

Return Value

An NSSortDescriptor object initialized with the property key path specified by keyPath, sort order specified by ascending, and the selector specified by selector.

Availability

• Available in Mac OS X v10.3 and later.

See Also

• – initWithKey:ascending:

Related Sample Code

• GridCalendar

Declared In

NSSortDescriptor.h

key

Returns the receiver’s property key path.

- (NSString *)key

Return Value

The receiver’s property key path.

Discussion

This key path specifies the property that is compared during sorting.

Availability

• Available in Mac OS X v10.3 and later.

Related Sample Code

• iSpend

Declared In

NSSortDescriptor.h

reversedSortDescriptor

Returns a copy of the receiver with the sort order reversed.

- (id)reversedSortDescriptor

Return Value

A copy of the receiver with the sort order reversed

Availability

• Available in Mac OS X v10.3 and later.

Declared In

NSSortDescriptor.h

selector

Returns the selector the receiver specifies to use when comparing objects.

- (SEL)selector

Return Value

The selector the receiver specifies to use when comparing objects.

Availability

• Available in Mac OS X v10.3 and later.

Declared In

NSSortDescriptor.h

---