< Previous PageNext Page >

Hide TOC

Predicate Format String Syntax

This article describes the syntax of the predicate string and some aspects of the predicate parser.

Parser Basics

The predicate string parser is whitespace insensitive, case insensitive with respect to keywords, and supports nested parenthetical expressions. Note that the parser string is different from a string expressions passed to the regex engine. The sections describe the parser text, not the syntax for the regex engine.

Variables are denoted with a $ (for example $VARIABLE_NAME). The parser does not perform semantic type checking. ? is not a valid parser token.

The format string supports printf-style format arguments such as %x (see Formatting String Objects)). Two important arguments are %@ and %K.

%@ is a var arg substitution for an object value—often a string, number, or date.
%K is a var arg substitution for a key path.

When string variables are substituted into a format string using %@ , they are surrounded by quotation marks. If you want to specify a dynamic property name, use %K in the format string, as shown in the following example.

NSString *attributeName = @"firstName";

NSString *attributeValue = @"Adam";

NSPredicate *predicate = [NSPredicate predicateWithFormat:@"%K like %@",

        attributeName, attributeValue];

The predicate format string in this case evaluates to firstName like "Adam".

Single or double quoting variables (or substitution variable strings) will cause %@, %K, or $variable to be interpreted as a literal in the format string and so will prevent any substitution. In the following example, the predicate format string evaluates to firstName like "%@" (note the single quotes around %@).

NSString *attributeName = @"firstName";

NSString *attributeValue = @"Adam";

NSPredicate *predicate = [NSPredicate predicateWithFormat:@"%K like '%@'",

        attributeName, attributeValue];

Basic Comparisons

=, ==

The left-hand expression is equal to the right-hand expression.

>=, =>

The left-hand expression is greater than or equal to the right-hand expression.

<=, =<

The left-hand expression is less than or equal to the right-hand expression.

>

The left-hand expression is greater than the right-hand expression.

<

The left-hand expression is less than the right-hand expression.

!=, <>

The left-hand expression is not equal to the right-hand expression.

BETWEEN

The left-hand expression is between the values specified in the right-hand side.

The right-hand side is a two value array (an array is required to specify order) giving upper and lower bounds. For example, 1 BETWEEN { 0 , 33 }, or $INPUT BETWEEN { $LOWER, $UPPER }.

In Objective-C, you could create a BETWEEN predicate as shown in the following example:

NSPredicate *betweenPredicate = [NSPredicate predicateWithFormat: @"attributeName BETWEEN %@",

                                     [NSArray arrayWithObjects:one, ten, nil]];

This creates a predicate that matches ( ( 1 <= attributeValue ) && ( attributeValue <= 10 ) ), as illustrated in the following example:

NSNumber *one = [NSNumber numberWithInteger:1];

NSNumber *ten = [NSNumber numberWithInteger:10];

NSPredicate *betweenPredicate = [NSPredicate predicateWithFormat: @"attributeName BETWEEN %@",

                                     [NSArray arrayWithObjects:one, ten, nil]];

NSNumber *five = [NSNumber numberWithInteger:5];

NSDictionary *dictionary = [NSDictionary dictionaryWithObject:five forKey:@"attributeName"];

BOOL between = [betweenPredicate evaluateWithObject:dictionary];

if (between) {

    NSLog(@"between");

Boolean Value Predicates

TRUEPREDICATE

A predicate that always evaluates to TRUE.

FALSEPREDICATE

A predicate that always evaluates to FALSE.

Basic Compound Predicates

AND, &&

Logical AND.

OR, ||

Logical OR.

NOT, !

Logical NOT.

String Comparisons

String comparisons are by default case and diacritic sensitive. You can modify an operator using the key characters c and d within square braces to specify case and diacritic insensitivity respectively, for example firstName BEGINSWITH[cd] $FIRST_NAME.

BEGINSWITH

The left-hand expression begins with the right-hand expression.

CONTAINS

The left-hand expression contains the right-hand expression.

ENDSWITH

The left-hand expression ends with the right-hand expression.

LIKE

The left hand expression equals the right-hand expression: ? and * are allowed as wildcard characters, where ? matches 1 character and * matches 0 or more characters. In Mac OS X v10.4, wildcard characters do not match newline characters.

MATCHES

The left hand expression equals the right hand expression using a regex-style comparison according to ICU v3 (for more details see the ICU User Guide for Regular Expressions).

Aggregate Operations

ANY, SOME

Specifies any of the elements in the following expression. For example ANY children.age < 18.

ALL

Specifies all of the elements in the following expression. For example ALL children.age < 18.

NONE

Specifies none of the elements in the following expression. For example, NONE children.age < 18. This is logically equivalent to NOT (ANY ...).

IN

Equivalent to an SQL IN operation, the left-hand side must appear in the collection specified by the right-hand side.

For example, name IN { 'Ben', 'Melissa', 'Matthew' }. The collection may be an array, a set, or a dictionary—in the case of a dictionary, its values are used.

In Objective-C, you could create a IN predicate as shown in the following example:

NSPredicate *inPredicate =

            [NSPredicate predicateWithFormat: @"attribute IN %@", aCollection];

where aCollection may be an instance of NSArray, NSSet, NSDictionary, or of any of the corresponding mutable classes.

array[index]

Specifies the element at the specified index in the array array.

array[FIRST]

Specifies the first element in the array array.

array[LAST]

Specifies the last element in the array array.

array[SIZE]

Specifies the size of the array array.

Identifiers

C style identifier

Any C style identifier that is not a reserved word.

#symbol

Used to escape a reserved word into a user identifier.

[\]{octaldigit}{3}

Used to escape an octal number ( \ followed by 3 octal digits).

[\][xX]{hexdigit}{2}

Used to escape a hex number ( \x or \X followed by 2 hex digits).

[\][uU]{hexdigit}{4}

Used to escape a Unicode number ( \u or \U followed by 4 hex digits).

Literals

Single and double quotes produce the same result, but they do not terminate each other. For example, "abc" and 'abc' are identical, whereas "a'b'c" is equivalent to a space-separated concatenation of a, 'b', c.

FALSE, NO

Logical false.

TRUE, YES

Logical true.

NULL, NIL

A null value.

SELF

Represents the object being evaluated.

"text"

A character string.

'text'

A character string.

Comma-separated literal array

For example, { 'comma', 'separated', 'literal', 'array' }.

Standard integer and fixed-point notations

For example, 1, 27, 2.71828, 19.75.

Floating-point notation with exponentiation

For example, 9.2e-5.

0x

Prefix used to denote a hexadecimal digit sequence.

0o

Prefix used to denote an octal digit sequence.

0b

Prefix used to denote a binary digit sequence.

Reserved Words

The following words are reserved:

AND, OR, IN, NOT, ALL, ANY, SOME, NONE, LIKE, CASEINSENSITIVE, CI, MATCHES, CONTAINS, BEGINSWITH, ENDSWITH, BETWEEN, NULL, NIL, SELF, TRUE, YES, FALSE, NO, FIRST, LAST, SIZE, ANYKEY, SUBQUERY, CAST, TRUEPREDICATE, FALSEPREDICATE