[iOS] Useful Collection Operators

@avg

The @avg operator uses valueForKeyPath: to get the values specified by the property specified by the key path to the right of the operator, converts each to a double, and returns the average value as an instance of NSNumber. In the case where the value is nil, 0 is assumed instead.

The following example returns the average value of the transaction amount for the objects in transactions:

NSNumber *transactionAverage = [transactions valueForKeyPath:@"@avg.amount"];

The formatted result of transactionAverage is $456.54.

@count

The @count operator returns the number of objects in the left key path collection as an instance of NSNumber, the key path to the right of the operator is ignored.

The following example returns the number of Transaction objects in transactions:

NSNumber *numberOfTransactions = [transactions valueForKeyPath:@"@count"];

The value of numberOfTransactions is 13.

@max

The @max operator compares the values of the property specified by the key path to the right of the operator and returns the maximum value found. The maximum value is determined using the compare: method of the objects at the specified key path. The compared property objects must support comparison with each other. If the value of the right side of the key path is nil, it is ignored.

The following example returns the maximum value of the date values (date of the latest transaction) for the Transaction objects intransactions:

NSDate *latestDate = [transactions valueForKeyPath:@"@max.date"];

The latestDate value (formatted) is Jul 15, 2010.

@min

The @min operator compares the values of the property specified by the key path to the right of the operator and returns the minimum value found. The minimum value is determined using the compare: method of the objects at the specified key path. The compared property objects must support comparison with each other. If the value of the right side of the key path is nil, it is ignored.

The following example returns the minimum value (date of the earliest transaction) of the date property for the Transaction objects intransactions:

NSDate *earliestDate = [transactions valueForKeyPath:@"@min.date"];

The earliestDate value (formatted) is Dec 1, 2009.

@sum

The @sum operator returns the sum of the values of the property specified by the key path to the right of the operator. Each number is converted to a double, the sum of the values is computed, and the total is wrapped as an instance of NSNumber and returned. If the value of the right side of the key path is nil, it is ignored.

The following example returns the sum of the amounts property for the transactions in transactions:

NSNumber *amountSum = [transactions valueForKeyPath:@"@sum.amount"];

The resulting amountSum value (formatted) is $5,935.00.

@distinctUnionOfObjects

The @distinctUnionOfObjects operator returns an array containing the distinct objects in the property specified by the key path to the right of the operator.

The following example returns the payee property values for the transactions in transactions with any duplicate values removed:

NSArray *payees = [transactions valueForKeyPath:@"@distinctUnionOfObjects.payee"];

The resulting payees array contains the following strings: Car Loan, General Cable, Animal Hospital, Green Power, Mortgage.

The @unionOfObjects operator is similar, but does not remove duplicate objects.

Important: This operator raises an exception if any of the leaf objects is nil.

@unionOfObjects

The @unionOfObjects operator returns an array containing the distinct objects in the property specified by the key path to the right of the operator. Unlike @distinctUnionOfObjects, duplicate objects are not removed.

The following example returns the payee property values for the transactions in transactions:

NSArray *payees = [transactions valueForKeyPath:@"@unionOfObjects.payee"];

The resulting payees array contains the following strings: Green Power, Green Power, Green Power, Car Loan, Car Loan, Car Loan, General Cable, General Cable, General Cable, Mortgage, Mortgage, Mortgage, Animal Hospital.

The @distinctUnionOfArrays operator is similar, but removes duplicate objects.

Important: This operator raises an exception if any of the leaf objects is nil.

Array and Set Operators

The array and set operators operate on nested collections, that is, a collection where each entry contains a collection.

The variable arrayOfTransactions is used in the example for each operator. It is an array containing two arrays of Transaction objects.

The following code snippet shows how the nested collection would be created:

// Create the array that contains additional arrays.

self.arrayOfTransactionsArray = [NSMutableArray array];

// Add the array of objects used in the above examples.

[arrayOfTransactionsArray addObject:transactions];

// Add a second array of objects; this array contains alternate values.

[arrayOfTransactionsArrays addObject:moreTransactions];

The first array of Transaction objects contains the data listed in Table 1 and the second array (moreTransactions) contains Transactionobjects with the hypothetical data in Table 2.

Table 2  Hypothetical Transaction data in the moreTransactions array

payee values	amount values (formatted as currency)	date values (formatted as month day, year)
General Cable - Cottage	$120.00	Dec 18, 2009
General Cable - Cottage	$155.00	Jan 9, 2010
General Cable - Cottage	$120.00	Dec 1, 2010
Second Mortgage	$1,250.00	Nov 15, 2010
Second Mortgage	$1,250.00	Sep 20, 2010
Second Mortgage	$1,250.00	Feb 12, 2010
Hobby Shop	$600.00	Jun 14, 2010

@distinctUnionOfArrays

The @distinctUnionOfArrays operator returns an array containing the distinct objects in the property specified by the key path to the right of the operator.

The following code example will return the distinct values of the payee property in all the arrays with arrayOfTransactionsArrays:

NSArray *payees = [arrayOfTransactionsArrays valueForKeyPath:@"@distinctUnionOfArrays.payee"];

The resulting payees array contains the following values: Hobby Shop, Mortgage, Animal Hospital, Second Mortgage, Car Loan, General Cable - Cottage, General Cable, Green Power.

The @unionOfArrays operator is similar, but does not remove duplicate objects.

Important: This operator raises an exception if any of the leaf objects is nil.

@unionOfArrays

The @unionOfArrays operator returns an array containing the objects in the property specified by the key path to the right of the operator. Unlike @distinctUnionOfArrays, duplicate objects are not removed.

The following code example will return the values of the payee property in all the arrays with arrayOfTransactionsArrays:

NSArray *payees = [arrayOfTransactionsArrays valueForKeyPath:@"@unionOfArrays.payee"];

The resulting payees array contains the following values: Green Power, Green Power, Green Power, Car Loan, Car Loan, Car Loan, General Cable, General Cable, General Cable, Mortgage, Mortgage, Mortgage, Animal Hospital, General Cable - Cottage, General Cable - Cottage, General Cable - Cottage, Second Mortgage, Second Mortgage, Second Mortgage, Hobby Shop.

Important: This operator raises an exception if any of the leaf objects is nil.

@distinctUnionOfSets

The @distinctUnionOfSets operator returns a set containing the distinct objects in the property specified by the key path to the right of the operator.

This operator works the same as @distinctUnionOfArrays, except that it expects an NSSet instance containing NSSet instances ofTransaction objects rather than arrays. It returns an NSSet instance. Using the example data set, the returned set would contain the results as those shown in @distinctUnionOfArrays.

Important: This operator raises an exception if any of the leaf objects is nil.