PATH WebObjects 4.0 Documentation > EOControl Reference

EOSortOrdering

Inherits From:
NSObject

Conforms To: NSCoding
NSObject (NSObject)

Declared in: EOControl/EOSortOrdering.h

An EOSortOrdering object specifies the way that a group of objects should be sorted, using a property key and a method selector for comparing values of that property. EOSortOrderings are used both to generate SQL when fetching rows from a database server, and to sort objects in memory. Both the EOFetchSpecification class and the added NSArray sorting methods accept an array of EOSortOrderings, which are applied in series to perform sorts by more than one property.

Sorting with SQL

When an EOSortOrdering is used to fetch data from a relational database, it's rendered into an ORDER BY clause for a SQL SELECT statement according to the concrete adaptor you're using. For more information, see the class description for EOSQLExpression. The Framework predefines symbols for four comparison selectors, listed in the table below. The table also shows an example of how the comparison selectors can be mapped to SQL.

Defined Name SQL Expression

EOCompareAscending (key) asc

EOCompareDescending (key) desc

EOCompareCaseInsensitiveAscending upper(key) asc

EOCompareCaseInsensitiveDescending upper(key) desc

`Defined Name`	SQL Expression
EOCompareAscending	(key) asc
EOCompareDescending	(key) desc
EOCompareCaseInsensitiveAscending	upper(key) asc
EOCompareCaseInsensitiveDescending	upper(key) desc

Using the mapping in the table above, the array of EOSortOrderings (nameOrdering ) created in the following code example:

NSArray *nameOrdering = [NSArray arrayWithObjects:

    [EOSortOrdering sortOrderingWithKey:@"lastName" selector:EOCompareAscending],

    [EOSortOrdering sortOrderingWithKey:@"firstName" selector:EOCompareAscending],

    nil];

results in this ORDER BY clause:

order by (lastName) asc, (firstName) asc

In-Memory Sorting

Enterprise Objects Framework adds a method each to NSArray and NSMutableArray for sorting objects in memory. NSArray's sortedArrayUsingKeyOrderArray: returns a new array of objects sorted according to the specified EOSortOrderings. Similarly, NSMutableArray's sortUsingKeyOrderArray: sorts the array of objects. This code fragment, for example, sorts an array of Employee objects by last name, then first name using the array of EOSortOrderings created above:

NSArray *sortedEmployees = [employees sortedArrayUsingKeyOrderArray:nameOrdering];

Comparison Methods

The predefined comparison selectors are:

Defined Name

EOCompareAscending - compareAscending:

EOCompareDescending - compareDescending:

EOCompareCaseInsensitiveAscending - compareCaseInsensitiveAscending:

EOCompareCaseInsensitiveDescending - compareCaseInsensitiveDescending:

Defined Name
EOCompareAscending	- compareAscending:
EOCompareDescending	- compareDescending:
EOCompareCaseInsensitiveAscending	- compareCaseInsensitiveAscending:
EOCompareCaseInsensitiveDescending	- compareCaseInsensitiveDescending:

The first two can be used with any value class; the second two with NSString objects only. The sorting methods extract property values using key-value coding and apply the selectors to the values. If you use custom value classes, you should be sure to implement the appropriate comparison methods to avoid exceptions when sorting objects.

Adopted Protocols

NSCoding - encodeWithCoder: - initWithCoder:
Creating instances + sortOrderingWithKey:selector: - initWithKey:selector:
Examining a sort ordering - key - selector

sortOrderingWithKey:selector:

+ (EOSortOrdering *)sortOrderingWithKey: (NSString *)key selector: (SEL)selector

Creates and returns an EOSortOrdering based on key and selector.

See also: - initWithKey:selector:

initWithKey:selector:

- (id)initWithKey: (NSString *)key selector: (SEL)aSelector

Initializes a newly allocated EOSortOrdering based on key and selector and returns self . This is the designated initializer for the EOSortOrdering class.

key

- (NSString *)key

Returns the key by which the receiver orders items.

See also: - selector

selector

- (SEL)selector

Returns the method selector used to compare values when sorting.

See also: - key