Predicate Format String Syntax
This article describes the syntax of the predicate string and some aspects of the predicate parser.
The parser string is different from a string expression passed to the regex engine. This article describes the parser text, not the syntax for the regex engine.
Parser Basics
The predicate string parser is whitespace insensitive, case insensitive with respect to keywords, and supports nested parenthetical expressions. The parser does not perform semantic type checking.
Variables are denoted with a dollar-sign ($
) character (for example, $VARIABLE_NAME
). The question mark (?
) character is not a valid parser token.
The format string supports printf
-style format specifiers such as %x
(see Formatting String Objects). Two important format specifiers 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 string using the %@
format specifier, 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) cause %@
, %K
, or $variable
to be interpreted as a literal in the format string and so 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.
The left-hand expression is between, or equal to either of, 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 %@", @[@1, @10]];
This creates a predicate that matches
( ( 1 <= attributeValue ) && ( attributeValue <= 10 ) )
, as illustrated in the following example:NSPredicate *betweenPredicate =
[NSPredicate predicateWithFormat: @"attributeName BETWEEN %@", @[@1, @10]];
NSDictionary *dictionary = @{ @"attributeName" : @5 };
BOOL between = [betweenPredicate evaluateWithObject:dictionary];
if (between) {
NSLog(@"between");
}
=
, ==
>=
, =>
<=
, =<
>
<
!=
, <>
BETWEEN
Boolean Value Predicates
A predicate that always evaluates to
TRUE
.A predicate that always evaluates to
FALSE
.
TRUEPREDICATE
FALSEPREDICATE
Basic Compound Predicates
Logical AND.
Logical OR.
Logical NOT.
AND
, &&
OR
, ||
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
.
The left-hand expression begins with the right-hand expression.
The left-hand expression contains the right-hand expression.
The left-hand expression ends with the right-hand expression.
The left hand expression equals the right-hand expression:
?
and*
are allowed as wildcard characters, where?
matches1
character and*
matches0
or more characters.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).The left hand argument to this operator is an expression that evaluates to a universal type identifier (UTI) you want to match. The right hand argument is an expression that evaluates to a UTI. The comparison evaluates to
TRUE
if the UTI returned by the left hand expression conforms to the UTI returned by the right hand expression. For information on which types conform to a given type, see System-Declared Uniform Type Identifiers in Uniform Type Identifiers Reference. To learn how to declare conformance to a custom UTI, see Declaring New Uniform Type Identifiers in Uniform Type Identifiers Overview.The clause
A UTI-CONFORMS-TO B
provides the same result as employing theUTTypeConformsTo
method as follows:UTTypeConformsTo (A, B)
When evaluating attachments in an app extension item (of type
NSExtensionItem
), you could use a statement similar to the following:SUBQUERY (
extensionItems,
$extensionItem,
SUBQUERY (
$extensionItem.attachments,
$attachment,
ANY $attachment.registeredTypeIdentifiers UTI-CONFORMS-TO "com.adobe.pdf"
).@count == $extensionItem.attachments.@count
).@count == 1
The left hand argument to this operator is an expression that evaluates to a universal type identifier (UTI) you want to match. The right hand argument is an expression that evaluates to a UTI. The comparison evaluates to
TRUE
if the UTI returned by the left hand expression equals the UTI returned by the right hand expression.The clause
A UTI-EQUALS B
provides the same result as employing theUTTypeEqual
method as follows:UTTypeEqual (A, B)
See the code example in the
UTI-CONFORMS-TO
entry, which applies as well to theUTI-EQUALS
operator by replacing the operator.
BEGINSWITH
CONTAINS
ENDSWITH
LIKE
MATCHES
UTI-CONFORMS-TO
UTI-EQUALS
Aggregate Operations
Specifies any of the elements in the following expression. For example
ANY children.age < 18
.Specifies all of the elements in the following expression. For example
ALL children.age < 18
.Specifies none of the elements in the following expression. For example,
NONE children.age < 18
. This is logically equivalent toNOT (ANY ...)
.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', 'Nick' }
. 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 ofNSArray
,NSSet
,NSDictionary
, or of any of the corresponding mutable classes.Specifies the element at the specified index in the array
array
.Specifies the first element in the array
array
.Specifies the last element in the array
array
.Specifies the size of the array
array
.
ANY
, SOME
ALL
NONE
IN
array[index]
array[FIRST]
array[LAST]
array[SIZE]
Identifiers
Any C style identifier that is not a reserved word.
Used to escape a reserved word into a user identifier.
Used to escape an octal number (
\
followed by 3 octal digits).Used to escape a hex number (
\x
or\X
followed by 2 hex digits).Used to escape a Unicode number (
\u
or\U
followed by 4 hex digits).
- C style identifier
- #symbol
- [\]{octaldigit}{3}
- [\][xX]{hexdigit}{2}
- [\][uU]{hexdigit}{4}
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
.
Logical false.
Logical true.
A null value.
Represents the object being evaluated.
A character string.
A character string.
For example,
{ 'comma', 'separated', 'literal', 'array' }
.For example,
1
,27
,2.71828
,19.75
.For example,
9.2e-5
.Prefix used to denote a hexadecimal digit sequence.
Prefix used to denote an octal digit sequence.
Prefix used to denote a binary digit sequence.
FALSE
, NO
TRUE
, YES
NULL
, NIL
SELF
"text"
'text'
- Comma-separated literal array
- Standard integer and fixed-point notations
- Floating-point notation with exponentiation
0x
0o
0b
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
, FETCH
, CAST
, TRUEPREDICATE
, FALSEPREDICATE
, UTI-CONFORMS-TO
, UTI-EQUALS
,
Copyright © 2005, 2014 Apple Inc. All Rights Reserved. Terms of Use | Privacy Policy | Updated: 2014-09-17