NSPredicate

The NSPredicate class is used to define logical conditions used to constrain a search either for a fetch or for in-memory filtering.

You use predicates to represent logical conditions, used for describing objects in persistent stores and in-memory filtering of objects. Although it is common to create predicates directly from instances of NSComparisonPredicate, NSCompoundPredicate, and NSExpression, you often create predicates from a format string which is parsed by the class methods on NSPredicate. Examples of predicate format strings include:

Simple comparisons, such as grade == "7" or firstName like "Shaffiq"

Case and diacritic insensitive lookups, such as name contains[cd] "itroen"

Logical operations, such as (firstName like "Mark") OR (lastName like "Adderley")

In OS X v10.5 and later, you can create between predicates such as date between {$YESTERDAY, $TOMORROW}.

You can create predicates for relationships, such as:

group.name like "work*"

ALL children.age > 12

ANY children.age > 12

You can create predicates for operations, such as @sum.items.price < 1000. For a complete syntax reference, refer to the Predicate Programming Guide.

Parameters

The substitution variables dictionary. The dictionary must contain key-value pairs for all variables in the receiver.

Return Value

YEStrue if object matches the conditions specified by the receiver after substituting in the values in variables for any replacement tokens, otherwise NOfalse.

Discussion

This method returns the same result as the two step process of first invoking predicateWithSubstitutionVariables: on the receiver and then invoking evaluateWithObject: on the returned predicate. This method is optimized for situations which require repeatedly evaluating a predicate with substitution variables with different variable substitutions.

Availability

Declaration

Discussion

When securely decoding an NSPredicate object encoded using NSSecureCoding, evaluation is disabled because it is potentially unsafe to evaluate predicates 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 predicate, you can enable the receiver for evaluation by calling allowEvaluation.

Declaration

Special Considerations

The string returned by this method is not guaranteed to be the same as the string used to create the predicate using predicateWithFormat: etc. You cannot use this method to create a persistent representation of a predicate that you could use to recreate the original predicate. If you need a persistent representation of a predicate, create an archive (NSPredicate adopts the NSCoding protocol).