A predicate describes a condition, and resolves to being either true or false.
In ActionStep, predicates a special kind of object used to determine whether an object meets certain conditions. They are typically used to filter collections.
Predicates can be used in one of two ways.
The first, and most common way to use predicates is to create them using a SQL-like format string. More information on the syntax of this string can be found at the Predicates Programming Guide. The predicate is created using a format string as follows.
var predicate:NSPredicate = NSPredicate.predicateWithFormat(formatString);
The second way is to manually build predicate and expression objects using the ActionStep API.
The NSArray class provides two methods through which you can filter your data using predicates. Let’s say we’re working with an array called “people” and a predicate named “pred”.
// // Returns an array containing the results of the filtering. // people is left intact. // var filteredPeople:NSArray = people.filteredArrayUsingPredicate(pred); // // Modifies the people array, discarding other information // people.filterUsingPredicate(pred);
The predicate API consists of 4 primary classes:
The base class for all predicates. This class is used to create predicates from a format string, and is also used to represent true and false constant values.
Expressions are objects that are dynamically evaluated to yield an object.
Examples of possible expressions are:
These predicates are used to compare the results of two expressions. All of the logical operators you are familiar with are provided for use, as well as some interesting ones.
Compound predicates represent AND, OR and NOT operations. They contain multiple predicates and are evaluated exactly as &&, || and ! operators are in ActionScript.
Key path expressions are a way to dig down into objects. They are written using a dot (”.”) separated list of property names. Further information can be found at What is a Key Path?.
There are a number of predefined functions that can be used in predicate expressions.
TODO Insert table
For defining your own functions, see Can I add my own functions?
There are a number of constant values that can be used in expressions. These include:
These values are self-explanatory, excluding SELF. SELF represents the top level object that is being tested.