Class

NSPredicate

A definition of logical conditions used to constrain a search either for a fetch or for in-memory filtering.

Overview

Predicates represent logical conditions, which you can use to filter collections of objects. Although it's 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")

  • Temporal range constraints, such as date between {$YESTERDAY, $TOMORROW}.

  • Relational conditions, such as group.name like "work*"

  • Aggregate 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 using the evaluate(with:substitutionVariables:) method, so that the predicate can be predefined before substituting concrete values at runtime.

Topics

Creating a Predicate

init(format: String, argumentArray: [Any]?)

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

init(format: String, arguments: CVaListPointer)

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

init(format: String, CVarArg...)

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

func withSubstitutionVariables([String : Any])

Returns a copy of the predicate with the predicate'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 Boolean value.

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

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

init?(fromMetadataQueryString: String)

Initializes a predicate with a metadata query string.

Evaluating a Predicate

func evaluate(with: Any?)

Returns a Boolean value indicating whether the specified object matches the conditions specified by the predicate.

func evaluate(with: Any?, substitutionVariables: [String : Any]?)

Returns a Boolean value indicating whether the specified object matches the conditions specified by the predicate after substituting in the values in a given variables dictionary.

func allowEvaluation()

Forces a predicate that was securely decoded to allow evaluation.

Getting a String Representation

var predicateFormat: String

The predicate's format string.

Relationships

Inherits From

See Also

Filtering

class NSExpression

An expression for use in a comparison predicate.

class NSComparisonPredicate

A specialized predicate that you use to compare expressions.

class NSCompoundPredicate

A specialized predicate that evaluates logical combinations of other predicates.