An expression for use in a comparison 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 (between); 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 subquery 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 (unionSet, intersectSet, and minusSet) 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).


Initializing an Expression

init(expressionType: NSExpression.ExpressionType)

Initializes the expression with the specified expression type.

init(format: String, argumentArray: [Any])

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

init(format: String, arguments: CVaListPointer)

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

Creating an Expression for a Value

init(forConstantValue: Any?)

Returns a new expression that represents a given constant value.

class func expressionForEvaluatedObject()

Returns a new expression that represents the object being evaluated.

init(forKeyPath: String)

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

init(forVariable: String)

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

class func expressionForAnyKey()

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

Creating a Collection Expression

init(forAggregate: [NSExpression])

Returns a new aggregate expression for a given collection.

init(forUnionSet: NSExpression, with: NSExpression)

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

init(forIntersectSet: NSExpression, with: NSExpression)

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

init(forMinusSet: NSExpression, with: NSExpression)

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

Creating a Subquery

init(forSubquery: NSExpression, usingIteratorVariable: String, predicate: NSPredicate)

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

init(block: (Any?, [NSExpression], NSMutableDictionary?) -> Any, arguments: [NSExpression]?)

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

Creating an Expression for a Function

init(forFunction: String, arguments: [Any])

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

init(forFunction: NSExpression, selectorName: String, arguments: [Any]?)

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

var arguments: [NSExpression]?

The arguments for the expression.

var collection: Any

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

var constantValue: Any?

The constant value of the expression.

var expressionType: NSExpression.ExpressionType

The expression type for the expression.

var function: String

The function for the expression.

var keyPath: String

The key path for the expression.

var operand: NSExpression

The operand for the expression.

var predicate: NSPredicate

The predicate of a subquery expression.

var left: NSExpression

The left expression of an aggregate expression.

var right: NSExpression

The right expression of an aggregate expression.

var variable: String

The variable for the expression.

Evaluating an Expression

func expressionValue(with: Any?, context: NSMutableDictionary?)

Evaluates an expression using a given object and context.

func allowEvaluation()

Force an expression that was securely decoded to allow evaluation.

Accessing the Expression Block

var expressionBlock: (Any?, [NSExpression], NSMutableDictionary?) -> Any

The block that is executed to evaluate the expression.


enum NSExpression.ExpressionType

Defines the possible types of NSExpression.


Inherits From

See Also


class NSPredicate

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

class NSComparisonPredicate

A specialized predicate that you use to compare expressions.

class NSCompoundPredicate

A specialized predicate that evaluates logical combinations of other predicates.