< Previous PageNext Page > Hide TOC

Set and Array Operators

Array operators allow you to specify operations to be performed on a collection's items using a key path of the form keyPathToArray.@operator.keyPathToProperty. This article describes the available collection operators.

To perform an operation on the items in a collection, a key prefixed with “@” is used to specify a collection operator. The key path to the left of the collection operator, if present, is used to determine the array or set, relative to the receiver, that is used in the operation. The key path to the right of the collection operator specifies the property of the items in the collection, that is used in the operation. All the collection operators, with the exception of @count, require a key path to the right of the collection operator. It is not currently possible to define your own collection operators.

The array operator examples in the following sections assume that accountsArray is an array containing Account objects as described in Table 1 and that transactionArray is an array containing Transaction objects as described in Table 2. The savingsAccount variable is an instance of Account.

Contents:

@avg
@count
@distinctUnionOfArrays
@distinctUnionOfObjects
@distinctUnionOfSets
@max
@min
@sum
@unionOfArrays
@unionOfObjects
@unionOfSets

@avg

The @avg operator uses valueForKeyPath:to get the value for each item in the receiver, converts the value to a double, and returns the average of the values as an instance of NSNumber.

The following example returns the average opening balance of your accounts.

[accountsArray valueForKeyPath:@"@avg.openingBalance"]

@count

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

The following example returns the number of transactions in the savings account object.

[savingsAccount valueForKeyPath:@"transactions.@count"]

@distinctUnionOfArrays

The @distinctUnionOfArrays operator returns an array containing the distinct objects in the arrays returned by sending valueForKeyPath: to each item in the receiver, passing the key path to the right of the array operator.

The following example returns an array containing the payees for the savings account transactions, with the duplicate payee objects removed.

[accountsArray valueForKeyPath:@"@distinctUnionOfArrays.transactions.payee"]

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

@distinctUnionOfObjects

The @distinctUnionOfObjects operator returns an array containing the distinct objects returned by sending valueForKeyPath: to each item in the receiver, passing the key path to the right of the array operator.

The following example returns an array containing the account payees, with the duplicates removed.

[savingsAccount

     valueForKeyPath:@"transactions.@distinctUnionOfObjects.payee"]

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

@distinctUnionOfSets

The @distinctUnionOfSets operator returns an array containing the distinct objects returned by sending valueForKeyPath: to each item in the receiver, passing the key path to the right of the @ operator.

This operator is the same as @distinctUnionOfArrays , but operates on a set (an instance of NSSet), rather than an array.

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

@max

The @max operator compares the objects returned by sending valueForKeyPath: to each item in the receiver array passing the key path to the right of the array operator as the parameter, returning 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.

The following example returns the date of the latest transaction in the savings account.

[savingsAccount valueForKeyPath:@"transactions.@max.date"]

@min

The @min operator compares the objects returned by sending valueForKeyPath: to each item in the receiver array with the key path to the right of the array operator as the parameter, returning 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.

The following example returns the date of the earliest transaction in the savings account.

[savingsAccount valueForKeyPath:@"transactions.@min.date"]

@sum

The @sum operator returns the total of adding the NSNumber objects returned by sending valueForKeyPath: to each item in the receiver array, with the key path to the right of the array operator as the parameter. Each number is converted to a double and an instance of NSNumber containing the total sum is returned.

The following example returns the sum of all transactions for the savings account.

[savingsAccount valueForKeyPath:@"transactions.@sum.amount"]

@unionOfArrays

The @unionOfArrays operator returns an array containing all the object values in the arrays returned by sending valueForKeyPath: to each item in the receiving array, passing the key path to the right of the array operator as the parameter. Unlike @distinctUnionOfArrays, duplicate objects are not removed.

@unionOfObjects

The @unionOfObjects operator returns an array containing all the objects values returned by sending valueForKeyPath: to each item in the receiving array, passing the key path to the right of the array operator as the parameter. Unlike @distinctUnionOfObjects, duplicate objects are not removed.

@unionOfSets

The @unionOfSets operator returns an array containing all the objects values returned by sending valueForKeyPath: to each item in the receiving set, passing the key path to the right of the operator as the parameter. Unlike @distinctUnionOfSets, duplicate objects are not removed.

< Previous PageNext Page > Hide TOC