iOS Developer Library

Developer

Foundation Framework Reference NSExpression Class Reference

Options
Deployment Target:

On This Page
Language:

NSExpression

Inheritance


Conforms To


Import Statement


Swift

import Foundation

Objective-C

@import Foundation;

Availability


Available in iOS 3.0 and later.

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

  • Returns a new expression that represents a given constant value.

    Declaration

    Swift

    init(forConstantValue obj: AnyObject) -> NSExpression

    Objective-C

    + (NSExpression *)expressionForConstantValue:(id)obj

    Parameters

    obj

    The constant value the new expression is to represent.

    Return Value

    A new expression that represents the constant value, obj.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 3.0 and later.

  • Returns a new expression that represents the object being evaluated.

    Declaration

    Swift

    class func expressionForEvaluatedObject() -> NSExpression

    Objective-C

    + (NSExpression *)expressionForEvaluatedObject

    Return Value

    A new expression that represents the object being evaluated.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 3.0 and later.

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

    Declaration

    Swift

    init(forKeyPath keyPath: String) -> NSExpression

    Objective-C

    + (NSExpression *)expressionForKeyPath:(NSString *)keyPath

    Parameters

    keyPath

    The key path that the new expression should evaluate.

    Return Value

    A new expression that invokes valueForKeyPath: with keyPath.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 3.0 and later.

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

    Declaration

    Swift

    init(forVariable string: String) -> NSExpression

    Objective-C

    + (NSExpression *)expressionForVariable:(NSString *)string

    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.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 3.0 and later.

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

    Declaration

    Swift

    class func expressionForAnyKey() -> NSExpression

    Objective-C

    + (NSExpression *)expressionForAnyKey

    Return Value

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

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 7.0 and later.

  • Returns a new aggregate expression for a given collection.

    Declaration

    Swift

    init(forAggregate collection: [AnyObject]) -> NSExpression

    Objective-C

    + (NSExpression *)expressionForAggregate:(NSArray *)collection

    Parameters

    collection

    A collection object (an instance of NSArray, NSSet, or NSDictionary) that contains further expressions.

    Return Value

    A new expression that contains the expressions in collection.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 3.0 and later.

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

    Declaration

    Swift

    init(forUnionSet left: NSExpression, with right: NSExpression) -> NSExpression

    Objective-C

    + (NSExpression *)expressionForUnionSet:(NSExpression *)left with:(NSExpression *)right

    Parameters

    left

    An expression that evaluates to an NSSet object.

    right

    An expression that evaluates to a collection object (an instance of NSArray, NSSet, or NSDictionary).

    Return Value

    An new NSExpression object that represents the union of left and right.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 3.0 and later.

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

    Declaration

    Swift

    init(forIntersectSet left: NSExpression, with right: NSExpression) -> NSExpression

    Objective-C

    + (NSExpression *)expressionForIntersectSet:(NSExpression *)left with:(NSExpression *)right

    Parameters

    left

    An expression that evaluates to an NSSet object.

    right

    An expression that evaluates to a collection object (an instance of NSArray, NSSet, or NSDictionary).

    Return Value

    A new NSExpression object that represents the intersection of left and right.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 3.0 and later.

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

    Declaration

    Swift

    init(forMinusSet left: NSExpression, with right: NSExpression) -> NSExpression

    Objective-C

    + (NSExpression *)expressionForMinusSet:(NSExpression *)left with:(NSExpression *)right

    Parameters

    left

    An expression that evaluates to an NSSet object.

    right

    An expression that evaluates to a collection object (an instance of NSArray, NSSet, or NSDictionary).

    Return Value

    A new NSExpression object that represents the subtraction of right from left.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 3.0 and later.

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

    Declaration

    Swift

    init(forSubquery expression: NSExpression, usingIteratorVariable variable: String, predicate predicate: AnyObject) -> NSExpression

    Objective-C

    + (NSExpression *)expressionForSubquery:(NSExpression *)expression usingIteratorVariable:(NSString *)variable predicate:(id)predicate

    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)

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 3.0 and later.

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

    Declaration

    Swift

    init(forBlock block: (AnyObject!, [AnyObject]!, NSMutableDictionary!) -> AnyObject!, arguments arguments: [AnyObject]) -> NSExpression

    Objective-C

    + (NSExpression *)expressionForBlock:(id (^)(id evaluatedObject, NSArray *expressions, NSMutableDictionary *context))block arguments:(NSArray *)arguments

    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 NSExpression objects 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 NSExpression object 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.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 4.0 and later.

    See Also

    expressionBlock

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

    Declaration

    Swift

    init(forFunction name: String, arguments parameters: [AnyObject]) -> NSExpression

    Objective-C

    + (NSExpression *)expressionForFunction:(NSString *)name arguments:(NSArray *)parameters

    Parameters

    name

    The name of the function to invoke.

    parameters

    An array containing NSExpression objects 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 NSExpression object 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

    average:

    An NSArray object containing NSExpression objects representing numbers

    An NSNumber object (the average of values in the array)

    OS X v10.4 and later

    sum:

    An NSArray object containing NSExpression objects representing numbers

    An NSNumber object (the sum of values in the array)

    OS X v10.4 and later

    count:

    An NSArray object containing NSExpression objects representing numbers

    An NSNumber object (the number of elements in the array)

    OS X v10.4 and later

    min:

    An NSArray object containing NSExpression objects representing numbers

    An NSNumber object (the minimum of the values in the array)

    OS X v10.4 and later

    max:

    An NSArray object containing NSExpression objects representing numbers

    An NSNumber object (the maximum of the values in the array)

    OS X v10.4 and later

    median:

    An NSArray object containing NSExpression objects representing numbers

    An NSNumber object (the median of the values in the array)

    OS X v10.5 and later

    mode:

    An NSArray object containing NSExpression objects representing numbers

    An NSArray object (the mode of the values in the array)

    OS X v10.5 and later

    stddev:

    An NSArray object containing NSExpression objects representing numbers

    An NSNumber object (the standard deviation of the values in the array)

    OS X v10.5 and later

    add:to:

    An NSArray object containing two NSExpression objects representing numbers

    An NSNumber object (the sum of the values in the array)

    OS X v10.5 and later

    from:subtract:

    An NSArray object containing two NSExpression objects representing numbers

    An NSNumber object (the result of subtracting the second value in the array from the first value in the array)

    OS X v10.5 and later

    multiply:by:

    An NSArray object containing two NSExpression objects representing numbers

    An NSNumber object (the result of multiplying the values in the array)

    OS X v10.5 and later

    divide:by:

    An NSArray object containing two NSExpression objects representing numbers

    An NSNumber object (the result of dividing the first value in the array by the second value in the array)

    OS X v10.5 and later

    modulus:by:

    An NSArray object containing two NSExpression objects representing numbers

    An NSNumber object (the remainder of dividing the first value in the array by the second value in the array)

    OS X v10.5 and later

    sqrt:

    An NSArray object containing one NSExpression object representing a number

    An NSNumber object (the square root of the value in the array)

    OS X v10.5 and later

    log:

    An NSArray object containing one NSExpression object representing a number

    An NSNumber object (the log of the value in the array)

    OS X v10.5 and later

    ln:

    An NSArray object containing one NSExpression object representing a number

    An NSNumber object (the natural log of the value in the array)

    OS X v10.5 and later

    raise:toPower:

    An NSArray object containing two NSExpression objects representing numbers

    An NSNumber object (the result of raising the first value in the array to the power of the second value in the array)

    OS X v10.5 and later

    exp:

    An NSArray object containing one NSExpression object representing a number

    An NSNumber object (the base-e exponential of the value in the array)

    OS X v10.5 and later

    ceiling:

    An NSArray object containing one NSExpression object representing a number

    An NSNumber object (the smallest integral value not less than the value in the array)

    OS X v10.5 and later

    abs:

    An NSArray object containing one NSExpression object representing a number

    An NSNumber object (the absolute value of the value in the array)

    OS X v10.5 and later

    trunc:

    An NSArray object containing one NSExpression object representing a number

    An NSNumber object (the integral value nearest to but no greater than the value in the array)

    OS X v10.5 and later

    random

    nil

    An NSNumber object (a random integer value)

    OS X v10.5 and later

    random:

    An NSArray object containing one NSExpression object representing a number

    An NSNumber object (a random integer value between 0 and the value in the array (exclusive))

    OS X v10.5 and later

    now

    nil

    An [NSDate] object (the current date and time)

    OS X v10.5 and later

    floor:

    An NSArray object containing one NSExpression object representing a number

    An NSNumber object

    iOS 3.0 and later

    uppercase:

    An NSArray object containing one NSExpression object representing a string

    An NSString object

    iOS 3.0 and later

    lowercase:

    An NSArray object containing one NSExpression object representing a string

    An NSString object

    iOS 3.0 and later

    bitwiseAnd:with:

    An NSArray object containing two NSExpression objects representing numbers

    An NSNumber object (the number is treated as an NSInteger)

    iOS 3.0 and later

    bitwiseOr:with:

    An NSArray object containing two NSExpression objects representing numbers

    An NSNumber object (the number is treated as an NSInteger)

    iOS 3.0 and later

    bitwiseXor:with:

    An NSArray object containing two NSExpression objects representing numbers

    An NSNumber object (the number is treated as an NSInteger)

    iOS 3.0 and later

    leftshift:by:

    An NSArray object containing two NSExpression objects representing numbers

    An NSNumber object (the number is treated as an NSInteger)

    iOS 3.0 and later

    rightshift:by:

    An NSArray object containing two NSExpression objects representing numbers

    An NSNumber object (the number is treated as an NSInteger)

    iOS 3.0 and later

    onesComplement:

    An NSArray object containing one NSExpression object representing a number

    An NSNumber object (the number is treated as an NSInteger)

    iOS 3.0 and later

    noindex:

    An NSArray object containing an NSExpression object

    The result of evaluating the parameter as though the noindex: function expression didn't exist.

    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.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 3.0 and later.

  • Returns an expression which will return the result of invoking on a given target a selector with a given name using given arguments.

    Declaration

    Swift

    init(forFunction target: NSExpression, selectorName name: String, arguments parameters: [AnyObject]) -> NSExpression

    Objective-C

    + (NSExpression *)expressionForFunction:(NSExpression *)target selectorName:(NSString *)name arguments:(NSArray *)parameters

    Parameters

    target

    An NSExpression object 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 NSExpression objects 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.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 3.0 and later.

  • arguments arguments Property

    The arguments for the expression. (read-only)

    Declaration

    Swift

    var arguments: [AnyObject] { get }

    Objective-C

    @property(readonly, copy) NSArray *arguments

    Discussion

    An expression’s arguments is the array of expressions that will be passed as parameters during invocation of the selector on the operand of a function expression.

    Accessing this property raises an exception if it is not applicable to the expression.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 3.0 and later.

  • The collection of expressions in an aggregate expression, or the collection element of a subquery expression. (read-only)

    Declaration

    Swift

    var collection: AnyObject { get }

    Objective-C

    @property(readonly, retain) id collection

    Discussion

    Accessing this property raises an exception if it is not applicable to the expression.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 3.0 and later.

  • The constant value of the expression. (read-only)

    Declaration

    Swift

    var constantValue: AnyObject { get }

    Objective-C

    @property(readonly, retain) id constantValue

    Discussion

    Accessing this property raises an exception if it is not applicable to the expression.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 3.0 and later.

  • The expression type for the expression. (read-only)

    Declaration

    Swift

    var expressionType: NSExpressionType { get }

    Objective-C

    @property(readonly) NSExpressionType expressionType

    Discussion

    Accessing this property raises an exception if it is not applicable to the expression.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 3.0 and later.

  • function function Property

    The function for the expression. (read-only)

    Declaration

    Swift

    var function: String { get }

    Objective-C

    @property(readonly, copy) NSString *function

    Discussion

    Accessing this property raises an exception if it is not applicable to the expression.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 3.0 and later.

  • keyPath keyPath Property

    The key path for the expression. (read-only)

    Declaration

    Swift

    var keyPath: String { get }

    Objective-C

    @property(readonly, copy) NSString *keyPath

    Discussion

    Accessing this property raises an exception if it is not applicable to the expression.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 3.0 and later.

  • operand operand Property

    The operand for the expression. (read-only)

    Declaration

    Swift

    @NSCopying var operand: NSExpression { get }

    Objective-C

    @property(readonly, copy) NSExpression *operand

    Discussion

    The operand for an expression is the object on which the expression’s selector or block will be invoked. The object is the result of evaluating a key path or one of the defined functions. Accessing this property raises an exception if it is not applicable to the expression.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 3.0 and later.

  • predicate predicate Property

    The predicate of a subquery expression. (read-only)

    Declaration

    Swift

    @NSCopying var predicate: NSPredicate { get }

    Objective-C

    @property(readonly, copy) NSPredicate *predicate

    Discussion

    Accessing this property raises an exception if it is not applicable to the expression.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 3.0 and later.

  • The left expression of an aggregate expression. (read-only)

    Declaration

    Swift

    @NSCopying var leftExpression: NSExpression { get }

    Objective-C

    @property(readonly, copy) NSExpression *leftExpression

    Discussion

    Accessing this property raises an exception if it is not applicable to the expression.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 3.0 and later.

  • The right expression of an aggregate expression. (read-only)

    Declaration

    Swift

    @NSCopying var rightExpression: NSExpression { get }

    Objective-C

    @property(readonly, copy) NSExpression *rightExpression

    Discussion

    Accessing this property raises an exception if it is not applicable to the expression.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 3.0 and later.

  • variable variable Property

    The variable for the expression. (read-only)

    Declaration

    Swift

    var variable: String { get }

    Objective-C

    @property(readonly, copy) NSString *variable

    Discussion

    Accessing this property raises an exception if it is not applicable to the expression.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 3.0 and later.

  • Evaluates an expression using a given object and context.

    Declaration

    Swift

    func expressionValueWithObject(_ object: AnyObject?, context context: NSMutableDictionary?) -> AnyObject

    Objective-C

    - (id)expressionValueWithObject:(id)object context:(NSMutableDictionary *)context

    Parameters

    object

    The object against which the expression 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.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 3.0 and later.

  • Force an expression that was securely decoded to allow evaluation.

    Declaration

    Swift

    func allowEvaluation()

    Objective-C

    - (void)allowEvaluation

    Discussion

    When securely decoding an NSExpression object encoded using NSSecureCoding, evaluation is disabled because it is potentially unsafe to evaluate expressions you get out of an archive.

    Before you enable evaluation, you should validate key paths, selectors, etc to ensure no erroneous or malicious code will be executed. Once you’ve preflighted the expression, you can enable the expression for evaluation by calling allowEvaluation.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 7.0 and later.

  • The block that is executed to evaluate the expression. (read-only)

    Declaration

    Swift

    var expressionBlock: (AnyObject!, [AnyObject]!, NSMutableDictionary!) -> AnyObject! { get }

    Objective-C

    @property(readonly, copy) id (^expressionBlock)(id, NSArray *, NSMutableDictionary *)

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 4.0 and later.

Data Types

  • Defines the possible types of NSExpression.

    Declaration

    Swift

    enum NSExpressionType : UInt { case ConstantValueExpressionType case EvaluatedObjectExpressionType case VariableExpressionType case KeyPathExpressionType case FunctionExpressionType case UnionSetExpressionType case IntersectSetExpressionType case MinusSetExpressionType case SubqueryExpressionType case AggregateExpressionType case AnyKeyExpressionType case BlockExpressionType }

    Objective-C

    enum { NSConstantValueExpressionType = 0, NSEvaluatedObjectExpressionType, NSVariableExpressionType, NSKeyPathExpressionType, NSFunctionExpressionType, NSUnionSetExpressionType, NSIntersectSetExpressionType, NSMinusSetExpressionType, NSSubqueryExpressionType = 13, NSAggregateExpressionType = 14, NSAnyKeyExpressionType = 15, NSBlockExpressionType = 19 } typedef NSUInteger NSExpressionType;

    Constants

    • ConstantValueExpressionType

      NSConstantValueExpressionType

      An expression that always returns the same value.

      Available in iOS 3.0 and later.

    • EvaluatedObjectExpressionType

      NSEvaluatedObjectExpressionType

      An expression that always returns the parameter object itself.

      Available in iOS 3.0 and later.

    • VariableExpressionType

      NSVariableExpressionType

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

    • KeyPathExpressionType

      NSKeyPathExpressionType

      An expression that returns something that can be used as a key path.

      Available in iOS 3.0 and later.

    • FunctionExpressionType

      NSFunctionExpressionType

      An expression that returns the result of evaluating a function.

      Available in iOS 3.0 and later.

    • UnionSetExpressionType

      NSUnionSetExpressionType

      An expression that creates a union of the results of two nested expressions.

      Available in iOS 3.0 and later.

    • IntersectSetExpressionType

      NSIntersectSetExpressionType

      An expression that creates an intersection of the results of two nested expressions.

      Available in iOS 3.0 and later.

    • MinusSetExpressionType

      NSMinusSetExpressionType

      An expression that combines two nested expression results by set subtraction.

      Available in iOS 3.0 and later.

    • SubqueryExpressionType

      NSSubqueryExpressionType

      An expression that filters a collection using a subpredicate.

      Available in iOS 3.0 and later.

    • AggregateExpressionType

      NSAggregateExpressionType

      An expression that defines an aggregate of NSExpression objects.

      Available in iOS 3.0 and later.

    • AnyKeyExpressionType

      NSAnyKeyExpressionType

      An expression that represents any key.

      Available in iOS 7.0 and later.

    • BlockExpressionType

      NSBlockExpressionType

      An expression that uses a Block.

      Available in iOS 4.0 and later.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 3.0 and later.