iOS Developer Library

Developer

Foundation Framework Reference NSSortDescriptor Class Reference

Options
Deployment Target:

On This Page
Language:

NSSortDescriptor

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)

Inheritance


Import Statement


Swift

import Foundation

Objective-C

@import Foundation;

Availability


Available in iOS 2.0 and later.
  • Creates and returns an NSSortDescriptor with the specified key and ordering.

    Declaration

    Objective-C

    + (instancetype)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

    YEStrue if the receiver specifies sorting in ascending order, otherwise NOfalse.

    Return Value

    An NSSortDescriptor initialized with the specified key and ordering.

    Import Statement

    Objective-C

    @import Foundation;

    Availability

    Available in iOS 4.0 and later.

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

    Declaration

    Swift

    init(key keyPath: String, ascending ascending: Bool)

    Objective-C

    - (instancetype)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

    YEStrue if the receiver specifies sorting in ascending order, otherwise NOfalse.

    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:).

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

  • Creates an NSSortDescriptor with the specified ordering and comparison selector.

    Declaration

    Objective-C

    + (instancetype)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

    YEStrue if the receiver specifies sorting in ascending order, otherwise NOfalse.

    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.

    Import Statement

    Objective-C

    @import Foundation;

    Availability

    Available in iOS 4.0 and later.

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

    Declaration

    Swift

    init(key keyPath: String, ascending ascending: Bool, selector selector: Selector)

    Objective-C

    - (instancetype)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

    YEStrue if the receiver specifies sorting in ascending order, otherwise NOfalse.

    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.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Objective-C

    + (instancetype)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

    YEStrue if the receiver specifies sorting in ascending order, otherwise NOfalse.

    cmptr

    A comparator block.

    Return Value

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

    Import Statement

    Objective-C

    @import Foundation;

    Availability

    Available in iOS 4.0 and later.

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

    Declaration

    Swift

    init(key key: String, ascending ascending: Bool, comparator cmptr: NSComparator)

    Objective-C

    - (instancetype)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

    YEStrue if the receiver specifies sorting in ascending order, otherwise NOfalse.

    cmptr

    A comparator block.

    Return Value

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

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 4.0 and later.

  • ascending ascending Property

    A Boolean value that indicates whether the receiver specifies sorting in ascending order. (read-only)

    Declaration

    Swift

    var ascending: Bool { get }

    Objective-C

    @property(readonly) BOOL ascending

    Discussion

    YEStrue if the receiver specifies sorting in ascending order, otherwise NOfalse.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

  • key key Property

    The receiver’s property key path. (read-only)

    Declaration

    Swift

    var key: String? { get }

    Objective-C

    @property(readonly, copy) NSString *key

    Discussion

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

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

  • selector selector Property

    The selector the receiver specifies to use when comparing objects.

    Declaration

    Swift

    var selector: Selector { get }

    Objective-C

    @property(readonly) SEL selector

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Swift

    func compareObject(_ object1: AnyObject, toObject object2: AnyObject) -> NSComparisonResult

    Objective-C

    - (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.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

  • A sort descriptor with the sort order reversed. (read-only)

    Declaration

    Swift

    var reversedSortDescriptor: AnyObject! { get }

    Objective-C

    @property(readonly, retain) id reversedSortDescriptor

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

  • Force a sort descriptor that was securely decoded to allow evaluation.

    Declaration

    Swift

    func allowEvaluation()

    Objective-C

    - (void)allowEvaluation

    Discussion

    When securely decoding an NSSortDescriptor object encoded using NSSecureCoding, evaluation is disabled because it is potentially unsafe to evaluate descriptors you get out of an archive.

    Before you enable evaluation, you should validate key paths, selectors, etc to ensure no erroneous or malicious code will be executed. Once you’ve preflighted the sort descriptor, you can enable the receiver for evaluation by calling allowEvaluation.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 7.0 and later.

  • An NSComparator for the sort descriptor. (read-only)

    Declaration

    Swift

    var comparator: NSComparator? { get }

    Objective-C

    @property(readonly) NSComparator comparator

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 4.0 and later.