NSPredicate Class Reference

Inherits from
Conforms to
Framework
/System/Library/Frameworks/Foundation.framework
Availability
Available in iOS 3.0 and later.
Companion guide
Declared in
NSPredicate.h
Related sample code

Overview

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:

You can create predicates for relationships, such as:

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

You can also create predicates that include variables, so that the predicate can be pre-defined before substituting concrete values at runtime. In OS X v10.4, for predicates that use variables, evaluation is a two step process (see predicateWithSubstitutionVariables: and evaluateWithObject:). In OS X v10.5 and later, you can use evaluateWithObject:substitutionVariables:, which combines these steps.

Tasks

Creating a Predicate

Evaluating a Predicate

Getting a String Representation

Class Methods

predicateWithBlock:

Creates and returns a predicate that evaluates using a specified block object and bindings dictionary.

+ (NSPredicate *)predicateWithBlock:(BOOL (^)(id evaluatedObject, NSDictionary *bindings))block
Parameters
block

The block is applied to the object to be evaluated.

The block takes two arguments:

evaluatedObject

The object to be evaluated.

bindings

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

The block returns YES if the evaluatedObject evaluates to true, otherwise NO.

Return Value

A new predicate by that evaluates objects using block.

Special Considerations

In OS X v10.6, Core Data supports this method in the in-memory and atomic stores, but not in the SQLite-based store.

Availability
  • Available in iOS 4.0 and later.
Declared In
NSPredicate.h

predicateWithFormat:

Creates and returns a new predicate formed by creating a new string with a given format and parsing the result.

+ (NSPredicate *)predicateWithFormat:(NSString *)format,, ...
Parameters
format

The format string for the new predicate.

...

A comma-separated list of arguments to substitute into format.

Return Value

A new predicate formed by creating a new string with format and parsing the result.

Discussion

For details of the format of the format string and of limitations on variable substitution, see “Predicate Format String Syntax”.

Availability
  • Available in iOS 3.0 and later.
Declared In
NSPredicate.h

predicateWithFormat:argumentArray:

Creates and returns a new predicate by substituting the values in a given array into a format string and parsing the result.

+ (NSPredicate *)predicateWithFormat:(NSString *)predicateFormat argumentArray:(NSArray *)arguments
Parameters
predicateFormat

The format string for the new predicate.

arguments

The arguments to substitute into predicateFormat. Values are substituted into predicateFormat in the order they appear in the array.

Return Value

A new predicate by substituting the values in arguments into predicateFormat, and parsing the result.

Discussion

For details of the format of the format string and of limitations on variable substitution, see “Predicate Format String Syntax”.

Availability
  • Available in iOS 3.0 and later.
Declared In
NSPredicate.h

predicateWithFormat:arguments:

Creates and returns a new predicate by substituting the values in an argument list into a format string and parsing the result.

+ (NSPredicate *)predicateWithFormat:(NSString *)format arguments:(va_list)argList
Parameters
format

The format string for the new predicate.

argList

The arguments to substitute into predicateFormat. Values are substituted into predicateFormat in the order they appear in the argument list.

Return Value

A new predicate by substituting the values in argList into predicateFormat and parsing the result.

Discussion

For details of the format of the format string and of limitations on variable substitution, see “Predicate Format String Syntax”.

Availability
  • Available in iOS 3.0 and later.
Declared In
NSPredicate.h

predicateWithValue:

Creates and returns a predicate that always evaluates to a given value.

+ (NSPredicate *)predicateWithValue:(BOOL)value
Parameters
value

The value to which the new predicate should evaluate.

Return Value

A predicate that always evaluates to value.

Availability
  • Available in iOS 3.0 and later.
Declared In
NSPredicate.h

Instance Methods

allowEvaluation

Force a predicate that was securely decoded to allow evaluation.

- (void)allowEvaluation
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.

Availability
  • Available in iOS 7.0 and later.
Declared In
NSPredicate.h

evaluateWithObject:

Returns a Boolean value that indicates whether a given object matches the conditions specified by the receiver.

- (BOOL)evaluateWithObject:(id)object
Parameters
object

The object against which to evaluate the receiver.

Return Value

YES if object matches the conditions specified by the receiver, otherwise NO.

Availability
  • Available in iOS 3.0 and later.
Declared In
NSPredicate.h

evaluateWithObject:substitutionVariables:

Returns a Boolean value that indicates whether a given object matches the conditions specified by the receiver after substituting in the values in a given variables dictionary.

- (BOOL)evaluateWithObject:(id)object substitutionVariables:(NSDictionary *)variables
Parameters
object

The object against which to evaluate the receiver.

variables

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

Return Value

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

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
  • Available in iOS 3.0 and later.
Declared In
NSPredicate.h

predicateFormat

Returns the receiver’s format string.

- (NSString *)predicateFormat
Return Value

The receiver’€™s format string.

Special Considerations

The string returned by this method is not guaranteed to be the same as a 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).

Availability
  • Available in iOS 3.0 and later.
Declared In
NSPredicate.h

predicateWithSubstitutionVariables:

Returns a copy of the receiver with the receiver’s variables substituted by values specified in a given substitution variables dictionary.

- (NSPredicate *)predicateWithSubstitutionVariables:(NSDictionary *)variables
Parameters
variables

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

Return Value

A copy of the receiver with the receiver’s variables substituted by values specified in variables.

Discussion

The receiver itself is not modified by this method, so you can reuse it for any number of substitutions.

Availability
  • Available in iOS 3.0 and later.
Declared In
NSPredicate.h