NSExpression Class Reference
| Inherits from | |
| Conforms to | |
| Framework | /System/Library/Frameworks/Foundation.framework |
| Availability | Available in iOS 3.0 and later. |
| Companion guide | |
| Declared in | NSExpression.h |
Overview
NSExpression is used to represent expressions in a predicate.
Comparison operations in an NSPredicate are based on two expressions, as represented by instances of the NSExpression class. Expressions are created for constant values, key paths, and so on.
Generally, anywhere in the NSExpression class hierarchy where there is composite API and subtypes that may only reasonably respond to a subset of that API, invoking a method that does not make sense for that subtype will cause an exception to be thrown.
Expression Types
In OS X v10.5, NSExpression introduces several new expression types: NSSubqueryExpressionType, NSAggregateExpressionType, NSUnionSetExpressionType, NSIntersectSetExpressionType, and NSMinusSetExpressionType.
Aggregate Expressions
The aggregate expression allows you to create predicates containing expressions that evaluate to collections that contain further expressions. The collection may be an NSArray, NSSet, or NSDictionary object.
For example, consider the BETWEEN operator (NSBetweenPredicateOperatorType); its right hand side is a collection containing two elements. Using just the OS X v10.4 API, these elements must be constants, as there is no way to populate them using variable expressions. On OS X v10.4, it is not possible to create a predicate template to the effect of date between {$YESTERDAY, $TOMORROW}; instead you must create a new predicate each time.
Aggregate expressions are not supported by Core Data.
Subquery Expressions
The NSSubqueryExpressionType creates a sub-expression, evaluation of which returns a subset of a collection of objects. It allows you to create sophisticated queries across relationships, such as a search for multiple correlated values on the destination object of a relationship.
Set Expressions
The set expressions (NSUnionSetExpressionType, NSIntersectSetExpressionType, and NSMinusSetExpressionType) combine results in a manner similar to the NSSet methods.
Both sides of these expressions must evaluate to a collection; the left-hand side must evaluate to an NSSet object, the right-hand side can be any other collection type.
(expression UNION expression) |
(expression INTERSECT expression) |
(expression MINUS expression) |
Set expressions are not supported by Core Data.
Function Expressions
On OS X v10.4, NSExpression only supports a predefined set of functions: sum, count, min, max, and average. These predefined functions were accessed in the predicate syntax using custom keywords (for example, MAX(1, 5, 10)).
On OS X v10.5 and later, function expressions also support arbitrary method invocations. To use this extended functionality, you can now use the syntax FUNCTION(receiver, selectorName, arguments, ...), for example:
FUNCTION(@"/Developer/Tools/otest", @"lastPathComponent") => @"otest" |
All methods must take 0 or more id arguments and return an id value, although you can use the CAST expression to convert datatypes with lossy string representations (for example, CAST(####, "NSDate")). The CAST expression is extended in OS X v10.5 to provide support for casting to classes for use in creating receivers for function expressions.
Note that although Core Data supports evaluation of the predefined functions, it does not support the evaluation of custom predicate functions in the persistent stores (during a fetch).
Tasks
Initializing an Expression
-
– initWithExpressionType: -
+ expressionWithFormat: -
+ expressionWithFormat:argumentArray: -
+ expressionWithFormat:arguments:
Creating an Expression for a Value
-
+ expressionForConstantValue: -
+ expressionForEvaluatedObject -
+ expressionForKeyPath: -
+ expressionForVariable:
Creating a Collection Expression
-
+ expressionForAggregate: -
+ expressionForUnionSet:with: -
+ expressionForIntersectSet:with: -
+ expressionForMinusSet:with:
Creating a Subquery
Creating an Expression Using Blocks
Creating an Expression for a Function
Getting Information About an Expression
-
– arguments -
– collection -
– constantValue -
– expressionType -
– function -
– keyPath -
– leftExpression -
– operand -
– predicate -
– rightExpression -
– variable
Evaluating an Expression
Accessing the Expression Block
Class Methods
expressionForAggregate:
Returns a new aggregate expression for a given collection.
Parameters
- collection
A collection object (an instance of
NSArray,NSSet, orNSDictionary) that contains further expressions.
Return Value
A new expression that contains the expressions in collection.
Availability
- Available in iOS 3.0 and later.
Declared In
NSExpression.hexpressionForBlock:arguments:
Creates an NSExpression object that will use the Block for evaluating objects.
Parameters
- block
The Block is applied to the object to be evaluated.
The Block takes three arguments and returns a value:
- evaluatedObject
The object to be evaluated.
- expressions
An array of predicate expressions that evaluates to a collection.
- context
A dictionary that the expression can use to store temporary state for one predicate evaluation.
Note that context is mutable, and that it can only be accessed during the evaluation of the expression. You must not attempt to retain it for use elsewhere. ]
The Block returns the evaluatedObject.
- arguments
An array containing
NSExpressionobjects that will be used as parameters during the invocation of selector.For a selector taking no parameters, the array should be empty. For a selector taking one or more parameters, the array should contain one
NSExpressionobject which will evaluate to an instance of the appropriate type for each parameter.If there is a mismatch between the number of parameters expected and the number you provide during evaluation, an exception may be raised or missing parameters may simply be replaced by
nil(which occurs depends on how many parameters are provided, and whether you have over- or underflow).See
expressionForFunction:arguments:for a complete list of arguments.
Return Value
An expression that filters a collection using the specified Block.
Availability
- Available in iOS 4.0 and later.
See Also
Declared In
NSExpression.hexpressionForConstantValue:
Returns a new expression that represents a given constant value.
Parameters
- obj
The constant value the new expression is to represent.
Return Value
A new expression that represents the constant value, obj.
Availability
- Available in iOS 3.0 and later.
Declared In
NSExpression.hexpressionForEvaluatedObject
Returns a new expression that represents the object being evaluated.
Return Value
A new expression that represents the object being evaluated.
Availability
- Available in iOS 3.0 and later.
Declared In
NSExpression.hexpressionForFunction:arguments:
Returns a new expression that will invoke one of the predefined functions.
Parameters
- name
The name of the function to invoke.
- parameters
An array containing
NSExpressionobjects that will be used as parameters during the invocation of selector.For a selector taking no parameters, the array should be empty. For a selector taking one or more parameters, the array should contain one
NSExpressionobject which will evaluate to an instance of the appropriate type for each parameter.If there is a mismatch between the number of parameters expected and the number you provide during evaluation, an exception may be raised or missing parameters may simply be replaced by
nil(which occurs depends on how many parameters are provided, and whether you have over- or underflow).
Return Value
A new expression that invokes the function name using the parameters in parameters.
Discussion
The name parameter can be one of the following predefined functions.
Function |
Parameter |
Returns | Availability |
|---|---|---|---|
|
An |
An | OS X v10.4 and later |
|
An |
An | OS X v10.4 and later |
|
An |
An | OS X v10.4 and later |
|
An |
An | OS X v10.4 and later |
| An | An | OS X v10.4 and later |
| An | An | OS X v10.5 and later |
| An | An | OS X v10.5 and later |
| An | An | OS X v10.5 and later |
| An | An | OS X v10.5 and later |
| An | An | OS X v10.5 and later |
| An | An | OS X v10.5 and later |
| An | An | OS X v10.5 and later |
| An | An | OS X v10.5 and later |
| An | An | OS X v10.5 and later |
| An | An | OS X v10.5 and later |
| An | An | OS X v10.5 and later |
| An | An | OS X v10.5 and later |
| An | An | OS X v10.5 and later |
| An | An | OS X v10.5 and later |
| An | An | OS X v10.5 and later |
| An | An | OS X v10.5 and later |
|
| An | OS X v10.5 and later |
| An | An | OS X v10.5 and later |
|
| An | OS X v10.5 and later |
| An | An | iOS 3.0 and later |
| An | An | iOS 3.0 and later |
| An | An | iOS 3.0 and later |
| An | An | iOS 3.0 and later |
| An | An | iOS 3.0 and later |
| An | An | iOS 3.0 and later |
| An | An | iOS 3.0 and later |
| An | An | iOS 3.0 and later |
| An | An | iOS 3.0 and later |
| An | The result of evaluating the parameter as though the | iOS 3.0 and later |
This method raises an exception immediately if the selector is invalid; it raises an exception at runtime if the parameters are incorrect.
The parameters argument is a collection containing an expression which evaluates to a collection, as illustrated in the following examples:
NSNumber *number1 = [NSNumber numberWithInteger:20]; |
NSNumber *number2 = [NSNumber numberWithInteger:40]; |
NSArray *numberArray = [NSArray arrayWithObjects: number1, number2, nil]; |
NSExpression *arrayExpression = [NSExpression expressionForConstantValue: numberArray]; |
NSArray *argumentArray = [NSArray arrayWithObject: arrayExpression]; |
NSExpression* expression = |
[NSExpression expressionForFunction:@"sum:" arguments:argumentArray]; |
id result = [expression expressionValueWithObject: nil context: nil]; |
BOOL ok = [result isEqual: [NSNumber numberWithInt: 60]]; // ok == YES |
[NSExpression expressionForFunction:@"random" arguments:nil]; |
[NSExpression expressionForFunction:@"max:" |
arguments: [NSArray arrayWithObject: |
[NSExpression expressionForConstantValue: |
[NSArray arrayWithObjects: |
[NSNumber numberWithInt: 5], [NSNumber numberWithInt: 10], nil]]]]; |
[NSExpression expressionForFunction:@"subtract:from:" |
arguments: [NSArray arrayWithObjects: |
[NSExpression expressionForConstantValue: [NSNumber numberWithInt: 5]], |
[NSExpression expressionForConstantValue: [NSNumber numberWithInt: 10]], nil]]; |
Special Considerations
This method throws an exception immediately if the selector is unknown; it throws at runtime if the parameters are incorrect.
Availability
- Available in iOS 3.0 and later.
Declared In
NSExpression.hexpressionForFunction:selectorName:arguments:
Returns an expression which will return the result of invoking on a given target a selector with a given name using given arguments.
Parameters
- target
An
NSExpressionobject which will evaluate an object on which the selector identified by name may be invoked.- name
The name of the method to be invoked.
- parameters
An array containing
NSExpressionobjects which can be evaluated to provide parameters for the method specified by name.
Return Value
An expression which will return the result of invoking the selector named name on the result of evaluating the target expression with the parameters specified by evaluating the elements of parameters.
Discussion
See the description of expressionForFunction:arguments: for examples of how to construct the parameter array.
Special Considerations
This method throws an exception immediately if the selector is unknown; it throws at runtime if the parameters are incorrect.
This expression effectively allows your application to invoke any method on any object it can navigate to at runtime. You must consider the security implications of this type of evaluation.
Availability
- Available in iOS 3.0 and later.
See Also
Declared In
NSExpression.hexpressionForIntersectSet:with:
Returns a new NSExpression object that represent the intersection of a given set and collection.
Parameters
- left
An expression that evaluates to an
NSSetobject.- right
An expression that evaluates to a collection object (an instance of
NSArray,NSSet, orNSDictionary).
Return Value
A new NSExpression object that represents the intersection of left and right.
Availability
- Available in iOS 3.0 and later.
Declared In
NSExpression.hexpressionForKeyPath:
Returns a new expression that invokes valueForKeyPath: with a given key path.
Parameters
- keyPath
The key path that the new expression should evaluate.
Return Value
A new expression that invokes valueForKeyPath: with keyPath.
Availability
- Available in iOS 3.0 and later.
Declared In
NSExpression.hexpressionForMinusSet:with:
Returns a new NSExpression object that represent the subtraction of a given collection from a given set.
Parameters
- left
An expression that evaluates to an
NSSetobject.- right
An expression that evaluates to a collection object (an instance of
NSArray,NSSet, orNSDictionary).
Return Value
A new NSExpression object that represents the subtraction of right from left.
Availability
- Available in iOS 3.0 and later.
Declared In
NSExpression.hexpressionForSubquery:usingIteratorVariable:predicate:
Returns an expression that filters a collection by storing elements in the collection in a given variable and keeping the elements for which qualifier returns true.
Parameters
- expression
A predicate expression that evaluates to a collection.
- variable
Used as a local variable, and will shadow any instances of variable in the bindings dictionary. The variable is removed or the old value replaced once evaluation completes.
- predicate
The predicate used to determine whether the element belongs in the result collection.
Return Value
An expression that filters a collection by storing elements in the collection in the variable variable and keeping the elements for which qualifier returns true
Discussion
This method creates a sub-expression, evaluation of which returns a subset of a collection of objects. It allows you to create sophisticated queries across relationships, such as a search for multiple correlated values on the destination object of a relationship.
For example, suppose you have an Apartment entity that has a to-many relationship to a Resident entity, and that you want to create a query for all apartments inhabited by a resident whose first name is "Jane" and whose last name is "Doe". Using only API available for OS X v 10.4, you could try the predicate:
resident.firstname == "Jane" && resident.lastname == "Doe" |
but this will always return false since resident.firstname and resident.lastname both return collections. You could also try:
resident.firstname CONTAINS "Jane" && resident.lastname CONTAINS "Doe" |
but this is also flawed—it returns true if there are two residents, one of whom is John Doe and one of whom is Jane Smith. The only way to find the desired apartments is to do two passes: one through residents to find "Jane Doe", and one through apartments to find the ones where our Jane Does reside.
Subquery expressions provide a way to encapsulate this type of qualification into a single query.
The string format for a subquery expression is:
SUBQUERY(collection_expression, variable_expression, predicate); |
where expression is a predicate expression that evaluates to a collection, variableExpression is an expression which will be used to contain each individual element of collection, and predicate is the predicate used to determine whether the element belongs in the result collection.
Using subqueries, the apartment query could be reformulated as
(SUBQUERY(residents, $x, $x.firstname == "Jane" && $x.lastname == "Doe").@count != 0) |
or
(SUBQUERY(residents, $x, $x.firstname == "Jane" && $x.lastname == "Doe")[size] != 0) |
Availability
- Available in iOS 3.0 and later.
Declared In
NSExpression.hexpressionForUnionSet:with:
Returns a new NSExpression object that represent the union of a given set and collection.
Parameters
- left
An expression that evaluates to an
NSSetobject.- right
An expression that evaluates to a collection object (an instance of
NSArray,NSSet, orNSDictionary).
Return Value
An new NSExpression object that represents the union of left and right.
Availability
- Available in iOS 3.0 and later.
Declared In
NSExpression.hexpressionForVariable:
Returns a new expression that extracts a value from the variable bindings dictionary for a given key.
Parameters
- string
The key for the variable to extract from the variable bindings dictionary.
Return Value
A new expression that extracts from the variable bindings dictionary the value for the key string.
Availability
- Available in iOS 3.0 and later.
Declared In
NSExpression.hexpressionWithFormat:
Initializes the receiver with the specified expression arguments.
Parameters
- expressionFormat,
The expression format.
- ...
A comma-separated list of arguments to substitute into format. The list is terminated by
nil.
Return Value
An initialized NSExpression object with the specified format.
Availability
- Available in iOS 5.0 and later.
See Also
Declared In
NSExpression.hexpressionWithFormat:argumentArray:
Initializes the receiver with the specified expression format and array of arguments.
Parameters
- expressionFormat
The expression format.
- arguments
An array of arguments to be used with the expressionFormat string.
Return Value
An initialized NSExpression object with the specified arguments.
Availability
- Available in iOS 5.0 and later.
Declared In
NSExpression.hexpressionWithFormat:arguments:
Initializes the receiver with the specified expression format and arguments list.
Parameters
- expressionFormat
The expression format.
- argList
A list of arguments to be inserted into the expressionFormat string. The argument list is terminated by
nil.
Return Value
An initialized NSExpression object with the specified arguments.
Availability
- Available in iOS 5.0 and later.
See Also
Declared In
NSExpression.hInstance Methods
arguments
Returns the arguments for the receiver.
Return Value
The arguments for the receiver—that is, the array of expressions that will be passed as parameters during invocation of the selector on the operand of a function expression.
Discussion
This method raises an exception if it is not applicable to the receiver.
Availability
- Available in iOS 3.0 and later.
Declared In
NSExpression.hcollection
Returns the collection of expressions in an aggregate expression, or the collection element of a subquery expression.
Return Value
Returns the collection of expressions in an aggregate expression, or the collection element of a subquery expression.
Discussion
This method raises an exception if it is not applicable to the receiver.
Availability
- Available in iOS 3.0 and later.
Declared In
NSExpression.hconstantValue
Returns the constant value of the receiver.
Return Value
The constant value of the receiver.
Discussion
This method raises an exception if it is not applicable to the receiver.
Availability
- Available in iOS 3.0 and later.
Declared In
NSExpression.hexpressionBlock
Returns the expression’s expression Block.
Return Value
The expression’s expression Block as created in expressionForBlock:arguments:.
Availability
- Available in iOS 4.0 and later.
See Also
Declared In
NSExpression.hexpressionType
Returns the expression type for the receiver.
Return Value
The expression type for the receiver.
Discussion
This method raises an exception if it is not applicable to the receiver.
Availability
- Available in iOS 3.0 and later.
Declared In
NSExpression.hexpressionValueWithObject:context:
Evaluates an expression using a given object and context.
Parameters
- object
The object against which the receiver is evaluated.
- context
A dictionary that the expression can use to store temporary state for one predicate evaluation. Can be
nil.Note that context is mutable, and that it can only be accessed during the evaluation of the expression. You must not attempt to retain it for use elsewhere. ]
Return Value
The evaluated object.
Availability
- Available in iOS 3.0 and later.
Declared In
NSExpression.hfunction
Returns the function for the receiver.
Return Value
The function for the receiver.
Discussion
This method raises an exception if it is not applicable to the receiver.
Availability
- Available in iOS 3.0 and later.
Declared In
NSExpression.hinitWithExpressionType:
Initializes the receiver with the specified expression type.
Parameters
- type
The type of the new expression, as defined by
NSExpressionType.
Return Value
An initialized NSExpression object of the type type.
Special Considerations
This method is the designated initializer for NSExpression.
Availability
- Available in iOS 3.0 and later.
See Also
Declared In
NSExpression.hkeyPath
Returns the key path for the receiver.
Return Value
The key path for the receiver.
Discussion
This method raises an exception if it is not applicable to the receiver.
Availability
- Available in iOS 3.0 and later.
Declared In
NSExpression.hleftExpression
Returns the left expression of an aggregate expression.
Return Value
The left expression of a set expression.
Discussion
This method raises an exception if it is not applicable to the receiver.
Availability
- Available in iOS 3.0 and later.
Declared In
NSExpression.hoperand
Returns the operand for the receiver.
Return Value
The operand for the receiver—that is, the object on which the selector will be invoked.
Discussion
The object is the result of evaluating a key path or one of the defined functions. This method raises an exception if it is not applicable to the receiver.
Availability
- Available in iOS 3.0 and later.
Declared In
NSExpression.hpredicate
Return the predicate of a subquery expression.
Return Value
The predicate of a subquery expression.
Discussion
This method raises an exception if it is not applicable to the receiver.
Availability
- Available in iOS 3.0 and later.
Declared In
NSExpression.hrightExpression
Returns the right expression of an aggregate expression.
Return Value
The right expression of a set expression.
Discussion
This method raises an exception if it is not applicable to the receiver.
Availability
- Available in iOS 3.0 and later.
Declared In
NSExpression.hvariable
Returns the variable for the receiver.
Return Value
The variable for the receiver.
Discussion
This method raises an exception if it is not applicable to the receiver.
Availability
- Available in iOS 3.0 and later.
Declared In
NSExpression.hConstants
NSExpressionType
Defines the possible types of NSExpression.
enum {
NSConstantValueExpressionType = 0,
NSEvaluatedObjectExpressionType,
NSVariableExpressionType,
NSKeyPathExpressionType,
NSFunctionExpressionType,
NSAggregateExpressionType,
NSSubqueryExpressionType = 13,
NSUnionSetExpressionType,
NSIntersectSetExpressionType,
NSMinusSetExpressionType,
NSBlockExpressionType = 19
}
typedef NSUInteger NSExpressionType;
Constants
NSConstantValueExpressionTypeAn expression that always returns the same value.
Available in iOS 3.0 and later.
Declared in
NSExpression.h.NSEvaluatedObjectExpressionTypeAn expression that always returns the parameter object itself.
Available in iOS 3.0 and later.
Declared in
NSExpression.h.NSVariableExpressionTypeAn expression that always returns whatever value is associated with the key specified by ‘variable’ in the bindings dictionary.
Available in iOS 3.0 and later.
Declared in
NSExpression.h.NSKeyPathExpressionTypeAn expression that returns something that can be used as a key path.
Available in iOS 3.0 and later.
Declared in
NSExpression.h.NSFunctionExpressionTypeAn expression that returns the result of evaluating a function.
Available in iOS 3.0 and later.
Declared in
NSExpression.h.NSAggregateExpressionTypeAn expression that defines an aggregate of
NSExpressionobjects.Available in iOS 3.0 and later.
Declared in
NSExpression.h.NSSubqueryExpressionTypeAn expression that filters a collection using a subpredicate.
Available in iOS 3.0 and later.
Declared in
NSExpression.h.NSUnionSetExpressionTypeAn expression that creates a union of the results of two nested expressions.
Available in iOS 3.0 and later.
Declared in
NSExpression.h.NSIntersectSetExpressionTypeAn expression that creates an intersection of the results of two nested expressions.
Available in iOS 3.0 and later.
Declared in
NSExpression.h.NSMinusSetExpressionTypeAn expression that combines two nested expression results by set subtraction.
Available in iOS 3.0 and later.
Declared in
NSExpression.h.NSBlockExpressionTypeAn expression that uses a Block.
Available in iOS 4.0 and later.
Declared in
NSExpression.h.
Availability
- Available in iOS 3.0 and later.
Declared In
NSExpression.h© 2012 Apple Inc. All Rights Reserved. (Last updated: 2012-05-14)