An expression for use in a comparison predicate.
SDKs
- iOS 3.0+
- macOS 10.4+
- Mac Catalyst 13.0+
- tvOS 9.0+
- watchOS 2.0+
Framework
- Foundation
Declaration
class 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: NSSubquery
, NSAggregate
, NSUnion
, NSIntersect
, and NSMinus
.
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 (NSComparison
); 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 NSExpression
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 (NSExpression
, NSExpression
, and NSExpression
) 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, selector
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).