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 |
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:
Simple comparisons, such as
grade == "7"orfirstName 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 > 12ANY 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.
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
-
+ predicateWithFormat: -
+ predicateWithFormat:argumentArray: -
+ predicateWithFormat:arguments: -
– predicateWithSubstitutionVariables: -
+ predicateWithValue: -
+ predicateWithBlock:
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.
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
YESif the evaluatedObject evaluates to true, otherwiseNO.
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.hpredicateWithFormat:
Creates and returns a new predicate formed by creating a new string with a given format and parsing the result.
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.hpredicateWithFormat:argumentArray:
Creates and returns a new predicate by substituting the values in a given array into a format string and parsing the result.
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.hpredicateWithFormat:arguments:
Creates and returns a new predicate by substituting the values in an argument list into a format string and parsing the result.
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.hpredicateWithValue:
Creates and returns a predicate that always evaluates to a given 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.hInstance Methods
evaluateWithObject:
Returns a Boolean value that indicates whether a given object matches the conditions specified by the receiver.
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.hevaluateWithObject: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.
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.hpredicateFormat
Returns the receiver’s format string.
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.hpredicateWithSubstitutionVariables:
Returns a copy of the receiver with the receiver’s variables substituted by values specified in a given substitution variables dictionary.
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© 2009 Apple Inc. All Rights Reserved. (Last updated: 2009-10-09)