Class

NSExpression

An expression for use in a comparison predicate.

Declaration

@interface NSExpression : NSObject

Overview

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

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

In macOS 10.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).

Topics

Initializing an Expression

initWithExpressionType:

Initializes the expression with the specified expression type.

expressionWithFormat:

Initializes the expression with the specified expression arguments.

expressionWithFormat:argumentArray:

Initializes the expression with the specified expression format and array of arguments.

expressionWithFormat:arguments:

Initializes the expression with the specified expression format and arguments list.

Creating an Expression for a Value

expressionForConstantValue:

Returns a new expression that represents a given constant value.

expressionForEvaluatedObject

Returns a new expression that represents the object being evaluated.

expressionForKeyPath:

Returns a new expression that invokes valueForKeyPath: with a given key path.

expressionForVariable:

Returns a new expression that extracts a value from the variable bindings dictionary for a given key.

expressionForAnyKey

Returns a new expression that represents any key for a Spotlight query.

Creating a Collection Expression

expressionForAggregate:

Returns a new aggregate expression for a given collection.

expressionForUnionSet:with:

Returns a new NSExpression object that represent the union of a given set and collection.

expressionForIntersectSet:with:

Returns a new NSExpression object that represent the intersection of a given set and collection.

expressionForMinusSet:with:

Returns a new NSExpression object that represent the subtraction of a given collection from a given set.

Creating a Subquery

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

Creating an Expression Using Blocks

expressionForBlock:arguments:

Creates an NSExpression object that will use the Block for evaluating objects.

Creating an Expression for a Function

expressionForFunction:arguments:

Returns a new expression that will invoke one of the predefined functions.

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

Getting Information About an Expression

arguments

The arguments for the expression.

collection

The collection of expressions in an aggregate expression, or the collection element of a subquery expression.

constantValue

The constant value of the expression.

expressionType

The expression type for the expression.

function

The function for the expression.

keyPath

The key path for the expression.

operand

The operand for the expression.

predicate

The predicate of a subquery expression.

leftExpression

The left expression of an aggregate expression.

rightExpression

The right expression of an aggregate expression.

variable

The variable for the expression.

Evaluating an Expression

expressionValueWithObject:context:

Evaluates an expression using a given object and context.

allowEvaluation

Force an expression that was securely decoded to allow evaluation.

Accessing the Expression Block

expressionBlock

The block that is executed to evaluate the expression.

Constants

NSExpressionType

Defines the possible types of NSExpression.

Relationships

Inherits From

See Also

Filtering

NSPredicate

A definition of logical conditions used to constrain a search either for a fetch or for in-memory filtering.

NSComparisonPredicate

A specialized predicate that you use to compare expressions.

NSCompoundPredicate

A specialized predicate that evaluates logical combinations of other predicates.