NSSortDescriptor Class Reference

Inherits from
NSObject
Conforms to
NSCoding
NSCopying
NSObject (NSObject)
Framework
/System/Library/Frameworks/Foundation.framework
Availability
Available in iOS 2.0 and later.
Companion guide
Sort Descriptor Programming Topics
Declared in
NSSortDescriptor.h
Related sample code

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:

Adopted Protocols

NSCoding
NSCopying

Tasks

Initializing a Sort Descriptor

Getting Information About a Sort Descriptor

Using Sort Descriptors

Create an NSComparator for the Sort Descriptor.

Class Methods

sortDescriptorWithKey:ascending:

Creates and returns an NSSortDescriptor with the specified key and ordering.

+ (id)sortDescriptorWithKey:(NSString *)key ascending:(BOOL)ascending
Parameters
key

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 initialized with the specified key and ordering.

Availability
  • Available in iOS 4.0 and later.
See Also
Related Sample Code
Declared In
NSSortDescriptor.h

sortDescriptorWithKey:ascending:comparator:

Creates and returns an NSSortDescriptor object initialized to do with the given ordering and comparator block.

+ (id)sortDescriptorWithKey:(NSString *)key ascending:(BOOL)ascending comparator:(NSComparator)cmptr
Parameters
key

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.

cmptr

A comparator block.

Return Value

An NSSortDescriptor initialized with the specified key, ordering and comparator.

Availability
  • Available in iOS 4.0 and later.
See Also
Declared In
NSSortDescriptor.h

sortDescriptorWithKey:ascending:selector:

Creates an NSSortDescriptor with the specified ordering and comparison selector.

+ (id)sortDescriptorWithKey:(NSString *)key ascending:(BOOL)ascending selector:(SEL)selector
Parameters
key

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 iOS 4.0 and later.
See Also
Declared In
NSSortDescriptor.h

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 iOS 2.0 and later.
Declared In
NSSortDescriptor.h

comparator

Creates and returns an NSComparator for the sort descriptor.

- (NSComparator)comparator
Return Value

An NSComparator object representing the sort descriptor.

Availability
  • Available in iOS 4.0 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 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 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 iOS 2.0 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 iOS 2.0 and later.
See Also
Related Sample Code
Declared In
NSSortDescriptor.h

initWithKey:ascending:comparator:

Returns an NSSortDescriptor object initialized to do with the given ordering and comparator block.

- (id)initWithKey:(NSString *)key ascending:(BOOL)ascending comparator:(NSComparator)cmptr
Parameters
key

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.

cmptr

A comparator block.

Return Value

An NSSortDescriptor initialized with the specified key, ordering and comparator.

Availability
  • Available in iOS 4.0 and later.
See Also
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 iOS 2.0 and later.
See Also
Related Sample Code
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 iOS 2.0 and later.
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 iOS 2.0 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 iOS 2.0 and later.
Declared In
NSSortDescriptor.h


© 2009 Apple Inc. All Rights Reserved. (Last updated: 2009-08-28)

Did this document help you? Yes It's good, but... Not helpful...