Mac Developer Library

Developer

Foundation Framework Reference NSPredicate Class Reference

Options
Deployment Target:

On This Page
Language:

NSPredicate

Conforms To


Import Statement


Swift

import Foundation

Objective-C

@import Foundation;

Availability


Available in OS X v10.4 and later.

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.

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.

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

    Declaration

    Objective-C

    + (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.

    Import Statement

    Objective-C

    @import Foundation;

    Availability

    Available in OS X v10.4 and later.

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

    Declaration

    Swift

    init(format predicateFormat: String, argumentArray arguments: [AnyObject]?) -> NSPredicate

    Objective-C

    + (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.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.4 and later.

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

    Declaration

    Swift

    init(format format: String, arguments argList: CVaListPointer) -> NSPredicate

    Objective-C

    + (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.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.4 and later.

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

    Declaration

    Swift

    func predicateWithSubstitutionVariables(_ variables: [NSObject : AnyObject]) -> Self

    Objective-C

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

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.4 and later.

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

    Declaration

    Swift

    init(value value: Bool) -> NSPredicate

    Objective-C

    + (NSPredicate *)predicateWithValue:(BOOL)value

    Parameters

    value

    The value to which the new predicate should evaluate.

    Return Value

    A predicate that always evaluates to value.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.4 and later.

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

    Declaration

    Swift

    init(block block: (AnyObject!, [NSObject : AnyObject]!) -> Bool) -> NSPredicate

    Objective-C

    + (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 YEStrue if the evaluatedObject evaluates to true, otherwise NOfalse.

    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.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.6 and later.

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

    Declaration

    Swift

    func evaluateWithObject(_ object: AnyObject) -> Bool

    Objective-C

    - (BOOL)evaluateWithObject:(id)object

    Parameters

    object

    The object against which to evaluate the receiver.

    Return Value

    YEStrue if object matches the conditions specified by the receiver, otherwise NOfalse.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.4 and later.

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

    Declaration

    Swift

    func evaluateWithObject(_ object: AnyObject, substitutionVariables variables: [NSObject : AnyObject]?) -> Bool

    Objective-C

    - (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

    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.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.5 and later.

  • Force a predicate that was securely decoded to allow evaluation.

    Declaration

    Swift

    func allowEvaluation()

    Objective-C

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

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.9 and later.

  • The receiver’s format string. (read-only)

    Declaration

    Swift

    var predicateFormat: String { get }

    Objective-C

    @property(readonly, copy) NSString *predicateFormat

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

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.4 and later.