Class

NSPredicate

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

Overview

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 NSComparison​Predicate, NSCompound​Predicate, 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 first​Name like "Shaffiq"

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

  • Logical operations, such as (first​Name like "Mark") OR (last​Name like "Adderley")

  • In macOS 10.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 with​Substitution​Variables(_:​) and evaluate(with:​)). In macOS 10.5 and later, you can use evaluate(with:​substitution​Variables:​), which combines these steps.

Symbols

Creating a Predicate

init(format:​ String, argument​Array:​ [Any]?)

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

init(format:​ String, arguments:​ CVa​List​Pointer)

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

func with​Substitution​Variables([String :​ Any])

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

init(value:​ Bool)

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

init(block:​ (Any?, [String :​ Any]?) -> Bool)

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

Evaluating a Predicate

func evaluate(with:​ Any?)

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

func evaluate(with:​ Any?, substitution​Variables:​ [String :​ Any]?)

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.

func allow​Evaluation()

Force a predicate that was securely decoded to allow evaluation.

Getting a String Representation

var predicate​Format:​ String

The receiver’s format string.